chore: merge 1.3.10 unified completion verdict (#30/#31)

chore: date 1.3.10 changelog for release
fix: address completion verdict review findings
2026-10-15 00:38:40 -04:00 · 2026-10-15 00:38:19 -04:00 · 2026-10-15 00:28:20 -04:00 · 2026-10-15 00:03:15 -04:00 · 2026-10-14 23:54:11 -04:00 · 2026-10-14 23:39:50 -04:00
58 changed files with 4963 additions and 180 deletions
@@ -41,10 +41,35 @@ for CODE_DIR in "${CODE_DIRS[@]}"; do
        fi
    fi
    # 复杂度只对"本次改动触及的函数"硬拦: 全量拦截会让存量债务挡住一切提交
    # (含纯文档提交),久之只剩绕过一条路;存量 ≥C 函数降为告警,随触及随还。
    # 用 HEAD 对比工作区+暂存区: 钩子在 `git add && git commit` 同一命令里先于 add 运行
    if command -v radon &> /dev/null; then
-        RADON_OUTPUT=$(radon cc "$CODE_DIR" -n C -s 2>&1 || true)
+        mapfile -t CHANGED_PY < <(git diff HEAD --name-only --diff-filter=AM -- "$CODE_DIR" | grep '\.py$' || true)
-        if echo "$RADON_OUTPUT" | grep -qE '^\s+[FMC]\s'; then
+        if [[ ${#CHANGED_PY[@]} -gt 0 ]]; then
-            ERRORS+="[radon] 存在圈复杂度 ≥ C 的函数：\n$RADON_OUTPUT\n"
+            TOUCHED=$(git diff HEAD -U0 -- "${CHANGED_PY[@]}" | python3 -c '
 import json, re, subprocess, sys
 hunks, path = {}, None
 for line in sys.stdin:
    if line.startswith("+++ "):
        path = line[6:].strip() if line.startswith("+++ b/") else None
    m = re.match(r"@@ -\S+ \+(\d+)(?:,(\d+))? @@", line)
    if m and path:
        start, count = int(m.group(1)), int(m.group(2) or 1)
        hunks.setdefault(path, []).append((start, start + max(count, 1) - 1))
 data = json.loads(subprocess.run(["radon", "cc", "-j", "-n", "C", *hunks], capture_output=True, text=True).stdout or "{}")
 for path, blocks in data.items():
    for b in blocks if isinstance(blocks, list) else []:
        if any(s <= b["endline"] and e >= b["lineno"] for s, e in hunks.get(path, [])):
            print("%s:%s %s - %s (%s)" % (path, b["lineno"], b["name"], b["rank"], b["complexity"]))
 ' 2>&1 || true)
            if [[ -n "$TOUCHED" ]]; then
                ERRORS+="[radon] 本次改动触及的函数圈复杂度 ≥ C：\n$TOUCHED\n"
            fi
        fi
        LEGACY_COUNT=$(radon cc "$CODE_DIR" -n C 2>/dev/null | grep -cE '^\s+[FMC]\s' || true)
        if [[ "$LEGACY_COUNT" -gt 0 ]]; then
            WARNINGS+="[radon] $CODE_DIR/ 存量 ${LEGACY_COUNT} 个函数圈复杂度 ≥ C(未被本次改动触及,不阻塞)。\n"
        fi
    fi
@@ -31,7 +31,7 @@ LLM__QWEN__1__TIMEOUT_S=120
 #   模型不支持所配档位时报错并列出它真正支持的档(库带能力表,含出处与实测日期)
 # LLM__QWEN__1__EFFORT_FALLBACK=error    # 档位打空时: error(默认,报错) | nearest(映射到最近的档)
 #   默认报错的理由是钱: 静默的 medium→max 在部分模型上是数倍账单;nearest 等距取弱侧
-# LLM__QWEN__1__MISSING_DONE=retry       # SSE 缺 [DONE]: retry(默认) | salvage
+# LLM__QWEN__1__MISSING_DONE=retry       # SSE 真截断(无 [DONE] 且无 finish+其后实测 usage): retry(默认) | salvage;1.3.10 起 finish+实测 usage+干净关闭的无 DONE 流恒视为完整
 # LLM__QWEN__1__TRUST_ENV=true           # false = 绕过本地代理(LAN 直连)
 # LLM__QWEN__1__EXTRA_BODY={"temperature":0}   # 本源恒定的采样参数(JSON 对象串)
 #   并入请求体,优先级低于 chat(overlay=...);受控实验固定解码用它,免得漏传
@@ -200,3 +200,7 @@ PGW_TELEMETRY_BACKEND=none               # sqlite | postgres | none(必填)
 # SOAK_OCR__GLOBAL__MAX_CONCURRENCY=16
 # SOAK_OCR__GLOBAL__RPM=300
 # SOAK_OCR_FAULT_SOURCES=monkey_3,monkey_4
 # OpenAI 保真模式是 per-call response_mode="openai"，无新增环境键。
 # raw-only reasoning_effort 放调用 overlay；对应源不得设置 ENABLE_THINKING 或
 # REASONING_EFFORT，请求 reasoning_effort=None 只继承源配置，不撤销源级意图。
@@ -1,5 +1,51 @@
 # Changelog
 ## 1.3.10(2026-10-15)
 #30/#31 同根修复: 1.3.9 以 `[DONE]` 存在、正文非空、字段白名单判定成功,上游的正常结局被当瞬时错误重试到耗尽(magpie/glm 不发 `[DONE]` 时单次调用挂 1216s;只有思考的 length 截断每次写满 max_tokens 后重抽)。本版改以上游 `finish_reason` 与传输完整性为准,流式/非流式/缓存读写共用一份判定。设计 `research-wiki/designs/2026-10-14-issue30-31-completion-verdict-design.md`。
 ### 修复
 - **缺 `[DONE]` 但完整的流**(#31,**两种模式**): finish_reason 已到、其同帧或之后收到实测 usage、连接干净关闭 → 完整交回,用量记 measured,`stream_end="eof_after_finish"`。文本模式默认 `MISSING_DONE=retry` 原本同样会重试到耗尽;该键现在只管真截断(无 finish 或 finish 后无实测 usage)。
 - **只有思考的 length 截断**(#30): 保真模式原样交回(content 空、思考完整、finish_reason=length),不再重抽。
 - **`null` 与未知字段**(#30): 任意层 `null` 视为缺省(`refusal: null`、`tool_calls: null` 不再判失败,**非流式同样修复**);保真模式未知字段按 OpenAI 流式惯例无损合并(字符串拼接、对象递归、带 `index` 数组按 index 合并、`index/type/id/format` 同值幂等),Gemini `extra_content` 一类工具层扩展可原样回传。
 - **`reasoning` 别名**: vLLM/OpenRouter 的 `reasoning` 字段计入活性(此前只有思考的流会被 TTFT 看门狗误杀),文本模式无非空 `reasoning_content` 时投影为 `thinking`。
 - **截断结果不再写缓存**: 文本 salvage 结果此前会被缓存并在 TTL 内反复回放。
 ### 行为变更
 - **文本模式 length/过滤且无正文 → `ResultInvalidError`**(原 `TransientError` 重试到耗尽): 不重试、不换源、熔断记成功不计窗口;**不经 `AllSourcesExhausted` 包装**,直接到调用方。原因码见异常消息(`length_without_content` / `filtered_without_content`)。文本模式"只有思考 + stop"维持瞬时(证据收集中)。
 - **finish_reason 为 `network_error`/`error`**(GLM 等上游自报失败)即使有正文也判瞬时。
 - **保真模式**: 只有思考/拒答/空白 + 明确 finish(非上游错误)→ 原样交回;length 截断的半截工具(缺 id/name)→ `ResultInvalidError` `tool_truncated`;无参函数全程只发 `arguments: null`(其余字段齐全)→ `ResultInvalidError` `tool_arguments_null`(确定性方言,交付值不改写)。
 - 文本模式 `choice.index: null` 视为 0(此前整帧被丢弃);`tool_calls` 中全为 `null` 的元素按 `tool_calls: null` 处理,不产出会被上游拒收的空数组。
 - **缓存**: 只有自然结束(stop/tool_calls/无 finish 的旧口径)且有正文的结果写入;length/过滤/未登记 finish 值、salvaged、空正文均交付但不缓存,读到此类条目按 miss。未登记 finish 值按源告警一次。
 - **活性口径增补**: 未知字段的非空字符串片段(如 `reasoning`)算进展,`index/type/id/format` 等标签键不算;`stall_ms` 计量随之覆盖。
 ### 新增
 - `LLMResponse` / `TransportResult` 末尾追加 `finish_reason: str | None`、`stream_end: StreamEnd | None`(`done` / `eof_after_finish` / `salvaged`;非流式、缓存命中为 None);包根导出 `StreamEnd`。
 - 遥测 `llm_calls` 末尾追加可空列 `stream_end`(INSERT 字段 38 → 39,物理列 39 → 40;旧行 NULL 不回填;auto 档幂等补列,manual 档裁剪写入并点名缺列,补列 SQL 由 `telemetry_schema_sql()` 自取)。
 ### 破坏性(请先读)
 - **`TelemetryRecorder.record_llm_call` 新增必填 keyword `stream_end`**: 自建 recorder 未跟进会在装配期被形状闸拒绝(`**fields` 形态不受影响)。
 ### 提醒
 - 保真模式交付 `finish_reason=length` 的工具调用时 arguments 可能是半截 JSON: **执行工具前先查 `finish_reason`**。
 - 未知字段合并冲突时会**删除该字段**并按(源, 路径)告警一次: 结果可能缺字段,以告警为准。典型形态: 带 `index` 的数组(如 `reasoning_details`)后续帧元素缺 `index` 即判形态改变,**整个字段被删**。
 - 诚实边界: 中转在上游出错后主动正常关闭连接,与真完整在传输层不可区分;防线是"finish 必须存在、不属上游错误、且其后有实测 usage"。
 - 旧版本写入的 salvage/length 文本缓存无法辨认: 受影响集合须在升级后首次读写前更换 namespace/salt(同 1.3.9 提醒)。
 ## 1.3.9(2026-10-01)
 - 新增 `chat(response_mode="openai")`，返回 `LLMResponse.completion`：assistant 消息、工具调用、finish_reason、上游 response_id、usage 快照；支持流式聚合及非流式。
 - 修复 SSE 顶层 error 后接 DONE 被当成功、同帧 content/reasoning_content 丢失；工具实际进展纳入看门狗、首 token 与中段对冲。
 - 保真仅支持单 choice，拒绝 structured 组合；工具参数逐字拼接，不执行或修复工具；缺 DONE 不允许 salvage。
 - 保真缓存独立身份并完整回放；缺协议、畸形协议及无正文无工具的坏条目均按 miss 回源。**旧文本缓存可能含曾被吞错的半截结果，受影响集合须在升级首次读写前更换 namespace/salt（含 per-call 覆盖）**，库不会自动辨认旧污染。
 - 新模式不绕过 managed/raw 冲突校验；raw-only 仍须源级/请求级均无受管意图。`Transport.complete` 新增必填 `response_mode`，自定义实现需适配。
 - 分发采用 Apache-2.0；README 补充常驻事件循环线程桥接，不新增同步 API。
 ## 1.3.8(2026-09-14)
 流式中段沉默的计量与应对(issue #27 / #28):`generation_ms` 口径重定义为**净生成时间**(扣除所有超阈值中段沉默)并配 `stall_ms`/`stall_count` 归因字段与遥测两列;另加一条**默认关闭**的中段沉默对冲(主路首 token 之后相邻增量 chunk 间隔超阈值时,向异源并发再发一次)。两键均不设时行为逐字等于 1.3.7(默认关闭回归门: 既有 unit/contracts 全套件语义断言一行未改)。
@@ -2,10 +2,12 @@
 > [!URGENT]
 > **实验室内部通用基础库(生产级、非 MVP、零业务假设)**
 >
 > 1. 本项目是被多个科研/生产项目依赖的**库**,不是应用:稳定性、并发性、防御性、可观测与测试不可为"简单"让步(YAGNI 仍适用,但不削减健壮性)。库的 bug 会同时击穿所有下游项目。
 > 2. 你的所有思考过程和回复必须使用 **简体中文**。
 ## 1. 项目元数据
 - **核心目标**: PolyGateway = 统一的大语言模型(LLM/VLM/OCR,音频预留)调度与中转库。治理单位是**一次模型调用**:请求封装、多源多账号、限流、错误分类与重试、熔断、Redis 响应缓存、流式看门狗、遥测(含成本)、结构化输出策略。全组件端口化可插拔。
 - **架构权威文档**: `research-wiki/ARCHITECTURE.md`(架构单一事实源,含 D1-D14 决策及讨论过程、子系统设计、三项目迁移验收标准;**不受 400 行设计文档限制**,以无歧义传达既有讨论为准绳)。开发顺序见 `research-wiki/ROADMAP.md`;`research-wiki/designs/` 仅存放每次实现具体功能的设计文档。
 - **参考项目**: `reference/` 下三个项目是本库的需求来源与代码蓝本(**只读,勿改**;M4 起"只读"指工作区文件与 main 检出不变——迁移实施经 `git worktree` 在 `~/Projects/m4-worktrees/` 的 feature 分支进行,worktree 的 git 操作会写 `reference/*/.git` 元数据,属预期);库必须能按 ARCHITECTURE.md §11 被它们迁移接入,否则即边界缺口。
@@ -35,11 +37,13 @@ make ci        # 只读验证(check + test)
 > **同一理由适用于长跑命令**: 需要后台跑时(如全套件测试),命令末尾**不得接管道**,否则退出码失真;要判完成用 `wait`/轮询 PID,不要用会匹配到自身的 `pgrep -f "<完整命令串>"`。
 ### Phase 1: 规划与设计
 1. 涉及**公共 API、端口签名、架构边界、新子系统**的变更**必须**调用 `brainstorming`(产出 2-3 备选方案+权衡)并经**人类确认**后实施;其余任务自判(判据: 是否改变库对下游的承诺)。动手前查阅 `research-wiki/`(单一事实源)。
 2. 功能产生运行时数据时**必须**调用 `structured-logging`。
 3. **里程碑级/跨多文件**功能编码前**必须**调用 `writing-plans`;小改动自判。审核门控: design 走 Claude 自审 → Codex 审 → **人类审**;plan 走 Claude 自审 → Codex 审 → 直接执行。
 ### Phase 2: 执行与验证
 1. **测试结果门**: 合并前每个行为变更必须有"先失败后通过"的测试证据(`test-driven-development`);bug 修复必带回归测试;不规定中间怎么走。
 2. **独立验证**: 里程碑级/跨多文件/合并前**必须**派全新上下文的 verifier subagent(`verification-before-completion`);任何规模的完成声明都必须逐条对应本会话内的工具输出(证据化声明,禁止虚报)。
 3. **反 gold-plating**: 不做任务外的重构、抽象与"顺手清理"。
@@ -47,6 +51,7 @@ make ci        # 只读验证(check + test)
 ## 4. 核心规则
 ### 4.1 核心原则(按优先级)
 - **P1 YAGNI**: 不写当前用不到的代码;但并发控制、防御校验、可观测埋点、错误隔离与测试是"当前需要",不在削减之列。
 - **P2 高可读性**: 领域术语命名;注释解释"为什么"。
 - **P3 单一职责**: 一句话说不清职责(需要"和")= 拆分。
@@ -69,6 +74,7 @@ make ci        # 只读验证(check + test)
 | 无缓存毒化 | 缓存 key 必含 model + messages 摘要 + 命名空间/租户 + salt;多模态 content 先摘要再 hash |
 ### 4.3 代码开发规范
 - 模块/类/方法必须有**中文 Docstring**;复杂逻辑用 `# Phase N` 注释组织。
 - 校验分层: 外部输入校验用显式异常(Python `-O` 移除 assert,禁止 assert 承担生产校验);assert 仅用于内部不变量。
 - 类名 `PascalCase`,私有前缀 `_`;导入顺序标准库→第三方→项目内。
@@ -76,6 +82,7 @@ make ci        # 只读验证(check + test)
 - 不考虑向后兼容,直接修改原文件。**例外**: `LLMResponse` 等已被三项目消费的公共类型,字段只增不删不改名(迁移兼容约束,见 ARCHITECTURE.md §5.1)。
 ### 4.4 Git 工作流
 - 一切开发在 feature 分支,严禁直改 main;频繁语义化提交;提交**必须**调用 `commit` skill;大改动前先提交回滚点。
 ### 4.4.1 发布流程(每步都是历史欠账换来的,不得跳步)
@@ -106,11 +113,13 @@ Gitea 包 registry 是 **owner 级**(`/iomgaa/-/packages/`)不是仓库级;PyPI
 发布验证补充（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` 等),降低迁移成本。
 - 装配只有两条路: `GatewayClient.from_env()`/`from_settings()`(工厂)或构造函数全量注入(测试/高级);库内部任何组件不得自读环境变量。
 ### 4.6 测试组织
 - `tests/{unit,integration,e2e}`;真实场景优先(录制的真实网关响应二次构造优于凭空 mock)。
 - 覆盖率目标 80%;并发/韧性行为是一等测试对象: 重试穿透取消、熔断开路半开、限流结算退款、Redis 掉线降级方向、缓存 key 隔离。
 - Redis 相关测试用真实 Redis(integration),不 mock Lua 行为;限流契约测试随实现一起交付(参考 CHSAnalyzer `tests/contracts_limiter.py`)。
@@ -154,6 +163,7 @@ project_root/
 | 第一次抽库尝试(教训与蓝本) | `reference/GovDoc-SaaS/packages/docagent-core/` |
 ## 7. 输出规范
 - 所有输出**中文**;文档优先表格/伪代码/Mermaid;禁止超 15 行代码块入文档、禁止连续超 5 条碎片列点;设计 ≤400 行、计划 ≤1000 行、报告 ≤300 行。
 - **例外**: `research-wiki/ARCHITECTURE.md` 不受行数限制——它的准绳是"后来的 AI/人类无需还原原始讨论即可准确理解全部决策及理由",宁详勿略(详细 ≠ 琐碎:记录论证与取舍,不堆砌实现细节)。
@@ -0,0 +1,202 @@
                                 Apache License
                           Version 2.0, January 2004
                        http://www.apache.org/licenses/
   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
   1. Definitions.
      "License" shall mean the terms and conditions for use, reproduction,
      and distribution as defined by Sections 1 through 9 of this document.
      "Licensor" shall mean the copyright owner or entity authorized by
      the copyright owner that is granting the License.
      "Legal Entity" shall mean the union of the acting entity and all
      other entities that control, are controlled by, or are under common
      control with that entity. For the purposes of this definition,
      "control" means (i) the power, direct or indirect, to cause the
      direction or management of such entity, whether by contract or
      otherwise, or (ii) ownership of fifty percent (50%) or more of the
      outstanding shares, or (iii) beneficial ownership of such entity.
      "You" (or "Your") shall mean an individual or Legal Entity
      exercising permissions granted by this License.
      "Source" form shall mean the preferred form for making modifications,
      including but not limited to software source code, documentation
      source, and configuration files.
      "Object" form shall mean any form resulting from mechanical
      transformation or translation of a Source form, including but
      not limited to compiled object code, generated documentation,
      and conversions to other media types.
      "Work" shall mean the work of authorship, whether in Source or
      Object form, made available under the License, as indicated by a
      copyright notice that is included in or attached to the work
      (an example is provided in the Appendix below).
      "Derivative Works" shall mean any work, whether in Source or Object
      form, that is based on (or derived from) the Work and for which the
      editorial revisions, annotations, elaborations, or other modifications
      represent, as a whole, an original work of authorship. For the purposes
      of this License, Derivative Works shall not include works that remain
      separable from, or merely link (or bind by name) to the interfaces of,
      the Work and Derivative Works thereof.
      "Contribution" shall mean any work of authorship, including
      the original version of the Work and any modifications or additions
      to that Work or Derivative Works thereof, that is intentionally
      submitted to Licensor for inclusion in the Work by the copyright owner
      or by an individual or Legal Entity authorized to submit on behalf of
      the copyright owner. For the purposes of this definition, "submitted"
      means any form of electronic, verbal, or written communication sent
      to the Licensor or its representatives, including but not limited to
      communication on electronic mailing lists, source code control systems,
      and issue tracking systems that are managed by, or on behalf of, the
      Licensor for the purpose of discussing and improving the Work, but
      excluding communication that is conspicuously marked or otherwise
      designated in writing by the copyright owner as "Not a Contribution."
      "Contributor" shall mean Licensor and any individual or Legal Entity
      on behalf of whom a Contribution has been received by Licensor and
      subsequently incorporated within the Work.
   2. Grant of Copyright License. Subject to the terms and conditions of
      this License, each Contributor hereby grants to You a perpetual,
      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
      copyright license to reproduce, prepare Derivative Works of,
      publicly display, publicly perform, sublicense, and distribute the
      Work and such Derivative Works in Source or Object form.
   3. Grant of Patent License. Subject to the terms and conditions of
      this License, each Contributor hereby grants to You a perpetual,
      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
      (except as stated in this section) patent license to make, have made,
      use, offer to sell, sell, import, and otherwise transfer the Work,
      where such license applies only to those patent claims licensable
      by such Contributor that are necessarily infringed by their
      Contribution(s) alone or by combination of their Contribution(s)
      with the Work to which such Contribution(s) was submitted. If You
      institute patent litigation against any entity (including a
      cross-claim or counterclaim in a lawsuit) alleging that the Work
      or a Contribution incorporated within the Work constitutes direct
      or contributory patent infringement, then any patent licenses
      granted to You under this License for that Work shall terminate
      as of the date such litigation is filed.
   4. Redistribution. You may reproduce and distribute copies of the
      Work or Derivative Works thereof in any medium, with or without
      modifications, and in Source or Object form, provided that You
      meet the following conditions:
      (a) You must give any other recipients of the Work or
          Derivative Works a copy of this License; and
      (b) You must cause any modified files to carry prominent notices
          stating that You changed the files; and
      (c) You must retain, in the Source form of any Derivative Works
          that You distribute, all copyright, patent, trademark, and
          attribution notices from the Source form of the Work,
          excluding those notices that do not pertain to any part of
          the Derivative Works; and
      (d) If the Work includes a "NOTICE" text file as part of its
          distribution, then any Derivative Works that You distribute must
          include a readable copy of the attribution notices contained
          within such NOTICE file, excluding those notices that do not
          pertain to any part of the Derivative Works, in at least one
          of the following places: within a NOTICE text file distributed
          as part of the Derivative Works; within the Source form or
          documentation, if provided along with the Derivative Works; or,
          within a display generated by the Derivative Works, if and
          wherever such third-party notices normally appear. The contents
          of the NOTICE file are for informational purposes only and
          do not modify the License. You may add Your own attribution
          notices within Derivative Works that You distribute, alongside
          or as an addendum to the NOTICE text from the Work, provided
          that such additional attribution notices cannot be construed
          as modifying the License.
      You may add Your own copyright statement to Your modifications and
      may provide additional or different license terms and conditions
      for use, reproduction, or distribution of Your modifications, or
      for any such Derivative Works as a whole, provided Your use,
      reproduction, and distribution of the Work otherwise complies with
      the conditions stated in this License.
   5. Submission of Contributions. Unless You explicitly state otherwise,
      any Contribution intentionally submitted for inclusion in the Work
      by You to the Licensor shall be under the terms and conditions of
      this License, without any additional terms or conditions.
      Notwithstanding the above, nothing herein shall supersede or modify
      the terms of any separate license agreement you may have executed
      with Licensor regarding such Contributions.
   6. Trademarks. This License does not grant permission to use the trade
      names, trademarks, service marks, or product names of the Licensor,
      except as required for reasonable and customary use in describing the
      origin of the Work and reproducing the content of the NOTICE file.
   7. Disclaimer of Warranty. Unless required by applicable law or
      agreed to in writing, Licensor provides the Work (and each
      Contributor provides its Contributions) on an "AS IS" BASIS,
      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
      implied, including, without limitation, any warranties or conditions
      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
      PARTICULAR PURPOSE. You are solely responsible for determining the
      appropriateness of using or redistributing the Work and assume any
      risks associated with Your exercise of permissions under this License.
   8. Limitation of Liability. In no event and under no legal theory,
      whether in tort (including negligence), contract, or otherwise,
      unless required by applicable law (such as deliberate and grossly
      negligent acts) or agreed to in writing, shall any Contributor be
      liable to You for damages, including any direct, indirect, special,
      incidental, or consequential damages of any character arising as a
      result of this License or out of the use or inability to use the
      Work (including but not limited to damages for loss of goodwill,
      work stoppage, computer failure or malfunction, or any and all
      other commercial damages or losses), even if such Contributor
      has been advised of the possibility of such damages.
   9. Accepting Warranty or Additional Liability. While redistributing
      the Work or Derivative Works thereof, You may choose to offer,
      and charge a fee for, acceptance of support, warranty, indemnity,
      or other liability obligations and/or rights consistent with this
      License. However, in accepting such obligations, You may act only
      on Your own behalf and on Your sole responsibility, not on behalf
      of any other Contributor, and only if You agree to indemnify,
      defend, and hold each Contributor harmless for any liability
      incurred by, or claims asserted against, such Contributor by reason
      of your accepting any such warranty or additional liability.
   END OF TERMS AND CONDITIONS
   APPENDIX: How to apply the Apache License to your work.
      To apply the Apache License to your work, attach the following
      boilerplate notice, with the fields enclosed by brackets "[]"
      replaced with your own identifying information. (Don't include
      the brackets!)  The text should be enclosed in the appropriate
      comment syntax for the file format. We also recommend that a
      file or class name and description of purpose be included on the
      same "printed page" as the copyright notice for easier
      identification within third-party archives.
   Copyright [yyyy] [name of copyright owner]
   Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
   You may obtain a copy of the License at
       http://www.apache.org/licenses/LICENSE-2.0
   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.
@@ -19,11 +19,13 @@
 | 调用期限 | 一次逻辑调用可选一条**墙钟硬边界**(`{SCOPE}__CALL_DEADLINE_S` 或 `chat(call_deadline_s=...)`,缺省不启用):治理的是**等待**——重试退避、配额轮询、熔断冷却、结构化重问与 embedding 分批共享同一份期限。三条须知:①**返回时刻 = 期限 + 清理耗时**(遥测/结算/缓存收尾在 `finally` 里跑完,允许超期;实测构造达期限的 5–7 倍),库只承诺切断等待、不给返回上界;②**到期 ≠ 未产出、≠ 未计费**,上游可能已算完并计费;③**不配置即逐字保持 1.3.5 语义**(纯 429 序列仍可能长等、有限大 `Retry-After` 仍照睡)。到期抛 `CallDeadlineExceeded`,**不属四分类、不属 `GatewayUnavailableError` 族** |
 | 长尾对冲 | **默认关闭**的可选加速(`{SCOPE}__HEDGE__AFTER_S`,仅 chat):一次尝试挂起超阈值时向**异源**并发再发一次,先回者赢、输家取消。流式以「首 token 未至」为触发判据(不误杀慢生成),非流式只有纯总时长阈值;对冲走完整限流/熔断准入,拿不到配额静默放弃。成本须知:开启即用配额换延迟(触发窗口内 in-flight 翻倍),输家取消按 est 保留预扣且**可能已被上游计费**(取消止不住上游);输家不喂熔断,遥测 attempt 行标 `error="hedge_cancelled"` 可按 `logical_call_id` join 对账;两路皆败只计一次重试预算;与 `call_deadline_s` 正交组合(装配守卫强制对冲阈值 < 期限)
 | 中段沉默对冲(可选,超业界现状能力) | **默认关闭**(`{SCOPE}__HEDGE__STALL_AFTER_S`,仅流式 chat):主路**首 token 之后**相邻增量 chunk 沉默超阈值时向异源并发再发一次,与首 token 对冲 `HEDGE__AFTER_S` **独立生效**、可独设可组合;仅设它且请求非流式 → 逐字走单路(中段沉默无非流式概念)。**诚实标注:中段沉默触发并发副本在主流网关/库中无公开先例**(业界收敛为看门狗掐流重试)。成本须知:下游实测沉默 >20s 占 19.0%,触发率远高于首 token 对冲,开启即用配额换延迟,输家可能已被上游计费;看门狗掐死**喂**熔断而对冲输家取消**不喂**(不对称声明),详见[1.3.8 生成时间口径与中段沉默对冲](#138-生成时间口径与中段沉默对冲) |
 | OpenAI 消息保真(1.3.9) | `chat(response_mode="openai")` 返回完整 assistant 消息/工具调用、finish_reason、上游 ID 与 usage；单 choice，复用治理，不执行工具；默认仍为文本模式 |
 | 完成判定(1.3.10) | 以上游 `finish_reason` 为准判定"生成结束、结果可交付":缺 `[DONE]` 但 finish 与其后的实测 usage 齐全即完整(两模式);length/过滤等确定性结局不再被当瞬时错误重试;未知/`null` 字段不再判失败;`LLMResponse.finish_reason` / `stream_end` 给出结束原因与方式,详见[1.3.10 统一完成判定](#1310-统一完成判定) |
 | 响应缓存 | Redis/内存;key 含 model + messages 摘要 + namespace(缓存隔离单位)+ salt + 采样参数 + 请求级推理档位(同 messages 跑 low 与 max 不互相命中),多模态 content 先摘要再 hash(防毒化);可 per-call 绕过(科研重采样) |
-| 流式看门狗 | TTFT / inter-token / 总超时三层活性;thinking token 刷活性不计结果;截断流(缺 `[DONE]`)判瞬时不入缓存 |
+| 流式看门狗 | TTFT / inter-token / 总超时三层活性;thinking token(含 `reasoning` 别名)刷活性不计结果;截断流(无 `[DONE]` 且无 finish+其后实测 usage)默认判瞬时(`MISSING_DONE=salvage` 的文本打捞结果交付但不入缓存) |
 | 推理可观测性 | "这次到底推理没推理"由多信号裁定(推理正文压倒 usage 明细),三态落在 `LLMResponse.thinking_observation`:`observed` / `absent` / `unknown`——**`unknown` 是"本次判不出",不是"没推理"**;本次实发档位与实测观测矛盾时按 `(源, 模型, 生效档位)` 各告警一次(能力表过期、开启未生效、注入了却观测不到;同一模型的 low 与 max 是两个独立的矛盾,不共用节流键);裁定结果随遥测落库 |
 | 推理档位 | 推理是**八档**(`none`/`auto`/`minimal`/`low`/`medium`/`high`/`xhigh`/`max`)而非开关:源级 `REASONING_EFFORT` + 请求级 `chat(reasoning_effort=...)`,`ENABLE_THINKING` 保留为语法糖;库带 24 条能力表(逐条 evidence 自报实测/文档推定),档位打空**默认报错并给出该模型最省的可用档与该配的键**,要静默映射需显式配 `EFFORT_FALLBACK=nearest`;实发档随 `LLMResponse.applied_effort` 与遥测落库 |
-| 遥测与成本 | 每次调用(含缓存命中与失败)必录 38 字段;三类行(`event_kind` = `attempt` / `cache_hit` / `terminal_failure`)加逐源诊断列(`http_status_code` / `error_type` / `cause_type` / `error_body`);SQLite / Postgres 后端(表已存在时**不需要** schema 建表权限,最小权限账号可直接用);按价格表折算成本落库(注意 `LLMResponse.cost` 本身恒为 `None`,成本只进遥测);多模态内容摘要落库不存原图 |
+| 遥测与成本 | 每次调用(含缓存命中与失败)必录 39 字段;三类行(`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`,及生成时间 `generation_ms`——**1.3.8 起为净口径**:赢家那次 transport 调用墙钟 − Σ超阈值中段沉默,仍含 TTFT 与尾部,排除准入排队/退避/触发前等待;1.3.7 的墙钟值由 `generation_ms + stall_ms` 还原——与沉默归因 `stall_ms` / `stall_count`(成对报告,None = 无沉默观测)、对冲计数 `hedges` / `hedge_won`),重试、换源、结构化重问、embedding 分批共享同一逻辑 ID;每次**领域失败**另落一条 `terminal_failure` 行,失败调用数从此是一条 `WHERE event_kind = 'terminal_failure'`,详见[1.3.5 逻辑调用统计与失败诊断](#135-逻辑调用统计与失败诊断)与[1.3.8 生成时间口径与中段沉默对冲](#138-生成时间口径与中段沉默对冲) |
 | 遥测的资源与降级 | 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、不建索引** |
@@ -124,7 +126,7 @@ stats.total_latency_ms             # 含缓存 IO、退避、准入等待、重
 | 定义 | **净生成时间** = 赢家那次 transport 调用的墙钟 − Σ(所有 > `STALL_THRESHOLD_MS`(缺省 1000ms)的相邻增量 chunk 沉默);仍**排除**准入排队/退避/对冲触发前等待(同 1.3.7) |
 | 边界 | 仍含 **TTFT 与尾部**(末 chunk → 流结束归活跃侧,墙钟基底口径的有意选择) |
 | 还原公式 | **墙钟 = `generation_ms + stall_ms`**(`stall_ms is None` 时墙钟 = `generation_ms`) |
-| `stall_ms` / `stall_count` | 沉默总额(毫秒)与超阈值相邻间隔个数,**成对报告**(只报净数无法行动);chunk = 任何增量产出(`content` 或 `reasoning_content` 均计),空 chunk / usage 帧 / SSE keepalive 不计时 |
+| `stall_ms` / `stall_count` | 沉默总额(毫秒)与超阈值相邻间隔个数,**成对报告**(只报净数无法行动);chunk = 任何增量产出(`content`、`reasoning_content`、工具实际增量,1.3.10 起另含未知字段的非空字符串片段如 `reasoning`),空 chunk / usage 帧 / SSE keepalive / 仅标签键(`index`/`type`/`id`/`format`)不计时 |
 | `stall_ms is None` 分支条件 | 非流式 / 增量 chunk <2 → 两字段 None 且 `generation_ms` **不退减**;None = 「无沉默观测」而非 0,下游预算公式以此为分支条件 |
 | 与基准口径的区隔 | NVIDIA TTFT/ITL/E2EL 与 vLLM 的基准口径**均不扣除**沉默——扣沉默是本库自造口径,与基准数字比较时不得混用 |
@@ -137,7 +139,7 @@ stats.total_latency_ms             # 含缓存 IO、退避、准入等待、重
 | `{SCOPE}__STREAM__STALL_THRESHOLD_MS` | 正整数毫秒 | **1000** | 仅改计量口径,不改任何行为;三层调整接口同权(env 键 / `GatewaySettings.stall_threshold_ms` / `GatewayClient(stall_threshold_ms=...)`);无 per-call 覆盖,不做自适应(防与对冲阈值耦出反馈环) |
 | `{SCOPE}__HEDGE__STALL_AFTER_S` | 有限正数秒 | **未设 = 关闭** | 独立于 `HEDGE__AFTER_S` 生效;守卫: `≥ min(各源 inter_token_timeout_s 或 timeout_s)`(对冲窗永不开)或 `≥ call_deadline_s` → 装配期 **ValueError**,单源 scope → warning;三层调整接口同权(env 键 / `GatewaySettings.hedge_stall_after_s` / `GatewayClient(hedge_stall_after_s=...)`);Embedding/OCR scope 配任一对冲键 → warning 后静默退化 |
-对冲语义(两阶段触发窗/复检防误触发/取消穿透)与成本披露见 [CHANGELOG 未发布段](CHANGELOG.md);运维「挂起率」统计须知不对称:看门狗掐死**喂**熔断失败计数,对冲输家取消**不喂**熔断。
+对冲语义(两阶段触发窗/复检防误触发/取消穿透)与成本披露见 [CHANGELOG 1.3.8 段](CHANGELOG.md);运维「挂起率」统计须知不对称:看门狗掐死**喂**熔断失败计数,对冲输家取消**不喂**熔断。
 ## 安装
@@ -145,7 +147,7 @@ stats.total_latency_ms             # 含缓存 IO、退避、准入等待、重
 ```bash
 pip install --extra-index-url https://gitea.iomgaa.online/api/packages/iomgaa/pypi/simple/ \
-    "polygateway[redis,postgres,structured]>=1.3.8,<2"
+    "polygateway[redis,postgres,structured]>=1.3.10,<2"
 ```
 核心仅依赖 `httpx` + `pydantic`;按需选 extras:
@@ -610,3 +612,110 @@ make ci        # 只读全量验证
 ## 兼容性承诺
 `LLMResponse` 等被下游消费的公共类型,字段**只增不删不改名**且新增字段必带默认值;`{SCOPE}__{PROVIDER}__{N}__{FIELD}` 与平铺韧性键名(`LLM_TIMEOUT` 等)沿用三项目既有习惯,不做破坏性改名。实验室内部库,随实验室项目需求演进。
 ## 1.3.9 OpenAI 工具消息保真（单 choice）
 `chat(..., response_mode="openai")` 仍返回 `LLMResponse`，完整协议结果在
 `response.completion`：`message`、`finish_reason`、`response_id`、`usage`。
 `content/thinking` 是旧文本投影（可剥离 think 标签）；回传代理或继续对话应使用
 completion.message，不能从旧投影重建工具响应。嵌套 JSON 是独立快照但仍可修改。
 ```python
 response = await client.chat(
    messages,
    response_mode="openai",
    overlay={"tools": tools, "tool_choice": "auto"},
 )
 completion = response.completion
 messages.append(completion.message)
 # 工具执行与 role=tool 结果由调用方添加；库不会执行工具。
 ```
 保真是 JSON 字段和值保真，不是 HTTP 字节透明代理。仅支持单 choice（`n=1`），
 可含多个并行 function tool_calls；arguments 逐字拼接，不解析、修复或执行。
 SSE 的 role/content/reasoning_content/tool_calls 按原语义聚合；1.3.10 起 `null` 视为缺省，
 未知增量字段按流式惯例无损合并（冲突删键并告警，见下节）；
 非流式保留整个 message 扩展字段，不返回顶层 logprobs/created 等其他字段。
 上游实际模型仍读 `model_reported`，配置别名是 `model`。
 | 边界 | 行为 |
 | --- | --- |
 | 空文本且有完整工具 | 正常成功；不完整工具失败（length 截断的半截工具归 ResultInvalid），其余见 1.3.10 结局表 |
 | error 帧 | 所有模式立即判失败并走已有重试；后续 DONE 不挽救 |
 | 缺 DONE | 1.3.10 起 finish + 其后实测 usage + 干净 EOF 即完整；真截断仍不受 salvage 放宽，防截断工具被执行 |
 | finish_reason=length | 原样返回（含只有思考的回答），不修补参数；**执行工具前先查 finish_reason**，arguments 可能是半截 JSON |
 | structured | 不可与保真并用；自行传 overlay.response_format 不启用库的修复/重问阶梯 |
 | raw 推理 | 保真不是校验逃生口；raw-only 要求源 ENABLE_THINKING/REASONING_EFFORT 均未设置，请求档为 None，再通过 overlay.reasoning_effort 传原值 |
 工具实际增量与正文/推理共用首 token、inter-token、stall 对冲及沉默计量；注释、
 usage、role-only、重复工具身份不算进展。非流式无中段事件，保持纯时长阈值对冲。
 `Transport.complete` 的自定义实现须接收必填 `response_mode`；不支持保真时明确
 RequestRejected，不能伪造 completion 或静默退回文本。
 缓存按返回模式隔离；缺协议、畸形协议或无正文无工具的条目按 miss 回源。命中保留历史上游 response_id/usage，生成本次治理 call_id，
 本次 attempts=0、cost=0。**旧文本缓存可能含修复前 error+DONE 的截断产物**：
 受影响调用集合须在首次读写前更换从未承载旧语义的 namespace 或 salt，包含工厂、
 全量注入和 per-call 覆盖，保留租户前缀与 epoch。未迁移仍可能读旧值，库不自动清除。
 遥测继续单一出口，不新增工具全文列；既有 TEXT_CAP 不覆盖 tool_calls.arguments。
 ### 线程模型的异步桥接
 库不新增同步客户端。socketserver 等工作线程应向**一个常驻事件循环线程**提交：
 client 必须在该 loop 内创建、使用并关闭，不能每请求 asyncio.run 或跨 loop 共用
 httpx/Redis 组件。下例的 loop 和 client 已由宿主完成初始化：
 ```python
 future = asyncio.run_coroutine_threadsafe(
    client.chat(messages, response_mode="openai", overlay=overlay), loop
 )
 try:
    response = future.result(timeout=timeout_s)
 except TimeoutError:
    future.cancel()  # 断连也应取消；取消不等于上游未计费。
    raise
 ```
 应用退出时先停止接单、取消/等待在途调用，在同一个 loop 中 await client.aclose()，
 再停 loop 并 join 线程；注入组件仍由所有者关闭。不要从 loop 本身阻塞调用 future.result。
 ## 1.3.10 统一完成判定
 #30/#31 同根: 1.3.9 以 `[DONE]` 存在、正文非空、字段白名单作为成功判据,上游的正常结局
 (不发 `[DONE]`、只有思考的 length 截断、`refusal: null`)被当瞬时错误重试到耗尽。1.3.10
 改以上游 `finish_reason` 与传输完整性为准,流式/非流式/缓存四处共用一份判定。
 | 结束方式(`stream_end`) | 条件 |
 | --- | --- |
 | `done` | 收到 `[DONE]` |
 | `eof_after_finish` | 未发 `[DONE]`,但 finish 已到、其同帧或之后收到的 usage 为实测,连接干净关闭(用量记 measured) |
 | `salvaged` | 文本模式 `MISSING_DONE=salvage` 打捞的截断结果(用量降 estimated,**不写缓存**) |
 | `None` | 非流式 / 缓存命中 / 失败行 |
 | 结局(首个匹配行生效) | `openai` 模式 | `text` 模式 |
 | --- | --- | --- |
 | finish 为 `network_error`/`error`(上游自报失败) | 瞬时错误 | 瞬时错误 |
 | 工具快照不成立 | length → `ResultInvalidError`;其余瞬时 | — |
 | 无任何产物 + length/过滤 | 原样交回 | `ResultInvalidError`(不重试、不计熔断) |
 | 无任何产物 + 其余(零增量抖动) | 瞬时错误 `empty_completion` | 同左 |
 | 有正文 | 交付 | 交付 |
 | 只有思考/拒答/空白 + length/过滤 | 原样交回 | `ResultInvalidError` |
 | 只有思考/拒答/空白 + stop 等 | 原样交回 | 瞬时错误(证据收集中) |
 | 只有思考/拒答/空白 + 无 finish | 瞬时错误 | 同左 |
 `ResultInvalidError` 不经 `AllSourcesExhausted` 包装,直接到调用方;原因码在异常消息里
 (`length_without_content` / `filtered_without_content` / `tool_truncated` 等,遥测 `error`
 列可检索)。只有自然结束(stop/tool_calls/function_call,或未上报 finish 的旧口径)且投影正文非空
 (或工具完整)的结果才写缓存;未登记的 finish 值按正常交付、不缓存并告警一次。无参函数只发
 `arguments: null` 的工具判 `ResultInvalidError`(`tool_arguments_null`,确定性方言,不改写不重试)。文本模式 `thinking` 在无非空 `reasoning_content` 时取
 `reasoning`(vLLM/OpenRouter 新名)。保真模式未知字段:字符串拼接、对象递归、带 `index` 的
 数组按 index 合并、`index/type/id/format` 同值幂等;冲突时**删除该字段**并按(源, 路径)
 告警一次——结果可能缺字段,以告警为准。诚实边界:中转在上游出错后主动正常关闭连接与真
 完整在传输层不可区分,防线是"finish 必须存在、不属上游错误、且其后有实测 usage"。
 遥测 `llm_calls` 追加可空列 `stream_end`;`TelemetryRecorder.record_llm_call` 新增必填
 keyword `stream_end`(**自建 recorder 须跟进,否则装配期被形状闸拒绝**)。
 ## 许可证
 PolyGateway 使用 [Apache License 2.0](LICENSE)。内部移植代码的原创 owner 已明确授权；
 分发范围不包含 `reference/` 外部参考仓。
@@ -4,11 +4,12 @@ build-backend = "setuptools.build_meta"
 [project]
 name = "polygateway"
-version = "1.3.8"
+version = "1.3.10"
 description = "PolyGateway：实验室统一的大语言模型（LLM/VLM/OCR）调度与中转库——多源、限流、重试、熔断、缓存、遥测"
 # registry 包页面的正文只认这一项:缺了页面就是一片空白(1.1.2 的教训,twine 会警告
 # long_description missing 但不阻塞上传)。README 在打包时被固化进产物,发布后再改无效。
 readme = "README.md"
 license = {file = "LICENSE"}
 requires-python = ">=3.12"
 dependencies = [
    "httpx>=0.27",
@@ -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` 退化成普通限速)。
@@ -566,7 +568,7 @@ flowchart TB
 ### 7.8 遥测与成本
-**必录字段**(继承三项目 15 字段规范;当前 38 个 INSERT 字段,物理表列 39 = 38 + 数据库自填的 `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**、**stall_ms**、**stall_count**。
+**必录字段**(继承三项目 15 字段规范;当前 39 个 INSERT 字段,物理表列 40 = 39 + 数据库自填的 `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**、**stall_ms**、**stall_count**、**stream_end**(1.3.10,§15)。
 **`stall_ms`/`stall_count` 两列(2026-09-11,1.3.8,issue #27,端口 36 → 38)**: 沉默归因进库,口径见 §7.2 净口径段。取 INTEGER 而非 REAL——落库值是 retry 层已取整的 int,与换算唯一处纪律(N8)一致。追加在 `total_latency_ms` 之后,可空无默认、旧行 NULL 不回填;`emit_cache_hit`/`emit_terminal_failure` 与失败/取消 attempt 行恒 NULL(缓存命中与终态行无 transport 观测;被取消的对冲输家无 TransportResult,其 `hedge_cancelled` 行 stall 恒 NULL,存在性由该行表达)。`generation_ms` **仍不进遥测列**(YAGNI)——墙钟由 `generation_ms + stall_ms` 还原。
@@ -789,3 +791,36 @@ src/polygateway/
 | Q6 | CHSAnalyzer 的 judge 迁移路径 | **已拍板(2026-07-22 用户)**: M4 实测 judge/core-eval 评估流水线**零调用方、从未接线**(全仓仅自测消费),且实验室网关无 claude 系模型——本轮**豁免不动**,judge.py 原样保留;待评估流水线真正启用时再收编走库(届时裁判模型从网关现有模型选) |
 | Q4 | conda 环境名 | `PolyGateway` |
 | Q5 | 本仓库工程脚手架(git init、`.claude/` skills、Makefile、pyproject、import-linter)何时落地 | 本文档终审通过后、M1 编码前一次落地 |
 ## 14. OpenAI 单 choice 消息保真（2026-10-01，#29 已批准增量）
 本节明确修订 §5/§6.2/§7.1/§7.2/§7.5/§7.6 中原仅文本契约，详细边界见 [设计](designs/2026-10-01-issue29-openai-fidelity-design.md)。不新增 Agent Loop 或第二套治理。
 | 接缝 | 增量契约 |
 |---|---|
 | 公共返回 | chat 追加 response_mode=text/openai，默认 text；LLMResponse/TransportResult 末尾追加 completion，内含 assistant message、finish_reason、response_id、usage；旧字段继续文本兼容投影 |
 | 请求所有权 | messages 字段保真；overlay 仍受 model/messages/stream/stream_options 保护；raw-only 复用既有路径，模式不绕过 managed 校验 |
 | 协议 | openai 单 choice；工具按 index 排序，name/arguments 逐片拼接；SSE 支持 role/content/reasoning_content/tool_calls，未知增量拒绝；非流式保留消息扩展字段；成功必含 assistant role |
 | 失败 | 所有 chat 模式 error 帧立即 TransientError；openai 缺 DONE 一律重试、不 salvage；tool-only 成功，纯空/不完整工具失败；text salvage 原语义不变 |
 | 活性 | 同帧正文/推理/工具实际进展只记一次；role/usage/finish/空帧/重复身份不算；沿既有看门狗、首 token、stall 对冲与唯一取整点 |
 | 缓存 | 仅 openai key 新增 response_mode 语义维度，默认 text key 不变；完整快照显式重建，缺 completion/role 或无有效正文/工具按 miss（与 transport 共用内核纯值判据，不依赖 transport 实现）；历史上游 id 回放，本次治理 id 重建 |
 | 迁移 | 旧 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`，逆命题不成立。诚实边界：中转在上游出错后主动正常关闭连接，与真完整在传输层不可区分。
@@ -72,6 +72,8 @@
 **已交付增补(2026-09-14)**: 流式中段沉默计量与对冲(issue #27/#28,1.3.8)——`generation_ms` 口径重定义为**净生成时间**(墙钟 − Σ超阈值中段沉默,仍含 TTFT 与尾部;1.3.7 墙钟口径由 `generation_ms + stall_ms` 还原,披露见 CHANGELOG 未发布段),`CallStats` 增 `stall_ms`/`stall_count` 归因字段,遥测表加同两列(INSERT 字段 36→38);`{SCOPE}__HEDGE__STALL_AFTER_S` 中段沉默对冲(独立于 `HEDGE__AFTER_S` 生效、默认关闭;无业界公开先例,超业界现状能力),`{SCOPE}__STREAM__STALL_THRESHOLD_MS` 计量阈值(默认 1000,三层可调)。设计 designs/2026-09-11-streaming-stall-design.md(人类已批准 + 独立审查补遗 B1-B4/N1-N9),实施 plans/2026-09-11-streaming-stall.md,验证 findings/2026-09-11-streaming-stall-validation.md。后续储备:自适应分位阈值(防反馈环,现不做)、流式透传下的 commit 点重审、embedding/OCR 对冲(现不做)。
 **已交付增补(2026-10-15,1.3.10 已发布)**: 统一完成判定(issue #30/#31,1.3.10)——以上游 `finish_reason` 与传输完整性判定流完成与结局,流式/非流式/缓存读写共用内核纯函数;缺 `[DONE]` 但 finish+实测 usage 完整即成功(两模式),文本 length/过滤无正文改 `ResultInvalidError`,保真模式 null/未知字段无损合并;`LLMResponse` 增 `finish_reason`/`stream_end`,遥测加 `stream_end` 列。设计 designs/2026-10-14-issue30-31-completion-verdict-design.md(人类授权 Claude 与独立 subagent 两轮审查后直接执行),实施 plans/2026-10-14-issue30-31-completion-verdict.md。后续储备:文本 n>1 混流修复、文本"只有思考+stop"证据收集。
 ## 7. 开放决策依赖
 | 决策 | 阻塞点 | 需拍板时间 |
@@ -0,0 +1,171 @@
 ---
 type: design
 node_id: design:2026-10-01-issue29-openai-fidelity-design
 title: OpenAI消息保真设计
 date: 2026-10-01
 ---
 # #29 OpenAI 消息保真设计
 > **修订指针(2026-10-14)**: §4.1"未知 delta 拒绝"、§4.2"reasoning-only 不算成功"与"缺 DONE 一律失败"、§5 活性口径、§6 缓存判据已由 [统一完成判定设计](2026-10-14-issue30-31-completion-verdict-design.md)(1.3.10)修订,以后者为准。
 > 状态：方向已获人类批准；计划独立审查 P1/P2 已修订并实施，首轮独立代码审查发现的缓存空产物及测试双向依赖已修复，等待父会话最终复核；按人类最终指定准备 1.3.9，取代未发布的 1.4.0；尚未发布。
 > 基线：`0e29deac1a72bfee348ed2f8061ea2c33be217e8` / 1.3.8；日期：2026-10-01。
 > 需求：[issue #29](https://gitea.iomgaa.online/iomgaa/PolyGateway/issues/29)。
 > 权威约束：ARCHITECTURE §2.3、§5、§6、§7.1–7.8；实现前按本文修订对应架构段落。
 ## 1. 批准记录与范围
 用户已明确同意：现有 `chat()` 增加显式 OpenAI 保真模式，`LLMResponse` 增加完整协议结果，复用治理链，修复工具聚合、活性、error 帧和缓存隔离；首版单 choice、不执行工具、不增加 Agent Loop。用户随后确认内部移植代码均为其原创且本人 owner，并明确授权 PolyGateway 使用 Apache-2.0；dissect3 也是其项目。以上不再重复请示。
 Codex 不可用，人类已授权原生 subagent 替代独立审查。具体 API 拼写与防御约束由本设计落实，经独立审查后实施；若审查要求改变已批准边界，才重新讨论。设计阶段已结束；实现验证记录见计划末尾，独立代码审查/发布前禁止宣称 issue 已解决。
 “保真”是受支持 OpenAI Chat Completions 消息字段和值保真，不是 HTTP 字节级透明代理，不覆盖任意供应商增量方言。model、stream、stream_options 仍由库控制；没有逐块回调、工具执行、同步客户端、美元预算或失败用量取证新功能。
 ## 2. 源码核验与方案比较
 | 已核实接缝 | 现状与修复目标 |
 | --- | --- |
 | `transports/openai_compat.py::_sse_delta` | 只读首 choice；content 早返回丢同帧 reasoning；忽略 tool_calls/error |
 | `_complete_stream` / `_complete_once` | 纯文本判空；raw 只存 usage；需新增协议快照与 tool-only 成功语义 |
 | `client.py::chat` / `_build_payload` | messages 已直传，overlay 已合并，无需白名单重写 |
 | `thinking.py::validate_thinking_raw` | raw-only 已支持；受管与 raw 冲突是既定保护，不得绕过 |
 | `middleware/retry.py::_build_response` | 唯一响应构造出口，新增字段在此搬运，不新增治理循环 |
 | `middleware/cache.py` | 已有完整消息/overlay 身份，但嵌套新类型需重建、模式需隔离 |
 | 方案 | 优势 | 代价/结论 |
 | --- | --- | --- |
 | A：chat 显式模式 + LLMResponse 内嵌协议结果 | 生命周期、取消、缓存、遥测和对冲单一实现；兼容旧投影 | 需定义组合约束和缓存身份；**选定** |
 | B：新增 chat_completion 入口，复用私有核心 | 接口像 OpenAI | 重复公共签名、输入校验和终态封装，收益不足，否决 |
 | C：独立 SDK 客户端或代理自聚合 | 局部改动直观 | 无法自动解决响应上浮/缓存/线路错误，复制治理，否决 |
 ## 3. 公共契约
 ### 3.1 模式与类型
 在 `types.py` 定义并从包根导出 `ResponseMode` 和 `OpenAIChatCompletion`：
 ```python
 ResponseMode = Literal["text", "openai"]
@dataclass(frozen=True)
 class OpenAIChatCompletion:
    """单 choice 的协议消息快照；嵌套 JSON 并非深度不可变。"""
    message: dict[str, Any]
    finish_reason: str | None
    response_id: str | None
    usage: dict[str, Any] | None
 ```
 `GatewayClient.chat` 末尾追加 keyword-only `response_mode: ResponseMode = "text"`；`ChatRequest` 末尾同字段同默认。`TransportResult`、`LLMResponse` 末尾追加 `completion: OpenAIChatCompletion | None = None`，已有字段不改名、不改位置。保真模式成功时 completion 必非 None；文本模式不承诺提供 completion。
 `Transport.complete` 追加必填 keyword-only `response_mode: ResponseMode`，依照现有端口纪律不使用默认值掩盖漏传。默认 transport 实现和测试 transport 一并适配；不新增 SDK 适配器（当前文件树尚无该实现）。自定义 transport 须实现新参数与返回契约，不支持模式时抛 RequestRejectedError，不静默回退。
 completion 是独立于上游容器的深拷贝 JSON 快照；frozen 只保证字段不能重绑，不伪称深度不可变。调用方可用 `copy.deepcopy(response.completion.message)` 构造下一轮；其修改不得污染别次调用、缓存条目或另一路对冲。不上 MappingProxyType，避免与既有 dataclasses.asdict/JSON 序列化冲突。
 ### 3.2 请求与组合校验
 | 条件 | 规则 |
 | --- | --- |
 | 未知模式 | 公共入口 ValueError，尚未创建逻辑调用上下文 |
 | openai + structured 非 None | 公共入口 ValueError；不注入 schema、不自动重问；overlay 的 response_format 仍可直传 |
 | openai + n | 仅允许缺省或严格整数 1（不接受 bool）；调用 overlay 在入口校验，选中源 extra_body 及最终 payload 在 HTTP 前校验，不接受被 overlay 遮蔽的非法源级 n |
 | text + n | 保留旧行为，本次不扩大旧文本多 choice 语义；明确只投影第一 choice |
 | 消息 | 保留 assistant/tool/reasoning_content/扩展字段，JSON 值不改写；保真入口校验可序列化并深拷贝，避免并发/重试期间调用方改动 |
 | overlay | 复用既有保护键、源级→请求级优先级；保真调用对快照作深拷贝，不原地改调用方容器 |
 源级 n 错误属选源后的请求拒绝，抛 RequestRejectedError，finally 结算规则不变。保真响应必须恰好一个 choice；SSE choice.index 必须为整数 0，usage-only choices=[] 合法；非流式一个 choice 可省略 index，存在时必须为 0。上游返回多 choice 是协议失败 TransientError，不能静默截取。
 ### 3.3 推理所有权不随返回模式变化
 复用 `effective_effort`、`resolve_thinking`、`validate_thinking_raw`，不改能力表与档位映射。raw-only 示例前提：源级 enable_thinking=None、reasoning_effort=None，请求级 reasoning_effort=None，然后 overlay 传 `{"reasoning_effort": "max"}`。`chat(reasoning_effort=None)` 是继承源，不是撤销源意图；raw 与任何有效受管意图（含 NONE）并存仍拒绝。raw-only 的 applied_effort 仍 None，不编造受管档位。
 ### 3.4 兼容投影与上游身份
 完整协议 `message` 不过 `_finalize_text`，保留 content 的缺省/null/空串区别、空白、think 标签；非流式保留整个 message 的 JSON 扩展字段。`LLMResponse.content/thinking` 仍是旧 `_finalize_text` 投影，content 为 null/缺省时投影空串；只用于旧消费面和现有遥测，代理回传以 completion 为准。
 response_id 是上游 id，允许未上报为 None，绝不拿 call_id 补齐；finish_reason 原样保存，缺失为 None，不从工具存在与否猜测；usage 保存原对象快照（最后一个非 null usage），不因 token 归一或 salvage 修改原文。字段存在但类型不符是协议失败。`length` 原样返回，不修复工具参数；下游决定是否执行。
 ## 4. 协议聚合与完成规则
 新增内部模块 `transports/_openai_completion.py`，只处理 chat 单 choice 协议校验、每尝试聚合与快照；不做 I/O、重试、计时、provider 推理或缓存。现有 openai_compat 保留 HTTP、看门狗、投影、usage 归一化与领域上下文。
 ### 4.1 SSE 聚合状态
 每次 complete 独立创建聚合器，不放 transport 实例共享状态。逐 JSON 帧先校验对象并查 error，再读取 choices/delta、元信息和 usage；坏类型统一转 TransientError，不让 AttributeError/TypeError 逃出治理。
 | 字段 | 合并规则 |
 | --- | --- |
 | content / reasoning_content | 非 null 必为 str，逐片拼接；同帧同时收集；不 trim；从未出现则不造键，仅 null 则保留 null |
 | role | openai 模式若出现必须 assistant；只出现 role 不算活性；最终成功必须含 assistant role；缺失失败，不伪造字段 |
 | tool_calls | 必为列表；每项 index 必为非负严格整数；按 index 分桶，末尾按 index 排序，索引不输出到最终工具对象 |
 | id / type | 每工具的身份字段，缺失片段不覆盖；相同重复幂等，冲突拒绝；不把重复完整 id 拼两次 |
 | function.name / function.arguments | 字符串增量按到达顺序逐字拼接，允许空片段；arguments 不 JSON 解析/修复/重排 |
 | response id / finish_reason | 首个非 null 固定，后续相同值允许、冲突拒绝；model_reported 沿用既有首有效值口径 |
 最终有效工具需非空 id、type="function"、非空 function.name，以及至少出现一次字符串 arguments（允许空串）；重复工具 id、缺字段、非 function 工具类型都拒绝，不伪造或丢弃。index 可非连续，按排序输出，不按列表位置猜 index。JSON 参数内容及工具业务 schema 不由库验证。
 SSE、非流式及缓存最终快照均要求 role="assistant"；缺失或其他 role 为协议失败/缓存 miss；合法 role-only 开头不算活性。
 非流式工具是完整列表：保留条目及扩展字段，仅校验上述必要字段/类型/唯一 id，不要求 index；存在的扩展字段不删除。SSE 保真仅支持 role/content/reasoning_content/tool_calls；未知 delta 字段或未知工具增量字段无法推定合并语义，明确拒绝为协议失败，避免宣称任意扩展字段无损；元数据如 logprobs 不属于本协议结果字段，文档明确不返回。
 ### 4.2 成功、截断与错误
 | 场景 | 行为 |
 | --- | --- |
 | openai：空正文 + 有完整工具 | 成功，不触发空补全重试 |
 | openai：非空投影正文、无工具 | 成功；存在任何不完整工具则仍拒绝，不用正文掩盖坏工具 |
 | openai：无正文且无有效工具 | 维持 empty_completion 瞬时失败；reasoning-only 不算成功 |
 | openai：EOF 无 DONE | 无论 missing_done=salvage、是否已有正文/工具/finish，都失败；不打捞潜在可执行结果 |
 | text：EOF 无 DONE | 保持已有 early_eof/retry/salvage 及 estimated/unavailable 行为 |
 | 任一 chat 模式出现顶层 error 键 | 立即 TransientError，即使值 null/空对象；不读取后续 usage/DONE 挽救，不缓存 |
 | 非流式 200 error / 非 JSON / 坏 envelope | TransientError；HTTP 非 200 分类沿用现有规则 |
 text 仍不接收 tool-only 成功，不承诺工具结果；共用解析路径的 error 检查、同帧双文本采集和真实工具进展活性修复适用于两模式。纯文本消费不新增工具完整性要求，以免把未承诺的工具结果变成默认请求失败。
 ## 5. 活性、治理、取消和可观测
 一帧有非空正文、非空推理、非空工具 name/arguments 增量或首次建立工具身份时，产生**一次**进展事件。重复相同身份、空 arguments、空 delta、role-only、usage-only、finish-only、注释不刷新活性。同帧多个字段和两个工具仍只记录一个时间戳，避免制造零间隔或虚增 stall_count。
 `stream_with_liveness_timeouts` 继续包进展迭代器；openai_compat 用同一事件更新时间戳、TTFT、max_gap、first_token_event、content_event。保持 `_stall_from_chunk_times` 与 retry 唯一取整点不变；真正沉默照常触发中段对冲。非流式不置两事件，stall=None，只保留纯时长阈值对冲。
 请求经原 Telemetry→Cache→Structured（None 直通）→Retry→准入→Transport 链。重试、异源对冲、失败预算、源健康、限流结算均原样复用；输家取消仍保守 est 结算、不喂熔断，赢家携自身完整快照。CancelledError 全栈穿透，连接与 permit finally 释放，无新的 shield 或后台任务。
 遵循 structured-logging：不新增数据库列/表/Recorder 参数。`_build_response` 搬运 completion；错误由 transport 抛出，经过既有 RetryMW._emit→TelemetryEmitter 单出口记 attempt/terminal 行。SSE error 使用现有 summarize_body/compose_message 有界摘要，携 source_name/operation=chat，最多记录有界错误体，不在日志新增完整工具参数、密钥或成功消息。
 现有 `llm_calls` schema（`research-wiki/schemas/llm-calls.md`）及覆盖指标复用。确定性验收指标：error→成功恰好 attempts=2；tool-only attempts=1；命中 attempts=0；失败不写缓存；无孤儿 permit/task。失败 usage 仍 unavailable，费用仍未知，不删除失败事件；不扩展遥测全文覆盖，tool_calls.arguments 不受现有 TEXT_CAP 截断的已知边界须继续声明。
 ## 6. 缓存语义
 `build_cache_key` 追加 `response_mode: ResponseMode = "text"`；仅非 text 时将 response_mode 写入 key 对象。默认文本 key 逐字不变；这是请求语义维度，不引入包版本/revision。tools、tool_choice、raw effort 已在 sampling/source fingerprint；assistant/tool 消息全字段已在 digest_messages，直接复用。
 CacheMW 显式序列化和重建 OpenAIChatCompletion，读时验证容器、单消息/工具必要字段与元信息类型。openai 条目 completion 缺失/null/畸形或无有效产物视 miss+warning，不能补默认伪造协议成功；text 旧条目允许缺新字段。transport 与缓存共用 types 内部纯值判据：完整工具或非空投影正文；无工具时还要求协议原正文非空，不能靠缓存旧投影伪装成功；不收紧快照构造用途。错误条目回源成功后覆写，失败不写。
 缓存中的 message/usage 与调用结果独立；命中保留历史上游 id/finish/usage，生成本次 call_id、清除历史 call_stats，最终返回本次 attempts=0；cost=0 延续原口径。缓存读写和序列化失败仅 warning，不冒泡，取消例外穿透；将 `_serialize` 异常纳入缓存降级边界，避免新增嵌套字段扩大失败面。
 旧文本缓存可能已被 error+DONE 毒化，不能自动判别。发布文档要求受影响调用集合首次读写前迁移 namespace/salt，保留租户前缀与 epoch；覆盖工厂和 per-call 身份。未迁移仍会回放旧值，不能宣称修复自动清除历史缓存；openai 新身份天然不命中旧文本。
 ## 7. 旧行为审计与非功能约束
 | 既有行为 | 处置 |
 | --- | --- |
 | 旧字段/默认文本/structured 阶梯/受管推理 | 保留；默认文本同帧漏 reasoning 属修复 |
 | HTTP 分类、retry/backoff、两类对冲、TPM/熔断 | 保留，不改算法与预算 |
 | 空补全、missing_done salvage | 文本保留；openai tool-only 放行、缺 DONE 强制失败 |
 | Redis TTL、命名空间、遥测幂等与单 helper | 保留；新增模式隔离与嵌套协议结果回放 |
 | 并发与取消 | 每尝试状态隔离，重试/对冲不得复用聚合器，CancelledError 穿透 |
 | 降级方向 | 缓存/遥测 warning；准入后端 fail-closed；不新增后端 |
 | 持久化/原子性/恢复 | 仅成功后一次写完整缓存值；沿用后端原子 set；无新的任务持久化或断点状态 |
 | 幂等与重复 | 重试/对冲可能产生重复上游计费，库不执行工具，因此不产生本地工具副作用；不承诺上游生成幂等 |
 ## 8. 测试、许可证与交付门
 单元测试复用 MockTransport/SSE/受控事件设施；新增两工具交错分片、同帧 content+reasoning、原样下一轮、raw=max、stream=False、缺 DONE、安全判错、缓存和治理组合。每个行为组须保留基线红、新实现绿日志；不以本阶段基线通过冒充新功能证据。
 真实 Redis 只测完整协议缓存往返/隔离与取消关联契约，不 mock Lua。真实模型跑专用通用函数工具双轮冒烟（标 slow，输出 Markdown），复用 `.env` 配置与预算，不在源码硬编码凭据；网络/额度失败如实失败，不改成无覆盖成功。不默认重跑全模型推理矩阵；本次不改 thinking 能力算法。
 许可证：采用 Apache-2.0 已授权；实施前核查实际分发文件及注明移植/参考的片段，区分参考协议事实与复制代码。reference/ 只读且不打包；AGPL 仓存在不自动污染本库，也不由授权覆盖第三方权利。发现实际复制的不兼容片段须上报，不擅自改许可证。加入标准 LICENSE 与 pyproject 元数据；只有确有通知义务才加 NOTICE，不捏造第三方来源。
 源码 docstring、README、CHANGELOG、ARCHITECTURE 同步；无新 env 键，`.env.example` 仅补 raw-only 源配置提示（不改默认）。Gitea Wiki 当前下线，不重建过期页面。线程代理文档说明：client 在同一常驻事件循环线程内创建/使用/关闭；工作线程 run_coroutine_threadsafe，等待超时/断连取消 Future；不逐请求 asyncio.run，不跨 loop 共享 client。
 发布由父会话在独立代码审查、全套件、相关 slow、构建包 LICENSE/元数据核验之后执行；沿 CLAUDE 发布九步，外部验证 registry/Release/包页和下游下载，不仅 bump。issue 只有在可安装产物及验收证据齐备后关闭；本阶段不触发这些动作。
@@ -0,0 +1,251 @@
 ---
 type: design
 node_id: design:2026-10-14-issue30-31-completion-verdict-design
 title: 统一完成判定设计(#30/#31)
 date: 2026-10-14
 ---
 # #30/#31 统一完成判定设计
 > 状态: 方向已获人类批准(2026-10-14,四项取舍与五个拍板点按推荐);人类授权"Claude 与独立 subagent 确认无误后直接执行",不再走人类设计审阅。两轮独立审查已闭合(R1 3 阻塞 + 9 应修;R2 通过,2 应修已并入),见 §11。
 > 基线: `22609c9`(1.3.9);目标版本 **1.3.10**;分支 `fix/issue30-31-completion-verdict`。
 > 需求: [#30](https://gitea.iomgaa.online/iomgaa/PolyGateway/issues/30)、[#31](https://gitea.iomgaa.online/iomgaa/PolyGateway/issues/31)。
 > 修订对象: [1.3.9 保真设计](2026-10-01-issue29-openai-fidelity-design.md) §4.1/§4.2/§5/§6、ARCHITECTURE §6.2/§7/§14。
 ## 1. 问题与根因
 两条 issue 是**同一根因**: 库判定"生成结束了、结果可交付"时,依赖库自己的推断(`[DONE]` 存在、正文非空、字段在白名单内、快照字段类型),而不是上游的权威声明(`finish_reason`)与传输完整性(干净 EOF + 结尾 usage)。推断失败一律落 `TransientError` → 重试/换源/计熔断,把确定性结局放大成 `max_attempts` 次付费重抽并推高健康源的熔断计数。
 | 表现 | 位置(1.3.9) | 后果 |
 | --- | --- | --- |
 | #31 缺 `[DONE]` 但 finish+usage 完整 | `openai_compat.py:668-671`(保真无条件拒);`_check_done:714`(文本 `missing_done=retry` 默认同样拒) | magpie/glm 两模式均重试到耗尽;实测 1216s 挂起、dissect3 38 次终败 |
 | #30-1 reasoning-only + `length` | `types.py:478-490`、`_reject_empty_completion` | 每次写满 max_tokens 后丢弃重抽 |
 | #30-2 未知键 / `tool_calls:null` | `_openai_completion.py:97-98,112-114,139-140,146-147`;**非流式也中**: `OpenAIChatCompletion` 拒 `tool_calls: None`(`types.py:451-453`,已实测) | 渠道一换 100% 失败,且以"瞬时"形态出现 |
 | 隐患: 只有 `reasoning` 字段的流 | 活性只认 content/reasoning_content | 两模式被看门狗当无进展 → TTFT 超时 |
 | 隐患: 文本 salvage 的截断结果被缓存 | `cache.py:197-204` 写路径无判定 | 半截结果 TTL 内反复回放 |
 补充事实: GLM 的 finish_reason 含 `network_error`/`sensitive`;2026-07-20 空补全裁决针对的是 stop/无 finish 的"零增量"抖动(`findings/2026-07-21-m25-acceptance.md:48`);vLLM 等实现每帧带累计 usage,finish 之前的 usage 不证明走完。
 ## 2. 方案比较
 | 方案 | 内容 | 结论 |
 | --- | --- | --- |
 | A 局部放行 | 按 issue 字面在三处各加例外 | 否决: 流式/非流式/缓存判据继续分叉;文本 #31 残留;`network_error` 被当成功 |
 | B 统一完成判定(选定) | 内核纯函数分两步(流完整性 → 结局分类),流式/非流式/缓存读写四处共用;"可交付"与"可缓存"拆两判据;未知字段无损合并 | 一次消除根因;代价是公共字段追加与遥测端口加参 |
 | C 透明透传 | 保真模式不做结局判定,原样交回 | 否决: 零增量抖动回归(违背 2026-07-20 裁决),截断流也被交出 |
 ## 3. 公共契约变更(只增不改)
 | 位置 | 变更 |
 | --- | --- |
 | `types.py` | 新增 `StreamEnd = Literal["done", "eof_after_finish", "salvaged"]`,包根导出 |
 | `TransportResult` / `LLMResponse` 末尾 | 追加 `finish_reason: str \| None = None`、`stream_end: StreamEnd \| None = None` |
 | `OpenAIChatCompletion` 校验 | `tool_calls: null` 合法(视同无工具,原样保留键) |
 | `TelemetryRecorder.record_llm_call` | 追加**无默认值** keyword-only `stream_end: str \| None`(**破坏性**: 自建 recorder 装配期被形状闸拒绝,CHANGELOG 单列) |
 | `llm_calls` 表 | 末尾追加可空列 `stream_end TEXT`(落点见 §7) |
 | `Transport.complete` 签名 | **不变** |
 `finish_reason` 取值: 流式取 choice 0(保真已强制单 choice;文本取 `index` 缺省或为 0 的 choice)首个非 null 值;非流式取 `choices[0].finish_reason`。保真模式非字符串维持 1.3.9 拒绝(Transient);文本模式非字符串记 None。`finish_reason` 不进遥测列(未获批)。
 | 场景 | `stream_end` |
 | --- | --- |
 | 流式收到 `[DONE]` | `"done"` |
 | 干净 EOF + finish + 结尾 measured usage | `"eof_after_finish"` |
 | 文本 `missing_done=salvage` 打捞 | `"salvaged"` |
 | 非流式 / 缓存命中 / 失败行 | `None`(与 `ttft_ms`/`stall_ms` 同"无从观测"口径) |
 与 `usage_source` 分工: 后者答"账单可信吗",前者答"内容完整吗"。`eof_after_finish ⇒ measured`(由 §4.2 条件保证);`salvaged ⇒ estimated|unavailable`;`estimated ⇒ salvaged`,逆命题不成立。
 ## 4. 统一完成判定
 ### 4.1 位置与形态
 全部放 `types.py` 内部纯函数(下划线前缀,不导出): CacheMW 要复用,import-linter 禁止 middleware 依赖 transports,而内核层 `ports : types : errors : streaming` 允许。函数只返回判定值,**不抛领域错误**(错误需 `source_name` 等上下文,由调用点翻译),不捕获任何异常,取消天然穿透。
 | 函数 | 职责 |
 | --- | --- |
 | `_tool_snapshot_ok(message)` | 工具快照是否成立(id/type/function.name/arguments 规则 + 唯一 id);`OpenAIChatCompletion.__post_init__` 复用 |
 | `_classify_finish(value)` | 映射到 finish 类别(下表) |
 | `_stream_is_complete(...)` | 第一步,返回 `StreamEnd \| None`(None = 截断) |
 | `_judge_outcome(...)` | 第二步,返回 `deliver` 或 `(reject_transient \| reject_result, 原因码)` |
 | `_is_cacheable(...)` | §6 判据 |
 | finish 类别 | 值(大小写敏感) |
 | --- | --- |
 | natural | `stop`、`tool_calls`、`function_call` |
 | truncated | `length` |
 | filtered | `content_filter`、`sensitive` |
 | upstream_error | `network_error`、`error` |
 | unknown | 其余非空字符串: 按 natural 交付、**不可缓存**、按源+值告警一次(文案写明"该值不缓存",便于下游定位命中率下降);`end_turn`/`stop_sequence` 等无证据不预先归类 |
 | absent | None |
 ### 4.2 第一步: 流完整性(仅流式)
 | 条件 | 结果 |
 | --- | --- |
 | 读取异常 / 活性超时 / error 帧 / 畸形帧 | 照旧 Transient(不动) |
 | 收到 `[DONE]` | `done` |
 | 干净 EOF、无 DONE、finish 已见、finish 帧**同帧或之后**收到的 usage 被 `_resolve_usage` 判为 measured | `eof_after_finish`,usage 记 measured(不降级) |
 | 干净 EOF、其余情形 | 截断: openai → Transient `missing_done`(仍不打捞);text → 原 `_check_done` 语义(零产物 early_eof、`retry` 抛、`salvage` 记 `salvaged`) |
 聚合器每尝试记录 `finish_seen` 与 `usage_after_finish`: 收到非 null usage 时,若 `finish_seen` 已真或同帧带 finish,则置后者为真;是否 measured 以**最后一个**非 null usage(与计费所用 `sink["usage"]` 同一对象)在流结束时判定;usage-only 帧(`choices: []`)在 finish 之后到达是常规形态,正确置位。状态随重试/对冲每尝试新建。
 诚实边界: 中转站在上游出错后主动正常结束响应,与真完整在传输层不可区分;防线是"finish 必须存在、不属 upstream_error、且其后有 measured usage",文档如实写明。
 ### 4.3 第二步: 结局分类
 产物定义——**保真模式**: 任何产物 = 消息中任一非空字符串片段(content、reasoning_content、reasoning、refusal、合并保留的未知字符串,空白也算)或至少一个非 null 工具条目;**文本模式**: 任何产物 = 投影 content 或 thinking(含 §4.4 别名)非空串(含空白),未知字段与工具增量只计活性不计产物,`_check_done` 零产物判据同口径。两模式**正文产物** = 投影 content strip 后非空,或(仅保真)工具快照成立且非空。
 表格**自上而下取首个匹配行**:
 | # | 条件 | openai 模式 | text 模式 |
 | --- | --- | --- | --- |
 | 1 | finish 为 upstream_error | Transient `upstream_finish_error` | 同左 |
 | 2 | (仅保真)存在工具条目但 `_tool_snapshot_ok` 不成立 | truncated → ResultInvalid `tool_truncated`;其余 → Transient `tool_incomplete` | 不适用 |
 | 3 | 无任何产物 + truncated/filtered | 交付(#30;隐藏推理模型写满预算的形态) | ResultInvalid `length_without_content` / `filtered_without_content` |
 | 4 | 无任何产物 + natural/unknown/absent | Transient `empty_completion`(保 2026-07-20 裁决) | 同左 |
 | 5 | 有正文产物 | 交付 | 交付 |
 | 6 | 有产物无正文 + truncated | 交付(#30) | ResultInvalid `length_without_content` |
 | 7 | 有产物无正文 + filtered | 交付 | ResultInvalid `filtered_without_content` |
 | 8 | 有产物无正文 + natural/unknown | 交付 | Transient `empty_completion`(待证据;消息带 finish 与 thinking 长度) |
 | 9 | 有产物无正文 + absent(流式仅 DONE 收尾,或非流式 body finish 为 null) | Transient `empty_completion` | 同左 |
 ResultInvalid 理由: `retry.py:409-414` 对其"不重试、不换源、熔断记成功不计窗口";length/过滤是预算或内容策略的确定性结局,不是源坏了。对冲下原路 ResultInvalid 等对冲路裁定,两败原样上抛(`retry.py:548-560`);StructuredMW 只捕 parse 抛出的 ResultInvalid,不会误重问(`structured.py:79`)。已知代价: 该分支 TPM 全额退款、用量不落成本(`actual=0`),与 Transient 丢成本同级,登记为已知边界。文本 length 改抛 ResultInvalid 后不再经 `AllSourcesExhausted` 包装,§10 要求核对下游 catch 点。
 原因码以固定格式 `"{源} {code}: …"` 写进异常 message,从而进遥测 `error` 列(LIKE 可检索);不新增列、不改 `_failure_reason`(Transient 一族熔断原因记 `network_error` 属已知口径)。
 保真模式行 2 之外的工具快照成立 + `length`: 交付,arguments 可能是半截 JSON——docstring 与 CHANGELOG 提醒调用方先查 `finish_reason` 再执行工具。非流式跳过第一步,直接以 body 的 finish_reason 走第二步。
 ### 4.4 文本模式 reasoning 别名
 投影 `thinking`: 本次尝试出现过**非空** `reasoning_content` 则只用它,否则用 `reasoning`。保真 `completion.message` 保留上游原键不改名。两模式活性、产物摘要、`thinking_observation` 均基于该投影。
 ## 5. 字段合并与活性
 ### 5.1 null 与已知字段
 null 规则**优先于**已知字段类型校验: chunk、choice、delta、工具条目、function 五层任意键值为 null 视为缺省,数组中的 null 元素(如 `tool_calls: [null]`)跳过;键从未出现时保留 `key: null`(含 `tool_calls`、`refusal`、`role`、`function.arguments`)。保真成功仍须最终 role=assistant(全程只有 `role: null` 即缺 role,照旧失败)。其余已知字段(content/reasoning_content/role/tool_calls 及工具 id/type/function.name/arguments)非 null 时语义逐字沿用 1.3.9。
 ### 5.2 未知字段(delta、`tool_calls[]` 条目、`function` 三层统一)
 | 值 | 规则 |
 | --- | --- |
 | 标签键 `index`/`type`/`id`/`format`(任意未知层级) | 同值幂等,不拼接;不同值 = 冲突 |
 | 其他字符串 | 按到达顺序拼接(OpenAI SDK 流式累加惯例) |
 | 数字/布尔 | 同值幂等;不同值 = 冲突(不学 SDK 相加) |
 | 对象 | 递归套用本表 |
 | 数组且元素均为带整数 `index` 的对象 | 按 index 合并(`reasoning_details` 一类);合并策略由该键首次出现形态决定,之后形态改变 = 冲突 |
 | 其他数组 | 追加 |
 | 冲突 | 删除该键路径,本尝试内不再接收;按 (源, 归一路径) 告警一次 |
 冲突删键是有损的: docstring 与 CHANGELOG 写明"可能缺字段,以告警为准"。上游方言确定,重拉同样结果,不视为缓存毒化。
 ### 5.3 活性
 已知字段活性逐字沿用 1.3.9(非空 content/reasoning_content、工具 name/arguments 非空增量、首次建立工具身份)。未知字段仅当本帧在非标签键上并入非空字符串片段(含追加型数组中的字符串元素)时算进展(`reasoning` 由此计入);同帧只记一次。残余风险如实登记: 上游每帧重复下发的非标签字符串(如 `status`)会被拼接并持续刷新看门狗。文本模式同口径。README 中"增量 chunk = content 或 reasoning_content"的 stall/TTFT 口径表述同步更新为本节口径。
 ### 5.4 告警节流
 节流集合放 transport 实例(与 `_warned_mismatches` 分立,纯 asyncio 中立),键为 (源, 归一路径) 与 (源, 未知 finish 值):路径中数组下标归一为 `[]`,finish 值截断至 64 字符;集合上限 1024,饱和后记一次"告警已饱和"不再增长。日志只写源名与路径,不回显值(可能含工具参数)。聚合器以只读集合交出冲突路径,transport 负责告警。
 ## 6. 可交付 vs 可缓存
 可缓存 ⊂ 可交付。两模式同一判据 `_is_cacheable`,读写共用:
 | 条件(任一成立即不可缓存) | 理由 |
 | --- | --- |
 | `stream_end == "salvaged"` | 截断结果,修现存毒化 |
 | 无正文产物 | 不把空回答固化进 TTL |
 | finish 类别为 truncated/filtered/unknown | 截断有随机性,同 key 换时可成功;未知值不可证明是自然结束 |
 | openai 模式 completion 原文 content 为空且无工具(沿 1.3.9) | 不信任旧投影 |
 | 路径 | 规则 |
 | --- | --- |
 | 写 | 不可缓存 → 跳过,debug 日志 |
 | 读 | `_is_cacheable` 在命中覆盖(`cache.py:224` `fields.update`)**之前**、对存储原值判定;不可缓存 → miss + warning |
 | 读: 非法 `stream_end` | 不在 Literal 域内 → miss + warning(关乎内容完整性,故与 `_coerce_observation` 的宽容方向相反) |
 | 读: 顶层无 finish_reason | 回退 `completion.finish_reason`(1.3.9 保真 length 条目因此可识别);文本旧条目两字段缺省 → None → 仍可命中 |
 | 命中返回 | `stream_end=None`;`finish_reason` 取判定所用值(顶层缺省时为回退值),非字符串视 miss |
 | 序列化 | `_RESPONSE_FIELDS` 由 `dataclasses.fields` 自动派生,无需改动 |
 旧 salvage/length 文本污染无法辨认: CHANGELOG 继续要求受影响集合迁移 namespace/salt。
 ## 7. 遥测落点
 | 位置 | 变更 |
 | --- | --- |
 | `middleware/telemetry.py` `_AttemptUsage.of(response)` | 读 `response.stream_end`(本次 LLMResponse 有字段,不像 1.3.8 走 `emit_attempt` kw,避免约 50 处调用点) |
 | `_record` | 新增参数,单一 helper 下沉 recorder |
 | `emit_cache_hit` / `emit_terminal_failure` / 失败与取消 attempt 行 | 显式 None |
 | `telemetry/schema.py` | SQLite/PG 两份 CREATE 末尾、`SQLITE_BACKFILL`、`_PG_BACKFILL_DECLS`(列序对齐)、`COLUMNS`;`telemetry_schema_sql()` 随之输出 |
 | sqlite/postgres recorder | 按 `COLUMNS` 写入;auto 档幂等补列、manual 档裁剪写入并点名缺列(沿 1.3.8) |
 | tests | 约 20 处测试替身 `record_llm_call` 补参数 |
 | 文档 | README "必录字段数"按 `inspect.signature` 实测更新;`schemas/llm-calls.md` 加列并修正陈旧计数 |
 ## 8. 旧行为审计
 | 既有行为 | 处置 |
 | --- | --- |
 | 保真缺 DONE 一律失败 | **替换**: §4.2 判完整时成功;其余仍失败、仍不打捞 |
 | 文本 `missing_done=retry` 遇缺 DONE 即抛 | **替换**: 同上;`missing_done` 只管真截断 |
 | 文本 salvage + estimated | 保留,另标 `salvaged`,不再写缓存 |
 | 零增量 + DONE → Transient | **保留**(`test_stream_zero_content_with_done_is_transient` 红线回归) |
 | 保真 reasoning-only/空产物失败 | **替换**: §4.3 行 3/6/7/8 |
 | 未知 delta/工具/function 字段拒绝;null 已知字段拒绝 | **替换**: §5 |
 | 非流式 `tool_calls: null` 拒绝 | **替换**: 合法 |
 | 多 choice/index≠0 拒绝、最终 role 必须 assistant、error 帧立即失败 | 保留 |
 | 工具快照强校验 | 保留;仅 length 截断时改归 ResultInvalid |
 | finish_reason 冲突拒绝(Transient) | 保留(登记: 确定性方言,将来可改 ResultInvalid) |
 | 已知字段活性口径 | 保留;未知字段按 §5.3 增补 |
 | 缓存写路径无判定 | **替换**: 按 `_is_cacheable` |
 | 文本 n>1 混流 | 不在范围,另开 issue |
 ## 9. 非功能维度
 | 维度 | 回答 |
 | --- | --- |
 | 并发与取消 | 新状态在每尝试聚合器/sink 内;判定为纯函数,不新增 try/except,`CancelledError` 原路穿透;finally 结算与 permit 释放不变 |
 | 降级方向 | 缓存跳写/视 miss 只 debug/warning;遥测新列缺失按 manual 档裁剪 + 告警,不冒泡;限流/熔断不涉及 |
 | 幂等与重复 | 减少重复付费重抽;标签键与身份字段幂等;告警节流有界 |
 | 持久化与原子性 | 仅新增一可空列,补列沿既有探测后 ALTER 幂等流程;缓存仍成功后单次原子 set |
 | 错误分类 | 仅落 Transient 与 ResultInvalid 两类,不新增类;原因码见 §4.3 |
 | 可观测 | `stream_end` 字段 + 遥测列;冲突路径与未知 finish 有界告警;遵 structured-logging 更新 `schemas/llm-calls.md` |
 ## 10. 测试、文档与交付
 全部用假 SSE / MockTransport 复现,每条先红后绿;真实中转冒烟标 slow 按发布清单 diff 交集跑。
 | 组 | 用例 |
 | --- | --- |
 | #31 验收 | 1 stop+usage+EOF 成功、`eof_after_finish`、measured、attempts=1;2 tool_calls 同上工具完整;3 无 finish 即关 → 失败;4 finish 无 usage → 失败;5 中途 `RemoteProtocolError` → 失败;6 带 DONE → `done` 不变 |
 | #31 补充 | usage 早于 finish(累计 usage)+EOF → 不完整;finish 后 usage 为 `{}` → 不完整;`network_error`+usage+EOF → Transient;文本模式 1/3/4(`retry`、`salvage` 两档) |
 | #30 验收 | reasoning-only+length → 交付、content 空、思考完整、attempts=1;流式 `refusal:null`+`tool_calls:null` 成功;非流式 message 带 `tool_calls:null`+`refusal:null` 成功 |
 | 结局表 | §4.3 每行至少一例,两模式、流式与非流式;文本 length → ResultInvalid 且熔断未计失败;零增量+DONE(带 stop/不带 finish)仍 Transient;content 非空 + 坏工具 + stop → Transient |
 | 合并/活性 | 只有 `reasoning` 刷新活性不超时;二次构造 OpenRouter `reasoning_details` 往返(`format`/`id` 不拼接);工具层嵌套对象原样保留可回传;数值冲突删键、告警一次、调用成功;节流饱和;`role:null`/`arguments:null` 视缺省 |
 | 缓存 | 四类不可缓存均不写、注入后读视 miss;非法 `stream_end` 视 miss;1.3.9 旧文本条目仍命中;1.3.9 保真 length 条目经回退识别为不可缓存;命中 `stream_end=None` |
 | 遥测 | sqlite/pg(integration)新列写入、旧库补列、manual 档裁剪;形状闸拒绝缺参 recorder |
 | 改写 | `test_openai_never_salvages`;`test_invalid_delta_is_domain_error` 中 `{"audio": {}}`、`{"index":0,"extra":1}`、null 已知字段参数;提交说明列出 |
 同步: 源码 docstring、README(能力表、`1.3.*` 安装约束核对、活性口径、字段数)、CHANGELOG 1.3.10(行为变更段、破坏性段: recorder 端口、namespace/salt 提醒、半截工具参数提醒、冲突删键提醒)、ARCHITECTURE §6.2/§7/§14、1.3.9 设计加修订指针、`schemas/llm-calls.md`、`research-wiki/migrations/` 三份核对下游对 ResultInvalid 的 catch 点、`docs-convention.md` §2 清单。另开 issue: 文本 n>1 混流;文本"有产物无正文 + stop"证据收集。发布按 CLAUDE.md §4.4.1 九步,#30/#31 在 registry 可安装且验收证据齐备后关闭。
 证据: `retry.py:404-450,548-560`;`cache.py:197-236`;`structured.py:79`;[openai-python `_streaming.py`](https://github.com/openai/openai-python/blob/main/src/openai/_streaming.py) 与 `lib/streaming/_deltas.py`;[vLLM reasoning outputs](https://docs.vllm.ai/en/latest/features/reasoning_outputs/);GLM finish 枚举来自第三方镜像,实现前以真实中转探针再核;Gemini `extra_content` 路径未核实原文,测试按通用嵌套对象构造。
 ## 11. 审查修订记录
 | 轮次 | 意见 | 处置 |
 | --- | --- | --- |
 | R1 | B1 `tool_calls:null` 被快照拒(非流式现存) | 采纳: §3/§5.1/§10 |
 | R1 | B2 结局表行重叠 | 采纳: 首匹配行序 + `_tool_snapshot_ok` 前置 |
 | R1 | B3 文本"任何产物"不可计算 | 采纳: §4.3 分模式定义 |
 | R1 | S1 eof_after_finish 但 usage 非 measured | 采纳: 条件加 measured |
 | R1 | S2/S3 活性冲突与标签拼接 | 采纳: §5.2/§5.3 |
 | R1 | S4 告警集合无界 | 采纳: §5.4 |
 | R1 | S5 无产物 + length 与 #30 原文冲突 | 采纳(人类授权代决): 保真交付、文本 ResultInvalid、stop/absent 仍 Transient |
 | R1 | S6-S9 缓存顺序、遥测落点、原因码、null 优先 | 采纳: §6/§7/§4.3/§5.1 |
 | R1 | 建议 1-7 | 采纳 1/2/3/5/6/7;建议 4 不标不可缓存(上游确定性,非毒化) |
 | R2 | 结论通过;N1 measured 以最后 usage 判定、N2 非空 reasoning_content | 采纳: §4.2/§4.4 |
 | R2 | 建议 1-4: 命中回退值、未知 finish 告警文案、数组字符串活性与残余风险、null 五层与数组 null 元素 | 全部采纳: §6/§4.1/§5.3/§5.1 |
 | 代码审查 | I1 保真可缓存须同时要求投影正文非空(think 标签剥净后为空不缓存) | 采纳: `_is_cacheable` |
 | 代码审查 | I2 无参函数 `arguments` 全程 null → 快照不成立被判 Transient 重试 | 人类授权代决: 归 ResultInvalid `tool_arguments_null`(确定性方言);不改写交付值(改写破坏保真,重试救不回) |
 | 代码审查 | I3 文本 `index:null` 整帧丢弃、`index:False` 冒充 0 | 采纳: null 视 0,bool 拒 |
 | 代码审查 | Minor: `[null]` 产出空 `tool_calls`、非流式缺 role 先于判定、告警路径长度有界、README 表述 | 采纳;index 数组缺 index 整键删除登记于 CHANGELOG 提醒 |
@@ -0,0 +1,18 @@
 # #29 分发来源前置核查
 日期：2026-10-01；基线 0e29dea；在 T1 前执行。本记录不是法律认证。
 | 范围 | 实际核查与结论 |
 |---|---|
 | 跟踪源码 | `git ls-files src` 列出 polygateway Python 模块与 py.typed，无 vendor 子树、外部 LICENSE/NOTICE、打包外部代码目录 |
 | 内部移植 | rg 检索移植/参考/Copyright/SPDX/copied/adapted：streaming、sources、Redis Lua、ports、openai_compat 的来源为三个内部项目；用户已明确均本人原创并授权 Apache-2.0 |
 | 外部参考声明 | 阅读 types.py Effort、providers.py ThinkingWire/注册表、thinking.py 能力证据段；使用的是协议词汇/参数形态/实测结论，未发现来自外部仓的成段实现或第三方版权头；不把相同协议字符串认定为复制实现 |
 | 打包边界 | pyproject 仅从 src 发现包，reference 不跟踪、不纳入分发；本次不复制外部参考实现 |
 | 许可来源 | 系统 `/usr/share/common-licenses/Apache-2.0` 提供标准许可正文；构建时核对包内文本与元数据 |
 未发现需额外通知的实际复制片段，因此不编造 NOTICE。外部参考仓含 AGPL 不等于本库受其许可约束；用户对原创代码的授权也不能覆盖第三方。实施/审查若发现新的实际复制证据，停止并提交主管处理，不用本文替代核查。
 ## 审查意见处置
 P1 采纳：协议快照缺 role 不可直接进入下一轮，SSE/非流式/缓存统一要求 assistant；不补造 role，默认 text 不变。
 P2 采纳：将本次来源核查前移到 T0，T6 仅复核及落实 LICENSE/打包/文档。两项均是已批准方向的正确性修订，无需新增用户授权。
@@ -225,6 +225,31 @@
      "id": "finding:2026-09-09-134-thinking-contracts-validation",
      "label": "1.3.4 T0–T4 与 T7 确定性验证",
      "type": "finding"
    },
    {
      "id": "design:2026-10-01-issue29-openai-fidelity-design",
      "label": "OpenAI消息保真设计",
      "type": "design"
    },
    {
      "id": "plan:2026-10-01-issue29-openai-fidelity",
      "label": "OpenAI消息保真实现计划",
      "type": "plan"
    },
    {
      "id": "review:2026-10-01-issue29-cache-review",
      "label": "保真缓存审查修复与1.4.0准备",
      "type": "review"
    },
    {
      "id": "plan:2026-09-10-24-hedged-requests",
      "label": "issue #24 长尾对冲请求与裸生成时间实施计划",
      "type": "plan"
    },
    {
      "id": "design:2026-09-10-24-hedged-requests-design",
      "label": "长尾对冲请求(issue #24)设计",
      "type": "design"
    }
  ],
  "links": [
@@ -472,6 +497,34 @@
      "relation": "implements",
      "evidence": "1.3.5 逻辑调用统计与结构化失败诊断实施计划落地已批准设计",
      "added": "2026-09-09T13:42:00.298915+00:00"
    },
    {
      "source": "plan:2026-10-01-issue29-openai-fidelity",
      "target": "design:2026-10-01-issue29-openai-fidelity-design",
      "relation": "implements",
      "evidence": "已批准方向与独立审查P1/P2修订",
      "added": "2026-10-01T17:52:42.425248+00:00"
    },
    {
      "source": "schema:llm-calls",
      "target": "design:2026-10-01-issue29-openai-fidelity-design",
      "relation": "implements",
      "evidence": "复用既有单出口与schema，无新增列；工具error为attempt失败",
      "added": "2026-10-01T17:52:43.831331+00:00"
    },
    {
      "source": "review:2026-10-01-issue29-cache-review",
      "target": "design:2026-10-01-issue29-openai-fidelity-design",
      "relation": "informs",
      "evidence": "统一缓存与transport的有效产物判据，保持内核依赖边界",
      "added": "2026-10-01T18:27:16.434742+00:00"
    },
    {
      "source": "plan:2026-09-10-24-hedged-requests",
      "target": "design:2026-09-10-24-hedged-requests-design",
      "relation": "implements",
      "evidence": "计划头部与设计 §9 批准状态(2026-09-10 H1-H8 全数获批)",
      "added": "2026-09-10T16:48:37.849653+00:00"
    }
  ]
 }
@@ -1,8 +1,8 @@
 # Research Wiki 索引
-> 自动生成，更新时间：2026-09-09 18:01 UTC
+> 自动生成，更新时间：2026-10-02 02:23 UTC
-## design (43)
+## design (47)
 - [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`
@@ -25,6 +25,9 @@
 - [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`
 - [2026-09-09-136-call-budgets-design](designs/2026-09-09-136-call-budgets-design.md) `design:2026-09-09-136-call-budgets-design`
 - [2026-09-10-24-hedged-requests-design](designs/2026-09-10-24-hedged-requests-design.md) `design:2026-09-10-24-hedged-requests-design`
 - [2026-09-11-streaming-stall-design](designs/2026-09-11-streaming-stall-design.md) `design:2026-09-11-streaming-stall-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`
@@ -38,6 +41,7 @@
 - [M2.5 治理韧性: 半死源隔离与健康感知调度](designs/m25-resilience.md) `design:m25-resilience`
 - [M3 OCR 端口族设计](designs/m3-ocr.md) `design:m3-ocr`
 - [M4 迁移验证设计(GovDoc→CHS,发 v1.0)](designs/m4-migration.md) `design:m4-migration`
 - [OpenAI消息保真设计](designs/2026-10-01-issue29-openai-fidelity-design.md) `design:2026-10-01-issue29-openai-fidelity-design`
 - [stall 判定改为非生产性等待口径](designs/issue8-stall-budget.md) `design:issue8-stall-budget`
 - [响应可观测字段扩展(Issue #3)](designs/response-observability-fields.md) `design:response-observability-fields`
 - [建表前先探测,判死只认「确定写不进去」](designs/issue9-telemetry-ddl-probe.md) `design:issue9-telemetry-ddl-probe`
@@ -48,18 +52,23 @@
 - [调用方自定义维度设计(issue #11)](designs/issue11-caller-dimensions.md) `design:issue11-caller-dimensions`
 - [采样参数透传设计(issue #4)](designs/sampling-params.md) `design:sampling-params`
-## finding (17)
+## finding (22)
 - [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`
 - [1.3.5 发布完成与外部验收：合并后门、registry 产物与页面亲查](findings/2026-09-09-135-release-completion.md) `finding:2026-09-09-135-release-completion`
 - [1.3.6 可选调用期限与取消结算验证记录](findings/2026-09-10-136-call-deadline-validation.md) `finding:2026-09-10-136-call-deadline-validation`
 - [1.3.8 流式中段沉默:净口径与中段对冲验证报告](findings/2026-09-11-streaming-stall-validation.md) `finding:2026-09-11-streaming-stall-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`
 - [2026-09-11-streaming-stall-hedging-research](findings/2026-09-11-streaming-stall-hedging-research.md) `finding:2026-09-11-streaming-stall-hedging-research`
 - [2026-10-01-issue29-license-audit](findings/2026-10-01-issue29-license-audit.md) `finding:2026-10-01-issue29-license-audit`
 - [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`
 - [issue #24 长尾对冲请求与裸生成时间验证报告](findings/2026-09-10-24-hedged-requests-validation.md) `finding:2026-09-10-24-hedged-requests-validation`
 - [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`
@@ -68,10 +77,12 @@
 - [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 (38)
+## plan (42)
 - [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`
 - [1.3.6 可选调用期限与取消结算修复实施计划](plans/2026-09-10-136-call-deadline.md) `plan:2026-09-10-136-call-deadline`
 - [1.3.8 流式中段沉默:计量口径与对冲实施计划](plans/2026-09-11-streaming-stall.md) `plan:2026-09-11-streaming-stall`
 - [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`
@@ -90,12 +101,14 @@
 - [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 #24 长尾对冲请求与裸生成时间实施计划](plans/2026-09-10-24-hedged-requests.md) `plan:2026-09-10-24-hedged-requests`
 - [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`
 - [M2.5 治理韧性实现计划](plans/m25-resilience.md) `plan:m25-resilience`
 - [M3 OCR 实现计划](plans/m3-ocr.md) `plan:m3-ocr`
 - [M4 迁移实现计划(T0-T14)](plans/m4-migration.md) `plan:m4-migration`
 - [OpenAI消息保真实现计划](plans/2026-10-01-issue29-openai-fidelity.md) `plan:2026-10-01-issue29-openai-fidelity`
 - [plan-issue14-admission-wait-policy](plans/plan-issue14-admission-wait-policy.md) `plan:plan-issue14-admission-wait-policy`
 - [响应可观测字段扩展实现计划](plans/response-observability-fields.md) `plan:response-observability-fields`
 - [实现计划: HTTP 错误响应体留存(Issue #10)](plans/issue10-error-body-retention-plan.md) `plan:issue10-error-body-retention-plan`
@@ -109,8 +122,13 @@
 - [调用方自定义维度实现计划(issue #11)](plans/issue11-caller-dimensions.md) `plan:issue11-caller-dimensions`
 - [采样参数透传实现计划(issue #4)](plans/sampling-params-plan.md) `plan:sampling-params-plan`
-## review (1)
+## review (6)
 - [2026-09-11-138-branch-review](reviews/2026-09-11-138-branch-review.md) `review:2026-09-11-138-branch-review`
 - [2026-09-11-138-verifier](reviews/2026-09-11-138-verifier.md) `review:2026-09-11-138-verifier`
 - [2026-09-11-streaming-stall-design-review](reviews/2026-09-11-streaming-stall-design-review.md) `review:2026-09-11-streaming-stall-design-review`
 - [2026-09-11-streaming-stall-plan-review](reviews/2026-09-11-streaming-stall-plan-review.md) `review:2026-09-11-streaming-stall-plan-review`
 - [保真缓存审查修复与1.4.0准备](reviews/2026-10-01-issue29-cache-review.md) `review:2026-10-01-issue29-cache-review`
 - [整分支审查: issue #14 熔断等待档](reviews/issue14-branch-review.md) `review:issue14-branch-review`
 ## schema (1)
@@ -160,3 +160,14 @@
 - [2026-09-09 13:42 UTC] 重建索引: 100 篇页面
 - [2026-09-09 16:49 UTC] 重建索引: 101 篇页面
 - [2026-09-09 18:01 UTC] 重建索引: 102 篇页面
 - [2026-09-10 16:48 UTC] 新增边: plan:2026-09-10-24-hedged-requests --implements--> design:2026-09-10-24-hedged-requests-design
 - [2026-09-10 16:48 UTC] 重建索引: 107 篇页面
 - [2026-10-01 17:52 UTC] 新增 design: OpenAI消息保真设计 (design:2026-10-01-issue29-openai-fidelity-design)
 - [2026-10-01 17:52 UTC] 新增 plan: OpenAI消息保真实现计划 (plan:2026-10-01-issue29-openai-fidelity)
 - [2026-10-01 17:52 UTC] 新增边: plan:2026-10-01-issue29-openai-fidelity --implements--> design:2026-10-01-issue29-openai-fidelity-design
 - [2026-10-01 17:52 UTC] 新增边: schema:llm-calls --implements--> design:2026-10-01-issue29-openai-fidelity-design
 - [2026-10-01 17:52 UTC] 重建索引: 119 篇页面
 - [2026-10-01 18:24 UTC] 新增 review: 保真缓存审查修复与1.4.0准备 (review:2026-10-01-issue29-cache-review)
 - [2026-10-01 18:27 UTC] 新增边: review:2026-10-01-issue29-cache-review --informs--> design:2026-10-01-issue29-openai-fidelity-design
 - [2026-10-01 18:27 UTC] 重建索引: 120 篇页面
 - [2026-10-02 02:23 UTC] 重建索引: 120 篇页面
@@ -31,3 +31,9 @@ date: 2026-07-20
 | 存储兼容 | 真实 PG 沙箱: auto 追加十列、manual 裁剪写入、旧行新列恒 NULL、新旧进程混写共存 | 2026-09-09 实跑 30 passed(见下方证据索引) |
 本版**新增十列**(见 schema:llm-calls),不新建表、不新增依赖。证据索引见 `findings/2026-09-09-135-call-observability-validation.md`;覆盖度真实基线仍待首次生产运行填入,不写伪百分比。
 ## #29 验收增量（2026-10-01）
 复用指标及 llm_calls，不另建表：error→正常 attempts=2、tool-only attempts=1、
 cache_hit attempts=0；协议失败不写缓存，取消不得遗留 permit/task。
 确定性证据位于 `tests/unit/test_openai_fidelity.py`；完整协议不新增遥测正文列。
@@ -202,3 +202,7 @@ stack = ExtractionProviderStack(
 | **AIMD 自适应并发**(库常量: 每源初始 8、429 削减 ×0.5、成功 +1/limit、下限 1、ceiling=max(64, 源级 max_concurrency)) | 冷启动每源并发从"无上限"变为 8 起步爬升——高吞吐下游首分钟吞吐低于旧行为;无 env 开关(韧性常量,同 jitter 系数先例),需要禁用者构造函数注入自定义 pacer |
 | 连败通道受健康证据抑制(窗口样本 ≥ min_calls 且失败率 < fail_rate 时 5 连败不开路) | CHS "连败必开"在高流量健康源上不再成立(防随机噪声误熔唯一好源);冷启动/低流量语义不变 |
 | 结构化重问缺省 1→2 | 解析失败时最多多一跳成本;`PGW_STRUCTURED_MAX_RETRIES=1` 可显式还原 |
 ## 1.3.10 影响核对(2026-10-14,#30/#31)
 CHS 已把 `ResultInvalidError` 作终态(坏结果≠坏服务,熔断记成功),1.3.10 文本 length/过滤且无正文落该分类与既有语义同向,worker `_TERMINAL` 分支无需改;缺 `[DONE]` 而完整的流从此直接成功。
@@ -170,3 +170,7 @@ loop = AgentLoop(client, max_steps=...,
 | R7 | 内存限流在多进程(arq)下的口径须在文档/配置中显式警示(B7 过渡期语义),避免误配全局限额 | M1 |
 以上 G1/G2 若按本文方向解决,GovDoc 全量迁移中业务代码(agent/workflow/govdoc api)对治理层的消费**零改动**,改动收敛于: 装配净新增、types.py/protocols.py/test_imports.py 三处改写、`.env` 改键。
 ## 1.3.10 影响核对(2026-10-14,#30/#31)
 装配处 `retryable_exceptions=(TransientError, AllSourcesExhausted)`(§4)**不含** `ResultInvalidError`:文本 length/过滤且无正文改抛它后,AgentLoop 步级重试**不再**重抽该步——这正是本次修复的意图(确定性结局重抽只花钱)。业务侧若想对 length 截断做"加大 max_tokens 再试",须显式 except `ResultInvalidError` 并按异常消息原因码 `length_without_content` 分支;其余缺 `[DONE]` 而完整的流(#31)从此直接成功。
@@ -200,3 +200,7 @@ ocr = FrameOcrAdapter(OcrTextPort_from_env()) # 业务适配器包装库 OCR 端
 ---
 *不确定项声明*: 库侧 `from_env(role=...)`、OCR 装配工厂的具体 API 名称以 M1/M3 设计文档定稿为准，本文 §5.2/§6 中相应伪代码届时同步修订；`telemetry.db` 是否存在项目外的离线分析脚本消费方未能实测（项目内 grep 无读取方）。
 ## 1.3.10 影响核对(2026-10-14,#30/#31)
 AgentLoop 注入的 `(TransientError, AllSourcesExhausted)`(§4 点 3)**不含** `ResultInvalidError`:文本 length/过滤且无正文改抛它后,步级重试不再重抽该步(意图如此)。需要"加大 max_tokens 再试"的业务须显式 except 并按原因码 `length_without_content` 分支。§保留项 3"缺 `[DONE]` 判瞬时、不写缓存"在 1.3.10 收窄为"无 finish 或 finish 后无实测 usage 才算截断";finish+实测 usage+干净 EOF 视完整。
@@ -0,0 +1,345 @@
 ---
 type: plan
 node_id: plan:2026-10-01-issue29-openai-fidelity
 title: OpenAI消息保真实现计划
 date: 2026-10-01
 ---
 # #29 OpenAI 消息保真实现计划
 > 状态：计划及首轮代码独审已完成，P1/P2 均采纳；缓存空产物和测试双向依赖已修复，发布目标按人类最终指定改为 1.3.9（取代未发布的 1.4.0），最终独审与 T8 外部发布仍由父会话执行。
 > 设计：[批准方向的设计落实稿](../designs/2026-10-01-issue29-openai-fidelity-design.md)。
 > 目标：同一 chat 治理链返回可供下游继续工具对话的完整单 choice 协议结果，拒绝截断和 error 帧伪成功。
 > 方案：增加 response_mode 与嵌套 completion；协议解析与聚合内聚在 transport 内部模块，治理层仅传模式/搬结果；旧文本默认保持兼容。
 > 技术：Python 3.12+、frozen dataclass、httpx SSE、现有 asyncio 看门狗/对冲、pytest、真实 Redis；不加运行时依赖。
 ## 0. 工作区、审批与执行纪律
 | 项目 | 已核验值 |
 | --- | --- |
 | 工作目录 | `/home/iomgaa/.config/superpowers/worktrees/PolyGateway/issue29-openai-fidelity` |
 | 分支 | `feat/issue29-openai-fidelity` |
 | 基线 | `0e29deac1a72bfee348ed2f8061ea2c33be217e8` / 1.3.8 |
 | 原工作区 | `/home/iomgaa/Projects/PolyGateway`，main 上已有未提交文档与 .pi，不得覆盖或夹带提交 |
 | 基线命令 | `conda run -n PolyGateway pytest tests/unit -q` |
 | 基线结果 | 1627 passed in 12.25s；仅单元基线，不代表集成/slow/新增功能通过 |
 所有 Python 命令用 PolyGateway conda 环境；始终从上述隔离目录执行，确认 pytest 配置 pythonpath=src，避免误测主工作区 editable 安装。不要复制主树 `.env` 到受跟踪路径；需要真实验证时显式读取已有配置，不输出秘密。reference/ 不存在于新 worktree 的跟踪树，不为规划复制/修改参考仓。
 技术方向、内部原创权属和 Apache-2.0 已获用户明确批准；细化设计与计划由独立 subagent 审查，Codex 不再调用。只在新产品/权利边界未获授权时暂停。父会话掌握审查、后续编码、合并/发布权限；当前任务不执行这些步骤。
 本计划不涉及参考实现迁移，保真校验不适用；涉及既有移植流式看门狗的消费面，必须对照本库 `streaming.py`、1.3.8 stall 设计逐段保持其超时/取消/换算语义，不能借工具支持改算法。
 ## 1. 文件结构与职责锁定
 | 路径（相对工作目录） | 动作与职责 |
 | --- | --- |
 | `src/polygateway/types.py` | 新 ResponseMode/OpenAIChatCompletion；末尾追加 ChatRequest.response_mode、两个响应 completion |
 | `src/polygateway/__init__.py` | 导出新公共类型；最终发布时同步版本 |
 | `src/polygateway/ports.py` | complete 增必填模式参数；说明工具进展与单 choice 契约 |
 | `src/polygateway/client.py` | chat 新模式校验、消息/overlay 快照、组合拒绝；不重写治理入口 |
 | `src/polygateway/transports/_openai_completion.py`（新） | 协议结构校验、每尝试聚合、非流式快照；无 I/O/计时 |
 | `src/polygateway/transports/openai_compat.py` | error 检查、解析器接线、投影/usage/空补全/DONE、统一进展事件 |
 | `src/polygateway/middleware/retry.py` | 模式传入、completion 搬运；无重试/对冲算法改写 |
 | `src/polygateway/middleware/cache.py` | 模式 key、嵌套序列化/重建、缺协议 miss、序列化降级 |
 | `tests/unit/test_openai_completion.py`（新） | 纯协议聚合与非流式校验的源命名测试 |
 | `tests/unit/test_openai_compat.py` | 真实 transport 的 SSE/非流式/error/raw/DONE/活性测试 |
 | `tests/unit/test_types.py`, `test_client.py`, `test_ports.py`, `test_cache.py` | 公共类型、校验、端口、缓存往返与兼容 |
 | `tests/unit/test_retry.py`, `test_hedge.py`, `test_stall_hedge.py`, `test_deadline.py`, `test_backpressure.py` | 模式传递、错误重试、工具活性/对冲、取消与结算 |
 | `tests/integration/test_governance_stack.py`, `test_redis_cache.py`, `test_redis_cross_connection.py` | 完整链路、真实缓存往返、必要 fake 签名适配 |
 | `tests/e2e/conftest.py` | 现有取证 transport 包装显式转传模式，不改变 thinking 矩阵判据 |
 | `tests/e2e/test_openai_tools_live.py`（新） | 受控少量真实工具双轮冒烟，独立 slow 用例 |
 | `tests/unit/test_package.py` | LICENSE 文件/包元数据回归 |
 | `LICENSE`, `pyproject.toml` | 标准 Apache-2.0 与打包元数据；不捆绑 reference/ |
 | `README.md`, `CHANGELOG.md`, `.env.example`, `research-wiki/ARCHITECTURE.md` | 新模式、限制、raw 配置、缓存迁移、同步桥接说明 |
 | `research-wiki/findings/2026-10-01-issue29-license-audit.md`（新） | 分发源码第三方来源核查证据与范围 |
 | `research-wiki/graph/edges.json`, `index.md`, `log.md`, `schemas/llm-calls.md`, `metrics/call-telemetry-coverage.md` | 审查通过后的设计/计划/复用遥测关系注册，不新增表或指标实体 |
 其余测试若显式调用 complete 必须补参数，仅机械适配；不重构不相关 fixture。`thinking.py`/能力表/streaming.py 算法不在预期改动内。不要为“兼容 SDK”创建不存在的 openai_sdk.py。
 ## 2. 跨任务接口
 T1 定义公共字段，T2–T5 均消费同一类型名，禁止再起 tool_response/raw_response 别名。
 ```python
 ResponseMode = Literal["text", "openai"]
@dataclass(frozen=True)
 class OpenAIChatCompletion:
    """单 choice 协议结果，message/usage 是独立 JSON 快照。"""
    message: dict[str, Any]
    finish_reason: str | None
    response_id: str | None
    usage: dict[str, Any] | None
 ```
 公共与端口变化均是追加参数/字段：
 ```python
 # GatewayClient.chat 的末尾 keyword-only 参数；其余参数保持原样。
 response_mode: ResponseMode = "text"
 # ChatRequest 末尾字段。
 response_mode: ResponseMode = "text"
 # Transport.complete 末尾必填 keyword-only 参数。
 response_mode: ResponseMode
 # TransportResult / LLMResponse 末尾字段。
 completion: OpenAIChatCompletion | None = None
 ```
 `build_cache_key` 在已有 keyword-only 参数之后增加 `response_mode: ResponseMode = "text"`，仅非 text 时参与摘要。缓存重建只依赖内核类型/本层校验，不 import transports；若复用协议类型重建的最低形态检查，把纯 JSON 快照检查放类型自身的具名构造方法，不把 transport 的 SSE 状态机下沉到内核。
 T2 内部模块只由同目录 transport 消费，不成为公共导出。采用以下窄接口（内部类型在该模块定义）：
 ```python
@dataclass(frozen=True)
 class ChatDelta:
    """一帧提取结果；progress 表示真实生成进展。"""
    content: str
    reasoning_content: str
    progress: bool
 ```
 ```python
 class ChatCompletionAccumulator:
    """每次 transport 尝试独享的单 choice 聚合状态。"""
    def __init__(self, *, response_mode: ResponseMode) -> None: ...
    def add_chunk(self, chunk: dict[str, Any]) -> ChatDelta: ...
    def finish(self) -> OpenAIChatCompletion: ...
 def parse_chat_completion(body: dict[str, Any]) -> OpenAIChatCompletion: ...
 ```
 上述 `...` 是签名约定而非待交付占位实现。聚合器抛含判据的 TransientError（operation=chat）；openai_compat 负责补选中源上下文、复用有界摘要。聚合器不判断 DONE、不读时钟；transport 掌握线路完整性。text 模式可共用帧提取与进展识别，但不调用严格 openai finish，保持旧文本工具容忍边界。
 ## 3. 分任务与独立验收
 ### T0 — 审查与来源前置核查
 - [x] T1 前已核查分发来源，见 findings/2026-10-01-issue29-license-audit.md；发现不兼容复制即停止。
 - [ ] 父会话安排全新上下文原生 subagent 审查设计/计划，重点：单 choice、未知增量字段、身份重复/冲突、raw/managed、缓存错误降级及取消。
 - [ ] 核对每条意见，修订文档并记录接受/不接受的理由；如改变用户已批边界，走主管决定，不静默改契约。
 - [ ] 在隔离树注册文档关系，复用 llm-calls schema/call-telemetry-coverage 指标；不在主树运行生成器。
 - [ ] 文档审查通过后才调用 commit skill 提交设计/计划；当前阶段禁止提交。
 验证命令：`wc -l research-wiki/designs/2026-10-01-issue29-openai-fidelity-design.md research-wiki/plans/2026-10-01-issue29-openai-fidelity.md` → 分别 ≤400、≤1000；`git diff --check` → 无错误。Wiki 命令经 `conda run -n PolyGateway python .claude/tools/research_wiki.py --help` 核对实际参数后执行 add_entity/add_edge/rebuild_index；检查生成 diff 不改原有条目正文。
 ### T1 — 公共契约贯穿完整治理链
 文件：types.py、__init__.py、ports.py、client.py、middleware/retry.py；单元 types/client/ports/retry；所有显式 fake complete 签名。
 先补测试：默认 text 不变、新类型可导入、末尾带默认字段不破旧构造；非法 response_mode、openai+structured、n=2/0/True 在适用边界拒绝；保真消息与嵌套 overlay 脱离调用方容器，返回上一轮 assistant 和 role=tool 请求 JSON 逐字段相同。
 实现：chat 校验放在 context/handler 前；选源后非法 source.extra_body.n 在 transport HTTP 前 RequestRejected；模式作为必填端口参数穿透重试/对冲，_build_response 原样搬 completion。不把模式塞进发给上游的 payload。
 验收：调用级拒绝不发 HTTP；源级拒绝结算/释放正常；自定义 transport fake 看见准确模式；既有旧构造回归全绿。命令：
 ```bash
 conda run -n PolyGateway pytest tests/unit/test_types.py tests/unit/test_client.py tests/unit/test_ports.py tests/unit/test_retry.py -q
 ```
 先红测试须为行为断言或缺失 API 的明确证据，记录基线 SHA 与测试名；绿后提交点：`feat: add explicit OpenAI response contract`。
 ### T2 — 内聚协议解析器与 error 帧修复
 文件：新增 _openai_completion.py、openai_compat.py；新增 test_openai_completion.py，扩展 test_openai_compat.py。
 补测 SSE/非流式/缓存缺 role、非 assistant role；合法 role-only 起始帧后工具成功。先红测试至少含下表各组；复用现有 SSE/MockTransport，不引入第二套 HTTP fake 框架。
 | 组 | 输入与精确预期 |
 | --- | --- |
 | 并行工具 | 2 工具交错 index；同帧两工具；name/arguments 分片；空白/Unicode/引号逐字相等；最终按 index 排序 |
 | 身份 | id/type 同值重复只保留一次，冲突失败；缺 id/type/name/arguments、重复 id、bool/负数 index、非 function 类型失败 |
 | 文本 | 同帧正文+推理均保留；缺省/null/空串区别；原消息 think 标签不剥，旧投影仍剥 |
 | envelope | 顶层数组/null、choices/delta/tool_calls 非容器、坏字段类型、多 choice/非零 choice index 均受控失败 |
 | 非流式 | 完整消息、扩展字段、usage/finish/id 全保留；工具参数不做业务 JSON 修复；原响应对象改动不影响快照 |
 | error | 首帧 error、正文后 error+usage+DONE、error=null、error={}、salvage 配置下 error 都立即失败；text/openai 两模式参数化 |
 复用现有 summarize_body/compose_message，断言异常与遥测诊断有界，不打印工具参数正文。默认文本模式不因无用工具字段的严格 finish 校验而新增失败，但不吞顶层 error。无新 HTTP 状态映射。
 命令：`conda run -n PolyGateway pytest tests/unit/test_openai_completion.py tests/unit/test_openai_compat.py tests/unit/test_http_error_body.py -q` → PASS；提交点：`fix: preserve chat deltas and reject upstream error frames`。
 ### T3 — 完成语义、活性与非流式接线
 文件：openai_compat.py、ports.py docstring；test_openai_compat.py、test_streaming.py。
 先红：tool-only + DONE 成功 attempts=1；空文本且空工具失败；正文+坏工具不成功；openai 缺 DONE 即使 missing_done=salvage 仍失败；text salvage 保持；finish_reason=length 原样交回，不解析 arguments。非流式工具同样成功，两事件永不置位、ttft/stall=None。
 按设计接线：一帧一进展，同帧多个字段只记一个 chunk_time；真正非空工具增量/首次身份触发事件，重复身份和 role/usage/finish/空片段不触发。看门狗仍包进展迭代器，stall 派生/净额取整不动。
 测试以受控 Event/FakeClock 驱动，避免用几十毫秒竞争制造脆弱测试：持续工具片段撑过 TTFT/inter-token；只有注释/usage 必超时；工具首进展设置 first_token_event；真实停顿计入 max_inter_token/stall，两字段与正文相同口径。
 命令：`conda run -n PolyGateway pytest tests/unit/test_openai_completion.py tests/unit/test_openai_compat.py tests/unit/test_streaming.py -q` → PASS；提交点：`feat: complete tool responses with unified stream liveness`。
 ### T4 — 完整协议缓存往返与隔离
 文件：middleware/cache.py；test_cache.py、tests/integration/test_redis_cache.py。
 先红测试：同消息 text/openai key 不同、旧默认 text key 字节不变；tools、tool_choice、raw effort、tool result、assistant arguments 改动均 miss；相同请求完整 completion round-trip，非流式扩展字段不丢，message 的 null/缺省可区别；usage 缺省/null 均为 None；openai 缺 completion/null/坏 message/坏工具条目 miss 后回源，不冒 dict 假装 dataclass。
 检查命中历史 response_id 不变、本次 call_id 重建、attempts=0、cache_hit=true、cost=0；变更一次命中消息不污染下一次命中；旧 text 缓存继续可读。失败路径无 set；序列化/backend set 抛错 warning 后仍返回结果；CancelledError 原样穿透。
 实现保真重建校验不能 import transport（import-linter 必守）；内核值类型可提供纯值构造校验，协议拼接算法只保留在 transport；避免两份 SSE/tool 聚合逻辑。
 命令：
 ```bash
 conda run -n PolyGateway pytest tests/unit/test_cache.py -q
 conda run -n PolyGateway pytest tests/integration/test_redis_cache.py -q
 conda run -n PolyGateway lint-imports
 ```
 真实 Redis 专用测试 namespace，沿既有 fixture 清理自有 key，不 flush 共享 DB；未配置 skip 必须记录为未覆盖，发布前补实测。提交点：`fix: isolate and round-trip OpenAI completion caches`。
 ### T5 — 完整链路、对冲、取消与遥测不变量
 文件：test_retry.py、test_hedge.py、test_stall_hedge.py、test_deadline.py、test_backpressure.py、tests/integration/test_governance_stack.py、test_redis_cross_connection.py、tests/e2e/conftest.py；生产 retry 仅修必要搬运漏项，不改算法。
 先红→绿证据须覆盖真实 OpenAICompatTransport 接入 GatewayClient，而不是只用返回预制 completion 的 fake 证明解析成功：
 | 场景 | 断言 |
 | --- | --- |
 | 第一次部分正文/工具→error→DONE，第二次正常 | 只返回第二次 completion，attempts=2；第一次 error 的字段不会污染结果或缓存 |
 | 工具持续进展 | 首 token 对冲及时止窗，中段 event 复位，未错误触发 |
 | 真沉默触发对冲 | 副路完整工具结果胜出，返回自己的 id/usage，输家不泄露半成品 |
 | primary 超时但副路尚在运行 | 不提前判总失败；两败仍只烧一次超级尝试预算 |
 | 流中/准入中/退避中取消与 deadline | CancelledError/CallDeadlineExceeded 类型保留，permit/inflight/task 收口，TPM 保守结算 |
 | 观测与降级 | 正常/失败/cache_hit 遥测沿单 helper；attempt 行/terminal 行口径不变；后端写失败不影响结果 |
 命令：
 ```bash
 conda run -n PolyGateway pytest tests/unit/test_retry.py tests/unit/test_hedge.py tests/unit/test_stall_hedge.py tests/unit/test_deadline.py tests/unit/test_backpressure.py -q
 conda run -n PolyGateway pytest tests/integration/test_governance_stack.py tests/integration/test_redis_cross_connection.py -q
 ```
 不删除“不需要失败计费”对应的现有失败遥测/attempts/结算；本任务不新增失败 token 取证。提交点：`test: cover governed tool retries hedges and cancellation`。
 ### T6 — 来源审计、Apache-2.0 与用户文档
 文件：LICENSE、pyproject.toml、test_package.py、新 license-audit finding、README、CHANGELOG、.env.example、ARCHITECTURE；设计/计划 Wiki 注册关系。
 | 工作 | 验收 |
 | --- | --- |
 | 来源审计复核（初审前置 T0） | 查 tracked 分发文件的移植/参考/版权注释及具体片段；列内部原创授权记录，外部只读 reference 的路径/许可/实际使用范围；未发现不等于法律认证 |
 | 第三方义务 | 对实际复制片段核实许可、保留通知；发现 AGPL 不兼容复制须上报，不借用户授权覆盖第三方 |
 | LICENSE | 使用标准 Apache-2.0 全文，不自行重写；版权归属沿项目元数据，不猜用户真实姓名；NOTICE 仅在实际需要时新增 |
 | 包元数据 | 当前 setuptools>=68，采用 `license = {file = "LICENSE"}` 兼容现有后端；验证 wheel/sdist 包含 license，不为 PEP 639 单独提高构建依赖 |
 | 文档 | 新 chat 示例 ≤15 行；response_mode 与 raw 所有权分开；单 choice、未知 SSE 方言失败、非流式、length、无 DONE 不打捞、缓存旧值迁移、取消/线程桥接限制写清 |
 `.env.example` 只解释 raw-only 必须去掉源级受管意图，不加模式 env 键。README 应说明“完整协议结果”仅四字段及已定义 SSE 字段，不能暗示返回所有顶层 logprobs/created 等；上游模型使用 LLMResponse.model_reported，不把 model 配置别名当真实版本。
 ARCHITECTURE 更新 §5 类型/签名、§6.2 空补全与 error、§7.1 DONE 与工具协议、§7.2/7.6 工具活性、§7.5 缓存维度，并明确这些只是批准方向的增量，不引入 Agent Loop。站点下线，无具体 Wiki 页面可同步。
 验证：`conda run -n PolyGateway pytest tests/unit/test_package.py -q` 先红后绿；`git diff --check`；构建验收见 T8。提交点：`docs: document faithful chat and Apache-2.0 distribution`。
 ### T7 — 少量真实工具冒烟与独立验证
 新增 tests/e2e/test_openai_tools_live.py，复用 tests/e2e/conftest.py 的请求取证/输出机制，不为本次重跑整个 thinking 矩阵。fixture 的 complete 显式转传 response_mode 是机械接线，不改取证判分算法。
 测试使用通用无业务领域的函数，如 echo_value；强制工具选择但工具在测试内执行纯函数，库本体不执行。流式、非流式各一次工具请求，随后带原 assistant+tool 消息做第二轮；断言 ID、finish、arguments 可用和请求消息相等。并行两工具完整逐字拼接的硬门由确定性 fixture 保证，不把模型偶尔不发两个工具解释为库聚合正确。
 真实测试标 slow/requires_llm，预算与超时不紧于现有 `.env` 生产配置。raw=max 使用已配支持模型的 raw-only 源；不发明新模型/API。Markdown 安全报告记录模式、源/model_reported、attempts、finish、工具数、结果/失败原因；不输出 key、敏感消息或完整参数。费用/网络异常如实呈现，不宽泛 skip。
 命令：
 ```bash
 conda run -n PolyGateway pytest -m slow tests/e2e/test_openai_tools_live.py tests/e2e/test_smoke_gateway.py -q
 make ci
 ```
 全套件由当前前台执行；若预计长跑需 tmux，禁用缓冲、保存原退出码，不在 pytest 末尾接管道。生成唯一日志路径 `tests/outputs/issue29/<任务>-<red|green>-<时间>.log`，不提交产物。无新增功能代码的当前阶段仅跑过单元基线，不预填完成框。
 父会话安排全新上下文 verifier 独立查实际 diff 与测试输出。若修改了准入/取消/退避生产逻辑，补 `tests/integration/test_redis_governance_time.py` 和 `test_redis_cross_connection.py` 对应 slow 子集；仅机械传参/协议解析时记录无 Lua/退避算法交集的理由。慢测试 skip/失败不得当通过。
 - [ ] 审查员检查依赖铁律、未知字段策略、旧文本回归与大对象保留成本。
 - [ ] 每项行为能链接红绿日志、命令、SHA、退出码；基线失败必须归因，不能“重跑绿了”掩盖。
 - [ ] 合并前测试/独立审查通过；提交均调用 commit skill，不夹带主树既有文档差异。
 ### T8 — 发布与 issue 外部验收（父会话持有，不由本设计任务执行）
 发布版本已由人类最终指定为 1.3.9（取代未发布的 1.4.0），不能在规划中冒称已发布。遵守 CLAUDE.md §4.4.1 全步骤：README/CHANGELOG/两处版本先完成 → 合并 main/push → 合并后 lint/全套件/相交 slow → tag push → 构建/twine check → registry 上传 → 实际下载核验 → Release/挂库/包页核验。
 | 发布门 | 可接受证据 |
 | --- | --- |
 | 构建 | `conda run -n PolyGateway python -m build` 和 twine check 成功；解包核 LICENSE、许可元数据、completion 类型/参数/解析器均在产物中 |
 | 安装 | 在独立临时环境从私有索引下载/安装已发布版本；必要时 --no-build-isolation 避免索引无 setuptools；核来源/hash，不误用本地 editable |
 | 外部页面 | registry 包正文与仓库链接、Gitea Release/tag 实际可见；不以 POST 返回码代替最终状态 |
 | 下游 | 以发布包运行不含业务逻辑的 tool 双轮接入验收；给 dissect3 说明同 loop 线程桥接和 raw-only 配置，不在本计划越权修改其业务仓 |
 | 关闭 issue | 再查询 open issue，#29 评论附版本/验收/限制与缓存迁移说明后关闭；若出现新 issue 单独定范围，不假称本计划涵盖未来问题 |
 ## 4. 自审清单与残余边界
 | 需求 | 覆盖任务 |
 | --- | --- |
 | 工具双并行、消息往返、raw=max、非流式 | T1–T3、T7 |
 | error+DONE 所有模式失败、attempts=2 | T2、T5 |
 | 缺 DONE 不 salvage 工具、length 不修复 | T3 |
 | 活性、对冲、取消、准入/结算 | T3、T5 |
 | 完整缓存、模式隔离、旧默认 key 与污染迁移 | T4、T6 |
 | Apache 授权与第三方来源、分发验证 | T6、T8 |
 | 测试先红后绿、独立审查、外部发布完成 | 各任务、T7、T8 |
 当前残余：首轮代码独审已完成，修复后待父会话最终复核；严格 SSE 方言会拒绝未定义增量字段，不承诺任意 OpenAI 兼容网关；旧文本毒化缓存只能由使用方迁移身份；公共 dataclass 嵌套 JSON 可变，靠快照隔离而非深冻结；模型真实冒烟依赖外部可用性。以上均需在文档和验收中如实保留，不当成全部自动解决。
 ## 5. 本轮实施记录（2026-10-01，未发布）
 P1 最终 assistant role、P2 来源核查前置均已采纳，证据见来源核查 finding。
 T1–T6 代码/文档/许可已落实；T7 工具真实冒烟、Redis、质量门已执行，独立代码审查由父会话接续；T8 禁止本 worker 执行。
 | 验证 | 实际结果/证据 |
 | --- | --- |
 | 基线红 | tests/outputs/issue29/baseline-red.log：error+DONE 未抛、双文本丢 reasoning、模式 API 缺失，3 failed |
 | 扩展红绿 | expanded-red.log 19 failed（git archive 0e29dea 的 src，不改主树）；expanded-green.log 同19 passed |
 | 防御红绿 | defense-red.log 3 failed：usage 裸错误/空 tool_calls 丢失；defense-green.log 同3 passed |
 | 全量 | ci-final.log + ci-final.exit=0：1812 passed、23 skipped、110 deselected，覆盖率95%；之后仅增测试/文档，无生产变更 |
 | 最后定向 | targeted-final.log：264 passed，包含后增的非流式事件/取消/managed冲突/名称分片回归 |
 | 真实缓存 | test_redis_cache.py 6 passed，专用随机 key，无共享数据清理 |
 | 真实工具 | live-final.log + live-final.exit=0：流式/非流式双轮2 passed，101.34s；安全Markdown在 tests/outputs/issue29/live |
 | 构建 | /tmp/pgw-issue29-dist-final 的 wheel/sdist、twine check、LICENSE/源码字节核验通过；仍1.3.8本地测试产物，绝非发布 |
 23 skips 为17个已转专用时间语义的 Redis 契约变体、6个缺私有图像语料的 OCR 测试；未把这些当本次通过。110 deselected 为默认 slow；未重跑全模型 thinking 矩阵，因为只机械转传端口参数、未改其判据或能力表。
 未提交代码，供父会话独立验收完整工作区。conda 启动有基础环境 RequestsDependencyWarning（pytest本体无该告警），pi-lens 使用错误环境时的缺包/枚举提示已用 conda 实证排除，不据此改变依赖。
 Wiki add_entity 会覆写无frontmatter同名文件，现场检查发现后已从本会话原始 tool-write 精确恢复两文档，并加 frontmatter 后保留 P1/P2 修订；没有丢失设计内容。
 补充最终证据：unit-final.log 1678 passed（23.84s），smoke.log + smoke.exit=0 为既有真实 chat 冒烟4 passed（97.18s）；未跑昂贵全模型矩阵。源代码最后变更早于 ci-final，后续只增测试/文档；最后单元覆盖全部新增测试。
 ## 6. 审查修复与1.4.0准备（2026-10-01，未发布）
 已读取首轮独立报告并核验采纳 P2 空产物缓存、Minor 测试双向依赖，详见 [审查处置](../reviews/2026-10-01-issue29-cache-review.md)。本轮只在隔离 feature 树写入，主树既有脏文档未改；不合并、不 push/tag/上传、不关issue。
 | 本轮命令/证据（日志均在 tests/outputs/issue29，不提交） | 实际结果 |
 | --- | --- |
 | 新缓存回归修复前：review-cache-red.log | 10 failed、1 passed：五种无效产物×两种缓存投影误命中；合法tool-only通过 |
 | 四模块定向：review-cache-green.log | 268 passed，17.71s；包含11项新增缓存回归 |
 | 真实Redis+包测试：review-redis-package.log | 13 passed，2.66s（6 Redis、7包） |
 | 首次 lint / make ci | 测试import顺序失败；已修正，不作为通过证据 |
 | tmux make ci：review-ci-final.log / .exit=0 | 1827 passed、23 skipped、110 deselected，317.28s；95%覆盖；格式102文件、ruff通过、依赖契约1 kept/0 broken |
 | 远端 tags 与 registry simple | 最大均1.3.8，没有1.4.0；版本两处改1.4.0，README约束>=1.4.0,<2，CHANGELOG定版 |
 | build / twine / 解包：review-build-final.log、review-twine.log、review-artifacts.log | 1.4.0 wheel/sdist 均通过；所有Python源码、README、标准LICENSE逐字相同，Version/License-File正确且无reference |
 | README数字断言 | inspect.signature 实测 TelemetryRecorder.record_llm_call 为38字段，未凭记忆更新 |
 wheel SHA256 `3186d01d7710c3b5ef727b59f95e8c2db0821277a79491ffb913dd2ce34a888d`；sdist SHA256 `b254dedf65d25673cf57986a613a1f4e9895da8b5be1e6ee241f00065a95ad90`。这些是隔离树本地构建，不是registry产物。解包探针首次使用email默认ASCII解码比较中文README产生误报，改为METADATA正文原始字节比较后通过，未改包来迎合错误探针。
 跳过项仍为17个独立slow Redis时间变体及6个缺私有图像语料OCR；110 slow未选中。本轮不重复付费网关：复用前轮流式/非流式工具双轮2通过和chat冒烟4通过，当前生产改动只统一空产物判据，工具/文本正常行为已有定向与全套件证明；合并后slow发布门由父执行。构建有setuptools许可表格弃用提醒（兼容setuptools>=68设计），并有基础conda RequestsDependencyWarning；均不等于当前构建或测试失败。
 按commit skill提交feature全部实现、修复、许可与发布准备，原main脏文件及运行产物不纳入。提交后交父最终独立复核；T8外部发布尚未完成，不能提前关闭#29。
 ## 7. 版本定案与历史文档归档（2026-10-01 EDT / 2026-10-02 UTC）
 用户最终指定本次发布 __1.3.9__，取代尚未打 tag/上传的 1.4.0。上节 1.4.0 构建散列、测试结果与历史提交标题均是当时实证，保留原样，不冒充 1.3.9 产物。README 安装约束、能力标题、CHANGELOG 与两处版本同步；自定义 `Transport.complete(response_mode=...)` 适配要求及旧缓存更换 namespace/salt 提醒保持不变。CHANGELOG 使用执行环境本地日期 2026-10-01（EDT），知识库时间戳明确使用 UTC。
 历史六文档独立归档提交 `ce10881`；采纳独审发现，仅补 #24 implements 边缺少的 plan/design 两节点。验证旧新节点/边/日志并集完整、120 个索引链接与计数一致、三文件仅空白/空引用格式、无冲突标记。剩余 15 个历史未注册端点以及 wiki lint 的 15 条孤立/稀疏提示均未扩大处理。原始备份 `/tmp/pgw140-release` 及 stash 保留。
 本轮只准备与本地构建，不合并、不 push/tag/上传、不关闭 issue；后续独审及发布外部验收仍是硬门。相关功能代码未变，可复用 `/tmp/pgw140-release/main-ci.log` 的 1828 项通过、95% 覆盖及 `main-slow.log` 的 6 项真实网关通过（205.81s）；本轮另执行包/协议定向、质量检查和 1.3.9 构建解包验证。
 | 本轮证据（`/tmp/pgw139-prepare/`） | 实际结果 |
 | --- | --- |
 | source.log / tests.log | 显式 `PYTHONPATH=/home/iomgaa/Projects/PolyGateway/src` 确认源码位置及1.3.9；包+缓存+协议四模块276 passed，12.43s，无新增行为测试 |
 | check.log | `make check` 格式、ruff、依赖契约通过，1 kept/0 broken |
 | docs-validation.log / wiki-lint.log | #24两端点补齐；原新记录保全、120链接计数通过；存量15个端点缺口及15条lint提示未清理 |
 | remote-tags.txt / registry-simple.html | 2026-10-02 UTC读取远端tag与匿名simple均无1.3.9/1.4.0，无版本冲突；发布前仍须复查 |
 | build.log / twine.log / artifacts.log / unpacked-import.log | 1.3.9 wheel/sdist构建、twine及全Python源码/README/LICENSE逐字核验通过；解包路径独立导入成功，38遥测字段实测不变 |
 本地 wheel SHA256 `45306557152fd44f8135928041e47924834c3b4039c586f72d521f51b4590dd3`；sdist SHA256 `8f455973e7fef71811e2b86f5a14cb03469d893ac9720b902f522d2b1a8dcd40`。产物位于 `/tmp/pgw139-prepare/dist`，不是已发布包。构建仅有已知许可证表格弃用提示、conda基础环境依赖警告；不为清警告增加依赖。
@@ -0,0 +1,230 @@
 ---
 type: plan
 node_id: plan:2026-10-14-issue30-31-completion-verdict
 title: 统一完成判定实现计划(#30/#31)
 date: 2026-10-14
 ---
 # #30/#31 统一完成判定实现计划
 **目标**: 按[设计](../designs/2026-10-14-issue30-31-completion-verdict-design.md)(下称"设计")实现统一完成判定,修复 #30/#31 并发布 1.3.10。
 **方案概述**: 在 `types.py` 内核放一组纯判定函数(流完整性 → 结局分类 → 可缓存),transport 两条路径、CacheMW 读写共用;聚合器改为 null 优先 + 未知字段无损合并;`LLMResponse`/`TransportResult` 追加 `finish_reason`/`stream_end`,遥测加 `stream_end` 列。
 **技术**: Python 3.12、httpx、pydantic、pytest(asyncio)、SQLite/PG 遥测、Redis 缓存。环境 `conda run -n PolyGateway`。
 本计划不涉及参考实现迁移,保真校验不适用。
 ## 0. 执行纪律
 - 分支 `fix/issue30-31-completion-verdict`。每个任务一次提交,经 `commit` skill;pre-commit 钩子会跑全套件 + ruff + "改动触及函数复杂度 < C",故**每个提交点必须全绿**,改到的既有高复杂度函数(`add_chunk` F42、`_complete_stream`/`_complete_once` C、`_rehydrate` C、`OpenAIChatCompletion.__post_init__` D)须在同一提交内拆到 B 及以下;钩子(2026-10-14 经人类同意改为只拦"本次改动触及"的块,存量 ≥C 降为告警,提交 5d2ad40)按 radon 块判定,**类块**(`ChatCompletionAccumulator` C16、`OpenAIChatCompletion` D24)同样须降到 B 及以下。不改 `OpenAICompatTransport.complete()`(C14),新增逻辑一律放在拆出的 helper 中。
 - 每个任务的统一验证(与钩子一致): `conda run -n PolyGateway pytest tests/ -q`(含 integration,本地有 Redis/PG 时真跑)+ `conda run -n PolyGateway ruff check src` + `conda run -n PolyGateway radon cc -n C <本任务改动文件>`(输出必须为空,或仅含本任务未触及的存量块)。各任务列出的子集命令只作开发期快速回路。
 - 测试结果门: 每个任务的新增/改写测试先在未改实现的代码上运行并记录**失败**输出(粘贴进提交说明正文的"Red:"一行,写明失败用例名与断言),再实现至通过。
 - 后台长跑命令末尾禁止接管道(CLAUDE.md §3)。
 ## 1. 文件结构
 | 文件 | 职责变化 |
 | --- | --- |
 | `src/polygateway/types.py` | 新增 `StreamEnd`、`FinishClass`、`_OutputSummary`、`_Verdict` 与七个纯函数(§2 列出;另 `_effective_finish`);`TransportResult`/`LLMResponse` 末尾追加两字段;`OpenAIChatCompletion` 接受 `tool_calls: None` 并复用 `_tool_snapshot_ok` |
 | `src/polygateway/__init__.py` | 导出 `StreamEnd`;`__version__` → 1.3.10(T6) |
 | `src/polygateway/transports/_openai_completion.py` | 聚合器: null 优先、未知字段合并、标签键、冲突路径、finish/usage 位置记录、reasoning 别名;`parse_chat_completion` 容忍 null |
 | `src/polygateway/transports/openai_compat.py` | 两条路径改走判定;有界告警节流;`finish_reason`/`stream_end` 填充;投影别名 |
 | `src/polygateway/middleware/retry.py` | `_build_response` 搬运两字段 |
 | `src/polygateway/middleware/cache.py` | 写/读按 `_is_cacheable`;`stream_end` 校验;finish 回退 |
 | `src/polygateway/ports.py` | `record_llm_call` 追加 `stream_end` |
 | `src/polygateway/middleware/telemetry.py` | `_AttemptUsage.stream_end`、`_record` 搬运、两 emit 显式 None |
 | `src/polygateway/telemetry/schema.py`、`sqlite.py`、`postgres.py` | 新列 + 补列 |
 | tests | 新增 `tests/unit/test_completion_verdict.py`;改写/扩充 `test_openai_completion.py`、`test_openai_fidelity.py`、`test_openai_compat.py`、`test_cache.py`、`test_telemetry.py`、`test_types.py`、`test_ports.py`、`tests/integration/test_postgres_telemetry.py` 及各 `record_llm_call` 替身 |
 | 文档 | README、CHANGELOG、ARCHITECTURE §6.2/§7/§14、1.3.9 设计修订指针、`schemas/llm-calls.md`、`migrations/` 三份、pyproject 版本 |
 ## 2. 跨任务接口(T1 定义,后续任务只消费)
 ```python
 StreamEnd = Literal["done", "eof_after_finish", "salvaged"]
 FinishClass = Literal["natural", "truncated", "filtered", "upstream_error", "unknown", "absent"]
 def _classify_finish(value: str | None) -> FinishClass: ...
 def _tool_snapshot_ok(message: Mapping[str, Any]) -> bool: ...
 def _stream_is_complete(
    *, done: bool, finish_reason: str | None, usage_after_finish: bool, usage_measured: bool
 ) -> StreamEnd | None: ...
 ```
 ```python
@dataclass(frozen=True)
 class _OutputSummary:
    any_output: bool      # 设计 §4.3 "任何产物"
    body_output: bool     # 设计 §4.3 "正文产物"
    tools_present: bool   # 至少一个非 null 工具条目(仅保真有意义)
    tools_ok: bool        # tools_present 时 _tool_snapshot_ok 结果;无工具恒 True
@dataclass(frozen=True)
 class _Verdict:
    deliver: bool
    error_kind: Literal["transient", "result_invalid"] | None  # deliver 时为 None
    code: str | None      # 设计 §4.3 原因码
 ```
 ```python
 def _summarize_text(content: str, thinking: str) -> _OutputSummary: ...
 def _summarize_message(message: Mapping[str, Any], projected_content: str) -> _OutputSummary: ...
 def _judge_outcome(*, mode: ResponseMode, summary: _OutputSummary, finish: FinishClass) -> _Verdict: ...
 def _is_cacheable(
    *, mode: ResponseMode, content: str, finish_reason: str | None,
    stream_end: str | None, completion: OpenAIChatCompletion | None,
 ) -> bool: ...
 ```
 缓存读写共用(T1 定义,T4 消费),顶层优先、回退 `completion.finish_reason`,避免读写口径分叉:
 ```python
 def _effective_finish(finish_reason: Any, completion: OpenAIChatCompletion | None) -> str | None: ...
 ```
 `types.py` 无 `from __future__ import annotations`: `StreamEnd`/`FinishClass` 必须定义在 `TransportResult`/`LLMResponse` 之前。
 聚合器对外只读属性(T2 定义,T3 消费): `finish_reason: str | None`、`finish_seen: bool`、`usage_after_finish: bool`、`conflicts: frozenset[str]`(归一路径)、`raw_message() -> dict[str, Any]`(未校验的合并消息深拷贝,含按 index 排序组装的 `tool_calls`,与 `finish()` 同一组装函数,供 `_tool_snapshot_ok` 判定)、`finish() -> OpenAIChatCompletion`(保真快照,校验失败抛 Transient,与 1.3.9 同)。`ChatDelta` 追加字段 `reasoning: str`(别名片段,默认 `""`)。
 ## 3. 任务
 ### T1 内核判定函数与公共字段
 - 文件: `src/polygateway/types.py`、`src/polygateway/__init__.py`;测试 `tests/unit/test_completion_verdict.py`(新)、`tests/unit/test_types.py`、`tests/unit/test_package.py`(导出)。
 - 行为:
  - `_classify_finish` 按设计 §4.1 表,大小写敏感;None → `absent`。
  - `_tool_snapshot_ok`: `tool_calls` 缺省或 None → True;否则必须是 list,每个非 None 元素满足 1.3.9 规则(非空唯一 id、`type == "function"`、非空 `function.name`、字符串 `arguments`);list 中 None 元素跳过。`OpenAIChatCompletion.__post_init__` 改为调用它(并拆分以降复杂度),`tool_calls: None` 合法且原样保留键。
  - `_stream_is_complete`: `done` → `"done"`;否则 `finish_reason is not None and usage_after_finish and usage_measured` → `"eof_after_finish"`;否则 None。
  - `_summarize_text`: any = `content != "" or thinking != ""`;body = `content.strip() != ""`;tools_present False、tools_ok True。
  - `_summarize_message`: any = 递归遍历 message 中除 `role`、`tool_calls` 外所有值存在非空字符串,或 tools_present;tools_present = `tool_calls` 为含非 None 元素的 list;tools_ok = `_tool_snapshot_ok(message)`;body = `projected_content.strip() != ""` 或 (tools_present 且 tools_ok)。
  - `_judge_outcome`: 严格按设计 §4.3 九行首匹配;原因码字面量: `upstream_finish_error`、`tool_truncated`、`tool_incomplete`、`length_without_content`、`filtered_without_content`、`empty_completion`。行 2 仅 `mode == "openai"` 时生效。
  - `_is_cacheable`: 设计 §6 四条,任一成立 False;`stream_end` 不在 `StreamEnd` 域且非 None → False;openai 模式且 `completion is None` → False。
  - `TransportResult`、`LLMResponse` 末尾追加 `finish_reason: str | None = None`、`stream_end: StreamEnd | None = None`(放在现有最后一个字段之后,不扰动位置构造);docstring 写清 None 语义与 `usage_source` 分工。
  - 包根导出 `StreamEnd`;`_has_completion_output` 本任务**保留不动**(T3/T4 迁移后删除)。
 - 测试(新文件): `_classify_finish` 全值表参数化;`_stream_is_complete` 真值表(含 usage 早于 finish、usage 非 measured);`_judge_outcome` 九行 × 两模式参数化(每行至少一例,含"正文非空+坏工具+stop → transient tool_incomplete");`_summarize_message` 对 refusal-only、reasoning-only、whitespace content、未知嵌套字符串、`tool_calls: [None]`;`_is_cacheable` 四类否例 + 正例 + 非法 stream_end。`test_types.py`: `OpenAIChatCompletion` 接受 `tool_calls=None`、拒非 list、`[None]` 合法;两新字段默认 None。
 - 验证: `conda run -n PolyGateway pytest tests/unit/test_completion_verdict.py tests/unit/test_types.py tests/unit/test_package.py -q` → 全过;`make lint` 无新增问题。
 - [ ] 提交 `feat: add kernel completion verdict functions and response fields`
 ### T2 聚合器: null 优先、未知字段合并、finish/usage 记录
 - 文件: `src/polygateway/transports/_openai_completion.py`;测试 `tests/unit/test_openai_completion.py`。
 - 保留 `message`、`tools` 实例属性名与语义(`test_openai_completion.py:70,93` 直接依赖)。
 - 行为(设计 §5、§4.2):
  - 每帧: 校验 chunk 对象;`usage` 非 null 时记录为 `last_usage`,若 `finish_seen` 或同帧 choice 带非 null finish → `usage_after_finish = True`。
  - choices: 保真维持单 choice/index 0 校验;文本模式取 `index` 缺省或为 0 的第一个 choice,其余忽略。
  - finish_reason: 保真走 `_identity`(非字符串/冲突 → Transient,同 1.3.9);文本模式首个字符串值生效,非字符串忽略。任一模式见到非 null 即 `finish_seen = True`。
  - null 五层(设计 §5.1): chunk 层 `choices: null`、choice 层 `delta: null` 视为缺省;例外: 顶层 `error` 键(含 `error: null`)仍由 `_check_chat_error` 按 error 帧拒绝(不动,保 `test_error_before_done_is_failure`)。
  - delta 与工具条目、function 三层: 值为 None 的键 → 若目标无此键则 `setdefault(key, None)`(保真),不做类型校验;`tool_calls` list 中 None 元素跳过。
  - 已知字段非 None 时逐字沿用 1.3.9 校验与合并(content/reasoning_content 拼接、role 必须 assistant、工具 id/type `_identity`、name/arguments 拼接)。
  - 未知字段(delta 层除 role/content/reasoning_content/tool_calls;工具层除 index/id/type/function;function 层除 name/arguments): 交给 `_merge_unknown(target, key, value, path)`,规则见设计 §5.2;标签键集合 `{"index", "type", "id", "format"}`;冲突 → 从 target 删除该键、把归一路径(数组下标替换为 `[]`,如 `delta.reasoning_details[].format`)加入 `conflicts` 与本尝试"封禁路径"集合,后续同路径值丢弃。`_merge_unknown` 返回"是否并入非空字符串片段"。
  - `reasoning`: 在保真模式作为普通未知字符串合并进 message;两模式都把其片段放入 `ChatDelta.reasoning`。
  - progress: 1.3.9 已知字段口径 **或** 任一 `_merge_unknown` 返回 True(文本模式也调用合并函数计算活性,但合并结果不对外)。
  - 新增只读属性见 §2;`finish()` 改为: 组装 message(含排序后工具)后构造 `OpenAIChatCompletion`(校验失败仍抛 Transient)。
  - `parse_chat_completion` 拆为两步: `check_completion_body(body) -> tuple[dict, str | None]`(只校验 body 为对象、恰好一个 choice、index 缺省或为 0、message 为对象、保真下 finish 为字符串或 null,失败抛 Transient;返回原始 message 与 finish)与 `build_completion(message, body) -> OpenAIChatCompletion`(构造快照,失败抛 Transient)。快照构造前剔除 `tool_calls` 中的 None 元素(与流式跳过一致,避免回传 `[null]` 被上游 400);`tool_calls: null` 原样保留。
  - `_merge_unknown` 按值类型拆分私有函数(标签键、字符串、标量、对象、index 数组、其他数组),每个 ≤ B。
  - 拆分 `add_chunk` 为 `_take_meta`、`_take_choice`、`_take_delta`、`_take_tools`、`_take_tool` 等私有方法,每个 ≤ B。
 - 测试: 改写 `test_invalid_delta_is_domain_error` 参数: 删除 `{"audio": {}}`、`{"index":0,"extra":1}` 与 null 已知字段参数(改为正例),保留 role 非 assistant、content 非字符串、tool index 非法等仍应拒绝的参数。新增: `refusal:null`+`tool_calls:null` 帧成功且快照含 `refusal: None`;只有 `reasoning` 的帧 progress=True 且 `ChatDelta.reasoning` 有值;二次构造的 OpenRouter `reasoning_details` 分片(每帧重复 `format`/`id`,`text` 分片)合并后 `format` 不重复、`text` 拼接完整;工具层嵌套对象 `extra_content={"google":{"thought_signature":"s"}}` 原样保留;数值冲突 → 键被删、`conflicts` 含归一路径、调用成功;同路径冲突后再到达的值被丢弃;形态改变(字符串→对象、index 数组→普通数组)即冲突;布尔值冲突;其他数组追加;同帧多个字段/多个未知字符串只产生一次 progress;chunk `choices:null`、choice `delta:null` 视缺省;`role:null`、`arguments:null` 视缺省;全程只有 `role:null` → `finish()` 失败;非流式 `tool_calls:[None, 合法工具]` 快照只含合法工具;`usage_after_finish` 四种顺序(finish 前 usage、finish 同帧、finish 后 usage-only 帧、无 usage);文本模式 index=1 的 choice 被忽略;重复 tool id 不拼接(既有用例保持)。
 - 验证: §0 统一验证;快速回路 `conda run -n PolyGateway pytest tests/unit/test_openai_completion.py tests/unit/test_openai_fidelity.py tests/unit/test_openai_compat.py -q`。T2 期间 transport 仍调用 `parse_chat_completion` 的组合(保留为两步的薄包装),行为不变。
 - [ ] 提交 `fix: merge unknown and null stream fields losslessly in completion accumulator`
 ### T3 transport 两条路径接入判定
 - 文件: `src/polygateway/transports/openai_compat.py`;测试 `tests/unit/test_openai_fidelity.py`、`tests/unit/test_openai_compat.py`。
 - 行为:
  - `_complete_stream`: 流结束后先算 `usage_measured = _resolve_usage(sink.get("usage") or {})[2] == "measured"`,再 `stream_end = _stream_is_complete(done=..., finish_reason=acc.finish_reason, usage_after_finish=acc.usage_after_finish, usage_measured=...)`。
    - None 且 openai → Transient `"{源} missing_done: …"`;None 且 text → 沿 `_check_done`(零产物按 `_summarize_text` 的 any 判定 early_eof;`retry` 抛;`salvage` → `stream_end="salvaged"`)。
    - `salvaged` 时 usage 沿 `_resolve_stream_usage(..., salvaged=True)`;`done`/`eof_after_finish` 时 salvaged=False。
  - 投影: `thinking` = 非空 reasoning_content 片段拼接,否则 `ChatDelta.reasoning` 片段拼接;再走既有 `_finalize_text`(think 标签)。
  - 判定: openai → `summary = _summarize_message(acc.raw_message(), content)`;text → `_summarize_text(content, thinking)`;`verdict = _judge_outcome(mode, summary, _classify_finish(acc.finish_reason))`;非 deliver → 按 `error_kind` 抛 `TransientError` 或 `ResultInvalidError`,message 固定格式 `f"{source.name} {code}: finish_reason={fr!r}, thinking_len={len(thinking)}"`,带 `source_name`、`operation="chat"`;`ResultInvalidError` 显式 `raw_text=""`(不回显推理内容)。deliver 且 openai → `acc.finish()` 构造快照。
  - 删除 `_reject_empty_completion` 与 1.3.9 的"保真缺 DONE"分支;`_check_done` 只保留文本截断语义。
  - `_complete_once`: 跳过第一步。保真: 先 `check_completion_body` 取原始 message 与 finish,用原始 message(剔除 None 工具后)算 `_summarize_message` 与 `_judge_outcome`,**仅 deliver 时**调 `build_completion` 构造快照——否则坏工具 + length 会在构造时抛 Transient,到不了 `tool_truncated`。文本: finish 取 `choices[0].get("finish_reason")`,非字符串记 None;同一判定;`stream_end=None`;投影别名同上(`message.get("reasoning_content") or message.get("reasoning")`,仅取字符串)。
  - 两路径 `TransportResult` 填 `finish_reason`、`stream_end`。
  - 告警节流: 实例属性 `_warned_fields: set[tuple[str, str]]`,上限 1024,饱和时记一次 `"告警集合已饱和,后续同类告警省略"`;对 `acc.conflicts` 中每个路径、以及 `_classify_finish == "unknown"` 的 finish 值(截断 64 字符,文案写明"该 finish_reason 不缓存")各告警一次;日志只含源名与路径/值,不回显字段内容。
  - 拆分 `_complete_stream`/`_complete_once` 至 ≤ B(建议抽 `_consume_stream`、`_verdict_or_raise`、`_project_text`)。
 - 测试(假 SSE,复用文件内既有 helper):
  - #31 验收 1-6(设计 §10),断言 `stream_end`、`usage_source`、attempts=1(经 GatewayClient 或 RetryMW 的既有测试设施)。
  - usage 早于 finish + EOF → 失败;finish 后 usage `{}` → 失败;`network_error`+usage+EOF → Transient。
  - 文本模式: stop+usage+EOF 无 DONE(`missing_done="retry"`)→ 成功 `eof_after_finish`;无 finish + EOF → retry 抛、salvage 记 `salvaged`。
  - #30 验收: 保真 reasoning-only+length → 交付,`completion.message["content"]` 缺省或空、`reasoning_content` 完整、`finish_reason=="length"`;文本同输入 → `ResultInvalidError` 且 message 含 `length_without_content`;保真 content 空+length(无任何产物)→ 交付;文本同 → ResultInvalid;保真/文本 零增量+DONE(带 stop、不带 finish)→ Transient(`test_stream_zero_content_with_done_is_transient` 保持不改);非流式 message 带 `tool_calls:null`+`refusal:null` → 成功;工具缺 name + length → ResultInvalid `tool_truncated`;content 非空 + 坏工具 + stop → Transient。
  - 只有 `reasoning` 字段的流不触发 TTFT 超时(用既有看门狗测试设施设置小 ttft)且文本 `thinking` 等于拼接值;同时有非空 reasoning_content 时以其为准。
  - 冲突/未知 finish 告警各只一次(loguru sink: `logger.add(list.append, level="WARNING")`,先例 `test_openai_compat.py:877`;caplog 抓不到 loguru);饱和用例预先往 `_warned_fields` 灌 1024 条再触发一次,断言饱和告警一次。
  - 结局表传输层覆盖: 设计 §4.3 九行 × 两模式,每行至少流式一例 + 非流式一例(行 2 只保真);非流式"工具缺 name + length → ResultInvalid `tool_truncated`";文本 length 用例经 GatewayClient 断言 attempts=1 且熔断窗口失败计数为 0;#30 reasoning-only+length 经 GatewayClient 断言 attempts=1。
  - 改写 `test_openai_never_salvages`: 断言"无 finish 的 EOF 在 `missing_done=salvage` 下仍失败",并新增"finish+usage+EOF 成功"作为对照。
 - 验证: `conda run -n PolyGateway pytest tests/unit -q` → 全过。
 - [ ] 提交 `fix: judge stream completion by finish reason and trailing usage`
 ### T4 retry 搬运与缓存读写判据
 - 文件: `src/polygateway/middleware/retry.py`、`src/polygateway/middleware/cache.py`、`src/polygateway/types.py`(删除 `_has_completion_output`);测试 `tests/unit/test_cache.py`、`tests/unit/test_retry.py`、`tests/integration/test_redis_cache.py`。
 - 行为:
  - `_build_response` 搬运 `finish_reason`、`stream_end`。
  - 写路径: 序列化前 `_is_cacheable(mode=request.response_mode, content=response.content, finish_reason=response.finish_reason, stream_end=response.stream_end, completion=response.completion)` 为 False → `logger.debug` 跳写。
  - 读路径(`_rehydrate`): 重建 completion 后、`fields.update` 之前: `stored_end = fields.get("stream_end")` 非 None 且不在域 → miss+warning;`finish = fields.get("finish_reason")`,非 None 且非 str → miss;为 None 且 completion 存在 → 回退 `completion.finish_reason`;`_is_cacheable(...)` False → miss+warning;命中覆盖加 `stream_end=None`、`finish_reason=finish`。拆分 `_rehydrate` 至 ≤ B。
  - 删除 `_has_completion_output` 及其 import(全仓 grep 为零)。
 - 读写判定的 finish 统一取 `_effective_finish(response.finish_reason, response.completion)`(读路径对存储值同样调用)。
 - 测试: 不可缓存六类(salvaged、reasoning-only length 保真、文本 length 带正文、unknown finish、保真 reasoning-only + stop(交付但无正文产物)、`content_filter` 带正文)均不写入(fake cache backend 断言 set 未调用)且第二次调用 attempts=1;手工注入上述条目 → 读视 miss;非法 `stream_end` 注入 → miss;1.3.9 旧文本条目(无新键)→ 命中;1.3.9 保真条目(无顶层 finish、completion.finish_reason="length")→ miss;命中返回 `stream_end is None`、`finish_reason` 为存储/回退值;retry 测试断言 LLMResponse 两字段来自 TransportResult。Redis integration 一例往返两新字段。
 - 验证: `conda run -n PolyGateway pytest tests/unit -q` → 全过;`conda run -n PolyGateway pytest tests/integration/test_redis_cache.py -q`(需本地 Redis)→ 全过。
 - [ ] 提交 `fix: gate cache writes and reads on a shared cacheability verdict`
 ### T5 遥测 `stream_end` 列与 recorder 端口
 - 文件: `src/polygateway/ports.py`、`src/polygateway/middleware/telemetry.py`、`src/polygateway/telemetry/schema.py`、`sqlite.py`、`postgres.py`;测试 `tests/unit/test_telemetry.py`、`tests/unit/test_ports.py`、`tests/integration/test_postgres_telemetry.py`,以及全仓 `def record_llm_call` 测试替身(`grep -rn "def record_llm_call" tests`)。
 - 行为:
  - `TelemetryRecorder.record_llm_call` 在 `stall_count` 之后追加 keyword-only `stream_end: str | None`(无默认),docstring 注明 1.3.10。
  - `_AttemptUsage` 加 `stream_end: str | None = None`,`of()` 读 `response.stream_end`;`emit_attempt` 把它传给 `_record`;`_record` 加同名参数并传给 recorder;`emit_cache_hit`、`emit_terminal_failure` 显式 `stream_end=None`。
  - `schema.py`: SQLite 与 PG CREATE 末尾 `stream_end TEXT`;`SQLITE_BACKFILL`、`_PG_BACKFILL_DECLS` 追加 `("stream_end", "TEXT")`;`COLUMNS` 追加 `"stream_end"`。sqlite/postgres 若有硬编码列数或参数位次随之更新(以 `COLUMNS` 为准)。
 - 替身与计数(按审查实测清单): ① 固定字段 fixture `tests/unit/test_telemetry.py:142` `_record_minimal`、`tests/integration/test_postgres_telemetry.py:121` `_minimal_fields` 补 `stream_end: None`(sqlite 按 `fields[col]` 取值,缺键 KeyError);② 硬编码计数 38→39 / 列清单追加: `test_ports.py:325`、`test_telemetry.py:53`(`_EXPECTED_COLUMNS`)`:271`、`:301-303`、`:779`、`:829`,`test_postgres_telemetry.py:33`、`:778`、`:1151`、`:1352`(执行时以 grep 复核行号);③ `test_ports.py:112` `_DummyRecorder` 补参数,`stream_end` 加入 `:332` 无默认值参数化列表;④ `**fields` 替身(14 处)无需改动。源码 docstring "38 字段"同步: `ports.py:293`、`middleware/telemetry.py:373`、`sqlite.py:146`、`schema.py:8`。形状闸 `middleware/telemetry.py:323` `_assert_recorder_shape` 从协议签名派生,不改闸本身。
 - 测试: 成功流式行写 `done`/`eof_after_finish`;非流式、缓存命中、失败、取消、终态行为 NULL;旧库(无列)auto 档补列后写入;manual 档缺列 → 裁剪写入且告警点名 `stream_end`;形状闸拒绝缺 `stream_end` 参数的 recorder;PG integration 同上(需本地 PG,沿既有 fixture)。所有替身补参数。
 - 验证: `conda run -n PolyGateway pytest tests/unit -q` → 全过;`conda run -n PolyGateway pytest tests/integration/test_postgres_telemetry.py -q` → 全过;`conda run -n PolyGateway python -c "import inspect, polygateway.ports as p; print(len(inspect.signature(p.TelemetryRecorder.record_llm_call).parameters) - 1)"` 记录字段数供 T6 使用。
 - [ ] 提交 `feat: record stream end mode in telemetry`
 ### T6 文档、版本与另开 issue
 - 文件: `README.md`、`CHANGELOG.md`、`research-wiki/ARCHITECTURE.md`、`research-wiki/designs/2026-10-01-issue29-openai-fidelity-design.md`(顶部加"§4.1/§4.2/§5/§6 部分规则已由 2026-10-14 设计修订"指针)、`research-wiki/schemas/llm-calls.md`、`research-wiki/migrations/*.md`、`pyproject.toml`、`src/polygateway/__init__.py`。
 - 内容:
  - CHANGELOG `## 1.3.10(未发布)`: 修复段(#31 两模式、#30 两部分、非流式 `tool_calls:null`、reasoning 别名、salvage 不再缓存);**行为变更**段(文本 length/过滤无正文 → ResultInvalid 不再经 `AllSourcesExhausted`;未知 finish 不缓存;活性口径增补);**破坏性**段(`record_llm_call` 新增必填 `stream_end`);提醒(工具快照成立+length 时 arguments 可能半截;冲突删键以告警为准;旧缓存污染迁移 namespace/salt)。
  - README: 能力表补完成判定/`stream_end`;安装约束 `1.3.*` 核对;遥测字段数用 T5 实测值;活性口径一句。
  - ARCHITECTURE: §6.2 空补全/missing_done 行、§7 `usage_source` 与 `stream_end` 映射、§14 协议/失败/缓存行按设计改写。
  - `schemas/llm-calls.md`: 加 `stream_end` 列与取值表,修正陈旧计数。
  - `migrations/` 三份: 核对下游对 `ResultInvalidError` 的 catch 点,写一行结论(有/无受影响路径)。
  - 版本 1.3.10 两处一致。
  - `docs-convention.md` §2 清单逐项过: Gitea Wiki 站点下线,由 README/CHANGELOG/ARCHITECTURE/schemas 承接;`.env.example` 无配置键变更(写明);`research-wiki/ROADMAP.md` 状态同步。
  - 另开 Gitea issue(tea CLI): "文本模式 n>1 时多 choice 增量混流";"文本模式有产物无正文 + stop 的证据收集(决定是否改 ResultInvalid)"。
 - 验证: `grep -n "1.3.10" pyproject.toml src/polygateway/__init__.py`;`conda run -n PolyGateway pytest tests/unit/test_package.py -q` → 过。
 - [ ] 提交 `docs: document completion verdict and bump version to 1.3.10`
 ### T7 合并前验证、审查与发布
 - [ ] `make lint`、`make test` 全绿(覆盖率不降);`tests/integration` 中 Redis/PG 相关全绿。
 - [ ] 派全新上下文 verifier subagent(`verification-before-completion`),逐条对照设计 §4-§7、§10 与本计划验收,输出证据表。
 - [ ] `requesting-code-review` 整分支审查;按 `receiving-code-review` 核验并修复。
 - [ ] slow 子集(按 diff 交集): 动了公开入口与 transport → `pytest -m slow tests/e2e/test_smoke_gateway.py tests/e2e/test_openai_tools_live.py`;不跑 `test_thinking_live.py`(未动 thinking 能力表)。另做一次 magpie/glm 真实探针: 记录是否出现 `eof_after_finish`,作为 #31 外部证据。
 - [ ] 按 CLAUDE.md §4.4.1 九步发布 1.3.10(CHANGELOG 定版日期、合并 main `--no-ff`、main 上重跑、tag、构建、上传、下载验证、Release + 包关联 + 页面核对)。
 - [ ] 在 #30/#31 评论验收证据与版本,关闭。
 ## 4. 设计覆盖自查
 | 设计条目 | 任务 |
 | --- | --- |
 | §3 公共字段、`StreamEnd` 导出、`tool_calls:null` | T1 |
 | §3 recorder 端口、列 | T5 |
 | §4.1 纯函数与 finish 分类 | T1 |
 | §4.2 流完整性、usage 位置与 measured | T2(记录)+T3(判定) |
 | §4.3 结局表、原因码、错误格式 | T1(判定)+T3(翻译) |
 | §4.4 reasoning 别名 | T2+T3 |
 | §5.1-5.3 null、合并、标签键、活性 | T2 |
 | §5.4 告警节流 | T3 |
 | §6 缓存读写 | T4 |
 | §7 遥测落点 | T5 |
 | §8 旧行为审计中的保留项(零增量+DONE、error 帧、多 choice) | T3 回归测试 |
 | §10 文档、另开 issue、发布 | T6+T7 |
 ## 5. 审查修订记录
 | 轮次 | 意见 | 处置 |
 | --- | --- | --- |
 | P1 | B1 非流式先构造快照导致 `tool_truncated` 不可达 | 采纳: T2 拆 `check_completion_body`/`build_completion`,T3 先判定后构造 |
 | P1 | S1 T5 替身/计数清单 | 采纳: T5 逐项列出 |
 | P1 | S2 类块复杂度、S3 验证与钩子一致 | 采纳: §0 |
 | P1 | S4 保留内部属性、S5 五层 null、S6 缓存漏两类、S7 结局表与熔断断言、S8 合并规则测试 | 采纳: T2/T3/T4 |
 | P1 | 建议 1-8 | 全部采纳;建议 4 选"剔除 None 工具元素" |
@@ -0,0 +1,29 @@
 ---
 type: review
 node_id: review:2026-10-01-issue29-cache-review
 title: 保真缓存审查修复与1.4.0准备
 date: 2026-10-01
 ---
 # 保真缓存审查修复与1.4.0准备
 ## 审查采纳
 | 级别/问题 | 核验与处置 |
 | --- | --- |
 | Important/P2：空协议缓存绕过成功判据 | 已实证：新测试在修复前 10 failed、1 passed；role-only、null/空/空白正文+空工具、reasoning-only，分别带空投影/伪造旧投影均误命中。采纳并修复。 |
 | Minor：协议/治理测试互相导入 | 已核验双向依赖；将帧构造放基础协议测试中，上层 fidelity 单向复用，没有新增 helpers 抽象。 |
 内核 `types._has_completion_output` 供 transport 和缓存共用：先经协议类型结构校验，有完整工具即有效；无工具须原协议正文和兼容投影均非空。快照类型仍允许描述空消息，不将成功判据强塞进构造器。缓存使用已有 warning/miss，text 旧缓存行为不变。没有 middleware→transport 依赖。
 ## 验证证据
 定向 `test_cache/test_openai_completion/test_openai_fidelity/test_openai_compat` 为 268 passed；日志 `tests/outputs/issue29/review-cache-{red,green}.log`（运行产物不提交）。完整质量门1827 passed/23 skipped/110 deselected、95%覆盖、退出0；真实Redis+包13通过；1.4.0 wheel/sdist源码/README/LICENSE逐字校验及twine通过，详见计划最新记录；首轮 lint 发现一个测试 import 顺序，修正后重新运行全门，未掩盖首次失败。
 ## 发布准备边界
 1.4.0 对应新增公共协议支持及 transport 端口参数；2026-10-01 远端 tags 和匿名 registry simple 最大版本均1.3.8，无1.4.0冲突。README安装约束、能力表、CHANGELOG定版、两处版本同步。新增 `.env.example` 仅四行说明，无凭据。源码/许可来源核查复用已独审 finding；新产物仍须父会话最终复核后发布。本轮不合并、不 push/tag/上传、不关issue；原main脏文件未改。
 ## 后续版本定案（2026-10-01 EDT / 2026-10-02 UTC）
 用户最终指定发布 **1.3.9**，取代本文当时准备但从未发布的 1.4.0。本文标题、历史构建及审查证据保留原值；当前发布目标与新构建核验见[计划 §7](../plans/2026-10-01-issue29-openai-fidelity.md)。版本号变更不撤销自定义 Transport 的 `response_mode` 适配要求。
@@ -177,3 +177,26 @@ ORDER BY model, calls DESC;
 ## 1.3.4 测试侧证据（不新增 schema）
 `tests/live_evidence.py`／e2e conftest 只在内存保存完整错误体与独立非流式身份，逐轮 Markdown 白名单输出到 `tests/outputs/134/live/`；凭据、Authorization、提示词、原始异常／响应均不落报告。生产数据仍经 TelemetryEmitter。评估复用 `metric:call-telemetry-coverage`，实际 live 覆盖基线待首次执行。
 ## #29 复用声明（2026-10-01）
 OpenAI 保真没有新增遥测表/列；仍经 RetryMW._emit → TelemetryEmitter。
 error 帧是失败 attempt，正文与思考仍为兼容投影，不新增工具全文列。
 本页原标题/表格停留 36 字段；实际 `telemetry/schema.py` 已含 stall_ms/stall_count
 共 38 个 INSERT 字段（§7.8 已登记）。本次不改 DDL，真实定义以源码为准。
 ## 1.3.10 `stream_end` 列（#31，2026-10-14）
 `llm_calls` 末尾追加可空 `stream_end TEXT`：INSERT 字段 38 → 39，物理列（含 `created_at`）39 → 40；
 上文"36 字段"标题为历史口径，以 `telemetry/schema.py` 的 `COLUMNS` 为准。
 | 值 | 含义 | 行 |
 | --- | --- | --- |
 | `done` | 收到 `[DONE]` | 流式成功 attempt |
 | `eof_after_finish` | 无 DONE，finish + 其后实测 usage + 干净 EOF | 流式成功 attempt |
 | `salvaged` | 文本 `missing_done=salvage` 打捞 | 流式成功 attempt |
 | NULL | 非流式 / 缓存命中 / 失败 / 取消 / 终态行，或补列前旧行 | — |
 来源: emitter 经 `_AttemptUsage.of(response)` 读 `LLMResponse.stream_end`（不走 `emit_attempt` kw）；
 命中与终态入口显式 None。评估复用 `metric:call-telemetry-coverage`；新增观察口径
 `SELECT stream_end, count(*) FROM llm_calls WHERE event_kind='attempt' GROUP BY 1` 统计中转不发 DONE 的比例。
@@ -47,12 +47,15 @@ from polygateway.types import (
    OcrLayoutElement,
    OcrLayoutResult,
    OcrTextResult,
    OpenAIChatCompletion,
    ResponseMode,
    SourceConfig,
    StreamEnd,
    TelemetryStatus,
    ThinkingObservation,
 )
-__version__ = "1.3.8"
+__version__ = "1.3.10"
 __all__ = [
    "DEFAULT_PROFILES",
@@ -70,6 +73,9 @@ __all__ = [
    "GatewayUnavailableError",
    "GovernanceBackendError",
    "LLMResponse",
    "ResponseMode",
    "StreamEnd",
    "OpenAIChatCompletion",
    "ModelPrice",
    "OcrClient",
    "OcrLayoutElement",
@@ -9,6 +9,7 @@
 from __future__ import annotations
 import asyncio
 import copy
 import dataclasses
 import hashlib
 import json
@@ -48,6 +49,7 @@ from polygateway.types import (
    ChatRequest,
    Effort,
    LLMResponse,
    ResponseMode,
    TelemetryStatus,
    _CallContext,
    coerce_effort,
@@ -372,9 +374,15 @@ class GatewayClient:
        tenant_id: str | None = None,
        meta: Mapping[str, Any] | None = None,
        call_deadline_s: float | None = None,
        response_mode: ResponseMode = "text",
    ) -> LLMResponse:
        """一次治理调用(签名冻结,ARCH §5.2;与三项目 LLMProvider 协议兼容)。
        `response_mode="openai"` 返回 `completion` 完整单 choice 消息快照；
        不支持与 structured 并用，不执行工具。空正文但完整工具是合法结果；
        缺 [DONE] 不打捞。默认 text 保持既有文本投影。返回模式不绕过受管推理
        校验；raw-only 要求源级与请求级推理意图均为 None。
        `overlay` 是采样参数覆盖层(`temperature`/`seed`/`max_tokens` 等),优先级
        高于源级 `extra_body`、低于结构化输出的注入。带默认值的 keyword-only
        参数不影响既有调用点(issue #4)。
@@ -393,6 +401,23 @@ class GatewayClient:
        `CallDeadlineExceeded`,但到期**不等于未产出、未计费**——在途请求可能已发出、
        已被上游计费,且清理仍在 `finally` 里完成,故返回时刻 = 期限 + 清理耗时。
        """
        if response_mode not in ("text", "openai"):
            raise ValueError("response_mode 必须为 text 或 openai")
        if response_mode == "openai":
            if structured is not None:
                raise ValueError("openai 模式不能与 structured 并用")
            if (
                overlay is not None
                and "n" in overlay
                and (type(overlay["n"]) is not int or overlay["n"] != 1)
            ):
                raise ValueError("openai 模式仅支持 n=1")
            try:
                json.dumps(messages, allow_nan=False)
            except (ValueError, TypeError) as exc:
                raise ValueError("messages 必须可 JSON 序列化") from exc
            messages = copy.deepcopy(messages)
            overlay = copy.deepcopy(dict(overlay)) if overlay is not None else None
        if structured is not None and not self._structured_available:
            raise ImportError(
                "结构化输出未启用: 安装 pip install 'polygateway[structured]' 后重新装配"
@@ -429,6 +454,7 @@ class GatewayClient:
        context = _CallContext(now=self._now)
        request = ChatRequest(
            messages=messages,
            response_mode=response_mode,
            session_id=session_id,
            parent_call_id=parent_call_id,
            cache_salt=cache_salt,
@@ -37,7 +37,7 @@ SOURCE_REASONS = frozenset(
 class PolyGatewayError(Exception):
    """库内一切领域错误的基类,携带来源上下文便于遥测与日志定位。
-    `body_text` 是**非 2xx 响应体的摘要**——网关拒绝这次调用时说的话(issue #10)。
+    `body_text` 是**HTTP 失败或 200 chat error 帧的摘要**——网关拒绝这次调用时说的话(issue #10)。
    它与 `ResultInvalidError.raw_text` 是两回事,严禁混用:
    ==============  ==================================================
@@ -17,7 +17,16 @@ from typing import TYPE_CHECKING, Any
 from loguru import logger
-from polygateway.types import ChatRequest, Effort, LLMResponse, ThinkingObservation
+from polygateway.types import (
    ChatRequest,
    Effort,
    LLMResponse,
    OpenAIChatCompletion,
    ResponseMode,
    ThinkingObservation,
    _effective_finish,
    _is_cacheable,
 )
 if TYPE_CHECKING:
    from collections.abc import Mapping
@@ -107,6 +116,7 @@ def build_cache_key(
    *,
    sampling: Mapping[str, Any] | None = None,
    reasoning_effort: Effort | None = None,
    response_mode: ResponseMode = "text",
 ) -> str:
    """缓存 key 公式;salt 仅非 None 时参与(VT 旧键语义: 不传 salt 键形不变)。
@@ -127,6 +137,8 @@ def build_cache_key(
        "messages": digest_messages(messages),
        "namespace": namespace,
    }
    if response_mode != "text":
        key_obj["response_mode"] = response_mode
    if salt is not None:
        key_obj["salt"] = salt
    if sampling:
@@ -137,6 +149,54 @@ def build_cache_key(
    return _KEY_PREFIX + hashlib.sha256(payload.encode("utf-8")).hexdigest()
 def _response_cacheable(mode: ResponseMode, response: LLMResponse) -> bool:
    """写路径判据;与读路径共用 `_is_cacheable` 与 `_effective_finish`,口径不分叉。"""
    return _is_cacheable(
        mode=mode,
        content=response.content,
        finish_reason=_effective_finish(response.finish_reason, response.completion),
        stream_end=response.stream_end,
        completion=response.completion,
    )
 def _restore_fields(raw: str, mode: ResponseMode) -> dict[str, Any]:
    """缓存原文 → LLMResponse 字段;不可缓存或形态坏抛 ValueError(调用方按 miss)。
    可缓存判定对**存储原值**进行、先于命中覆盖: 覆盖后 `stream_end` 恒 None,
    在那之后判会把 salvaged 条目放行(设计 §6)。
    """
    data = json.loads(raw)
    fields = {k: v for k, v in data.items() if k in _RESPONSE_FIELDS}
    completion = fields.get("completion")
    if completion is not None:
        if not isinstance(completion, dict):
            raise ValueError("缓存 completion 必须为对象")
        fields["completion"] = OpenAIChatCompletion(**completion)
    finish = _effective_finish(fields.get("finish_reason"), fields.get("completion"))
    if finish is not None and not isinstance(finish, str):
        raise ValueError("缓存 finish_reason 必须为字符串或 null")
    if not _is_cacheable(
        mode=mode,
        content=fields.get("content", ""),
        finish_reason=finish,
        stream_end=fields.get("stream_end"),
        completion=fields.get("completion"),
    ):
        # 非法 stream_end 也落这里: 它关乎内容完整性,不像 thinking_observation
        # 那样可以宽容降级
        raise ValueError("缓存条目不可缓存(截断/空正文/非自然结束/非法 stream_end)")
    fields["finish_reason"] = finish
    # JSON 里存的是 StrEnum 的字符串值,不转就复活成裸 str,与字段注解分叉
    # (下游 `is ThinkingObservation.OBSERVED` 会在命中路径上静默为 False);
    # 键缺失即升级前写入的旧条目,交给 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"])
    return fields
 class CacheMW:
    """洋葱第二层(遥测内、结构化外)。
@@ -176,6 +236,7 @@ class CacheMW:
            # 请求级档位必须逐次进 key: `self._fingerprint` 是装配期的集合级指纹,
            # 同一个 client 上 low 与 max 两次调用在它眼里毫无分别(issue #20)
            reasoning_effort=request.reasoning_effort,
            response_mode=request.response_mode,
        )
        cached = await self._safe_get(key)
        if cached is not None:
@@ -183,7 +244,17 @@ class CacheMW:
            if hit is not None:
                return hit
        response = await call_next(request)
-        await self._safe_set(key, self._serialize(response))
+        if not _response_cacheable(request.response_mode, response):
            # 交付照常,只是不进 TTL: 截断/空正文/非自然结束固化后会把一次偶然
            # 变成必然(设计 §6)。debug 级: 这是常规分流,不是故障
            logger.debug("结果不可缓存(截断/空正文/非自然结束),跳过写入")
            return response
        try:
            serialized = self._serialize(response)
        except Exception as exc:
            logger.warning("缓存序列化失败，跳过缓存: {}", type(exc).__name__)
        else:
            await self._safe_set(key, serialized)
        return response
    # —— 命中路径 ——
@@ -191,21 +262,15 @@ class CacheMW:
    def _rehydrate(self, raw: str, request: ChatRequest) -> LLMResponse | None:
        """反序列化 + 按本次调用的 structured 档零网络重建;失败按未命中。"""
        try:
-            data = json.loads(raw)
+            fields = _restore_fields(raw, request.response_mode)
            fields = {k: v for k, v in data.items() if k in _RESPONSE_FIELDS}
            structured_data = self._rebuild_structured(fields.get("content", ""), request)
            # JSON 里存的是 StrEnum 的字符串值,不转就复活成裸 str,与字段注解分叉
            # (下游 `is ThinkingObservation.OBSERVED` 会在命中路径上静默为 False);
            # 键缺失即升级前写入的旧条目,交给 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,
                ttft_ms=None,
                max_inter_token_ms=None,
                # 结束方式描述的是"那次流",命中没有流可言(与 ttft_ms 同口径)
                stream_end=None,
                call_id=str(uuid.uuid4()),
                structured_data=structured_data,
                # 显式覆盖: 历史条目里的 `call_stats` 是个 dict,而 `_RESPONSE_FIELDS`
@@ -357,6 +357,7 @@ class RetryMW:
            gen_started = self._now()
            result = await self._transport.complete(
                messages=request.messages,
                response_mode=request.response_mode,
                source=source,
                stream=request.stream,
                overlay=request.overlay,
@@ -739,6 +740,9 @@ class RetryMW:
    ) -> LLMResponse:
        return LLMResponse(
            content=result.content,
            completion=result.completion,
            finish_reason=result.finish_reason,
            stream_end=result.stream_end,
            thinking=result.thinking,
            model=source.model,
            provider=source.provider,
@@ -221,6 +221,9 @@ class _AttemptUsage:
    # 两字段留在此处只为让"尝试视图"形状完整,默认 None 即"无沉默观测"
    stall_ms: int | None = None
    stall_count: int | None = None
    # 1.3.10(#31): 与 stall 相反,结束方式**从 response 取**——LLMResponse 本次有
    # 该字段,免去约 50 处 emit_attempt 调用点加参;失败尝试 None = 无流可言
    stream_end: str | None = None
    @classmethod
    def of(cls, response: LLMResponse | None) -> _AttemptUsage:
@@ -239,6 +242,7 @@ class _AttemptUsage:
            model_reported=response.model_reported,
            reasoning_tokens=response.reasoning_tokens,
            thinking_observation=response.thinking_observation,
            stream_end=response.stream_end,
        )
@@ -370,7 +374,7 @@ def _assert_recorder_shape(recorder: TelemetryRecorder) -> None:
 class TelemetryEmitter:
-    """从请求与结果组装 38 字段并写入 recorder;一切写失败降级 warning。"""
+    """从请求与结果组装 39 字段并写入 recorder;一切写失败降级 warning。"""
    def __init__(
        self,
@@ -464,6 +468,7 @@ class TelemetryEmitter:
            total_latency_ms=None,
            stall_ms=stall_ms,
            stall_count=stall_count,
            stream_end=usage.stream_end,
        )
    async def emit_cache_hit(
@@ -514,6 +519,8 @@ class TelemetryEmitter:
            # 缓存命中行未产生 transport 观测: 无沉默可言,显式 None
            stall_ms=None,
            stall_count=None,
            # 命中/终态行无流可言(缓存命中已在 CacheMW 置 None,此处显式不信任)
            stream_end=None,
        )
    async def emit_terminal_failure(
@@ -569,6 +576,8 @@ class TelemetryEmitter:
            # 终态行无具体源与 transport 观测: 显式 None
            stall_ms=None,
            stall_count=None,
            # 命中/终态行无流可言(缓存命中已在 CacheMW 置 None,此处显式不信任)
            stream_end=None,
        )
    async def _record(
@@ -615,6 +624,8 @@ class TelemetryEmitter:
        # 本方法只搬运(同 reasoning_effort 先例)——
        stall_ms: int | None,
        stall_count: int | None,
        # —— 1.3.10: 结束方式(#31);入口已定型,本方法只搬运 ——
        stream_end: str | None,
    ) -> None:
        try:
            # 成本换算(M2 §6): 成功行按单价换算;缓存命中 0.0(未产生新调用);
@@ -685,6 +696,7 @@ class TelemetryEmitter:
                total_latency_ms=total_latency_ms,
                stall_ms=stall_ms,
                stall_count=stall_count,
                stream_end=stream_end,
            )
        except asyncio.CancelledError:
            raise
@@ -20,6 +20,7 @@ from .types import (
    OcrLayoutTransportResult,
    OcrTextResult,
    OcrTextTransportResult,
    ResponseMode,
    SourceConfig,
    SourceStats,
    TelemetryStatus,
@@ -40,6 +41,10 @@ class Middleware(Protocol):
 class Transport(Protocol):
    """一次原始调用的协议细节(请求组装/流式解析/错误翻译);不含任何治理。
    `response_mode` 为必填返回契约：openai 成功必须提供 completion，
    不支持者应 RequestRejected，不能静默退回文本。工具的实际增量与首次身份
    同正文/推理共用活性事件；同帧只置位一次，重复身份不算进展。
    `reasoning_effort` 是本次调用要求的推理档位(`None` = 不表态,随源级配置)。
    它必须走**协议参数**而不能让 transport 自己去读 `ChatRequest`: 端口只收拆开的
    请求要素,是为了让 transport 不依赖洋葱内部的请求类型(P7 端口最内层)。
@@ -70,6 +75,7 @@ class Transport(Protocol):
        reasoning_effort: Effort | None,
        first_token_event: asyncio.Event | None,
        content_event: asyncio.Event | None,
        response_mode: ResponseMode,
    ) -> TransportResult: ...
@@ -284,7 +290,7 @@ class TelemetryStatusProvider(Protocol):
@runtime_checkable
 class TelemetryRecorder(Protocol):
-    """遥测后端;38 字段冻结(M1 设计 §4.4 + issue #3/#4/#11/#16/#20 + 1.3.5/1.3.8),唯一调用点是 TelemetryEmitter。
+    """遥测后端;39 字段冻结(M1 设计 §4.4 + issue #3/#4/#11/#16/#20 + 1.3.5/1.3.8/1.3.10),唯一调用点是 TelemetryEmitter。
    新增参数不设默认值: 库外无第三方实现者(三项目迁移时删除了各自的同名
    Protocol),完整签名的成本为零,而少写一列会被 emitter 的降级吞成 warning。
@@ -351,4 +357,5 @@ class TelemetryRecorder(Protocol):
        total_latency_ms: int | None,
        stall_ms: int | None,
        stall_count: int | None,
        stream_end: str | None,
    ) -> None: ...
@@ -5,8 +5,8 @@
 多处各存一份必然漂移,而漂移的表现是"下游照打印的 SQL 建完表,库仍报缺列"。
 **`COLUMNS` 是 INSERT 字段序,不是物理列序**: 数据库自填的 `created_at` 不在其中(它带
-`DEFAULT now()` / `datetime('now')`,库从不显式写它)。物理表列 = 38 个 INSERT 字段 +
+`DEFAULT now()` / `datetime('now')`,库从不显式写它)。物理表列 = 39 个 INSERT 字段 +
-`created_at` = 39;列数断言一律按物理列数写,两套口径混用是最易错处。
+`created_at` = 40;列数断言一律按物理列数写,两套口径混用是最易错处。
 本模块只依赖标准库: `telemetry/` 与 `backends/`、`transports/`、`structured/` 同层且
 互不依赖(import-linter 契约执法)。
@@ -64,7 +64,8 @@ CREATE TABLE IF NOT EXISTS llm_calls (
    attempts             INTEGER,
    total_latency_ms     INTEGER,
    stall_ms             INTEGER,
-    stall_count          INTEGER
+    stall_count          INTEGER,
    stream_end           TEXT
 );
 """
@@ -108,7 +109,8 @@ CREATE TABLE IF NOT EXISTS llm_calls (
    attempts             INTEGER,
    total_latency_ms     INTEGER,
    stall_ms             INTEGER,
-    stall_count          INTEGER
+    stall_count          INTEGER,
    stream_end           TEXT
 );
 """
@@ -145,6 +147,8 @@ SQLITE_BACKFILL = (
    # 没记过这件事",与"观测过且零沉默"(0)是两回事
    ("stall_ms", "INTEGER"),
    ("stall_count", "INTEGER"),
    # 1.3.10 结束方式(#31): 可空无默认,旧行 NULL = 补列之前没记过;值域见 StreamEnd
    ("stream_end", "TEXT"),
 )
 # PG 补列的列定义。语句由此派生成两份文本(见下),使"库内执行的那份"与"打印给
@@ -174,6 +178,8 @@ _PG_BACKFILL_DECLS = (
    # 1.3.8 两列,列序与 SQLITE_BACKFILL 逐项对齐(理由同上)
    ("stall_ms", "INTEGER"),
    ("stall_count", "INTEGER"),
    # 1.3.10 结束方式(#31): 可空无默认,旧行 NULL = 补列之前没记过;值域见 StreamEnd
    ("stream_end", "TEXT"),
 )
 # 新列排在 created_at 之后: 与旧表 ALTER 追加的位置一致(见 SQLITE_BACKFILL 同款注释)。
@@ -226,6 +232,8 @@ COLUMNS = (
    # —— 1.3.8 沉默归因(issue #27)——
    "stall_ms",
    "stall_count",
    # —— 1.3.10 结束方式(#31)——
    "stream_end",
 )
 _COLUMN_SET = frozenset(COLUMNS)
@@ -143,7 +143,7 @@ class SQLiteRecorder:
                    logger.warning("SQLite 遥测补列失败(写入将逐行降级): {}", exc)
    async def record_llm_call(self, **fields: object) -> None:
-        """写一行遥测;字段集合即 38 字段冻结签名(ports.TelemetryRecorder)。
+        """写一行遥测;字段集合即 39 字段冻结签名(ports.TelemetryRecorder)。
        取值按 `self._columns`(manual 档可能已被裁剪),与 `self._insert` 的
        占位符同序——两者必须一起改,分开改就是把值写进错位的列。
@@ -0,0 +1,455 @@
 """OpenAI 单 choice 消息聚合：仅协议值处理，不做 I/O 或治理。
 1.3.10(#30): null 一律视为缺省;已知字段沿用 1.3.9 语义;未知字段按 OpenAI 流式
 累加惯例无损合并,冲突删键并登记路径——方言是确定性的,拒绝只会让重试重演同一失败。
 """
 import copy
 from dataclasses import dataclass
 from typing import Any
 from polygateway.errors import TransientError
 from polygateway.types import OpenAIChatCompletion, ResponseMode
 _DELTA_KNOWN = frozenset({"role", "content", "reasoning_content", "tool_calls"})
 _TOOL_KNOWN = frozenset({"index", "id", "type", "function"})
 _FUNCTION_KNOWN = frozenset({"name", "arguments"})
 # 标签键: 每帧可能重复下发的身份/格式标记,同值幂等,绝不拼接(拼成 "x-v1x-v1"
 # 回传上游会被拒);也不算生成进展
 _LABEL_KEYS = frozenset({"index", "type", "id", "format"})
 def _invalid(reason: str) -> TransientError:
    """协议形态失败，不回显可能敏感的工具参数。"""
    return TransientError(f"OpenAI 协议失败: {reason}", operation="chat")
 def _object(value: Any, name: str) -> dict[str, Any]:
    """外部对象先校验再读取。"""
    if not isinstance(value, dict):
        raise _invalid(f"{name} 必须为对象")
    return value
 def _identity(target: dict[str, Any], key: str, value: Any) -> bool:
    """身份字段只接受同值重复，不把重复完整 ID 当分片拼接。"""
    if value is None:
        return False
    if not isinstance(value, str):
        raise _invalid(f"{key} 必须为字符串")
    if key in target and target[key] != value:
        raise _invalid(f"{key} 冲突")
    changed = key not in target and bool(value)
    target[key] = value
    return changed
 def _append(target: dict[str, Any], key: str, value: Any) -> str:
    """字符串片段逐字拼接，保留缺省/null/空串区别。"""
    if value is None:
        target.setdefault(key, None)
        return ""
    if not isinstance(value, str):
        raise _invalid(f"{key} 必须为字符串或 null")
    target[key] = (target.get(key) or "") + value
    return value
 def _assemble(message: dict[str, Any], tools: dict[int, dict[str, Any]]) -> dict[str, Any]:
    """按 index 排序组装工具;`finish()` 与 `raw_message()` 共用,判定与快照同源。"""
    assembled = copy.deepcopy(message)
    if tools:
        assembled["tool_calls"] = [copy.deepcopy(tools[index]) for index in sorted(tools)]
    return assembled
 def _completion(message: dict[str, Any], metadata: dict[str, Any]) -> OpenAIChatCompletion:
    """复用内核最终快照校验并翻译领域错误。"""
    try:
        return OpenAIChatCompletion(
            message, metadata.get("finish_reason"), metadata.get("id"), metadata.get("usage")
        )
    except (ValueError, TypeError) as exc:
        raise _invalid(str(exc)) from exc
 # —— 未知字段合并(设计 §5.2) ——
 class _MergeConflictError(Exception):
    """合并冲突(内部控制流): 由 `_ExtensionMerger.merge_key` 就地收口为删键。"""
 def _is_indexed(items: list[Any]) -> bool:
    """数组元素(忽略 null)均为带整数 index 的对象。"""
    present = [item for item in items if item is not None]
    return bool(present) and all(
        isinstance(item, dict) and type(item.get("index")) is int for item in present
    )
 def _fragment_progress(key: str, value: Any) -> bool:
    """不落盘的活性判据(文本模式): 非标签键上的非空字符串片段。"""
    if isinstance(value, str):
        return key not in _LABEL_KEYS and value != ""
    if isinstance(value, dict):
        return any(_fragment_progress(k, v) for k, v in value.items())
    if isinstance(value, list):
        return any(_fragment_progress(key, item) for item in value)
    return False
 class _ExtensionMerger:
    """每尝试私有的未知字段合并器;冲突路径即封禁,后续同路径值丢弃。"""
    def __init__(self) -> None:
        self.conflicts: set[str] = set()
        self._array_modes: dict[str, bool] = {}
    def merge_key(self, target: dict[str, Any], key: str, value: Any, path: str) -> bool:
        """合并一个键;返回是否并入了非空字符串片段(活性)。"""
        if path in self.conflicts:
            return False
        if value is None:
            target.setdefault(key, None)
            return False
        try:
            merged, grew = self._merge(target.get(key), value, key, path)
        except _MergeConflictError:
            target.pop(key, None)
            self.conflicts.add(path)
            return False
        target[key] = merged
        return grew
    def _merge(self, old: Any, new: Any, key: str, path: str) -> tuple[Any, bool]:
        if isinstance(new, dict):
            return self._merge_dict(old, new, path)
        if isinstance(new, list):
            return self._merge_list(old, new, key, path)
        if key in _LABEL_KEYS or not isinstance(new, str):
            return self._merge_scalar(old, new)
        if old is not None and not isinstance(old, str):
            raise _MergeConflictError
        return (old or "") + new, new != ""
    @staticmethod
    def _merge_scalar(old: Any, new: Any) -> tuple[Any, bool]:
        """标签键与数字/布尔: 同值幂等,不同值冲突(不学 SDK 相加,计数相加会造假)。"""
        if old is None:
            return new, False
        if type(old) is type(new) and old == new:
            return old, False
        raise _MergeConflictError
    def _merge_dict(self, old: Any, new: dict[str, Any], path: str) -> tuple[Any, bool]:
        if old is not None and not isinstance(old, dict):
            raise _MergeConflictError
        target = old if old is not None else {}
        grew = False
        for sub_key, sub_value in new.items():
            grew |= self.merge_key(target, sub_key, sub_value, f"{path}.{sub_key}")
        return target, grew
    def _merge_list(self, old: Any, new: list[Any], key: str, path: str) -> tuple[Any, bool]:
        if old is not None and not isinstance(old, list):
            raise _MergeConflictError
        target = old if old is not None else []
        items = [item for item in new if item is not None]
        if not items:
            return target, False
        indexed = _is_indexed(items)
        if self._array_modes.setdefault(path, indexed) != indexed:
            raise _MergeConflictError  # 形态改变: 首次出现决定合并策略
        if indexed:
            return target, self._merge_indexed(target, items, f"{path}[]")
        return target, self._merge_appended(target, items, key, f"{path}[]")
    def _merge_appended(self, target: list[Any], items: list[Any], key: str, path: str) -> bool:
        grew = False
        for item in items:
            merged, item_grew = self._merge(None, item, key, path)
            target.append(merged)
            grew |= item_grew
        return grew
    def _merge_indexed(self, target: list[Any], items: list[Any], path: str) -> bool:
        grew = False
        for item in items:
            slot = next((e for e in target if e.get("index") == item["index"]), None)
            if slot is None:
                slot = {}
                target.append(slot)
            grew |= self._merge_dict(slot, item, path)[1]
        return grew
@dataclass(frozen=True)
 class ChatDelta:
    """一帧提取结果；progress 表示真实生成进展。
    `reasoning` 是 `reasoning` 字段(vLLM/OpenRouter 新名)的片段,投影 thinking 时
    作为 `reasoning_content` 缺席时的别名(设计 §4.4)。
    """
    content: str
    reasoning_content: str
    progress: bool
    reasoning: str = ""
 class ChatCompletionAccumulator:
    """每次 transport 尝试独享的聚合器，文本模式不严格校验工具产物。"""
    def __init__(self, *, response_mode: ResponseMode) -> None:
        """初始化尝试私有状态。"""
        self.mode = response_mode
        self.message: dict[str, Any] = {}
        self.metadata: dict[str, Any] = {}
        self.tools: dict[int, dict[str, Any]] = {}
        self._merger = _ExtensionMerger()
        self._finish_seen = False
        self._usage_after_finish = False
    # —— 只读视图(transport 判定消费) ——
    @property
    def finish_reason(self) -> str | None:
        """choice 0 首个非 null finish_reason;未见为 None。"""
        return self.metadata.get("finish_reason")
    @property
    def finish_seen(self) -> bool:
        """是否已收到 finish_reason。"""
        return self._finish_seen
    @property
    def usage_after_finish(self) -> bool:
        """finish 同帧或之后是否收到非 null usage(设计 §4.2)。"""
        return self._usage_after_finish
    @property
    def conflicts(self) -> frozenset[str]:
        """被删除的冲突键路径(数组下标已归一为 `[]`)。"""
        return frozenset(self._merger.conflicts)
    def raw_message(self) -> dict[str, Any]:
        """未校验的合并消息深拷贝(含排序工具),供构造快照前的结局判定。"""
        return _assemble(self.message, self.tools)
    # —— 聚合 ——
    def add_chunk(self, chunk: dict[str, Any]) -> ChatDelta:
        """聚合一个已解码帧，一帧至多一个活性事件。"""
        chunk = _object(chunk, "chunk")
        if self.mode == "openai":
            _identity(self.metadata, "id", chunk.get("id"))
        choice = self._take_choice(chunk.get("choices"))
        delta = self._take_delta(choice) if choice is not None else ChatDelta("", "", False)
        self._take_usage(chunk.get("usage"))
        return delta
    def _take_usage(self, usage: Any) -> None:
        """usage 在 finish 处理之后登记,使同帧 finish+usage 算作"之后"。"""
        if usage is None:
            return
        self.metadata["usage"] = _object(usage, "usage")
        if self._finish_seen:
            self._usage_after_finish = True
    def _take_choice(self, choices: Any) -> dict[str, Any] | None:
        """选出本帧 choice 并登记 finish;usage-only 帧返回 None。"""
        if choices is None:
            return None
        if not isinstance(choices, list):
            raise _invalid("choices 必须为数组")
        if not choices:
            return None
        if self.mode == "openai":
            if len(choices) != 1:
                raise _invalid("仅支持单 choice")
            choice = _object(choices[0], "choice")
            if type(choice.get("index")) is not int or choice["index"] != 0:
                raise _invalid("choice index 必须为 0")
            _identity(self.metadata, "finish_reason", choice.get("finish_reason"))
        else:
            choice = self._text_choice(choices)
            if choice is None:
                return None
        self._finish_seen = self._finish_seen or self.finish_reason is not None
        return choice
    def _text_choice(self, choices: list[Any]) -> dict[str, Any] | None:
        """文本模式取 index 缺省或为 0 的首个 choice,不混入其他 choice(n>1)。"""
        for raw in choices:
            choice = _object(raw, "choice")
            index = choice.get("index")
            # null 视缺省(=0);bool 不得冒充 0(`False == 0` 为真)
            if index is None or (type(index) is int and index == 0):
                finish = choice.get("finish_reason")
                if isinstance(finish, str) and "finish_reason" not in self.metadata:
                    self.metadata["finish_reason"] = finish
                return choice
        return None
    def _take_delta(self, choice: dict[str, Any]) -> ChatDelta:
        """拆分已知与未知字段;已知字段语义逐字沿用 1.3.9。"""
        raw_delta = choice.get("delta")
        delta = _object(raw_delta if raw_delta is not None else {}, "delta")
        if self.mode == "openai" and "role" in delta:
            self._take_role(delta["role"])
        content = self._take_text(delta, "content")
        reasoning_content = self._take_text(delta, "reasoning_content")
        alias = delta.get("reasoning") if isinstance(delta.get("reasoning"), str) else ""
        progress = bool(content or reasoning_content)
        if "tool_calls" in delta:
            progress |= self._take_tools(delta["tool_calls"])
        progress |= self._take_unknown(delta)
        return ChatDelta(content, reasoning_content, progress, alias)
    def _take_role(self, role: Any) -> None:
        if role is None:
            self.message.setdefault("role", None)
            return
        if role != "assistant":
            raise _invalid("role 必须为 assistant")
        self.message["role"] = role
    def _take_text(self, delta: dict[str, Any], key: str) -> str:
        if key not in delta:
            return ""
        if self.mode == "openai" or delta[key] is not None:
            return _append(self.message, key, delta[key])
        return ""
    def _take_unknown(self, delta: dict[str, Any]) -> bool:
        """未知 delta 键: 保真合并进 message;文本只算活性。"""
        grew = False
        for key, value in delta.items():
            if key in _DELTA_KNOWN:
                continue
            if self.mode == "openai":
                grew |= self._merger.merge_key(self.message, key, value, f"delta.{key}")
            else:
                grew |= _fragment_progress(key, value)
        return grew
    def _take_tools(self, tools: Any) -> bool:
        if self.mode != "openai":
            return isinstance(tools, list) and self._each_tool(tools, self._text_tool_progress)
        if tools is None:
            self.message.setdefault("tool_calls", None)
            return False
        if not isinstance(tools, list):
            raise _invalid("tool_calls 必须为数组")
        present = [tool for tool in tools if tool is not None]
        if self.message.get("tool_calls") is None and (present or not tools):
            # 显式 [] 原样保留;[null] 不造空数组(回传空 tool_calls 会被上游拒)
            self.message["tool_calls"] = []
        return self._each_tool(present, lambda raw: self._take_tool(_object(raw, "tool")))
    @staticmethod
    def _each_tool(tools: list[Any], take: Any) -> bool:
        """逐个非 null 工具增量聚合,返回本帧是否有进展。"""
        progress = False
        for raw in tools:
            if raw is not None:
                progress |= take(raw)
        return progress
    def _text_tool_progress(self, raw: Any) -> bool:
        """文本只消费可识别的工具进展，不承诺工具完整性。"""
        if not isinstance(raw, dict) or type(raw.get("index")) is not int:
            return False
        tool = self.tools.setdefault(raw["index"], {})
        progress = False
        for key in ("id", "type"):
            if isinstance(raw.get(key), str) and raw[key] and key not in tool:
                tool[key] = raw[key]
                progress = True
        fn = raw.get("function")
        if isinstance(fn, dict):
            progress |= any(
                isinstance(fn.get(k), str) and bool(fn[k]) for k in ("name", "arguments")
            )
        return progress
    def _take_tool(self, raw: dict[str, Any]) -> bool:
        index = raw.get("index")
        if type(index) is not int or index < 0:
            raise _invalid("tool index 必须为非负整数")
        tool = self.tools.setdefault(index, {})
        progress = _identity(tool, "id", raw.get("id"))
        progress |= _identity(tool, "type", raw.get("type"))
        if raw.get("function") is not None:
            progress |= self._take_function(tool, _object(raw["function"], "function"))
        for key, value in raw.items():
            if key not in _TOOL_KNOWN:
                progress |= self._merger.merge_key(tool, key, value, f"tool_calls[].{key}")
        return progress
    def _take_function(self, tool: dict[str, Any], fn: dict[str, Any]) -> bool:
        target = tool.setdefault("function", {})
        progress = False
        for key, value in fn.items():
            if key in _FUNCTION_KNOWN:
                progress |= bool(_append(target, key, value))
            else:
                path = f"tool_calls[].function.{key}"
                progress |= self._merger.merge_key(target, key, value, path)
        return progress
    def finish(self) -> OpenAIChatCompletion:
        """线路完整性由调用者保证；此处只校验最终消息。"""
        return _completion(self.raw_message(), self.metadata)
 def _strip_null_tools(message: dict[str, Any]) -> dict[str, Any]:
    """null 工具元素剔除: 与流式跳过同口径,原样回传 [null] 会被上游拒。"""
    tools = message.get("tool_calls")
    if isinstance(tools, list) and None in tools:
        kept = [tool for tool in tools if tool is not None]
        # 全为 null 视同 tool_calls:null,不造会被上游拒收的空数组
        return {**message, "tool_calls": kept or None}
    return message
 def _single_choice(body: dict[str, Any]) -> dict[str, Any]:
    """恰好一个 choice,index 缺省或为 0;拒绝静默截取多 choice。"""
    choices = body.get("choices")
    if not isinstance(choices, list) or len(choices) != 1:
        raise _invalid("仅支持单 choice")
    choice = _object(choices[0], "choice")
    if "index" in choice and (type(choice["index"]) is not int or choice["index"] != 0):
        raise _invalid("choice index 必须为 0")
    return choice
 def check_completion_body(body: Any) -> tuple[dict[str, Any], str | None]:
    """非流式保真形态校验(不构造快照): 单 choice、index 为 0、finish 为字符串或 null。
    与快照构造拆开: 结局判定要先于构造(截断的半截工具须判 ResultInvalid,
    构造时抛 Transient 就到不了那一行,设计 §4.3 行 2)。
    """
    choice = _single_choice(_object(body, "body"))
    finish = choice.get("finish_reason")
    if finish is not None and not isinstance(finish, str):
        raise _invalid("finish_reason 必须为字符串或 null")
    message = _object(choice.get("message"), "message")
    if message.get("role") != "assistant":
        # 形态失败先于结局判定,否则缺 role 的截断工具会被归成 ResultInvalid
        raise _invalid("role 必须为 assistant")
    return _strip_null_tools(message), finish
 def build_completion(
    message: dict[str, Any], body: dict[str, Any], finish: str | None
 ) -> OpenAIChatCompletion:
    """非流式快照构造;保留消息扩展字段。"""
    return _completion(message, {**body, "finish_reason": finish})
 def parse_chat_completion(body: dict[str, Any]) -> OpenAIChatCompletion:
    """非流式完整消息保留扩展字段，拒绝静默截取多 choice。"""
    message, finish = check_completion_body(body)
    return build_completion(message, body, finish)
@@ -12,7 +12,7 @@ import json
 import math
 import re
 import time
-from dataclasses import replace
+from dataclasses import dataclass, field, replace
 from typing import TYPE_CHECKING, Any
 import httpx
@@ -38,11 +38,24 @@ from polygateway.thinking import (
    validate_thinking_raw,
 )
 from polygateway.transports._http_errors import compose_message, summarize_body
 from polygateway.transports._openai_completion import (
    ChatCompletionAccumulator,
    ChatDelta,
    build_completion,
    check_completion_body,
 )
 from polygateway.types import (
    Effort,
    EmbeddingTransportResult,
    ResponseMode,
    SourceConfig,
    StreamEnd,
    TransportResult,
    _classify_finish,
    _judge_outcome,
    _stream_is_complete,
    _summarize_message,
    _summarize_text,
 )
 if TYPE_CHECKING:
@@ -50,6 +63,10 @@ if TYPE_CHECKING:
    from collections.abc import AsyncIterator, Callable, Mapping
 _THINK_PATTERN = re.compile(r"<think>(.*?)</think>", re.DOTALL)
 # 方言告警节流上限与 finish 值截断(设计 §5.4): 键由上游决定,必须有界
 _WARN_CAP = 1024
 _FINISH_WARN_CHARS = 64
 _PATH_WARN_CHARS = 128
 # —— SSE 纯函数(VT llm.py 同款)——
@@ -62,29 +79,6 @@ def _sse_data_payload(raw: str) -> str | None:
    return line[len("data:") :].strip()
 def _sse_delta(chunk: dict[str, Any], usage_sink: dict[str, Any]) -> tuple[bool, str] | None:
    """从 chunk 提取增量: (True, content) 或 (False, reasoning);usage 帧旁路进 sink。"""
    if chunk.get("usage"):
        usage_sink["usage"] = chunk["usage"]
    if "model" not in usage_sink:
        # 首个**有效**值即固定: 末帧的异常值不得覆盖它;但首帧报空串也不能锁死
        # sink——否则后续真实版本会丢(issue #3)
        reported = _coerce_model_reported(chunk.get("model"))
        if reported is not None:
            usage_sink["model"] = reported
    choices = chunk.get("choices") or []
    if not choices:
        return None
    delta = choices[0].get("delta") or {}
    content = delta.get("content")
    if content:
        return (True, content)
    reasoning = delta.get("reasoning_content")
    if reasoning:
        return (False, reasoning)
    return None
 def _stall_from_chunk_times(
    times: list[float], threshold_ms: int
 ) -> tuple[float | None, float | None]:
@@ -108,10 +102,25 @@ def _stall_from_chunk_times(
    return (total, float(count)) if count else (0.0, 0.0)
 def _check_chat_error(chunk: Any) -> None:
    """所有模式拒绝顶层 error；诊断复用有界摘要。"""
    if not isinstance(chunk, dict):
        raise TransientError("chat 响应必须为 JSON 对象", operation="chat")
    if "error" in chunk:
        summary = summarize_body(json.dumps({"error": chunk["error"]}, ensure_ascii=False))
        raise TransientError(
            compose_message("上游 chat error 帧", summary), operation="chat", body_text=summary
        )
    if chunk.get("usage") is not None and not isinstance(chunk["usage"], dict):
        raise TransientError("chat usage 必须为对象或 null", operation="chat")
 async def _iter_sse_deltas(
-    lines: AsyncIterator[str], usage_sink: dict[str, Any]
+    lines: AsyncIterator[str],
-) -> AsyncIterator[tuple[bool, str]]:
+    usage_sink: dict[str, Any],
-    """逐行解析 SSE 流;[DONE] 置 sink["done"];畸形 JSON 帧 → 瞬时错误(可重试)。"""
+    accumulator: ChatCompletionAccumulator,
 ) -> AsyncIterator[ChatDelta]:
    """解析 SSE，一帧只产生一次进展事件。"""
    async for raw in lines:
        data = _sse_data_payload(raw)
        if data is None:
@@ -122,14 +131,138 @@ async def _iter_sse_deltas(
        try:
            chunk = json.loads(data)
        except json.JSONDecodeError as exc:
-            raise TransientError(
+            raise TransientError("SSE 帧畸形(malformed_json)", operation="chat") from exc
-                f"SSE 帧畸形(malformed_json): {data[:80]!r}", operation="chat"
+        _check_chat_error(chunk)
-            ) from exc
+        if chunk.get("usage") is not None:
-        delta = _sse_delta(chunk, usage_sink)
+            usage_sink["usage"] = chunk["usage"]
-        if delta is not None:
+        if "model" not in usage_sink:
            model = _coerce_model_reported(chunk.get("model"))
            if model is not None:
                usage_sink["model"] = model
        delta = accumulator.add_chunk(chunk)
        if delta.progress:
            yield delta
@dataclass
 class _StreamTiming:
    """一次流式尝试的计时与文本片段(每尝试新建,不跨重试/对冲共享)。"""
    content_parts: list[str] = field(default_factory=list)
    reasoning_parts: list[str] = field(default_factory=list)
    alias_parts: list[str] = field(default_factory=list)
    chunk_times: list[float] = field(default_factory=list)
    ttft_ms: float | None = None
    max_gap: float = 0.0
    @property
    def has_reasoning(self) -> bool:
        """出现过非空 reasoning_content: 别名 `reasoning` 让位(设计 §4.4)。"""
        return bool(self.reasoning_parts)
 async def _consume_deltas(
    guarded: AsyncIterator[ChatDelta],
    started: float,
    first_token_event: asyncio.Event | None,
    content_event: asyncio.Event | None,
 ) -> _StreamTiming:
    """消费进展事件: 计时、置位对冲事件、收集文本片段。"""
    timing = _StreamTiming()
    last = started
    async for delta in guarded:
        now = time.monotonic()
        # 增量 chunk 时间戳(1.3.8 沉默计量): 循环体只会被真实增量触发——
        # 空 chunk/usage 帧/SSE keepalive 已在聚合器被过滤
        timing.chunk_times.append(now)
        if content_event is not None:
            # 每个增量 chunk 置位一次: 中段沉默对冲的活性复位信号
            content_event.set()
        if timing.ttft_ms is None:
            timing.ttft_ms = (now - started) * 1000
            # 首个增量即对冲语义上的"首 token"(思考增量同样是存活证据,
            # 与看门狗活性口径一致);None = 调用方未启用对冲,零分支成本
            if first_token_event is not None:
                first_token_event.set()
        else:
            timing.max_gap = max(timing.max_gap, (now - last) * 1000)
        last = now
        for parts, text in (
            (timing.content_parts, delta.content),
            (timing.reasoning_parts, delta.reasoning_content),
            (timing.alias_parts, delta.reasoning),
        ):
            if text:
                parts.append(text)
    return timing
 def _raise_unless_deliverable(
    mode: ResponseMode,
    message: dict[str, Any] | None,
    content: str,
    thinking: str,
    finish_reason: str | None,
    source: SourceConfig,
 ) -> None:
    """结局判定(设计 §4.3)的唯一翻译点: 判定值 → 领域错误。
    原因码以固定格式进 message(遥测 error 列可检索);不回显推理/工具内容。
    """
    if mode == "openai" and message is not None:
        summary = _summarize_message(message, content)
    else:
        summary = _summarize_text(content, thinking)
    verdict = _judge_outcome(mode=mode, summary=summary, finish=_classify_finish(finish_reason))
    if verdict.deliver:
        return
    text = (
        f"{source.name} {verdict.code}: finish_reason={finish_reason!r}, "
        f"thinking_len={len(thinking)}"
    )
    if verdict.error_kind == "result_invalid":
        raise ResultInvalidError(text, raw_text="", source_name=source.name, operation="chat")
    raise TransientError(text, source_name=source.name, operation="chat")
 def _text_choice(body: dict[str, Any], source: SourceConfig) -> tuple[Any, str | None]:
    """文本模式取首个 choice 的 message 与 finish(非字符串 finish 记 None)。"""
    choices = body.get("choices") or []
    if not choices:
        raise TransientError(
            f"{source.name} 响应缺 choices", source_name=source.name, operation="chat"
        )
    if not isinstance(choices, list) or not isinstance(choices[0], dict):
        raise TransientError("chat choices 形态非法", operation="chat")
    finish = choices[0].get("finish_reason")
    return choices[0].get("message", {}), finish if isinstance(finish, str) else None
 def _nonstream_message(
    body: dict[str, Any], mode: ResponseMode, source: SourceConfig
 ) -> tuple[dict[str, Any], str | None]:
    """非流式取单 choice 的原始 message 与 finish;只校验形态,不构造快照。"""
    if mode == "openai":
        message, finish = check_completion_body(body)
    else:
        message, finish = _text_choice(body, source)
    if not isinstance(message, dict) or any(
        message.get(key) is not None and not isinstance(message[key], str)
        for key in ("content", "reasoning_content")
    ):
        raise TransientError("chat message 形态非法", operation="chat")
    return message, finish
 def _reasoning_of(message: dict[str, Any]) -> str:
    """非流式思考投影: 非空 reasoning_content 优先,否则 `reasoning` 别名。"""
    primary = message.get("reasoning_content")
    if isinstance(primary, str) and primary:
        return primary
    alias = message.get("reasoning")
    return alias if isinstance(alias, str) else ""
 # —— 错误翻译(CHS invokers.py 同款)——
@@ -387,6 +520,9 @@ class OpenAICompatTransport:
        # 都会连带改掉另一侧的行为。(键空间恰好不相交,故当下**不会**互相压制;
        # 分开维护的理由是语义,不是碰撞)
        self._warned_mismatches: set[tuple[str, str, Effort | None]] = set()
        # 方言告警(1.3.10)另立集合: 冲突删键/未知 finish 与推理对账语义无关
        self._warned_fields: set[tuple[str, str]] = set()
        self._warn_saturated = False
        self._client_factory = client_factory or _default_client_factory
        self._clients: dict[str, httpx.AsyncClient] = {}
@@ -458,6 +594,7 @@ class OpenAICompatTransport:
        reasoning_effort: Effort | None,
        first_token_event: asyncio.Event | None,
        content_event: asyncio.Event | None,
        response_mode: ResponseMode,
    ) -> TransportResult:
        """一次原始调用;HTTP/线路/流式异常按 ARCH §6.2 翻译为领域错误。
@@ -468,6 +605,16 @@ class OpenAICompatTransport:
        `content_event` 为中段沉默对冲处置位(1.3.8): 同款约定,流式路径**每个**
        增量 chunk 置位一次,非流式路径收它但永不置位。
        """
        if response_mode not in ("text", "openai"):
            raise RequestRejectedError(
                "非法 response_mode", source_name=source.name, operation="chat"
            )
        if response_mode == "openai":
            for layer in (source.extra_body, overlay):
                if "n" in layer and (type(layer["n"]) is not int or layer["n"] != 1):
                    raise RequestRejectedError(
                        "openai 模式仅支持 n=1", source_name=source.name, operation="chat"
                    )
        profile = get_provider(source.provider, registry=self._registry)
        try:
            payload, applied_effort = self._build_payload(
@@ -492,12 +639,30 @@ class OpenAICompatTransport:
        try:
            if stream:
                result = await self._complete_stream(
-                    client, url, payload, source, profile, first_token_event, content_event
+                    client,
                    url,
                    payload,
                    source,
                    profile,
                    first_token_event,
                    content_event,
                    response_mode,
                )
            else:
                result = await self._complete_once(
-                    client, url, payload, source, profile, first_token_event, content_event
+                    client,
                    url,
                    payload,
                    source,
                    profile,
                    first_token_event,
                    content_event,
                    response_mode,
                )
        except TransientError as exc:
            if exc.source_name is None:
                exc.source_name = source.name
            raise
        except StreamLivenessTimeout as exc:
            raise TransientError(f"{source.name} 流活性超时({exc.kind})", **ctx) from exc
        except httpx.TimeoutException as exc:
@@ -585,6 +750,7 @@ class OpenAICompatTransport:
        profile: ProviderProfile,
        first_token_event: asyncio.Event | None,
        content_event: asyncio.Event | None,
        response_mode: ResponseMode,
    ) -> TransportResult:
        started = time.monotonic()
        async with client.stream("POST", url, json=payload) as resp:
@@ -594,55 +760,59 @@ class OpenAICompatTransport:
                    source, resp.status_code, body, resp.headers, operation="chat"
                )
            sink: dict[str, Any] = {}
            accumulator = ChatCompletionAccumulator(response_mode=response_mode)
            guarded = stream_with_liveness_timeouts(
-                _iter_sse_deltas(resp.aiter_lines(), sink),
+                _iter_sse_deltas(resp.aiter_lines(), sink, accumulator),
                ttft_s=source.ttft_timeout_s or source.timeout_s,
                inter_token_s=source.inter_token_timeout_s or source.timeout_s,
                total_s=source.timeout_s,
            )
-            content_parts: list[str] = []
+            timing = await _consume_deltas(guarded, started, first_token_event, content_event)
-            thinking_parts: list[str] = []
+        return self._stream_result(sink, accumulator, timing, source, profile, response_mode)
-            ttft_ms: float | None = None
+
-            last = started
+    def _stream_result(
-            max_gap = 0.0
+        self,
-            chunk_times: list[float] = []
+        sink: dict[str, Any],
-            async for is_content, text in guarded:
+        accumulator: ChatCompletionAccumulator,
-                now = time.monotonic()
+        timing: _StreamTiming,
-                # 增量 chunk 时间戳(1.3.8 沉默计量): 循环体只会被真实增量触发——
+        source: SourceConfig,
-                # 空 chunk/usage 帧/SSE keepalive 已在 _sse_data_payload/_sse_delta
+        profile: ProviderProfile,
-                # 被过滤,这里逐字追加即可;阈值判定不在热路径,派生收敛在
+        response_mode: ResponseMode,
-                # _stall_from_chunk_times(设计 §3 派生原则)
+    ) -> TransportResult:
-                chunk_times.append(now)
+        """流结束后的统一判定(设计 §4.2-§4.3): 完整性 → 结局 → 组装。"""
-                if content_event is not None:
+        self._warn_dialect(source, accumulator.conflicts, accumulator.finish_reason)
-                    # 每个增量 chunk 置位一次: 中段沉默对冲的活性复位信号
+        thinking_parts = timing.reasoning_parts if timing.has_reasoning else timing.alias_parts
-                    content_event.set()
+        content, thinking = self._finalize_text(timing.content_parts, thinking_parts, profile)
-                if ttft_ms is None:
+        stream_end = _stream_is_complete(
-                    ttft_ms = (now - started) * 1000
+            done=bool(sink.get("done")),
-                    # 首个增量即对冲语义上的"首 token"(思考增量同样是存活证据,
+            finish_reason=accumulator.finish_reason,
-                    # 与看门狗活性口径一致);None = 调用方未启用对冲,零分支成本
+            usage_after_finish=accumulator.usage_after_finish,
-                    if first_token_event is not None:
+            usage_measured=_resolve_usage(sink.get("usage") or {})[2] == "measured",
-                        first_token_event.set()
+        )
-                else:
+        if stream_end is None:
-                    max_gap = max(max_gap, (now - last) * 1000)
+            stream_end = self._truncated(timing, thinking_parts, source, response_mode)
-                last = now
+        message = accumulator.raw_message() if response_mode == "openai" else None
-                (content_parts if is_content else thinking_parts).append(text)
+        _raise_unless_deliverable(
-        salvaged = self._check_done(sink, content_parts, thinking_parts, source)
+            response_mode, message, content, thinking, accumulator.finish_reason, source
-        content, thinking = self._finalize_text(content_parts, thinking_parts, profile)
+        )
-        self._reject_empty_completion(content, source)
+        completion_result = accumulator.finish() if response_mode == "openai" else None
-        prompt, completion, usage_source = _resolve_stream_usage(sink, salvaged)
+        prompt, completion, usage_source = _resolve_stream_usage(sink, stream_end == "salvaged")
        reasoning_tokens = _coerce_reasoning_tokens(sink.get("usage"))
-        stall_ms, stall_count = _stall_from_chunk_times(chunk_times, source.stall_threshold_ms)
+        stall_ms, stall_count = _stall_from_chunk_times(
            timing.chunk_times, source.stall_threshold_ms
        )
        return TransportResult(
            content=content,
            thinking=thinking,
            prompt_tokens=prompt,
            completion_tokens=completion,
            usage_source=usage_source,
-            ttft_ms=ttft_ms,
+            ttft_ms=timing.ttft_ms,
-            max_inter_token_ms=(max_gap if ttft_ms is not None else None),
+            max_inter_token_ms=(timing.max_gap if timing.ttft_ms is not None else None),
            stall_ms=stall_ms,
            stall_count=stall_count,
            raw={"usage": sink.get("usage")},
            completion=completion_result,
            cached_prompt_tokens=_coerce_cached_tokens(sink.get("usage")),
            model_reported=_coerce_model_reported(sink.get("model")),
            reasoning_tokens=reasoning_tokens,
@@ -651,38 +821,56 @@ class OpenAICompatTransport:
            thinking_observation=observe_thinking(
                thinking=thinking, reasoning_tokens=reasoning_tokens
            ),
            finish_reason=accumulator.finish_reason,
            stream_end=stream_end,
        )
-    def _check_done(
+    def _truncated(
        self,
-        sink: dict[str, Any],
+        timing: _StreamTiming,
        content_parts: list[str],
        thinking_parts: list[str],
        source: SourceConfig,
-    ) -> bool:
+        response_mode: ResponseMode,
-        """缺 [DONE] 语义(设计 §6): 零内容恒 retry;有内容按 missing_done 策略。"""
+    ) -> StreamEnd:
-        if sink.get("done"):
+        """截断流(设计 §4.2): 保真不打捞;文本按 missing_done,零产物恒 retry。"""
            return False
        ctx: dict[str, Any] = {"source_name": source.name, "operation": "chat"}
-        if not content_parts and not thinking_parts:
+        if response_mode == "openai":
            raise TransientError(f"{source.name} missing_done: 保真响应截断,禁止打捞", **ctx)
        if not any(timing.content_parts) and not any(thinking_parts):
            raise TransientError(f"{source.name} SSE early_eof: 零内容断流", **ctx)
        if source.missing_done == "retry":
            raise TransientError(f"{source.name} SSE missing_done: 截断且无 [DONE]", **ctx)
-        return True
+        return "salvaged"
-    def _reject_empty_completion(self, content: str, source: SourceConfig) -> None:
+    def _warn_dialect(
-        """空补全 → 瞬时错误(2026-07-20 人类裁决,M1 验证发现)。
+        self, source: SourceConfig, conflicts: frozenset[str], finish_reason: str | None
-
+    ) -> None:
-        服务 200 且流程完整([DONE]/usage 正常)但 content 为空——MiniMax 等
+        """方言告警: 冲突删键与未登记 finish 各按 (源, 路径/值) 只喊一次。"""
-        网关的间歇异常形态。视为服务抖动: 退避重试/换源,**绝不缓存空响应**;
+        for raw_path in sorted(conflicts):
-        承 CHS "VLM 零 content"归瞬时的先例(invokers.py:309)。
+            path = raw_path[:_PATH_WARN_CHARS]  # 键名由上游决定,长度同样须有界
-        """
+            self._warn_once(
-        if not content.strip():
+                source.name, f"field:{path}", f"字段 {path} 合并冲突已删除,保真结果缺该字段"
            raise TransientError(
                f"{source.name} 空补全(empty_completion): 流程完整但零内容",
                source_name=source.name,
                operation="chat",
            )
        if finish_reason is not None and _classify_finish(finish_reason) == "unknown":
            value = finish_reason[:_FINISH_WARN_CHARS]
            self._warn_once(
                source.name,
                f"finish:{value}",
                f"未登记的 finish_reason {value!r},按正常结束交付,该值的结果不缓存",
            )
    def _warn_once(self, source_name: str, key: str, text: str) -> None:
        """有界节流: 键由上游决定,长跑 worker 不能让集合无限增长(设计 §5.4)。"""
        if (source_name, key) in self._warned_fields:
            return
        if len(self._warned_fields) >= _WARN_CAP:
            if not self._warn_saturated:
                self._warn_saturated = True
                logger.warning("方言告警节流集合已饱和({}),后续同类告警省略", _WARN_CAP)
            return
        self._warned_fields.add((source_name, key))
        # 单参数传入 loguru: 文案可能含上游给的花括号(同 `_warn_on_thinking_mismatch`)
        logger.warning("源 {} —— {}", source_name, text)
    def _finalize_text(
        self, content_parts: list[str], thinking_parts: list[str], profile: ProviderProfile
@@ -704,6 +892,7 @@ class OpenAICompatTransport:
        profile: ProviderProfile,
        first_token_event: asyncio.Event | None,
        content_event: asyncio.Event | None,
        response_mode: ResponseMode,
    ) -> TransportResult:
        """非流式快路径(三项目均无,库新增): 单 JSON 响应,仅 total 超时。
@@ -711,6 +900,9 @@ class OpenAICompatTransport:
        为纯时间阈值(对冲只能靠 `hedge_after_s` 触发)。`content_event`(1.3.8)
        同款: 接收但**永不置位**——非流式无"中段"概念,stall 两值走
        TransportResult 默认 None(排除条款)。
        无流完整性可言,直接以 body 的 finish_reason 走结局判定;保真模式**先判定
        后构造快照**,否则半截工具在构造时就抛 Transient,到不了 `tool_truncated`。
        """
        resp = await client.post(url, json=payload)
        if resp.status_code != 200:
@@ -723,16 +915,17 @@ class OpenAICompatTransport:
            raise TransientError(
                f"{source.name} 非流式响应非法 JSON", source_name=source.name, operation="chat"
            ) from exc
-        choices = body.get("choices") or []
+        _check_chat_error(body)
-        if not choices:
+        message, finish = _nonstream_message(body, response_mode, source)
            raise TransientError(
                f"{source.name} 响应缺 choices", source_name=source.name, operation="chat"
            )
        message = choices[0].get("message") or {}
        content, thinking = self._finalize_text(
-            [message.get("content") or ""], [message.get("reasoning_content") or ""], profile
+            [message.get("content") or ""], [_reasoning_of(message)], profile
        )
        self._warn_dialect(source, frozenset(), finish)
        raw_message = message if response_mode == "openai" else None
        _raise_unless_deliverable(response_mode, raw_message, content, thinking, finish, source)
        completion_result = (
            build_completion(message, body, finish) if response_mode == "openai" else None
        )
        self._reject_empty_completion(content, source)
        prompt, completion, usage_source = _resolve_usage(body.get("usage") or {})
        reasoning_tokens = _coerce_reasoning_tokens(body.get("usage"))
        return TransportResult(
@@ -744,6 +937,7 @@ class OpenAICompatTransport:
            ttft_ms=None,
            max_inter_token_ms=None,
            raw={"usage": body.get("usage")},
            completion=completion_result,
            cached_prompt_tokens=_coerce_cached_tokens(body.get("usage")),
            model_reported=_coerce_model_reported(body.get("model")),
            reasoning_tokens=reasoning_tokens,
@@ -752,6 +946,7 @@ class OpenAICompatTransport:
            thinking_observation=observe_thinking(
                thinking=thinking, reasoning_tokens=reasoning_tokens
            ),
            finish_reason=finish,
        )
    async def aclose(self) -> None:
@@ -4,6 +4,7 @@
 fake,字段顺序即公共承诺;新增字段只增不删且必带默认值。
 """
 import copy
 import dataclasses
 import json
 import math
@@ -422,6 +423,280 @@ class _CallContext:
        return True
 ResponseMode = Literal["text", "openai"]
 StreamEnd = Literal["done", "eof_after_finish", "salvaged"]
 """流式结束方式(1.3.10, #31): `done` = 收到 `[DONE]`;`eof_after_finish` = 未发
 `[DONE]` 但 finish_reason 与其后的实测 usage 齐全、连接干净关闭;`salvaged` = 文本
 模式按 `missing_done=salvage` 打捞的截断结果。非流式/缓存命中/失败行为 `None`。"""
 FinishClass = Literal["natural", "truncated", "filtered", "upstream_error", "unknown", "absent"]
@dataclass(frozen=True)
 class OpenAIChatCompletion:
    """单 choice 协议结果，构造时快照隔离；嵌套 JSON 仍可变。"""
    message: dict[str, Any]
    finish_reason: str | None
    response_id: str | None
    usage: dict[str, Any] | None
    def __post_init__(self) -> None:
        """校验协议快照；transport 翻译错误，缓存坏条目按 miss。"""
        message = self.message
        _check_completion_shape(message, self.finish_reason, self.response_id, self.usage)
        json.dumps({"message": message, "usage": self.usage}, allow_nan=False)
        object.__setattr__(self, "message", copy.deepcopy(message))
        object.__setattr__(self, "usage", copy.deepcopy(self.usage))
 def _check_completion_shape(message: Any, finish_reason: Any, response_id: Any, usage: Any) -> None:
    """快照字段形态校验;违约抛 ValueError(由 transport/缓存各自翻译)。"""
    if not isinstance(message, dict) or message.get("role") != "assistant":
        raise ValueError("completion message 必须含 assistant role")
    if not all(_str_or_none(message.get(key)) for key in ("content", "reasoning_content")):
        raise ValueError("completion content/reasoning_content 必须为字符串或 null")
    if not (_str_or_none(finish_reason) and _str_or_none(response_id)):
        raise ValueError("completion 身份/结束原因必须为字符串或 null")
    if not isinstance(usage, dict | None):
        raise ValueError("completion usage 必须为对象或 null")
    if not isinstance(message.get("tool_calls", []), list | None):
        raise ValueError("completion tool_calls 必须为数组或 null")
    if not _tool_snapshot_ok(message):
        raise ValueError("completion tool 身份/函数字段缺失、冲突或非法")
 def _str_or_none(value: Any) -> bool:
    """协议字符串字段的形态判据: 字符串或 null。"""
    return value is None or isinstance(value, str)
 def _tool_ok(tool: Any, seen: set[str]) -> bool:
    """单个工具条目是否满足快照不变式;成立时登记其 id 供查重。"""
    if not isinstance(tool, dict):
        return False
    identity, fn = tool.get("id"), tool.get("function")
    ok = (
        isinstance(identity, str)
        and bool(identity)
        and identity not in seen
        and tool.get("type") == "function"
        and isinstance(fn, dict)
        and isinstance(fn.get("name"), str)
        and bool(fn["name"])
        and isinstance(fn.get("arguments"), str)
    )
    if ok:
        seen.add(identity)
    return ok
 def _tool_snapshot_ok(message: Mapping[str, Any]) -> bool:
    """工具快照不变式(1.3.9 规则): 缺省/null 视无工具;null 元素跳过。
    抽成纯判据而非留在快照构造里: 结局判定(#30)要在构造**之前**知道工具是否
    成立——截断的半截工具归 ResultInvalid,构造时抛 Transient 就到不了那一行。
    """
    tools = message.get("tool_calls")
    if tools is None:
        return True
    if not isinstance(tools, list):
        return False
    seen: set[str] = set()
    return all(tool is None or _tool_ok(tool, seen) for tool in tools)
 _FINISH_CLASSES: Mapping[str, FinishClass] = MappingProxyType(
    {
        "stop": "natural",
        "tool_calls": "natural",
        "function_call": "natural",
        "length": "truncated",
        "content_filter": "filtered",
        "sensitive": "filtered",  # GLM: 安全审核拦截
        "network_error": "upstream_error",  # GLM: 模型推理异常
        "error": "upstream_error",
    }
 )
 def _classify_finish(value: str | None) -> FinishClass:
    """finish_reason → 类别;大小写敏感(上游原值),未登记非空值为 unknown。"""
    if value is None:
        return "absent"
    return _FINISH_CLASSES.get(value, "unknown")
 def _stream_is_complete(
    *, done: bool, finish_reason: str | None, usage_after_finish: bool, usage_measured: bool
 ) -> StreamEnd | None:
    """流完整性(设计 §4.2): None = 截断。
    缺 `[DONE]` 时只认"上游声明结束 + 其后到达的实测 usage": 前者证明生成结束,
    后者证明流走到了 include_usage 的自然末尾(finish 之前的累计 usage 不算)。
    """
    if done:
        return "done"
    if finish_reason is not None and usage_after_finish and usage_measured:
        return "eof_after_finish"
    return None
@dataclass(frozen=True)
 class _OutputSummary:
    """一次结果的产物摘要(设计 §4.3 定义),判定的唯一输入形态。"""
    any_output: bool
    body_output: bool
    tools_present: bool
    tools_ok: bool
    null_arguments: bool = False
    """工具快照仅因 `function.arguments` 全程 null 而不成立(无参函数方言,审查 I2)。"""
 def _summarize_text(content: str, thinking: str) -> _OutputSummary:
    """文本模式: 产物只看投影正文与思考;空白也算产物,正文须非空白。"""
    return _OutputSummary(
        any_output=content != "" or thinking != "",
        body_output=content.strip() != "",
        tools_present=False,
        tools_ok=True,
    )
 def _has_string(value: Any) -> bool:
    """递归查找任一非空字符串片段。"""
    if isinstance(value, str):
        return value != ""
    if isinstance(value, dict):
        return any(_has_string(item) for item in value.values())
    if isinstance(value, list):
        return any(_has_string(item) for item in value)
    return False
 def _summarize_message(message: Mapping[str, Any], projected_content: str) -> _OutputSummary:
    """保真模式: 任一非空字符串字段(role 除外)或工具条目即产物。"""
    tools = message.get("tool_calls")
    tools_present = isinstance(tools, list) and any(tool is not None for tool in tools)
    tools_ok = _tool_snapshot_ok(message)
    fields = {k: v for k, v in message.items() if k not in ("role", "tool_calls")}
    return _OutputSummary(
        any_output=tools_present or _has_string(fields),
        body_output=projected_content.strip() != "" or (tools_present and tools_ok),
        tools_present=tools_present,
        tools_ok=tools_ok,
        null_arguments=not tools_ok and _tool_snapshot_ok(_fill_null_arguments(message)),
    )
 def _fill_null_arguments(message: Mapping[str, Any]) -> dict[str, Any]:
    """仅供判定: 把 null arguments 视作空串后再验快照,区分"只缺参数"与其他缺陷。
    不改写交付值——保真结果原样;此函数的产物只用于分类。
    """
    tools = message.get("tool_calls")
    if not isinstance(tools, list):
        return dict(message)
    filled = []
    for tool in tools:
        fn = tool.get("function") if isinstance(tool, dict) else None
        if isinstance(fn, dict) and "arguments" in fn and fn["arguments"] is None:
            tool = {**tool, "function": {**fn, "arguments": ""}}
        filled.append(tool)
    return {**message, "tool_calls": filled}
@dataclass(frozen=True)
 class _Verdict:
    """结局判定;`deliver` 为真时另两字段为 None。"""
    deliver: bool
    error_kind: Literal["transient", "result_invalid"] | None
    code: str | None
 _DELIVER = _Verdict(True, None, None)
 _EMPTY = _Verdict(False, "transient", "empty_completion")
 _WITHOUT_CONTENT: Mapping[str, str] = MappingProxyType(
    {"truncated": "length_without_content", "filtered": "filtered_without_content"}
 )
 def _judge_broken(
    *, mode: ResponseMode, summary: _OutputSummary, finish: FinishClass
 ) -> _Verdict | None:
    """行 1-2: 上游自报失败、坏工具——先于产物判断,正文不得掩盖。"""
    if finish == "upstream_error":
        return _Verdict(False, "transient", "upstream_finish_error")
    if mode == "openai" and summary.tools_present and not summary.tools_ok:
        if finish == "truncated":
            return _Verdict(False, "result_invalid", "tool_truncated")
        if summary.null_arguments:
            # 无参函数只发 arguments:null 是确定性方言: 重拉同样结果,不重试也不改写
            return _Verdict(False, "result_invalid", "tool_arguments_null")
        return _Verdict(False, "transient", "tool_incomplete")
    return None
 def _judge_outcome(*, mode: ResponseMode, summary: _OutputSummary, finish: FinishClass) -> _Verdict:
    """结局分类(设计 §4.3),自上而下首个匹配行生效。
    确定性结局(length/过滤)在文本模式归 ResultInvalid 而非 Transient: 重抽只会
    再花一份钱,还会把健康源推向熔断;保真模式原样交回,由下游按 finish 决定。
    """
    broken = _judge_broken(mode=mode, summary=summary, finish=finish)
    if broken is not None:
        return broken
    if summary.body_output:
        return _DELIVER
    if finish in _WITHOUT_CONTENT:  # 行 3/6/7: 确定性结局
        if mode == "openai":
            return _DELIVER
        return _Verdict(False, "result_invalid", _WITHOUT_CONTENT[finish])
    # 行 4/8/9: 零产物恒为抖动;有产物无正文时,只有保真且上游明确声明结束才交回
    if summary.any_output and mode == "openai" and finish != "absent":
        return _DELIVER
    return _EMPTY
 def _effective_finish(finish_reason: Any, completion: OpenAIChatCompletion | None) -> str | None:
    """缓存读写共用的 finish 口径: 顶层优先,缺省回退协议快照(1.3.9 条目无顶层)。"""
    if finish_reason is None and completion is not None:
        return completion.finish_reason
    return finish_reason
 def _is_cacheable(
    *,
    mode: ResponseMode,
    content: str,
    finish_reason: str | None,
    stream_end: str | None,
    completion: OpenAIChatCompletion | None,
 ) -> bool:
    """可缓存 ⊂ 可交付(设计 §6): 截断、空正文、非自然结束一律不进 TTL。
    缓存回放的是"同一请求的确定答案";length/过滤/未知结束带随机性或不可证明
    是自然结束,固化进 TTL 会把一次偶然变成必然(无缓存毒化铁律)。
    """
    if stream_end not in (None, "done", "eof_after_finish"):
        return False
    if _classify_finish(finish_reason) not in ("natural", "absent"):
        return False
    if mode == "openai":
        # 判原文而非投影: 协议原文为空时不信任缓存里的旧投影(1.3.9 同口径)
        if completion is None:
            return False
        raw = completion.message.get("content")
        summary = _summarize_message(completion.message, raw if isinstance(raw, str) else "")
        # 原文与投影都须有正文: 原文空不信任旧投影;投影空(think 标签剥净)不固化空回答
        has_tools = summary.tools_present and summary.tools_ok
        return summary.body_output and (content.strip() != "" or has_tools)
    return content.strip() != ""
@dataclass(frozen=True)
 class LLMResponse:
    """一次治理调用的统一响应(与三项目超集兼容,ARCH §5.1)。"""
@@ -487,6 +762,15 @@ class LLMResponse:
    call_stats: CallStats | None = None
    """本次**逻辑调用**的统计快照(1.3.5);`None` = 未知,不得读成 0。"""
    completion: OpenAIChatCompletion | None = None
    finish_reason: str | None = None
    """上游结束原因原值(1.3.10, #30/#31),两模式同口径;`None` = 未上报或不可观测。"""
    stream_end: StreamEnd | None = None
    """流式结束方式(1.3.10, #31),见 `StreamEnd`。与 `usage_source` 分工: 那个答
    "账单可信吗",这个答"内容完整吗";`eof_after_finish` 必为 measured。"""
@dataclass(frozen=True)
 class ChatRequest:
@@ -543,6 +827,8 @@ class ChatRequest:
    洋葱各层经 `dataclasses.replace` 派生请求时保留**同一引用**(不是拷贝),
    重试/重问/分批才能共享同一个逻辑 ID 与计数。"""
    response_mode: ResponseMode = "text"
@dataclass(frozen=True)
 class Usage:
@@ -627,6 +913,15 @@ class TransportResult:
    """超阈值相邻间隔个数(归因成对报告,Gregg 原则);值域与 `None` 语义同
    `stall_ms`。"""
    completion: OpenAIChatCompletion | None = None
    finish_reason: str | None = None
    """上游结束原因原值(1.3.10, #30/#31),两模式同口径;`None` = 未上报或不可观测。"""
    stream_end: StreamEnd | None = None
    """流式结束方式(1.3.10, #31),见 `StreamEnd`。与 `usage_source` 分工: 那个答
    "账单可信吗",这个答"内容完整吗";`eof_after_finish` 必为 measured。"""
@dataclass(frozen=True)
 class SourceConfig:
@@ -22,7 +22,13 @@ from polygateway.client import (
 )
 from polygateway.providers import get_provider
 from polygateway.transports.openai_compat import OpenAICompatTransport
-from polygateway.types import Effort, EmbeddingTransportResult, SourceConfig, TransportResult
+from polygateway.types import (
    Effort,
    EmbeddingTransportResult,
    ResponseMode,
    SourceConfig,
    TransportResult,
 )
 from tests.live_evidence import (
    AttemptEvidence,
    HttpEvidence,
@@ -293,6 +299,7 @@ class ObservedTransport:
        reasoning_effort: Effort | None,
        first_token_event: asyncio.Event | None,
        content_event: asyncio.Event | None,
        response_mode: ResponseMode,
    ) -> TransportResult:
        """与生产端口逐参数同签名。"""
        with self._capture.attempt_context(call_id):
@@ -306,6 +313,7 @@ class ObservedTransport:
                reasoning_effort=reasoning_effort,
                first_token_event=first_token_event,
                content_event=content_event,
                response_mode=response_mode,
            )
    async def embed(
@@ -0,0 +1,114 @@
 """真实网关工具双轮冒烟；复用安全 Markdown 报告，不运行工具副作用。"""
 import dataclasses
 import json
 import os
 from pathlib import Path
 from uuid import uuid4
 import pytest
 from dotenv import dotenv_values
 from polygateway import GatewayClient, GatewaySettings
 from tests.live_evidence import write_live_round
 _ENV = {k: v for k, v in {**dotenv_values(".env"), **os.environ}.items() if v is not None}
 pytestmark = [pytest.mark.slow, pytest.mark.requires_llm]
@pytest.mark.parametrize("stream", [True, False])
 async def test_tools_two_rounds(stream):
    """已配置源中选首源，只改变测试隔离与 raw-only 意图，不收紧生产超时。"""
    if not any(k.startswith("LLM__") and k.endswith("__API_KEY") for k in _ENV):
        pytest.skip("未配置真实源，未覆盖")
    settings = GatewaySettings.from_env("LLM", env=_ENV)
    source = dataclasses.replace(settings.sources[0], enable_thinking=None, reasoning_effort=None)
    settings = dataclasses.replace(
        settings,
        sources=(source,),
        cache_backend="none",
        cache_namespace=None,
        cache_ttl_s=None,
        telemetry_backend="none",
        telemetry_auto_migrate=False,
        limiter_backend="memory",
        breaker_backend="memory",
        hedge_after_s=None,
        hedge_stall_after_s=None,
    )
    tools = [
        {
            "type": "function",
            "function": {
                "name": "echo_value",
                "description": "Return the supplied value",
                "parameters": {
                    "type": "object",
                    "properties": {"value": {"type": "string"}},
                    "required": ["value"],
                },
            },
        }
    ]
    messages = [
        {
            "role": "user",
            "content": "Call echo_value with value hello. After receiving the tool result, reply with hello.",
        }
    ]
    status, error_type, counts = "FAIL", None, {}
    try:
        async with GatewayClient.from_settings(settings) as client:
            first = await client.chat(
                messages,
                stream=stream,
                response_mode="openai",
                overlay={
                    "tools": tools,
                    "tool_choice": {"type": "function", "function": {"name": "echo_value"}},
                },
            )
            completion = first.completion
            assert completion is not None and completion.message["role"] == "assistant"
            assert completion.response_id and completion.finish_reason == "tool_calls"
            calls = completion.message["tool_calls"]
            counts["tools"] = len(calls)
            assert calls
            messages.append(completion.message)
            for call in calls:
                assert call["function"]["name"] == "echo_value"
                arguments = json.loads(call["function"]["arguments"])
                assert arguments["value"] == "hello"
                messages.append(
                    {"role": "tool", "tool_call_id": call["id"], "content": arguments["value"]}
                )
            second = await client.chat(
                messages,
                stream=stream,
                response_mode="openai",
                overlay={"tools": tools, "tool_choice": "none"},
            )
            assert (
                second.completion is not None and second.completion.message["role"] == "assistant"
            )
            assert "hello" in (second.completion.message.get("content") or "").lower()
            counts["attempts"] = first.call_stats.attempts + second.call_stats.attempts
            status = "PASS"
    except Exception as exc:
        error_type = type(exc).__name__
        raise
    finally:
        write_live_round(
            Path("tests/outputs/issue29/live"),
            run_id=uuid4().hex,
            matrix_id="tools",
            round_index=1,
            safe_fields={
                "status": status,
                "stream": stream,
                "error_type": error_type,
                "counts": counts,
                "planned_rounds": 2,
                "completed_rounds": 2 if status == "PASS" else 0,
            },
        )
@@ -72,6 +72,8 @@ _EXPECTED_COLUMNS = [
    # —— 1.3.8 沉默归因两列(issue #27)——
    "stall_ms",
    "stall_count",
    # —— 1.3.10 结束方式(#31)——
    "stream_end",
 ]
 # 1.3.5 之前那张表的 27 个物理列(26 个 INSERT 字段 + created_at)。写成固定切片
@@ -173,6 +175,8 @@ def _minimal_fields(call_id: str | None = None, **overrides) -> dict[str, object
        # —— 1.3.8 两列: 沉默归因只属流式 chat 成功 attempt 行(issue #27),普通行 NULL ——
        "stall_ms": None,
        "stall_count": None,
        # —— 1.3.10: 结束方式只属流式成功 attempt 行,普通行 NULL ——
        "stream_end": None,
    }
    fields.update(overrides)
    return fields
@@ -775,7 +779,7 @@ class TestCallerDimensionsAcceptance:
                "WHERE table_schema = $1 AND table_name = 'llm_calls' ORDER BY ordinal_position",
                schema,
            )
-            # 22 → 38 个 recorder 字段(加 created_at 共 39 个物理列),且新列追加在末尾
+            # 22 → 39 个 recorder 字段(加 created_at 共 40 个物理列),且新列追加在末尾
            assert [r["column_name"] for r in cols] == _EXPECTED_COLUMNS
            rows = await _fetch(
                schema_dsn,
@@ -1106,7 +1110,7 @@ class TestCallObservabilityColumnsAcceptance:
    """
    async def test_pre_135_table_gains_the_ten_columns_and_old_rows_stay_null(self, pre_135_schema):
-        """27 列旧表 auto 补齐到 39 列(1.3.5 十列 + 1.3.8 两列),新行两类取值读得回,**历史行新增列一律 NULL**。
+        """27 列旧表 auto 补齐到 40 列(1.3.5 十列 + 1.3.8 两列 + 1.3.10 一列),新行两类取值读得回,**历史行新增列一律 NULL**。
        旧行不回填是本版的明示决策(设计 §5): NULL 表达的是"补列之前根本没记过
        这件事",与任何哨兵值都不是一回事。若哪天有人给这十列加了 DEFAULT,历史行
@@ -1148,7 +1152,7 @@ class TestCallObservabilityColumnsAcceptance:
                "WHERE table_schema = $1 AND table_name = 'llm_calls' ORDER BY ordinal_position",
                schema,
            )
-            # 26 → 38 个 recorder 字段(加 created_at 共 39 个物理列),新列追加在末尾:
+            # 26 → 39 个 recorder 字段(加 created_at 共 40 个物理列),新列追加在末尾:
            # 列序与新建库一致才不会让两条升级路径分叉
            assert [r["column_name"] for r in cols] == _EXPECTED_COLUMNS
@@ -1176,6 +1180,8 @@ class TestCallObservabilityColumnsAcceptance:
                # 1.3.8 两列: 普通成功 attempt 行无沉默观测 → NULL
                "stall_ms": None,
                "stall_count": None,
                # 1.3.10: 该行未传结束方式 → NULL
                "stream_end": None,
            }
            assert dict(by_id["term"]) == {
                "call_id": "term",
@@ -1192,6 +1198,8 @@ class TestCallObservabilityColumnsAcceptance:
                # 1.3.8 两列: 终态行无 transport 观测 → NULL
                "stall_ms": None,
                "stall_count": None,
                # 1.3.10: 终态行无流可言 → NULL
                "stream_end": None,
            }
            # 历史行: 十列逐列 NULL(整体比对,漏掉任一列都红)
            assert dict(by_id["pre135"]) == {
@@ -1349,7 +1357,7 @@ class TestPublishedSchemaScript:
        await _execute_script(fresh_dsn, script)
        actual = [r["column_name"] for r in await _fetch(fresh_dsn, _PHYSICAL_COLUMNS_SQL, schema)]
-        # 物理列 = 38 个 INSERT 字段 + 库从不显式写的 created_at;对着库常量比,不另抄一份
+        # 物理列 = 39 个 INSERT 字段 + 库从不显式写的 created_at;对着库常量比,不另抄一份
        assert set(actual) == set(COLUMNS) | {"created_at"}
        # 列序也不许漂: 新列必须排在 created_at 之后,否则新建库与 ALTER 升级的列序分叉
        assert actual == _EXPECTED_COLUMNS
@@ -30,6 +30,13 @@ def _resp(content="cached"):
    return LLMResponse(content, "", "m", "p", 1, 2, 30, None, None, False, "orig")
 def _const(response):
    async def terminal(request):
        return response
    return terminal
@pytest.fixture
 async def redis_cache():
    import redis.asyncio as aioredis
@@ -82,6 +89,23 @@ class TestRealRedisRoundtrip:
        assert first.cache_hit is False and second.cache_hit is True
        assert calls["n"] == 1
    async def test_completion_verdict_fields_roundtrip(self, redis_cache, namespace):
        """1.3.10: finish_reason/stream_end 经真实 Redis 往返;不可缓存结果不落库。"""
        mw = CacheMW(
            backend=redis_cache, model_fingerprint="m", default_namespace=namespace, ttl_s=60
        )
        from dataclasses import replace
        ok = replace(_resp(), finish_reason="stop", stream_end="eof_after_finish")
        first = await mw(ChatRequest(messages=_MSGS), _const(ok))
        second = await mw(ChatRequest(messages=_MSGS), _const(ok))
        assert first.cache_hit is False and second.cache_hit is True
        assert second.finish_reason == "stop" and second.stream_end is None
        truncated = replace(_resp(), stream_end="salvaged")
        other = [{"role": "user", "content": "integration-salvaged"}]
        await mw(ChatRequest(messages=other), _const(truncated))
        assert await redis_cache.get(build_cache_key("m", other, namespace, None)) is None
    async def test_namespace_isolation_on_shared_instance(self, redis_cache, namespace):
        """多项目共用同一 Redis 时,namespace 不同绝不互相命中(防毒化铁律)。"""
        other = f"pgw:test:{uuid.uuid4().hex}"
@@ -172,3 +196,22 @@ class TestClientWithRealRedis:
        second = await client.chat(_MSGS)
        assert first.cache_hit is False and second.cache_hit is True
        assert second.content == "hello"
 async def test_real_completion_roundtrip(redis_cache, namespace):
    """真实 Redis 保存完整嵌套协议对象，命中仍为值类型。"""
    from dataclasses import replace
    from tests.unit.test_openai_completion import accumulate
    completion = accumulate().finish()
    mw = CacheMW(backend=redis_cache, model_fingerprint="m", default_namespace=namespace, ttl_s=60)
    async def terminal(_):
        return replace(_resp(), completion=completion)
    request = ChatRequest(messages=_MSGS, response_mode="openai")
    first = await mw(request, terminal)
    second = await mw(request, terminal)
    assert second.cache_hit and second.completion == first.completion
    assert second.completion is not first.completion
@@ -86,6 +86,7 @@ class ScriptedTransport:
        reasoning_effort,
        first_token_event,
        content_event,
        response_mode,
    ):
        self.calls.append(source.name)
        if self.hang:
@@ -221,6 +221,7 @@ class ClockAdvancingTransport:
        reasoning_effort,
        first_token_event,
        content_event,
        response_mode,
    ):
        self.calls.append((source.name, call_id))
        advance, action = self.script.pop(0)
@@ -15,6 +15,7 @@ from polygateway.types import (
    ChatRequest,
    Effort,
    LLMResponse,
    OpenAIChatCompletion,
    SourceConfig,
    ThinkingObservation,
 )
@@ -891,3 +892,238 @@ class TestCallStatsNotPoisoned:
        without = ChatRequest(messages=_MSGS)
        assert with_ctx.cache_namespace == without.cache_namespace
        assert digest_messages(with_ctx.messages) == digest_messages(without.messages)
 class TestOpenAICompletionCache:
    """协议缓存不得混模式或把字典冒充公共值对象。"""
    def test_mode_isolation_preserves_text_key(self):
        assert build_cache_key("m", _MSGS, "proj", None) == build_cache_key(
            "m", _MSGS, "proj", None, response_mode="text"
        )
        assert build_cache_key("m", _MSGS, "proj", None) != build_cache_key(
            "m", _MSGS, "proj", None, response_mode="openai"
        )
    @pytest.mark.parametrize(
        "completion",
        [
            None,
            {},
            {
                "message": {"content": "ok"},
                "finish_reason": "stop",
                "response_id": None,
                "usage": None,
            },
        ],
    )
    async def test_missing_or_bad_completion_misses(self, completion):
        backend = InMemoryCache()
        mw = CacheMW(backend=backend, model_fingerprint="m", default_namespace="proj", ttl_s=60)
        raw = json.loads(mw._serialize(_resp()))
        raw["completion"] = completion
        assert (
            mw._rehydrate(json.dumps(raw), ChatRequest(messages=_MSGS, response_mode="openai"))
            is None
        )
    async def test_serialization_failure_does_not_fail_call(self):
        mw = CacheMW(
            backend=InMemoryCache(), model_fingerprint="m", default_namespace="proj", ttl_s=60
        )
        response = _resp(cost=object())
        async def terminal(_):
            return response
        assert await mw(ChatRequest(messages=_MSGS), terminal) is response
@pytest.mark.parametrize(
    "message",
    [
        {"role": "assistant"},
        {"role": "assistant", "content": None, "tool_calls": []},
        {"role": "assistant", "content": "", "tool_calls": []},
        {"role": "assistant", "content": " \n", "tool_calls": []},
        {"role": "assistant", "reasoning_content": "reason only"},
    ],
 )
@pytest.mark.parametrize("cached_content", ["", "stale projection"])
 async def test_openai_cache_without_output_misses_and_refills(message, cached_content):
    """空协议产物不能靠旧投影正文伪装成功；miss 后回源并覆写。"""
    backend = InMemoryCache()
    mw = _mw(backend)
    request = ChatRequest(messages=_MSGS, response_mode="openai")
    key = build_cache_key("m", _MSGS, "proj", None, response_mode="openai")
    bad = _resp(
        content=cached_content,
        completion=OpenAIChatCompletion(message, "stop", "bad", None),
    )
    await backend.set(key, mw._serialize(bad), ttl_s=60)
    fresh = _resp(
        completion=OpenAIChatCompletion(
            {"role": "assistant", "content": "cached"}, "stop", "fresh", None
        )
    )
    terminal = _Terminal(fresh)
    result = await mw(request, terminal)
    assert terminal.calls == 1 and result is fresh and not result.cache_hit
    hit = await mw(request, terminal)
    assert terminal.calls == 1 and hit.cache_hit
    assert hit.completion.response_id == "fresh"
 async def test_openai_tool_only_cache_hits_without_origin():
    """有效工具本身是产物，空文本投影不妨碍命中。"""
    backend = InMemoryCache()
    mw = _mw(backend)
    completion = OpenAIChatCompletion(
        {
            "role": "assistant",
            "content": None,
            "tool_calls": [
                {
                    "id": "call-1",
                    "type": "function",
                    "function": {"name": "echo", "arguments": "{}"},
                }
            ],
        },
        "tool_calls",
        "tool-response",
        None,
    )
    request = ChatRequest(messages=_MSGS, response_mode="openai")
    key = build_cache_key("m", _MSGS, "proj", None, response_mode="openai")
    await backend.set(key, mw._serialize(_resp(content="", completion=completion)), ttl_s=60)
    terminal = _Terminal(_resp())
    hit = await mw(request, terminal)
    assert hit.cache_hit and terminal.calls == 0
    assert hit.completion == completion
 # —— 1.3.10(#30/#31): 可缓存 ⊂ 可交付,读写共用同一判据(设计 §6)——
 _OK_COMPLETION = OpenAIChatCompletion({"role": "assistant", "content": "ok"}, "stop", "up", None)
 _THINK_LENGTH = OpenAIChatCompletion(
    {"role": "assistant", "reasoning_content": "t"}, "length", "up", None
 )
 _THINK_STOP = OpenAIChatCompletion(
    {"role": "assistant", "reasoning_content": "t"}, "stop", "up", None
 )
@pytest.mark.parametrize(
    ("mode", "response"),
    [
        ("text", _resp(stream_end="salvaged")),
        ("text", _resp(finish_reason="length")),
        ("text", _resp(finish_reason="content_filter")),
        ("text", _resp(finish_reason="end_turn")),
        ("openai", _resp(content="", finish_reason="length", completion=_THINK_LENGTH)),
        ("openai", _resp(content="", finish_reason="stop", completion=_THINK_STOP)),
    ],
 )
 async def test_uncacheable_results_are_delivered_but_not_written(mode, response):
    """截断/空正文/非自然结束: 照常交回,但不写缓存,下次回源。"""
    backend = InMemoryCache()
    mw = _mw(backend)
    terminal = _Terminal(response)
    request = ChatRequest(messages=_MSGS, response_mode=mode)
    assert (await mw(request, terminal)) is response
    assert (await mw(request, terminal)).cache_hit is False
    assert terminal.calls == 2 and not backend._store
 def _stored(mode, **fields):
    """直接注入一条缓存原文(模拟旧版本或别的进程写入)。"""
    backend = InMemoryCache()
    data = dataclasses.asdict(_resp(**fields))
    data.pop("structured_data", None)
    data.pop("call_stats", None)
    key = build_cache_key("m", _MSGS, "proj", None, response_mode=mode)
    backend._store[key] = (float("inf"), json.dumps(data))
    return backend, key
 async def _hit(backend, mode):
    terminal = _Terminal(_resp(content="fresh", completion=_OK_COMPLETION, finish_reason="stop"))
    response = await _mw(backend)(ChatRequest(messages=_MSGS, response_mode=mode), terminal)
    return response, terminal.calls
@pytest.mark.parametrize(
    ("mode", "fields"),
    [
        ("text", {"stream_end": "salvaged"}),
        ("text", {"stream_end": "bogus"}),
        ("text", {"finish_reason": "length"}),
        ("text", {"finish_reason": 5}),
        ("openai", {"content": "", "completion": _THINK_LENGTH, "finish_reason": "length"}),
    ],
 )
 async def test_injected_uncacheable_entries_read_as_miss(mode, fields):
    """读路径对存储原值判定(覆盖之前): 不可缓存即 miss 回源。"""
    backend, _ = _stored(mode, **fields)
    response, calls = await _hit(backend, mode)
    assert response.cache_hit is False and calls == 1
 async def test_legacy_fidelity_length_entry_falls_back_to_completion_finish():
    """1.3.9 保真条目无顶层 finish: 回退 completion.finish_reason 识别为不可缓存。"""
    completion = OpenAIChatCompletion({"role": "assistant", "content": "a"}, "length", None, None)
    backend, key = _stored("openai", completion=completion)
    data = json.loads(backend._store[key][1])
    for name in ("finish_reason", "stream_end"):
        data.pop(name)
    backend._store[key] = (float("inf"), json.dumps(data))
    response, calls = await _hit(backend, "openai")
    assert response.cache_hit is False and calls == 1
 async def test_legacy_text_entry_without_new_fields_still_hits():
    """1.3.9 文本条目无新键: 仍命中;命中 stream_end=None。"""
    backend, key = _stored("text")
    data = json.loads(backend._store[key][1])
    for name in ("finish_reason", "stream_end"):
        data.pop(name)
    backend._store[key] = (float("inf"), json.dumps(data))
    response, calls = await _hit(backend, "text")
    assert response.cache_hit is True and calls == 0
    assert response.stream_end is None and response.finish_reason is None
 async def test_hit_resets_stream_end_and_keeps_effective_finish():
    """命中: stream_end 置 None;finish_reason 取判定所用值(顶层缺省时回退)。"""
    backend, key = _stored("openai", completion=_OK_COMPLETION, stream_end="eof_after_finish")
    data = json.loads(backend._store[key][1])
    data.pop("finish_reason")
    backend._store[key] = (float("inf"), json.dumps(data))
    response, calls = await _hit(backend, "openai")
    assert response.cache_hit is True and calls == 0
    assert response.stream_end is None and response.finish_reason == "stop"
 async def test_new_fields_roundtrip_through_cache():
    """两新字段随序列化往返;命中只重置 stream_end。"""
    backend = InMemoryCache()
    mw = _mw(backend)
    terminal = _Terminal(_resp(finish_reason="stop", stream_end="eof_after_finish"))
    await mw(ChatRequest(messages=_MSGS), terminal)
    stored = json.loads(next(iter(backend._store.values()))[1])
    assert stored["finish_reason"] == "stop" and stored["stream_end"] == "eof_after_finish"
    hit = await mw(ChatRequest(messages=_MSGS), terminal)
    assert hit.cache_hit is True and hit.finish_reason == "stop" and hit.stream_end is None
 async def test_fidelity_think_only_projection_not_cached():
    """审查 I1: qwen think 标签剥离后投影为空的保真结果不写缓存。"""
    completion = OpenAIChatCompletion(
        {"role": "assistant", "content": "<think>x</think>"}, "stop", "up", None
    )
    response = _resp(content="", thinking="x", finish_reason="stop", completion=completion)
    backend = InMemoryCache()
    await _mw(backend)(ChatRequest(messages=_MSGS, response_mode="openai"), _Terminal(response))
    assert not backend._store
@@ -232,6 +232,7 @@ class _ScriptedGenClockTransport:
        reasoning_effort,
        first_token_event,
        content_event,
        response_mode,
    ):
        self.calls.append(call_id)
        result = self._results.pop(0)
@@ -1844,6 +1845,7 @@ class _ClockJumpTransport:
        reasoning_effort,
        first_token_event,
        content_event,
        response_mode,
    ):
        self.calls.append(call_id)
        self._clock.advance(self._jump)
@@ -0,0 +1,453 @@
 """统一完成判定在 transport 两条路径上的落点(#30/#31,设计 §4.2-§4.4、§5.4)。
 假 SSE 按 magpie/glm 实测形态二次构造: 末块 finish_reason + usage 后干净关闭、
 不发 [DONE];以及只有思考的 length 截断、null/未知字段等方言。
 """
 import asyncio
 import json
 import httpx
 import pytest
 from loguru import logger
 from polygateway.errors import AllSourcesExhausted, ResultInvalidError, TransientError
 from polygateway.transports.openai_compat import OpenAICompatTransport
 from tests.unit.test_openai_compat import _complete, _source, _sse_stream, _transport_for
 _USAGE = {"prompt_tokens": 11, "completion_tokens": 7}
 _TOOL = {
    "index": 0,
    "id": "call_1",
    "type": "function",
    "function": {"name": "lookup", "arguments": '{"q": 1}'},
 }
 def _f(delta=None, finish=None, usage=None, choices=True):
    """单 choice 帧;`choices=False` 构造 usage-only 帧。"""
    body = {"id": "up-1"}
    if choices:
        choice = {"index": 0, "delta": delta or {}}
        if finish is not None:
            choice["finish_reason"] = finish
        body["choices"] = [choice]
    else:
        body["choices"] = []
    if usage is not None:
        body["usage"] = usage
    return f"data: {json.dumps(body)}\n\n"
 def _assistant(**delta):
    return _f({"role": "assistant", **delta})
 async def _run(frames, *, done, mode="text", **source_kw):
    transport = _transport_for(lambda _: _sse_stream(*frames, done=done))
    try:
        return await _complete(transport, _source(**source_kw), response_mode=mode)
    finally:
        await transport.aclose()
 async def _run_once(body, *, mode="text"):
    transport = _transport_for(lambda _: httpx.Response(200, json=body))
    try:
        return await _complete(transport, _source(), stream=False, response_mode=mode)
    finally:
        await transport.aclose()
 # —— #31: 缺 [DONE] 但 finish + 其后实测 usage 完整 ——
@pytest.mark.parametrize("mode", ["text", "openai"])
@pytest.mark.parametrize("finish", ["stop", "length"])
 async def test_eof_after_finish_with_usage_succeeds(mode, finish):
    """验收 1: 末块 finish + usage 后干净关闭 → 成功、measured、eof_after_finish。"""
    frames = [_assistant(content="hel"), _f({"content": "lo"}, finish=finish, usage=_USAGE)]
    result = await _run(frames, done=False, mode=mode)
    assert result.content == "hello" and result.stream_end == "eof_after_finish"
    assert result.usage_source == "measured" and result.finish_reason == finish
    assert (result.prompt_tokens, result.completion_tokens) == (11, 7)
    if mode == "openai":
        assert result.completion.finish_reason == finish
 async def test_eof_after_finish_usage_only_frame_and_tools():
    """验收 2: tool_calls 结束、usage 在其后的 usage-only 帧 → 工具完整交回。"""
    frames = [
        _assistant(content=None, tool_calls=[_TOOL]),
        _f({}, finish="tool_calls"),
        _f(choices=False, usage=_USAGE),
    ]
    result = await _run(frames, done=False, mode="openai")
    tool = result.completion.message["tool_calls"][0]
    assert tool["function"] == {"name": "lookup", "arguments": '{"q": 1}'}
    assert result.stream_end == "eof_after_finish" and result.usage_source == "measured"
@pytest.mark.parametrize(
    "frames",
    [
        [_assistant(content="partial"), _f(choices=False, usage=_USAGE)],  # 验收 3: 无 finish
        [_assistant(content="partial"), _f({}, finish="stop")],  # 验收 4: 无 usage
        [_assistant(content="a", **{}), _f({}, usage=_USAGE), _f({}, finish="stop")],  # usage 早
        [_assistant(content="a"), _f({}, finish="stop", usage={})],  # usage 不可用
    ],
 )
 async def test_incomplete_eof_still_fails(frames):
    """截断不放宽: 保真仍不打捞,文本 retry 档仍抛。"""
    with pytest.raises(TransientError, match="missing_done"):
        await _run(frames, done=False, mode="openai", missing_done="salvage")
    with pytest.raises(TransientError, match="missing_done"):
        await _run(frames, done=False)
 async def test_text_salvage_marks_stream_end():
    """文本 salvage 打捞 → stream_end=salvaged,usage 降为 estimated。"""
    frames = [_assistant(content="partial"), _f(choices=False, usage=_USAGE)]
    result = await _run(frames, done=False, missing_done="salvage")
    assert result.stream_end == "salvaged" and result.usage_source == "estimated"
 async def test_read_error_mid_stream_fails():
    """验收 5: 读取中途 RemoteProtocolError → 失败,不当干净 EOF。"""
    class Broken(httpx.AsyncByteStream):
        async def __aiter__(self):
            yield _f({"role": "assistant", "content": "a"}, finish="stop", usage=_USAGE).encode()
            raise httpx.RemoteProtocolError("peer closed")
        async def aclose(self):
            return None
    transport = _transport_for(lambda _: httpx.Response(200, stream=Broken()))
    try:
        with pytest.raises(TransientError, match="网络错误"):
            await _complete(transport, _source(), response_mode="openai")
    finally:
        await transport.aclose()
@pytest.mark.parametrize("mode", ["text", "openai"])
 async def test_done_stream_marks_done(mode):
    """验收 6: 带 [DONE] 的正常流行为不变,stream_end=done。"""
    result = await _run([_assistant(content="ok"), _f({}, "stop", _USAGE)], done=True, mode=mode)
    assert result.stream_end == "done" and result.finish_reason == "stop"
@pytest.mark.parametrize("done", [True, False])
@pytest.mark.parametrize("mode", ["text", "openai"])
 async def test_upstream_error_finish_is_transient(done, mode):
    """GLM network_error: 上游自报失败,有正文也不交付。"""
    frames = [_assistant(content="half"), _f({}, finish="network_error", usage=_USAGE)]
    with pytest.raises(TransientError, match="upstream_finish_error"):
        await _run(frames, done=done, mode=mode)
 # —— #30 与结局表(设计 §4.3)——
 _THINK = [_assistant(reasoning_content="long thought")]
@pytest.mark.parametrize("done", [True, False])
 async def test_openai_reasoning_only_length_delivered(done):
    """#30 验收: 只有思考 + length → 交回,content 空,思考完整。"""
    result = await _run([*_THINK, _f({}, "length", _USAGE)], done=done, mode="openai")
    message = result.completion.message
    assert message.get("content") in (None, "") and message["reasoning_content"] == "long thought"
    assert result.finish_reason == "length" and result.thinking == "long thought"
@pytest.mark.parametrize(
    ("frames", "finish", "openai_ok", "text_error"),
    [
        (_THINK, "length", True, (ResultInvalidError, "length_without_content")),
        ([_assistant()], "length", True, (ResultInvalidError, "length_without_content")),
        (_THINK, "content_filter", True, (ResultInvalidError, "filtered_without_content")),
        ([_assistant()], "sensitive", True, (ResultInvalidError, "filtered_without_content")),
        (_THINK, "stop", True, (TransientError, "empty_completion")),
        ([_assistant(refusal="no")], "stop", True, (TransientError, "empty_completion")),
        ([_assistant()], "stop", False, (TransientError, "empty_completion")),
    ],
 )
 async def test_outcome_rows_stream(frames, finish, openai_ok, text_error):
    """行 3/4/6/7/8: 两模式的分叉。"""
    full = [*frames, _f({}, finish, _USAGE)]
    if openai_ok:
        assert (await _run(full, done=True, mode="openai")).finish_reason == finish
    else:
        with pytest.raises(TransientError, match="empty_completion"):
            await _run(full, done=True, mode="openai")
    error, code = text_error
    with pytest.raises(error, match=code) as caught:
        await _run(full, done=True)
    assert caught.type is error  # ResultInvalid 不得被 Transient 子类掩盖
@pytest.mark.parametrize("mode", ["text", "openai"])
 async def test_reasoning_only_without_finish_is_transient(mode):
    """行 9: 只靠 DONE 收尾、无 finish → 无法区分抖动与结局,维持瞬时。"""
    with pytest.raises(TransientError, match="empty_completion"):
        await _run([*_THINK, _f(choices=False, usage=_USAGE)], done=True, mode=mode)
 async def test_openai_whitespace_content_stop_delivered():
    """正文只有空白 + stop: 保真交回(#30 一-2)。"""
    result = await _run(
        [_assistant(content="  "), _f({}, "stop", _USAGE)], done=True, mode="openai"
    )
    assert result.completion.message["content"] == "  "
 async def test_truncated_tool_is_result_invalid():
    """行 2: length 截断的半截工具(缺 name)→ ResultInvalid tool_truncated。"""
    broken = {"index": 0, "id": "c", "type": "function", "function": {"arguments": '{"q'}}
    frames = [_assistant(tool_calls=[broken]), _f({}, "length", _USAGE)]
    with pytest.raises(ResultInvalidError, match="tool_truncated"):
        await _run(frames, done=True, mode="openai")
 async def test_content_cannot_mask_broken_tool():
    """行 2: 正文非空 + 坏工具 + stop → Transient tool_incomplete。"""
    broken = {"index": 0, "id": "c", "type": "function", "function": {"arguments": "{}"}}
    frames = [_assistant(content="text", tool_calls=[broken]), _f({}, "stop", _USAGE)]
    with pytest.raises(TransientError, match="tool_incomplete"):
        await _run(frames, done=True, mode="openai")
 async def test_null_refusal_and_tool_calls_stream():
    """#30 验收二: delta 带 refusal:null 与 tool_calls:null → 正常交回。"""
    frames = [_assistant(content="ok", refusal=None, tool_calls=None), _f({}, "stop", _USAGE)]
    result = await _run(frames, done=True, mode="openai")
    assert result.completion.message["content"] == "ok"
 # —— 非流式镜像 ——
 def _body(message, finish):
    choice = {"index": 0, "message": {"role": "assistant", **message}}
    if finish is not None:
        choice["finish_reason"] = finish
    return {"id": "up", "choices": [choice], "usage": _USAGE}
 async def test_nonstream_null_tool_calls_and_refusal():
    """非流式 message 带 tool_calls:null + refusal:null → 成功。"""
    body = _body({"content": "hi", "tool_calls": None, "refusal": None}, "stop")
    result = await _run_once(body, mode="openai")
    assert result.completion.message["tool_calls"] is None and result.stream_end is None
@pytest.mark.parametrize(
    ("message", "finish", "openai_expect", "text_expect"),
    [
        (
            {"reasoning_content": "t"},
            "length",
            None,
            (ResultInvalidError, "length_without_content"),
        ),
        ({"content": ""}, "content_filter", None, (ResultInvalidError, "filtered_without_content")),
        ({"reasoning_content": "t"}, "stop", None, (TransientError, "empty_completion")),
        ({"reasoning_content": "t"}, None, (TransientError, "empty_completion"), None),
        ({"content": "a"}, "network_error", (TransientError, "upstream_finish_error"), None),
        ({"content": "a"}, "length", None, None),
    ],
 )
 async def test_outcome_rows_nonstream(message, finish, openai_expect, text_expect):
    """非流式跳过流完整性,直接以 body finish 走结局表。"""
    body = _body(message, finish)
    for mode, expect in (("openai", openai_expect), ("text", text_expect or openai_expect)):
        if expect is None:
            result = await _run_once(body, mode=mode)
            assert result.finish_reason == finish and result.stream_end is None
        else:
            with pytest.raises(expect[0], match=expect[1]) as caught:
                await _run_once(body, mode=mode)
            assert caught.type is expect[0]
 async def test_nonstream_truncated_tool_is_result_invalid():
    """非流式先判定后构造快照: 缺 name + length → tool_truncated 而非构造期 Transient。"""
    tool = {"id": "c", "type": "function", "function": {"arguments": "{"}}
    with pytest.raises(ResultInvalidError, match="tool_truncated"):
        await _run_once(_body({"tool_calls": [tool]}, "length"), mode="openai")
 # —— reasoning 别名(设计 §4.4)——
 async def test_reasoning_alias_projects_thinking():
    """只有 reasoning 字段: 文本 thinking 取别名;非空 reasoning_content 优先。"""
    alias = await _run(
        [_assistant(reasoning="r1"), _f({"content": "a"}, "stop", _USAGE)], done=True
    )
    assert alias.thinking == "r1"
    both = [
        _assistant(reasoning="r1", reasoning_content="rc"),
        _f({"content": "a"}, "stop", _USAGE),
    ]
    assert (await _run(both, done=True)).thinking == "rc"
    empty_rc = [_assistant(reasoning="r1", reasoning_content=""), _f({"content": "a"}, "stop")]
    assert (await _run(empty_rc, done=True)).thinking == "r1"
    nonstream = await _run_once(_body({"content": "a", "reasoning": "nr"}, "stop"))
    assert nonstream.thinking == "nr"
 async def test_reasoning_alias_keeps_ttft_alive():
    """只有 reasoning 的思考期刷新活性,不被 TTFT 看门狗误杀。"""
    class Slow(httpx.AsyncByteStream):
        async def __aiter__(self):
            yield _assistant().encode()
            for _ in range(5):  # 0.5s 只有 reasoning,远超 ttft,但每帧间隔 < inter_token
                yield _f({"reasoning": "t"}).encode()
                await asyncio.sleep(0.1)
            yield _f({"content": "answer"}, "stop", _USAGE).encode()
            yield b"data: [DONE]\n\n"
        async def aclose(self):
            return None
    transport = _transport_for(lambda _: httpx.Response(200, stream=Slow()))
    try:
        source = _source(ttft_timeout_s=0.3, inter_token_timeout_s=0.25)
        result = await _complete(transport, source)
        assert result.content == "answer" and result.thinking == "ttttt"
    finally:
        await transport.aclose()
 # —— 有界告警节流(设计 §5.4)——
 def _sink():
    records = []
    handle = logger.add(lambda m: records.append(m.record["message"]), level="WARNING")
    return records, handle
 async def test_conflict_and_unknown_finish_warn_once():
    """同源同路径冲突、同一未知 finish 值各只告警一次,不回显字段值。"""
    frames = [
        _assistant(content="a", ext=1),
        _f({"ext": 2}),
        _f({}, "end_turn", _USAGE),
    ]
    transport = _transport_for(lambda _: _sse_stream(*frames))
    records, handle = _sink()
    try:
        for _ in range(2):
            result = await _complete(transport, _source(), response_mode="openai")
            assert "ext" not in result.completion.message
    finally:
        logger.remove(handle)
        await transport.aclose()
    conflict = [r for r in records if "delta.ext" in r]
    unknown = [r for r in records if "end_turn" in r]
    assert len(conflict) == 1 and len(unknown) == 1 and "不缓存" in unknown[0]
 async def test_warning_set_is_bounded():
    """节流集合饱和后只记一次饱和告警,不再增长。"""
    transport = OpenAICompatTransport()
    transport._warned_fields.update((f"s{i}", "k") for i in range(1024))
    records, handle = _sink()
    try:
        transport._warn_once("qwen_1", "field:x", "a")
        transport._warn_once("qwen_1", "field:y", "b")
    finally:
        logger.remove(handle)
        await transport.aclose()
    assert len(transport._warned_fields) == 1024
    assert sum("饱和" in r for r in records) == 1
 # —— 治理链: 确定性结局不重试、不计熔断 ——
 async def test_text_length_without_content_not_retried_nor_breaker_failure():
    """文本 length 无正文 → ResultInvalid 直抛,attempts=1,熔断不记失败。"""
    from tests.unit.test_client import _client
    calls = []
    def handler(_):
        calls.append(1)
        return _sse_stream(*_THINK, _f({}, "length", _USAGE))
    client = _client(handler=handler)
    failures = []
    original = client._breaker_backend.record_failure
    async def spy(*args, **kwargs):
        failures.append(args)
        return await original(*args, **kwargs)
    client._breaker_backend.record_failure = spy
    try:
        with pytest.raises(ResultInvalidError, match="length_without_content"):
            await client.chat([{"role": "user", "content": "hi"}])
    finally:
        await client._transport.aclose()
    assert len(calls) == 1 and failures == []
 async def test_openai_reasoning_length_single_attempt_via_client():
    """#30 验收经治理链: attempts=1;#31 形态经治理链不再重试到耗尽。"""
    from tests.unit.test_client import _client
    calls = []
    def handler(_):
        calls.append(1)
        return _sse_stream(*_THINK, _f({}, "length", _USAGE), done=False)
    client = _client(handler=handler)
    try:
        response = await client.chat([{"role": "user", "content": "hi"}], response_mode="openai")
    except AllSourcesExhausted:  # pragma: no cover - 失败即回归
        pytest.fail("reasoning-only length 不应重试到耗尽")
    finally:
        await client._transport.aclose()
    assert len(calls) == 1 and response.call_stats.attempts == 1
    assert response.stream_end == "eof_after_finish" and response.finish_reason == "length"
 async def test_eof_after_finish_stop_single_attempt_via_client():
    """#31 验收 1 经治理链: stop + usage 无 DONE,attempts=1、不重试到耗尽。"""
    from tests.unit.test_client import _client
    calls = []
    def handler(_):
        calls.append(1)
        return _sse_stream(_assistant(content="ok"), _f({}, "stop", _USAGE), done=False)
    client = _client(handler=handler)
    try:
        response = await client.chat([{"role": "user", "content": "hi"}])
    finally:
        await client._transport.aclose()
    assert len(calls) == 1 and response.call_stats.attempts == 1
    assert response.stream_end == "eof_after_finish" and response.usage_source == "measured"
 async def test_text_salvage_with_length_partial_content_delivered():
    """文本 salvage + length + 部分正文(finish 后无 usage): 交付、salvaged。"""
    frames = [_assistant(content="part"), _f({}, finish="length")]
    result = await _run(frames, done=False, missing_done="salvage")
    assert result.content == "part" and result.stream_end == "salvaged"
    assert result.finish_reason == "length"
 async def test_null_arguments_tool_is_result_invalid_stream():
    """审查 I2: 无参函数 arguments 全程 null → ResultInvalid,不重试。"""
    tool = {"index": 0, "id": "c", "type": "function", "function": {"name": "f", "arguments": None}}
    frames = [_assistant(tool_calls=[tool]), _f({}, "tool_calls", _USAGE)]
    with pytest.raises(ResultInvalidError, match="tool_arguments_null"):
        await _run(frames, done=True, mode="openai")
@@ -0,0 +1,265 @@
 """统一完成判定(#30/#31): 内核纯函数真值表。"""
 import pytest
 from polygateway.types import (
    LLMResponse,
    OpenAIChatCompletion,
    TransportResult,
    _classify_finish,
    _effective_finish,
    _is_cacheable,
    _judge_outcome,
    _OutputSummary,
    _stream_is_complete,
    _summarize_message,
    _summarize_text,
    _tool_snapshot_ok,
 )
 _TOOL = {"id": "t1", "type": "function", "function": {"name": "f", "arguments": "{}"}}
@pytest.mark.parametrize(
    ("value", "expected"),
    [
        ("stop", "natural"),
        ("tool_calls", "natural"),
        ("function_call", "natural"),
        ("length", "truncated"),
        ("content_filter", "filtered"),
        ("sensitive", "filtered"),
        ("network_error", "upstream_error"),
        ("error", "upstream_error"),
        ("end_turn", "unknown"),
        ("STOP", "unknown"),
        (None, "absent"),
    ],
 )
 def test_classify_finish(value, expected):
    assert _classify_finish(value) == expected
@pytest.mark.parametrize(
    ("done", "finish", "after", "measured", "expected"),
    [
        (True, None, False, False, "done"),
        (True, "stop", True, True, "done"),
        (False, "stop", True, True, "eof_after_finish"),
        (False, "length", True, True, "eof_after_finish"),
        (False, None, True, True, None),  # 无 finish 即截断
        (False, "stop", False, True, None),  # usage 早于 finish(累计 usage)
        (False, "stop", True, False, None),  # finish 后 usage 不可用
    ],
 )
 def test_stream_is_complete(done, finish, after, measured, expected):
    got = _stream_is_complete(
        done=done, finish_reason=finish, usage_after_finish=after, usage_measured=measured
    )
    assert got == expected
 def test_tool_snapshot_ok():
    assert _tool_snapshot_ok({"role": "assistant"})
    assert _tool_snapshot_ok({"tool_calls": None})
    assert _tool_snapshot_ok({"tool_calls": [None, _TOOL]})
    assert not _tool_snapshot_ok({"tool_calls": {}})
    assert not _tool_snapshot_ok({"tool_calls": [{"id": "t1", "type": "function"}]})
    assert not _tool_snapshot_ok({"tool_calls": [_TOOL, _TOOL]})  # 重复 id
 def test_summarize_text():
    assert _summarize_text("", "") == _OutputSummary(False, False, False, True)
    assert _summarize_text("  ", "") == _OutputSummary(True, False, False, True)
    assert _summarize_text("", "think") == _OutputSummary(True, False, False, True)
    assert _summarize_text("hi", "") == _OutputSummary(True, True, False, True)
@pytest.mark.parametrize(
    ("message", "projected", "expected"),
    [
        ({"role": "assistant"}, "", _OutputSummary(False, False, False, True)),
        ({"role": "assistant", "content": None}, "", _OutputSummary(False, False, False, True)),
        ({"role": "assistant", "refusal": "no"}, "", _OutputSummary(True, False, False, True)),
        (
            {"role": "assistant", "reasoning_content": "r"},
            "",
            _OutputSummary(True, False, False, True),
        ),
        ({"role": "assistant", "content": " "}, " ", _OutputSummary(True, False, False, True)),
        (
            {"role": "assistant", "x": {"y": ["", "z"]}},
            "",
            _OutputSummary(True, False, False, True),
        ),
        (
            {"role": "assistant", "tool_calls": [None]},
            "",
            _OutputSummary(False, False, False, True),
        ),
        (
            {"role": "assistant", "tool_calls": [_TOOL]},
            "",
            _OutputSummary(True, True, True, True),
        ),
        (
            {"role": "assistant", "tool_calls": [{"id": "t"}]},
            "",
            _OutputSummary(True, False, True, False),
        ),
        ({"role": "assistant", "content": "a"}, "a", _OutputSummary(True, True, False, True)),
    ],
 )
 def test_summarize_message(message, projected, expected):
    assert _summarize_message(message, projected) == expected
 _NONE = _OutputSummary(False, False, False, True)
 _THINK = _OutputSummary(True, False, False, True)
 _BODY = _OutputSummary(True, True, False, True)
 _BAD_TOOL = _OutputSummary(True, True, True, False)
@pytest.mark.parametrize(
    ("mode", "summary", "finish", "expected"),
    [
        # 行 1: upstream_error 优先于一切
        ("openai", _BODY, "upstream_error", ("transient", "upstream_finish_error")),
        ("text", _BODY, "upstream_error", ("transient", "upstream_finish_error")),
        # 行 2: 坏工具(仅保真),正文不得掩盖
        ("openai", _BAD_TOOL, "truncated", ("result_invalid", "tool_truncated")),
        ("openai", _BAD_TOOL, "natural", ("transient", "tool_incomplete")),
        ("text", _BAD_TOOL, "natural", None),
        # 行 3: 无产物 + truncated/filtered
        ("openai", _NONE, "truncated", None),
        ("openai", _NONE, "filtered", None),
        ("text", _NONE, "truncated", ("result_invalid", "length_without_content")),
        ("text", _NONE, "filtered", ("result_invalid", "filtered_without_content")),
        # 行 4: 零增量抖动(2026-07-20 裁决)
        ("openai", _NONE, "natural", ("transient", "empty_completion")),
        ("openai", _NONE, "absent", ("transient", "empty_completion")),
        ("openai", _NONE, "unknown", ("transient", "empty_completion")),
        ("text", _NONE, "absent", ("transient", "empty_completion")),
        # 行 5: 有正文
        ("openai", _BODY, "truncated", None),
        ("text", _BODY, "filtered", None),
        ("text", _BODY, "absent", None),
        # 行 6-9: 有产物无正文
        ("openai", _THINK, "truncated", None),
        ("text", _THINK, "truncated", ("result_invalid", "length_without_content")),
        ("openai", _THINK, "filtered", None),
        ("text", _THINK, "filtered", ("result_invalid", "filtered_without_content")),
        ("openai", _THINK, "natural", None),
        ("openai", _THINK, "unknown", None),
        ("text", _THINK, "natural", ("transient", "empty_completion")),
        ("openai", _THINK, "absent", ("transient", "empty_completion")),
        ("text", _THINK, "absent", ("transient", "empty_completion")),
    ],
 )
 def test_judge_outcome_rows(mode, summary, finish, expected):
    verdict = _judge_outcome(mode=mode, summary=summary, finish=finish)
    if expected is None:
        assert verdict.deliver and verdict.error_kind is None and verdict.code is None
    else:
        assert not verdict.deliver
        assert (verdict.error_kind, verdict.code) == expected
 def _completion(content="a", finish="stop", tools=None):
    message = {"role": "assistant", "content": content}
    if tools is not None:
        message["tool_calls"] = tools
    return OpenAIChatCompletion(message, finish, None, None)
@pytest.mark.parametrize(
    ("kwargs", "expected"),
    [
        ({"mode": "text", "content": "a", "finish_reason": "stop", "stream_end": "done"}, True),
        ({"mode": "text", "content": "a", "finish_reason": None, "stream_end": None}, True),
        (
            {
                "mode": "text",
                "content": "a",
                "finish_reason": "stop",
                "stream_end": "eof_after_finish",
            },
            True,
        ),
        ({"mode": "text", "content": "a", "finish_reason": None, "stream_end": "salvaged"}, False),
        ({"mode": "text", "content": " ", "finish_reason": "stop", "stream_end": "done"}, False),
        ({"mode": "text", "content": "a", "finish_reason": "length", "stream_end": None}, False),
        ({"mode": "text", "content": "a", "finish_reason": "sensitive", "stream_end": None}, False),
        ({"mode": "text", "content": "a", "finish_reason": "end_turn", "stream_end": None}, False),
        ({"mode": "text", "content": "a", "finish_reason": "stop", "stream_end": "bogus"}, False),
    ],
 )
 def test_is_cacheable_text(kwargs, expected):
    assert _is_cacheable(completion=None, **kwargs) is expected
 def test_is_cacheable_openai():
    ok = _completion()
    assert _is_cacheable(
        mode="openai", content="a", finish_reason="stop", stream_end="done", completion=ok
    )
    assert not _is_cacheable(
        mode="openai", content="a", finish_reason="stop", stream_end="done", completion=None
    )
    # 原文为空且无工具: 不信任旧投影
    assert not _is_cacheable(
        mode="openai",
        content="a",
        finish_reason="stop",
        stream_end="done",
        completion=_completion(content=""),
    )
    tool_only = _completion(content=None, finish="tool_calls", tools=[_TOOL])
    assert _is_cacheable(
        mode="openai", content="", finish_reason="tool_calls", stream_end=None, completion=tool_only
    )
 def test_effective_finish():
    assert _effective_finish("stop", _completion(finish="length")) == "stop"
    assert _effective_finish(None, _completion(finish="length")) == "length"
    assert _effective_finish(None, None) is None
 def test_completion_accepts_null_tool_calls():
    snap = OpenAIChatCompletion({"role": "assistant", "tool_calls": None}, "stop", None, None)
    assert "tool_calls" in snap.message and snap.message["tool_calls"] is None
    with pytest.raises(ValueError):
        OpenAIChatCompletion({"role": "assistant", "tool_calls": {}}, "stop", None, None)
 def test_response_fields_default_none():
    result = TransportResult("a", "", 0, 0, "unavailable", None, None, {})
    assert result.finish_reason is None and result.stream_end is None
    response = LLMResponse("a", "", "m", "p", 0, 0, 0, None, None, False, "c")
    assert response.finish_reason is None and response.stream_end is None
 def test_stream_end_exported():
    import polygateway
    assert "StreamEnd" in polygateway.__all__
 def test_openai_cacheable_requires_projected_body():
    """审查 I1: think 标签剥离后投影为空,即使原文非空也不可缓存。"""
    think_only = _completion(content="<think>x</think>")
    assert not _is_cacheable(
        mode="openai", content="", finish_reason="stop", stream_end="done", completion=think_only
    )
 def test_null_arguments_only_tool_is_result_invalid():
    """审查 I2: 无参函数 arguments 全程 null(其余齐全)→ 确定性方言,ResultInvalid。"""
    tool = {"id": "t1", "type": "function", "function": {"name": "f", "arguments": None}}
    summary = _summarize_message({"role": "assistant", "tool_calls": [tool]}, "")
    assert summary.null_arguments and not summary.tools_ok
    verdict = _judge_outcome(mode="openai", summary=summary, finish="natural")
    assert (verdict.error_kind, verdict.code) == ("result_invalid", "tool_arguments_null")
    broken = {"id": "t1", "type": "function", "function": {"arguments": None}}
    assert not _summarize_message({"role": "assistant", "tool_calls": [broken]}, "").null_arguments
@@ -1397,9 +1397,7 @@ class TestStallConfig:
    def test_stall_after_s_single_source_warns(self):
        """单源 scope 设 stall 阈值: 装配期 warning 放行(1.3.7 §5 同款)。"""
        with _captured_warnings() as warnings:
-            s = GatewaySettings.from_env(
+            s = GatewaySettings.from_env("LLM", env=_env(**{"LLM__HEDGE__STALL_AFTER_S": "8"}))
                "LLM", env=_env(**{"LLM__HEDGE__STALL_AFTER_S": "8"})
            )
        assert s.hedge_stall_after_s == 8.0
        assert any("单源" in m for m in warnings)
@@ -1422,9 +1420,7 @@ class TestStallConfig:
            "EMBED__BATCH_SIZE": "64",
        }
        with _captured_warnings() as warnings:
-            EmbeddingSettings.from_env(
+            EmbeddingSettings.from_env("EMBED", env={**embed_env, "EMBED__HEDGE__AFTER_S": "8"})
                "EMBED", env={**embed_env, "EMBED__HEDGE__AFTER_S": "8"}
            )
        assert any("仅对 chat scope 生效" in m for m in warnings)
        with _captured_warnings() as warnings:
            EmbeddingSettings.from_env(
@@ -65,6 +65,7 @@ class HedgeTransport:
        reasoning_effort,
        first_token_event,
        content_event,
        response_mode,
    ):
        self.calls.append(source.name)
        self.ft_events.append(first_token_event)
@@ -279,6 +279,7 @@ async def _complete(observed, *, call_id="a", stream=False):
        reasoning_effort=None,
        first_token_event=None,
        content_event=None,
        response_mode="text",
    )
@@ -1270,6 +1271,7 @@ async def test_structured_first_attempt_requires_exact_initial_messages():
                reasoning_effort=None,
                first_token_event=None,
                content_event=None,
                response_mode="text",
            )
        event = capture.attempts(session_id="first", parent_call_id="parent")[0].http[0]
        assert not request_is_valid(event)
@@ -90,6 +90,7 @@ async def _complete(
    reasoning_effort=None,
    first_token_event=None,
    content_event=None,
    response_mode="text",
 ):
    return await transport.complete(
        messages=[{"role": "user", "content": "hi"}],
@@ -100,9 +101,19 @@ async def _complete(
        reasoning_effort=reasoning_effort,
        first_token_event=first_token_event,
        content_event=content_event,
        response_mode=response_mode,
    )
 async def test_complete_helper_forwards_response_mode():
    """测试封装不得将显式保真模式静默退化成文本模式。"""
    from unittest.mock import AsyncMock
    transport = AsyncMock()
    await _complete(transport, _source(), response_mode="openai")
    assert transport.complete.call_args.kwargs["response_mode"] == "openai"
 # 单价刻意取"输出贵于输入"的真实形态: est_tokens 兜底把整估值塞进 completion
 # 时,虚高才显形(设计 §1 的 26 倍算例即此单价)。
 _PRICING = PricingTable({"qwen-max": ModelPrice(input_per_1m=1.0, output_per_1m=8.0)})
@@ -161,6 +172,8 @@ class TestSsePureFunctions:
        assert _sse_data_payload("data: [DONE]") == "[DONE]"
    async def test_iter_deltas_yields_and_flags_done(self):
        from polygateway.transports._openai_completion import ChatCompletionAccumulator, ChatDelta
        async def lines():
            for raw in [
                _chunk(content="he"),
@@ -173,16 +186,28 @@ class TestSsePureFunctions:
                    yield line
        sink = {}
-        out = [d async for d in _iter_sse_deltas(lines(), sink)]
+        out = [
-        assert out == [(True, "he"), (False, "think")]
+            d
            async for d in _iter_sse_deltas(
                lines(), sink, ChatCompletionAccumulator(response_mode="text")
            )
        ]
        assert out == [ChatDelta("he", "", True), ChatDelta("", "think", True)]
        assert sink["done"] is True and sink["usage"] == _USAGE
    async def test_malformed_frame_raises_transient(self):
        from polygateway.transports._openai_completion import ChatCompletionAccumulator
        async def lines():
            yield "data: {not-json"
        with pytest.raises(TransientError, match="malformed"):
-            _ = [d async for d in _iter_sse_deltas(lines(), {})]
+            _ = [
                d
                async for d in _iter_sse_deltas(
                    lines(), {}, ChatCompletionAccumulator(response_mode="text")
                )
            ]
 class TestStreamHappyPath:
@@ -0,0 +1,468 @@
 """协议聚合器的分片、防御与快照契约。"""
 import copy
 import json
 import pytest
 from polygateway.errors import TransientError
 from polygateway.transports._openai_completion import (
    ChatCompletionAccumulator,
    parse_chat_completion,
 )
 def chunk(delta, **extra):
    """构造单 choice 协议帧。"""
    return (
        "data: "
        + json.dumps({"id": "upstream-1", "choices": [{"index": 0, "delta": delta, **extra}]})
        + "\n\n"
    )
 def tool_frames():
    """两个交错分片工具，保留空白及 Unicode。"""
    return [
        chunk({"role": "assistant", "content": None}),
        chunk(
            {
                "tool_calls": [
                    {
                        "index": 1,
                        "id": "b",
                        "type": "function",
                        "function": {"name": "echo", "arguments": '{"v":'},
                    },
                    {
                        "index": 0,
                        "id": "a",
                        "type": "function",
                        "function": {"name": "echo", "arguments": "{"},
                    },
                ]
            }
        ),
        chunk(
            {
                "tool_calls": [
                    {"index": 0, "function": {"arguments": '"v": "中" }'}},
                    {"index": 1, "function": {"arguments": "2}"}},
                ]
            },
            finish_reason="tool_calls",
        ),
    ]
 def accumulate():
    """复用双工具网关帧样本。"""
    state = ChatCompletionAccumulator(response_mode="openai")
    for frame in tool_frames():
        state.add_chunk(json.loads(frame.removeprefix("data: ")))
    return state
@pytest.mark.parametrize("role", [None, "user", "tool"])
 def test_role_is_required_everywhere(role):
    """缺角色不能被协议成功掩盖。"""
    state = accumulate()
    state.message.pop("role")
    if role:
        state.message["role"] = role
    with pytest.raises(TransientError, match="role"):
        state.finish()
    with pytest.raises(TransientError, match="role"):
        parse_chat_completion({"choices": [{"message": state.message}]})
@pytest.mark.parametrize(
    "change",
    [
        lambda t: t.pop("id"),
        lambda t: t.update(type="custom"),
        lambda t: t["function"].pop("name"),
        lambda t: t["function"].pop("arguments"),
        lambda t: t["function"].update(arguments=12),
    ],
 )
 def test_incomplete_tool_is_not_success(change):
    """工具必需字段不能靠正文兜底。"""
    state = accumulate()
    state.message["content"] = "text"
    change(state.tools[0])
    with pytest.raises(TransientError):
        state.finish()
@pytest.mark.parametrize(
    "delta",
    [
        [],
        {"tool_calls": {}},
        {"content": []},
        {"role": "user"},
        {"tool_calls": [{"index": True}]},
        {"tool_calls": [{"index": -1}]},
        {"tool_calls": [{"index": None}]},
        {"tool_calls": [{"index": 0, "function": {"arguments": 12}}]},
    ],
 )
 def test_invalid_delta_is_domain_error(delta):
    """畸形输入不泄漏裸类型错误。"""
    state = ChatCompletionAccumulator(response_mode="openai")
    with pytest.raises(TransientError):
        state.add_chunk({"choices": [{"index": 0, "delta": delta}]})
 def test_identity_repeat_does_not_refresh_progress():
    """身份只初次生效算进展；同值重复不能续命。"""
    state = accumulate()
    repeated = {
        "choices": [
            {"index": 0, "delta": {"tool_calls": [{"index": 0, "id": "a", "type": "function"}]}}
        ]
    }
    assert not state.add_chunk(repeated).progress
    repeated["choices"][0]["delta"]["tool_calls"][0]["id"] = "other"
    with pytest.raises(TransientError, match="冲突"):
        state.add_chunk(repeated)
@pytest.mark.parametrize("delta", [{"role": "assistant"}, {}, {"content": ""}])
 def test_metadata_not_progress(delta):
    """空帧和角色不算 token。"""
    state = ChatCompletionAccumulator(response_mode="openai")
    assert not state.add_chunk({"choices": [{"index": 0, "delta": delta}]}).progress
 def test_nonstream_snapshot_and_length_preserved():
    """非流式扩展字段与参数原文独立保存，不修复 length 产物。"""
    message = accumulate().finish().message
    message["extension"] = {"nested": [1]}
    message["tool_calls"][0]["function"]["arguments"] = '{"unfinished":'
    original = copy.deepcopy(message)
    result = parse_chat_completion(
        {
            "id": "id",
            "choices": [{"message": message, "finish_reason": "length"}],
            "usage": {"extra": 3},
        }
    )
    message["extension"]["nested"].append(2)
    assert result.message == original
    assert result.finish_reason == "length" and result.usage == {"extra": 3}
@pytest.mark.parametrize("choices", [[], [{"index": 1, "message": {}}], [{}, {}]])
 def test_nonstream_single_choice(choices):
    """不会静默取第一个 choice。"""
    with pytest.raises(TransientError):
        parse_chat_completion({"choices": choices})
 def test_explicit_empty_tools_remains_present():
    """显式空工具列表与缺省不同，不删除已接收字段。"""
    state = ChatCompletionAccumulator(response_mode="openai")
    state.add_chunk(
        {
            "choices": [
                {"index": 0, "delta": {"role": "assistant", "content": "ok", "tool_calls": []}}
            ]
        }
    )
    assert state.finish().message["tool_calls"] == []
 def test_fragmented_name_and_arguments_with_usage():
    """名称/参数分片逐字拼接，usage 扩展原样快照。"""
    state = ChatCompletionAccumulator(response_mode="openai")
    state.add_chunk(
        {
            "id": "response",
            "choices": [
                {
                    "index": 0,
                    "delta": {
                        "role": "assistant",
                        "tool_calls": [
                            {
                                "index": 3,
                                "id": "call",
                                "type": "function",
                                "function": {"name": "ec", "arguments": " "},
                            }
                        ],
                    },
                }
            ],
        }
    )
    progress = state.add_chunk(
        {
            "choices": [
                {
                    "index": 0,
                    "delta": {
                        "content": "text",
                        "reasoning_content": "reason",
                        "tool_calls": [
                            {"index": 3, "function": {"name": "ho", "arguments": "{} "}}
                        ],
                    },
                    "finish_reason": "length",
                }
            ]
        }
    )
    assert (
        progress.content == "text" and progress.reasoning_content == "reason" and progress.progress
    )
    usage = {"prompt_tokens": 7, "completion_tokens": 2, "extra": {"nested": 9}}
    assert not state.add_chunk({"choices": [], "usage": usage}).progress
    result = state.finish()
    usage["extra"]["nested"] = 10
    assert result.message["tool_calls"][0]["function"] == {"name": "echo", "arguments": " {} "}
    assert result.usage["extra"]["nested"] == 9
    assert result.finish_reason == "length"
 # —— 1.3.10(#30): null 优先、未知字段无损合并、finish/usage 位置 ——
 def _feed(state, *chunks):
    """依次喂入已解码帧,返回每帧的 ChatDelta。"""
    return [state.add_chunk(c) for c in chunks]
 def _frame(delta, finish=None, **top):
    """单 choice 已解码帧。"""
    choice = {"index": 0, "delta": delta}
    if finish is not None:
        choice["finish_reason"] = finish
    return {"choices": [choice], **top}
 def test_null_known_and_unknown_fields_are_absent():
    """refusal/tool_calls/role/arguments 为 null 不判失败,键按缺省保留。"""
    state = ChatCompletionAccumulator(response_mode="openai")
    _feed(
        state,
        _frame({"role": None, "refusal": None, "tool_calls": None, "content": None}),
        _frame({"role": "assistant", "content": "hi"}, finish="stop"),
    )
    message = state.finish().message
    assert message["refusal"] is None and message["content"] == "hi"
    assert message["role"] == "assistant"
 def test_role_only_null_fails_at_finish():
    """全程只有 role:null 即缺 role,照旧失败。"""
    state = ChatCompletionAccumulator(response_mode="openai")
    _feed(state, _frame({"role": None, "content": "x"}, finish="stop"))
    with pytest.raises(TransientError, match="role"):
        state.finish()
 def test_null_arguments_and_null_tool_elements():
    """arguments:null 视缺省;tool_calls 中 null 元素跳过。"""
    state = ChatCompletionAccumulator(response_mode="openai")
    tool = {"index": 0, "id": "a", "type": "function", "function": {"name": "f"}}
    _feed(
        state,
        _frame({"role": "assistant", "tool_calls": [None, tool]}),
        _frame({"tool_calls": [{"index": 0, "function": {"arguments": None}}]}),
        _frame({"tool_calls": [{"index": 0, "function": {"arguments": "{}"}}]}, "tool_calls"),
    )
    assert state.finish().message["tool_calls"][0]["function"] == {"name": "f", "arguments": "{}"}
 def test_null_choices_and_delta_are_absent():
    """chunk 层 choices:null 与 choice 层 delta:null 视缺省。"""
    state = ChatCompletionAccumulator(response_mode="openai")
    assert not state.add_chunk({"choices": None}).progress
    assert not state.add_chunk({"choices": [{"index": 0, "delta": None}]}).progress
 def test_reasoning_alias_is_progress_and_preserved():
    """只有 reasoning 字段: 计活性、交别名片段、保真原键保留。"""
    for mode in ("openai", "text"):
        state = ChatCompletionAccumulator(response_mode=mode)
        delta = state.add_chunk(_frame({"role": "assistant", "reasoning": "think"}))
        assert delta.progress and delta.reasoning == "think" and delta.reasoning_content == ""
    state.add_chunk(_frame({"reasoning": " more"}))
    openai = ChatCompletionAccumulator(response_mode="openai")
    _feed(openai, _frame({"role": "assistant", "reasoning": "a"}), _frame({"reasoning": "b"}))
    assert openai.raw_message()["reasoning"] == "ab"
 def _detail(text, **extra):
    return {"type": "reasoning.text", "index": 0, "format": "x-v1", "text": text, **extra}
 def test_reasoning_details_merge_by_index_without_label_concat():
    """OpenRouter reasoning_details 分片: index 合并,format/id/type 不拼接。"""
    state = ChatCompletionAccumulator(response_mode="openai")
    _feed(
        state,
        _frame({"role": "assistant", "reasoning_details": [_detail("he", id="r1")]}),
        _frame({"reasoning_details": [_detail("llo", id="r1")]}),
        _frame({"content": "ok"}, finish="stop"),
    )
    details = state.finish().message["reasoning_details"]
    assert details == [
        {"type": "reasoning.text", "index": 0, "format": "x-v1", "text": "hello", "id": "r1"}
    ]
    assert not state.conflicts
 def test_tool_level_nested_extension_preserved():
    """工具层未知嵌套对象(如 thought signature)原样保留以便回传。"""
    state = ChatCompletionAccumulator(response_mode="openai")
    extra = {"google": {"thought_signature": "sig"}}
    tool = {"index": 0, "id": "a", "type": "function", "extra_content": extra}
    _feed(
        state,
        _frame({"role": "assistant", "tool_calls": [{**tool, "function": {"name": "f"}}]}),
        _frame({"tool_calls": [{"index": 0, "function": {"arguments": "{}", "strict": True}}]}),
    )
    snapshot = state.finish().message["tool_calls"][0]
    assert snapshot["extra_content"] == extra and snapshot["function"]["strict"] is True
@pytest.mark.parametrize(
    ("first", "second"),
    [(1, 2), (True, False), ("s", {"o": 1}), ([{"index": 0, "t": "a"}], ["plain"])],
 )
 def test_conflict_drops_key_and_bans_path(first, second):
    """数值/布尔/形态冲突: 删键、登记路径、后续同路径丢弃、调用成功。"""
    state = ChatCompletionAccumulator(response_mode="openai")
    _feed(
        state,
        _frame({"role": "assistant", "content": "a", "ext": first}),
        _frame({"ext": second}),
        _frame({"ext": first}, finish="stop"),
    )
    assert "ext" not in state.finish().message
    assert state.conflicts == frozenset({"delta.ext"})
 def test_plain_arrays_append_and_same_scalar_idempotent():
    """普通数组追加;同值标量幂等;追加数组中的字符串算活性。"""
    state = ChatCompletionAccumulator(response_mode="openai")
    deltas = _feed(
        state,
        _frame({"role": "assistant", "notes": ["a"], "n": 1}),
        _frame({"notes": ["b", None], "n": 1}),
    )
    message = state.raw_message()
    assert message["notes"] == ["a", "b"] and message["n"] == 1
    assert all(d.progress for d in deltas[1:])
 def test_one_progress_per_frame_with_many_fragments():
    """同帧多个字段只产生一次进展事件(ChatDelta 单值)。"""
    state = ChatCompletionAccumulator(response_mode="text")
    delta = state.add_chunk(_frame({"content": "a", "reasoning_content": "b", "x": "c"}))
    assert delta.progress is True
 def test_label_only_unknown_is_not_progress():
    """未知层仅标签键(type/format/id/index)不刷新活性。"""
    state = ChatCompletionAccumulator(response_mode="openai")
    assert not state.add_chunk(_frame({"meta": {"type": "x", "format": "y"}})).progress
@pytest.mark.parametrize(
    ("frames", "after"),
    [
        ([_frame({"content": "a"}, usage={"x": 1}), _frame({}, finish="stop")], False),
        ([_frame({"content": "a"}, finish="stop", usage={"x": 1})], True),
        ([_frame({"content": "a"}, finish="stop"), {"choices": [], "usage": {"x": 1}}], True),
        ([_frame({"content": "a"}, finish="stop")], False),
    ],
 )
 def test_usage_after_finish_tracking(frames, after):
    """usage 必须在 finish 同帧或之后到达才算流走到自然末尾。"""
    for mode in ("openai", "text"):
        state = ChatCompletionAccumulator(response_mode=mode)
        _feed(state, *frames)
        assert state.finish_seen and state.finish_reason == "stop"
        assert state.usage_after_finish is after
 def test_text_mode_ignores_other_choice_index():
    """文本模式只取 index 缺省或为 0 的 choice,不混入 index=1。"""
    state = ChatCompletionAccumulator(response_mode="text")
    delta = state.add_chunk(
        {
            "choices": [
                {"index": 1, "delta": {"content": "B"}, "finish_reason": "length"},
                {"index": 0, "delta": {"content": "A"}},
            ]
        }
    )
    assert delta.content == "A" and state.finish_reason is None
 def test_text_mode_finish_non_string_ignored():
    """文本模式 finish 非字符串记 None,不判失败。"""
    state = ChatCompletionAccumulator(response_mode="text")
    state.add_chunk(_frame({"content": "a"}, finish=5))
    assert state.finish_reason is None and not state.finish_seen
 def test_nonstream_null_tool_elements_stripped():
    """非流式 tool_calls 中 null 元素剔除(回传 [null] 会被上游拒),null 列表原样保留。"""
    tool = {"id": "a", "type": "function", "function": {"name": "f", "arguments": "{}"}}
    body = {
        "choices": [{"message": {"role": "assistant", "tool_calls": [None, tool], "refusal": None}}]
    }
    assert parse_chat_completion(body).message["tool_calls"] == [tool]
    body["choices"][0]["message"]["tool_calls"] = None
    assert parse_chat_completion(body).message["tool_calls"] is None
@pytest.mark.parametrize(("index", "taken"), [(None, True), (0, True), (False, False), (1, False)])
 def test_text_mode_choice_index_null_is_zero(index, taken):
    """审查 I3: 文本模式 index:null 视缺省(=0);bool 不冒充 0。"""
    state = ChatCompletionAccumulator(response_mode="text")
    delta = state.add_chunk(
        {"choices": [{"index": index, "delta": {"content": "hi"}, "finish_reason": "stop"}]}
    )
    assert (delta.content == "hi") is taken and (state.finish_reason == "stop") is taken
 def test_null_only_tool_elements_do_not_create_empty_list():
    """审查 Minor1: tool_calls null 后 [null] 不得产出会被上游拒收的空数组。"""
    state = ChatCompletionAccumulator(response_mode="openai")
    _feed(
        state,
        _frame({"role": "assistant", "content": "a", "tool_calls": None}),
        _frame({"tool_calls": [None]}, finish="stop"),
    )
    assert state.finish().message["tool_calls"] is None
    body = {"choices": [{"message": {"role": "assistant", "content": "a", "tool_calls": [None]}}]}
    assert parse_chat_completion(body).message["tool_calls"] is None
 def test_tool_calls_null_then_list_merges():
    """tool_calls 先 null 后列表: 正常聚合工具。"""
    state = ChatCompletionAccumulator(response_mode="openai")
    tool = {"index": 0, "id": "a", "type": "function", "function": {"name": "f", "arguments": "{}"}}
    _feed(
        state,
        _frame({"role": "assistant", "tool_calls": None}),
        _frame({"tool_calls": [tool]}, finish="tool_calls"),
    )
    assert state.finish().message["tool_calls"][0]["id"] == "a"
 def test_nonstream_role_checked_before_verdict():
    """审查 Minor3: 非流式缺 role 是形态失败,先于结局判定。"""
    from polygateway.transports._openai_completion import check_completion_body
    with pytest.raises(TransientError, match="role"):
        check_completion_body(
            {"choices": [{"message": {"content": "a"}, "finish_reason": "length"}]}
        )
@@ -0,0 +1,376 @@
 """OpenAI 消息保真回归：按网关 Chat Completions 形态构造。"""
 import json
 import httpx
 import pytest
 from polygateway.errors import AllSourcesExhausted, TransientError
 from tests.unit.test_client import _client
 from tests.unit.test_openai_compat import _complete, _source, _sse_stream, _transport_for
 from tests.unit.test_openai_completion import accumulate, chunk, tool_frames
 async def test_error_before_done_is_failure():
    """文本模式也不能接受 error 后的 DONE。"""
    transport = _transport_for(
        lambda _: _sse_stream(chunk({"content": "partial"}), 'data: {"error": null}\n\n')
    )
    try:
        with pytest.raises(TransientError):
            await _complete(transport, _source())
    finally:
        await transport.aclose()
 async def test_mixed_content_reasoning_survive():
    """同一帧双文本不互斥。"""
    transport = _transport_for(
        lambda _: _sse_stream(chunk({"content": "answer", "reasoning_content": "reason"}))
    )
    try:
        result = await _complete(transport, _source())
        assert (result.content, result.thinking) == ("answer", "reason")
    finally:
        await transport.aclose()
 async def test_tools_roundtrip_and_retry():
    """真实 transport 经过治理，失败重试不污染工具，消息可直接往返。"""
    requests = []
    def handler(request):
        requests.append(json.loads(request.content))
        if len(requests) == 1:
            return _sse_stream(
                chunk({"content": "partial"}),
                'data: {"error": {"code": "upstream_stream_read_error"}}\n\n',
            )
        return _sse_stream(*tool_frames())
    client = _client(handler=handler)
    try:
        response = await client.chat(
            [{"role": "user", "content": "hi"}],
            response_mode="openai",
            overlay={"reasoning_effort": "max"},
        )
        assert response.call_stats.attempts == 2
        message = response.completion.message
        assert message["role"] == "assistant" and message["content"] is None
        assert [t["id"] for t in message["tool_calls"]] == ["a", "b"]
        assert message["tool_calls"][0]["function"]["arguments"] == '{"v": "中" }'
        assert response.completion.response_id == "upstream-1"
        assert response.completion.finish_reason == "tool_calls"
        messages = [message, {"role": "tool", "tool_call_id": "a", "content": "ok"}]
        await client.chat(messages, response_mode="openai")
        assert requests[-1]["messages"] == messages
        assert requests[0]["reasoning_effort"] == "max"
    finally:
        await client._transport.aclose()
@pytest.mark.parametrize("role", [None, "user"])
 async def test_final_role_required(role):
    """非流式缺失或错误 role 必须协议失败。"""
    message = {"content": "ok"}
    if role:
        message["role"] = role
    client = _client(
        handler=lambda _: httpx.Response(200, json={"choices": [{"message": message}]})
    )
    try:
        with pytest.raises(AllSourcesExhausted):
            await client.chat(
                [{"role": "user", "content": "hi"}], stream=False, response_mode="openai"
            )
    finally:
        await client._transport.aclose()
@pytest.mark.parametrize("stream", [True, False])
 async def test_completion_cache_roundtrip(stream):
    """完整结果回放，修改返回对象不毒化缓存；模式隔离。"""
    from polygateway.backends.memory.cache import InMemoryCache
    completion = accumulate().finish()
    def handler(_):
        if stream:
            return _sse_stream(*tool_frames())
        return httpx.Response(
            200,
            json={
                "id": "upstream-1",
                "choices": [{"message": completion.message, "finish_reason": "tool_calls"}],
            },
        )
    client = _client(
        handler=handler, cache=InMemoryCache(), cache_namespace="tools", cache_ttl_s=60
    )
    try:
        first = await client.chat([], stream=stream, response_mode="openai")
        second = await client.chat([], stream=stream, response_mode="openai")
        assert not first.cache_hit and second.cache_hit
        assert second.completion == first.completion
        assert second.call_id != first.call_id and second.call_stats.attempts == 0
        second.completion.message["tool_calls"].clear()
        third = await client.chat([], stream=stream, response_mode="openai")
        assert len(third.completion.message["tool_calls"]) == 2
    finally:
        await client._transport.aclose()
@pytest.mark.parametrize(
    "kwargs",
    [
        {"response_mode": "bad"},
        {"response_mode": "openai", "structured": "json"},
        {"response_mode": "openai", "overlay": {"n": 2}},
        {"response_mode": "openai", "overlay": {"n": True}},
    ],
 )
 async def test_invalid_mode_combinations_fail_before_http(kwargs):
    """组合错误入口拒绝。"""
    def unexpected(_):
        pytest.fail("不应发送 HTTP")
    client = _client(handler=unexpected)
    try:
        with pytest.raises(ValueError):
            await client.chat([], **kwargs)
    finally:
        await client._transport.aclose()
 async def test_openai_never_salvages():
    """无 finish 后 usage 的截断流即使收全工具也不打捞(1.3.10: 判据由 DONE 改为完成判定)。"""
    transport = _transport_for(lambda _: _sse_stream(*tool_frames(), done=False))
    try:
        with pytest.raises(TransientError, match="missing_done"):
            await transport.complete(
                messages=[],
                source=_source(missing_done="salvage"),
                stream=True,
                overlay={},
                call_id="c",
                reasoning_effort=None,
                first_token_event=None,
                content_event=None,
                response_mode="openai",
            )
    finally:
        await transport.aclose()
 async def test_openai_finish_with_trailing_usage_is_complete_without_done():
    """对照: 同一工具流补上 finish 之后的 usage 帧,即使无 DONE 也完整交回(#31)。"""
    usage = 'data: {"choices": [], "usage": {"prompt_tokens": 3, "completion_tokens": 4}}\n\n'
    transport = _transport_for(lambda _: _sse_stream(*tool_frames(), usage, done=False))
    try:
        result = await transport.complete(
            messages=[],
            source=_source(),
            stream=True,
            overlay={},
            call_id="c",
            reasoning_effort=None,
            first_token_event=None,
            content_event=None,
            response_mode="openai",
        )
    finally:
        await transport.aclose()
    assert result.stream_end == "eof_after_finish"
    assert [t["id"] for t in result.completion.message["tool_calls"]] == ["a", "b"]
 async def test_tool_progress_sets_events():
    """工具首进展驱动两个事件与时间观测。"""
    import asyncio
    first, progress = asyncio.Event(), asyncio.Event()
    transport = _transport_for(lambda _: _sse_stream(*tool_frames()))
    try:
        result = await transport.complete(
            messages=[],
            source=_source(),
            stream=True,
            overlay={},
            call_id="c",
            reasoning_effort=None,
            first_token_event=first,
            content_event=progress,
            response_mode="openai",
        )
        assert first.is_set() and progress.is_set()
        assert result.ttft_ms is not None and result.stall_count == 0
    finally:
        await transport.aclose()
 async def test_real_transport_stall_hedge_cancels_loser():
    """真实工具流沉默触发异源对冲，连接关闭且赢家不混入半成品。"""
    import asyncio
    import time
    from polygateway.sources import RoundRobinSelector
    from polygateway.types import ChatRequest, _CallContext
    from tests.unit.test_retry import _src
    from tests.unit.test_stall_hedge import _harness
    entered, closed = asyncio.Event(), asyncio.Event()
    class Hanging(httpx.AsyncByteStream):
        """工具首帧后阻塞，取消由真实 httpx 流处理。"""
        async def __aiter__(self):
            yield tool_frames()[0].encode()
            yield tool_frames()[1].encode()
            entered.set()
            await asyncio.Event().wait()
        async def aclose(self):
            closed.set()
    count = 0
    def handler(_):
        nonlocal count
        count += 1
        if count == 1:
            return httpx.Response(200, stream=Hanging())
        return _sse_stream(*tool_frames())
    transport = _transport_for(handler)
    sources = [_src("s1"), _src("s2")]
    mw, limiter, *_ = _harness(
        sources, transport, stall_after_s=0.05, selector=RoundRobinSelector()
    )
    context = _CallContext(now=time.monotonic)
    try:
        response = await asyncio.wait_for(
            mw(ChatRequest(messages=[], response_mode="openai", call_context=context)), 3
        )
        assert entered.is_set() and closed.is_set()
        assert response.source_name == "s2" and len(response.completion.message["tool_calls"]) == 2
        assert context.snapshot().hedges == 1 and context.snapshot().attempts == 2
    finally:
        await transport.aclose()
@pytest.mark.parametrize("stream", [True, False])
 async def test_bad_usage_is_domain_failure(stream):
    """坏 usage 不能穿透成裸 AttributeError，包括默认文本模式。"""
    transport = _transport_for(
        lambda _: (
            _sse_stream(chunk({"content": "ok"}), 'data: {"choices": [], "usage": [1]}\n\n')
            if stream
            else httpx.Response(
                200, json={"choices": [{"message": {"content": "ok"}}], "usage": [1]}
            )
        )
    )
    try:
        with pytest.raises(TransientError):
            await _complete(transport, _source(), stream=stream)
    finally:
        await transport.aclose()
 async def test_nonstream_tool_result_has_no_liveness_events():
    """非流式工具不制造流式观测。"""
    import asyncio
    completion = accumulate().finish()
    first, progress = asyncio.Event(), asyncio.Event()
    transport = _transport_for(
        lambda _: httpx.Response(
            200, json={"choices": [{"message": completion.message, "finish_reason": "tool_calls"}]}
        )
    )
    try:
        result = await transport.complete(
            messages=[],
            source=_source(),
            stream=False,
            overlay={},
            call_id="c",
            reasoning_effort=None,
            first_token_event=first,
            content_event=progress,
            response_mode="openai",
        )
        assert result.completion.message == completion.message
        assert not first.is_set() and not progress.is_set()
        assert result.ttft_ms is None and result.stall_ms is None
    finally:
        await transport.aclose()
 async def test_openai_does_not_bypass_managed_conflict():
    """保真模式不静默撤销源级受管意图。"""
    from polygateway.errors import RequestRejectedError
    def unexpected(_):
        pytest.fail("冲突请求不应发送 HTTP")
    transport = _transport_for(unexpected)
    try:
        with pytest.raises(RequestRejectedError):
            await transport.complete(
                messages=[],
                source=_source(enable_thinking=True),
                stream=True,
                overlay={"reasoning_effort": "max"},
                call_id="c",
                reasoning_effort=None,
                first_token_event=None,
                content_event=None,
                response_mode="openai",
            )
    finally:
        await transport.aclose()
 async def test_cancel_tool_stream_releases_resources():
    """显式取消真实工具流，连接关闭且配额归还。"""
    import asyncio
    from polygateway.backends.memory.limiter import InMemoryLimiter
    from polygateway.types import GlobalLimits
    entered, closed = asyncio.Event(), asyncio.Event()
    class Hanging(httpx.AsyncByteStream):
        """可确定取消窗口的 HTTP 流。"""
        async def __aiter__(self):
            for frame in tool_frames()[:2]:
                yield frame.encode()
            entered.set()
            await asyncio.Event().wait()
        async def aclose(self):
            closed.set()
    source = _source(max_concurrency=1)
    limiter = InMemoryLimiter(
        scope="llm", sources={source.name: source}, global_limits=GlobalLimits(1, 0, 0)
    )
    client = _client(
        sources=[source], limiter=limiter, handler=lambda _: httpx.Response(200, stream=Hanging())
    )
    task = asyncio.create_task(client.chat([], response_mode="openai"))
    try:
        await asyncio.wait_for(entered.wait(), 2)
        task.cancel()
        with pytest.raises(asyncio.CancelledError):
            await task
        assert closed.is_set()
        assert (await limiter.source_stats(source.name)).inflight == 0
    finally:
        task.cancel()
        await client._transport.aclose()
@@ -88,3 +88,15 @@ def test_every_promised_export_is_actually_importable():
    """
    missing = [name for name in polygateway.__all__ if not hasattr(polygateway, name)]
    assert not missing, f"__all__ 承诺了但没绑上的符号: {missing}"
 def test_apache_license_metadata():
    """许可正文和包元数据同时存在，不以版本说明替代许可。"""
    import tomllib
    from pathlib import Path
    root = Path(__file__).resolve().parents[2]
    assert "Apache License" in (root / "LICENSE").read_text()
    assert "Version 2.0" in (root / "LICENSE").read_text()
    project = tomllib.loads((root / "pyproject.toml").read_text())["project"]
    assert project["license"] == {"file": "LICENSE"}
@@ -83,6 +83,7 @@ class _DummyTransport:
        reasoning_effort,
        first_token_event,
        content_event,
        response_mode,
    ):
        raise NotImplementedError
@@ -149,6 +150,7 @@ class _DummyRecorder:
        total_latency_ms,
        stall_ms,
        stall_count,
        stream_end,
    ) -> None: ...
@@ -321,7 +323,7 @@ class TestTelemetryRecorderSignature:
            "attempts",
            "total_latency_ms",
        } <= set(params)
-        assert len(params) - 1 == 38  # 减掉 self
+        assert len(params) - 1 == 39  # 减掉 self
    @pytest.mark.parametrize(
        "name",
@@ -340,6 +342,7 @@ class TestTelemetryRecorderSignature:
            "error_body",
            "attempts",
            "total_latency_ms",
            "stream_end",
        ],
    )
    def test_caller_dimensions_have_no_default(self, name):
@@ -90,6 +90,7 @@ class FakeTransport:
        reasoning_effort,
        first_token_event,
        content_event,
        response_mode,
    ):
        self.calls.append((source.name, call_id))
        self.efforts.append(reasoning_effort)
@@ -132,6 +133,7 @@ class _GenClockTransport:
        reasoning_effort,
        first_token_event,
        content_event,
        response_mode,
    ):
        advance = self._advances.pop(0)
        stall = self._stalls.pop(0) if self._stalls is not None else None
@@ -144,6 +146,7 @@ class _GenClockTransport:
            reasoning_effort=reasoning_effort,
            first_token_event=first_token_event,
            content_event=content_event,
            response_mode=response_mode,
        )
        if stall is not None:
            result = dataclasses.replace(result, stall_ms=stall[0], stall_count=stall[1])
@@ -78,6 +78,7 @@ class StallHedgeTransport:
        reasoning_effort,
        first_token_event,
        content_event,
        response_mode,
    ):
        self.calls.append(source.name)
        self.ft_events.append(first_token_event)
@@ -271,9 +272,7 @@ class TestStallHedgeTrigger:
        """参数化四格(设计 §5.2 逐字): 两阈值独立生效,各格触发语义不串。"""
        # 格 1: 仅 AFTER_S + 流式 pre-TTFT 挂起 → AFTER_S 触发(1.3.7 语义不变)
        s1, s2 = _src("s1"), _src("s2")
-        transport = StallHedgeTransport(
+        transport = StallHedgeTransport({"s1": [("hang",), ("ok", "late")], "s2": [("ok", "fast")]})
            {"s1": [("hang",), ("ok", "late")], "s2": [("ok", "fast")]}
        )
        mw, _, _ = _harness([s1, s2], transport, hedge_after_s=_STALL_AFTER_S)
        ctx = _ctx()
        resp = await asyncio.wait_for(mw(_req(ctx=ctx)), timeout=5)
@@ -312,9 +311,7 @@ class TestStallHedgeTrigger:
        # 格 3b: 两者皆设 + pre-TTFT 挂起 → 阶段 1 AFTER_S 触发(两阶段各管一段)
        s1, s2 = _src("s1"), _src("s2")
-        transport = StallHedgeTransport(
+        transport = StallHedgeTransport({"s1": [("hang",), ("ok", "late")], "s2": [("ok", "fast")]})
            {"s1": [("hang",), ("ok", "late")], "s2": [("ok", "fast")]}
        )
        mw, _, _ = _harness(
            [s1, s2], transport, hedge_after_s=_STALL_AFTER_S, stall_after_s=_STALL_AFTER_S
        )
@@ -340,9 +337,7 @@ class TestStallHedgeTrigger:
    async def test_stall_only_non_stream_degrades_to_single_leg(self):
        """仅 stall 已设 + `stream=False` → 逐字单路(中段沉默无非流式概念,入口门)。"""
        s1, s2 = _src("s1"), _src("s2")
-        transport = StallHedgeTransport(
+        transport = StallHedgeTransport({"s1": [("hang",), ("ok", "x")], "s2": [("ok", "other")]})
            {"s1": [("hang",), ("ok", "x")], "s2": [("ok", "other")]}
        )
        mw, _, _ = _harness([s1, s2], transport, stall_after_s=_STALL_AFTER_S)
        ctx = _ctx()
        task = asyncio.ensure_future(mw(_req(stream=False, ctx=ctx)))
@@ -92,6 +92,8 @@ _EXPECTED_COLUMNS = [
    # —— 1.3.8 沉默归因两列(issue #27)——
    "stall_ms",
    "stall_count",
    # —— 1.3.10 结束方式(#31)——
    "stream_end",
 ]
 # 1.3.5 之前的 26 个 INSERT 字段(旧表形态),供冻结 INSERT 语句与旧表补列用例复用
@@ -187,6 +189,8 @@ async def _record_minimal(recorder, call_id="c1", **overrides):
        # —— 1.3.8 沉默归因两列: 默认 None = 非流式/无沉默观测(合法事实)——
        "stall_ms": None,
        "stall_count": None,
        # —— 1.3.10 结束方式: 默认 None = 非流式/缓存命中/失败行 ——
        "stream_end": None,
    }
    fields.update(overrides)
    await recorder.record_llm_call(**fields)
@@ -268,7 +272,7 @@ class TestSchemaModule:
        # COLUMNS 是 INSERT 字段序,不含数据库自填的 created_at
        assert list(COLUMNS) == [c for c in _EXPECTED_COLUMNS if c != "created_at"]
-        assert len(COLUMNS) == 38
+        assert len(COLUMNS) == 39
        # 两端 DDL 的列出现顺序 == 物理列序(created_at 在第 19 位)
        for ddl in (SQLITE_DDL, PG_DDL):
            assert _first_occurrence_order(ddl, _EXPECTED_COLUMNS) == _EXPECTED_COLUMNS
@@ -282,8 +286,8 @@ class TestSchemaModule:
            "ALTER TABLE llm_calls ADD COLUMN cached_prompt_tokens INTEGER",
        )
        assert PG_BACKFILL[-1] == (
-            "stall_count",
+            "stream_end",
-            "ALTER TABLE llm_calls ADD COLUMN stall_count INTEGER",
+            "ALTER TABLE llm_calls ADD COLUMN stream_end TEXT",
        )
        assert all("IF NOT EXISTS" not in stmt for _, stmt in PG_BACKFILL)
@@ -297,10 +301,10 @@ class TestSchemaModule:
        assert insert_sql("sqlite", _PRE_135_COLUMNS) == _FROZEN_SQLITE_INSERT
        assert insert_sql("postgres", _PRE_135_COLUMNS) == _FROZEN_PG_INSERT
-        # 全量 38 列: 占位符随列数增长,且不留空洞
+        # 全量 39 列: 占位符随列数增长,且不留空洞
-        assert insert_sql("postgres", COLUMNS).count("$") == 38
+        assert insert_sql("postgres", COLUMNS).count("$") == 39
-        assert "$38)" in insert_sql("postgres", COLUMNS)
+        assert "$39)" in insert_sql("postgres", COLUMNS)
-        assert insert_sql("sqlite", COLUMNS).count("?") == 38
+        assert insert_sql("sqlite", COLUMNS).count("?") == 39
        # 裁剪列表按位置占位符重新编号,不留空洞
        assert insert_sql("postgres", ["call_id", "model"]) == (
            "INSERT INTO llm_calls (call_id, model) VALUES ($1, $2) ON CONFLICT DO NOTHING"
@@ -377,13 +381,14 @@ class TestBackendColumnParity:
        """新列只能追加在末尾: 旧表经 ALTER 补列必落末尾,插在中间会让两条路径分叉。"""
        from polygateway.telemetry.schema import COLUMNS
-        assert COLUMNS[-6:] == (
+        assert COLUMNS[-7:] == (
            "cause_type",
            "error_body",
            "attempts",
            "total_latency_ms",
            "stall_ms",
            "stall_count",
            "stream_end",
        )
@@ -776,7 +781,7 @@ class TestSQLiteCallerDimensionsAcceptance:
        conn = sqlite3.connect(db)
        cols = [r[1] for r in conn.execute("PRAGMA table_info(llm_calls)")]
-        assert cols == _EXPECTED_COLUMNS  # 22 → 38 个 recorder 字段(+ created_at 共 39 物理列)
+        assert cols == _EXPECTED_COLUMNS  # 22 → 39 个 recorder 字段(+ created_at 共 40 物理列)
        rows = dict(conn.execute("SELECT call_id, tenant_id FROM llm_calls").fetchall())
        assert rows["new-row"] == "tenant-a"
        assert rows["old-row"] == ""  # 不是 None: NULL 会被 RLS 静默吞掉
@@ -826,7 +831,7 @@ class TestSQLiteSchemaMode:
    """issue #13: `auto_migrate` 两档——auto 保持自动补列,manual 只裁剪写入不发 DDL。
    列数断言一律按**物理列数**写: 旧表 22 个 INSERT 字段 + `created_at` = 23,
-    补齐后 38 + `created_at` = 39。混用 INSERT 字段数与物理列数是本处最易错的地方。
+    补齐后 39 + `created_at` = 40。混用 INSERT 字段数与物理列数是本处最易错的地方。
    """
    def _physical_columns(self, db: Path) -> list[str]:
@@ -865,7 +870,7 @@ class TestSQLiteSchemaMode:
        assert "ALTER TABLE" in message  # 给出可直接执行的补列 SQL
    async def test_auto_mode_still_upgrades_the_legacy_table(self, tmp_path):
-        """auto + 同款旧表: 现状回归,补列后物理列数 23 → 39。"""
+        """auto + 同款旧表: 现状回归,补列后物理列数 23 → 40。"""
        db = tmp_path / "auto_legacy.db"
        _make_pre_tenant_db(db)
@@ -874,10 +879,10 @@ class TestSQLiteSchemaMode:
        recorder.close()
        assert self._physical_columns(db) == _EXPECTED_COLUMNS
-        assert len(self._physical_columns(db)) == 39
+        assert len(self._physical_columns(db)) == 40
    async def test_manual_mode_still_creates_a_fresh_table(self, tmp_path):
-        """manual 只管 ALTER,不管 CREATE: 全新库照建,39 个物理列齐全(设计 §4.2)。"""
+        """manual 只管 ALTER,不管 CREATE: 全新库照建,40 个物理列齐全(设计 §4.2)。"""
        db = tmp_path / "manual_fresh.db"
        recorder = SQLiteRecorder(db, auto_migrate=False)
        await _record_minimal(recorder, call_id="c-fresh", tenant_id="tenant-a")
@@ -1117,6 +1122,8 @@ class TestPostgresBackfillDiscipline:
        # 1.3.8 两列: 稳态定义随补列前移,否则每进程首写都去抢锁
        "stall_ms",
        "stall_count",
        # 1.3.10 一列,理由同上
        "stream_end",
    ]
    def _recorder(self, conn):
@@ -3586,3 +3593,92 @@ class TestTerminalRowSqlSemantics:
            ).fetchone()[0]
            == 0
        )
 # 1.3.8 形态(1.3.10 补列前)的表: 38 个 INSERT 字段 + created_at = 39 物理列。
 # 冻结字面量(由 _PRE_138_DDL 末行补两列),不从常量切片派生,理由同 _PRE_138_DDL。
 _PRE_1310_DDL = _PRE_138_DDL.replace(
    "    total_latency_ms     INTEGER\n);",
    "    total_latency_ms     INTEGER,\n    stall_ms             INTEGER,\n"
    "    stall_count          INTEGER\n);",
 )
 class TestStreamEndColumn:
    """1.3.10 结束方式列(#31): 落行、缺省 NULL、补列幂等、manual 告警、各入口取值。"""
    async def test_value_round_trips_and_default_is_null(self, tmp_path):
        db = tmp_path / "stream_end.db"
        recorder = SQLiteRecorder(db, auto_migrate=True)
        await _record_minimal(recorder, call_id="c-eof", stream_end="eof_after_finish")
        await _record_minimal(recorder, call_id="c-none")
        recorder.close()
        conn = sqlite3.connect(db)
        rows = dict(conn.execute("SELECT call_id, stream_end FROM llm_calls").fetchall())
        conn.close()
        assert rows == {"c-eof": "eof_after_finish", "c-none": None}
    async def test_auto_migrate_backfills_from_138_table(self, tmp_path):
        db = tmp_path / "pre1310.db"
        conn = sqlite3.connect(db)
        conn.execute(_PRE_1310_DDL)
        conn.commit()
        conn.close()
        for call_id in ("c1", "c2"):  # 二次初始化幂等
            recorder = SQLiteRecorder(db, auto_migrate=True)
            await _record_minimal(recorder, call_id=call_id, stream_end="done")
            recorder.close()
        conn = sqlite3.connect(db)
        assert [r[1] for r in conn.execute("PRAGMA table_info(llm_calls)")] == _EXPECTED_COLUMNS
        conn.close()
    async def test_manual_mode_names_the_new_alter(self, tmp_path, captured_warnings):
        db = tmp_path / "manual1310.db"
        conn = sqlite3.connect(db)
        conn.execute(_PRE_1310_DDL)
        conn.commit()
        conn.close()
        recorder = SQLiteRecorder(db, auto_migrate=False)
        await _record_minimal(recorder, call_id="c-manual", stream_end="done")
        recorder.close()
        conn = sqlite3.connect(db)
        assert len([r[1] for r in conn.execute("PRAGMA table_info(llm_calls)")]) == 39
        assert conn.execute("SELECT call_id FROM llm_calls").fetchone() == ("c-manual",)
        conn.close()
        assert "ALTER TABLE llm_calls ADD COLUMN stream_end TEXT" in captured_warnings[0]
    async def test_attempt_takes_stream_end_from_response(self):
        rec = _MemoryRecorder()
        await TelemetryEmitter(rec, text_cap=None, scope="LLM").emit_attempt(
            request=_REQ,
            source=_source(),
            call_id="c",
            latency_ms=1,
            response=_resp(stream_end="eof_after_finish"),
            error=None,
            reasoning_applies=True,
            operation="chat",
        )
        assert rec.rows[0]["stream_end"] == "eof_after_finish"
    async def test_failed_hit_and_terminal_rows_are_null(self):
        rec = _MemoryRecorder()
        emitter = TelemetryEmitter(rec, text_cap=None, scope="LLM")
        await emitter.emit_attempt(
            request=_REQ,
            source=_source(),
            call_id="c",
            latency_ms=1,
            response=None,
            error="boom",
            reasoning_applies=True,
            operation="chat",
        )
        # 命中行显式不信任 response 上的值(即使上游误带)
        await emitter.emit_cache_hit(
            request=_REQ, response=_resp(cache_hit=True, stream_end="done"), operation="chat"
        )
        await emitter.emit_terminal_failure(
            request=_REQ, call_id="c", error="dead", operation="chat", stats=_MIGRATED_STATS
        )
        assert [row["stream_end"] for row in rec.rows] == [None, None, None]
@@ -141,6 +141,7 @@ async def test_salvage_override_stays_in_domain(usage):
        reasoning_effort=None,
        first_token_event=None,
        content_event=None,
        response_mode="text",
    )
    assert result.usage_source in USAGE_SOURCES
Author	SHA1	Message	Date
iomgaa	25a90ebd05	chore: merge 1.3.10 unified completion verdict (#30/#31)	2026-10-15 00:38:40 -04:00
iomgaa	1201a04449	chore: date 1.3.10 changelog for release	2026-10-15 00:38:19 -04:00
iomgaa	abcdf6930e	fix: address completion verdict review findings - fidelity cacheability also requires a non-empty projected body, so think-tag-only answers are no longer cached - a no-argument tool sent with arguments null only is a deterministic dialect: ResultInvalid tool_arguments_null instead of retried - text mode treats choice index null as 0 and no longer lets False pose as 0 - null-only tool_calls elements no longer produce an empty tool_calls list; non-stream fidelity checks role before the verdict; warning paths are length-bounded - docs: ARCHITECTURE 7.8 field counts, README cache/watchdog wording, CHANGELOG notes, review record in the design, hook note in the plan Red: 8 new tests failed before this change (e.g. test_openai_cacheable_requires_projected_body, test_null_arguments_tool_is_result_invalid_stream, test_text_mode_choice_index_null_is_zero[None-True]).	2026-10-15 00:28:20 -04:00
iomgaa	31942f55f1	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.	2026-10-15 00:03:15 -04:00
iomgaa	779a9b29a3	feat: record stream end mode in telemetry llm_calls gains a nullable stream_end TEXT column (auto backfill, manual-mode trimming as in 1.3.8). TelemetryRecorder.record_llm_call takes a new required keyword stream_end; the emitter reads it from the response on attempt rows and writes NULL for failed, cache-hit and terminal rows. Red: 18 tests in tests/unit/test_telemetry.py and test_ports.py failed against the pre-change source (missing column, 38-field signature, stream_end absent from emitted rows).	2026-10-14 23:54:11 -04:00
iomgaa	48ba36dd94	fix: gate cache writes and reads on a shared cacheability verdict Cacheable is now a strict subset of deliverable: salvaged streams, content-less results and length/filter/unknown finishes are delivered but never written, and the read path applies the same verdict to the stored values before hit overrides (invalid stream_end or non-string finish read as a miss; 1.3.9 fidelity entries fall back to the completion's finish). Hits reset stream_end. The legacy _has_completion_output helper is folded into _is_cacheable. Red: 13 tests in tests/unit/test_cache.py failed before this change (uncacheable results were written and replayed; new fields not reset).	2026-10-14 23:39:50 -04:00
iomgaa	39a319e34e	fix: judge stream completion by finish reason and trailing usage Both transport paths now share one verdict: a stream is complete on [DONE] or on finish_reason followed by measured usage and a clean EOF (both modes; missing_done only governs real truncation). Outcomes follow the design's first-match table: upstream_error finishes stay transient, fidelity mode delivers reasoning-only/length results, text mode raises ResultInvalid for content-less length/filter endings, and non-stream fidelity judges before building the snapshot so truncated tools reach tool_truncated. Projections honour the reasoning alias, dialect warnings are bounded, and responses carry finish_reason and stream_end. Red: 39 of 46 tests in tests/unit/test_completion_transport.py failed before this change (e.g. eof_after_finish raised 保真响应缺 [DONE]; reasoning-only length raised empty_completion; reasoning-only stream hit the TTFT watchdog, re-confirmed by disabling alias liveness).	2026-10-14 23:31:54 -04:00
iomgaa	16743ca11d	fix: merge unknown and null stream fields losslessly in completion accumulator Null is treated as absent at every layer; unknown delta, tool and function fields merge by OpenAI streaming conventions (strings concat, label keys idempotent, indexed arrays by index) and conflicts drop the key and record its path instead of failing the call. The accumulator now tracks finish and usage-after-finish in both modes, exposes the reasoning alias, and non-stream parsing splits shape checks from snapshot construction. Red: 20 of 47 tests in tests/unit/test_openai_completion.py failed before this change (e.g. test_null_known_and_unknown_fields_are_absent raised TransientError 未知 delta 字段; finish_seen/raw_message missing).	2026-10-14 23:21:05 -04:00
iomgaa	e5ad67408a	feat: add kernel completion verdict functions and response fields Pure functions in types.py classify finish reasons, judge stream completeness and outcome, and decide cacheability; TransportResult and LLMResponse gain finish_reason and stream_end; snapshots accept tool_calls null. Red: tests/unit/test_completion_verdict.py failed at collection (ImportError: _classify_finish et al. undefined) before this change.	2026-10-14 23:12:00 -04:00
iomgaa	ab0e924849	docs: add implementation plan for unified completion verdict	2026-10-14 23:04:05 -04:00
iomgaa	607523ef5c	docs: fold round-2 review fixes into completion verdict design	2026-10-14 22:46:56 -04:00
iomgaa	95104af2a5	docs: add unified completion verdict design for issues 30 and 31	2026-10-14 22:39:47 -04:00
iomgaa	5d2ad40336	chore: gate complexity only on functions touched by the change Whole-tree radon blocking let 16 legacy C+ functions block every commit, including docs-only ones. Touched functions still block; legacy debt is reported as a warning.	2026-10-14 22:32:52 -04:00
iomgaa	22609c90d6	chore: merge approved 1.3.9 release preparation	2026-10-01 23:16:18 -04:00
iomgaa	a0cf8546dc	chore: prepare approved 1.3.9 release version	2026-10-01 23:08:37 -04:00
iomgaa	ce10881eb0	docs: archive preserved wiki records and register hedge nodes	2026-10-01 23:03:51 -04:00
iomgaa	bd82f16921	chore: merge 1.4.0 OpenAI message fidelity release	2026-10-01 14:48:47 -04:00
iomgaa	2c9c5a3aa7	test: forward response mode in transport helper	2026-10-01 14:48:29 -04:00
iomgaa	9185eab8c9	feat: preserve governed OpenAI tool messages in 1.4.0 Add faithful single-choice chat results, tool stream activity, error-frame retries, and isolated protocol caching. Reject empty cached completions with the same value predicate as transport, add regression coverage, and adopt Apache-2.0.	2026-10-01 14:32:19 -04:00