docs: fix plan per independent review (B1 emitter fake sync, B2 guard return contract, N1-N5)

2026-09-14 00:10:37 -04:00
parent 929d60e501
commit 6f3a620c73
2 changed files with 48 additions and 9 deletions
@@ -0,0 +1,37 @@
+核查完毕，所有证据齐备。撰写审查报告：
+
+## Review
+
+**结论：有条件执行** — 计划整体忠实于已批准设计（含 B1-B4/N1-N9)，同步清单两条 grep 重跑基本属实，TDD 红绿逻辑与编排伪代码经源码逐行验证成立；但有 **2 处计划文本级硬伤**（按字面执行必在 T3/T4 验收门炸出计划声称"零改动/不改断言"的返工）需先修计划，另 5 处建议项。无设计级返工、无人类门事项。
+
+### 8 条核查逐条裁决
+
+**1. 同步清单真实性 — 基本属实，一处虚列。** 重跑两条 grep:§2.2 的 11 处 `def complete` + 11 处调用点全部命中且行号准确（含 test_retry.py:112 第二 fake 与 :123 转发、e2e/conftest.py:294/:306 转发、test_live_evidence.py:280/:1270、test_usage_source_domain.py:142);§2.3 的 13 处 `**fields` fake 计数精确、3 处负例（:3327/:3349/:3354 均为故意残缺显式签名）、2 处 `**fields` recorder(sqlite.py:145/postgres.py:411)、_DummyRecorder(test_ports.py:102）全部属实。**虚列**：§2.3 #8 声称 test_hedge.py:122"零改动"不成立（显式全签名 fake，见 B1);test_backpressure.py:233 是 `*args, **kwargs` 才真零改动。另漏列两处硬编码计数断言（见 N1)。
+
+**2. 签名与行号 — 抽查 14 处，绝大多数精确。** 精确命中：ports.py:56/:306(36 参实测）、types.py:296/:328/:560/:581/:590/:633/:674、openai_compat.py:427/:553/:560/:659/:666（chunk 循环 :581-592、装配 :598-616)、retry.py:275/:314/:344/:346/:436/:484/:533-562/:574-578/:580-594、config.py:57/:195/:745-769/:772-849/:865/:904、client.py:240/:252/:280/:485、middleware/telemetry.py:198/:396/:449/:501/:556/:618、schema.py 五编辑点。**漂移**:`_attempt_hedged` 计划 :371-530、实际 **:415-531**；另有 5 处 ±1-6 小漂移（入口门 :268-279、from_env :394-424、_emit :668-700、_complete_once :659-705、_validate_hedge :375-392)。具名接缝均无歧义，不阻断（见 N2)。
+
+**3. TDD 红绿逻辑 — 四批次全部成立。** 批次 A（端口未加参→TypeError、纯函数不存在→ImportError、字段不存在→TypeError)、批次 B（字段缺失→AttributeError、仍得墙钟值→断言失败）、批次 C（冻结清单先扩→列数/列序断言失败，已验证 `_EXPECTED_COLUMNS` 派生机制；协议未加参而 _DummyRecorder 先加→装配闸 ValueError)、批次 D(kw 不存在→TypeError、`hedges==0`）均为真红，无伪 TDD。措辞瑕疵：批次 D "键未识 ValueError" 实为 AttributeError/TypeError(3 段键被 config.py:431 静默跳过），红仍成立（见 N3)。
+
+**4. 编排语义 — 并发正确性验证通过，与设计 §5.2 一致。** Event 复检防同 pass 误触发 ✓;check→clear 之间同步无 await（单线程循环下无交错）✓；每轮自建 waiter + finally 收口 + `cancelling()` 穿透逐字套用 :544-561 既有范式 ✓;Event 状态持久无丢失唤醒 ✓；残留竞速窗口已诚实标注（设计 N3① 批准形态）。仅 stall 时"阶段 1 无 timeout 等首 token→再进阶段 2"与设计 §5.2/B3 逐字一致——**pre-TTFT 沉默不被 stall 窗误吞正是设计意图**,TTFT 长等待由 ttft 看门狗治理 ✓。入口门三分支自洽（仅 stall+非流式→单路；AFTER_S+非流式→对冲路，事件退化为纯时间阈值，同 1.3.7)✓。**主路被看门狗掐死**:TransientError 在 `_attempt` except 分支转为 `_Failed` 返回（retry.py:393-406),primary task 正常完成 → Phase 5 "先了结的是失败则等另一路"(retry.py:505-509）原样承接，attempt 级记账（breaker/attempt_fails/遥测 error 行）在返回前已完成 ✓——设计 §11-N9 完全可由既有路径表达。
+
+**5. 换算与钟纪律 — 成立。** N8 唯一换算处落点核实：retry.py:346 是现状唯一 int 换算点；sink 三元组升级的消费方仅 `__call__`:289、`_record_generation`:578、`_register_hedge`:593 三处，全在 retry.py 且计划 §3.2 已枚举，无测试直调这两个私有函数（grep 实证）。N4 钟同源核实：client.py:243 `now=time.monotonic` 默认与 transport 内 `time.monotonic` 同钟 ✓。`record_generation` 加 kw-only 默认 None 对 embedding.py:391/ocr.py:407/test_types.py:648-669 零冲击 ✓。
+
+**6. 遥测链路 — 取舍安全，一处 fake 例外。** emit_attempt 加默认 None kw 对全部 ~45 处真实 emitter 直调（均关键字形态，grep 全量清点）与 embedding.py:532/ocr.py:611 安全 ✓；三处装配闸负例在协议 +2 参后仍不满足 `signature.bind`，负例仍绿 ✓（逻辑推理成立：残缺签名缺的不止两参）。**例外即 B1**:RetryMW._emit 是 emit_attempt 的调用方且将显式转发两 kw,"新参默认 None"只保护调用方、不保护被调的显式签名 fake。
+
+**7. 配置守卫 — 落点属实，返回契约有缺口。** check_hedge_assembly 调用点四处（client.py:252、config.py:384、test_config.py:1174/:1184）全关键字形态，加 kw-only 参可行；有效最小值守卫与 openai_compat.py:573 回落同款 ✓;B4 落点核实：EmbeddingSettings.__post_init__ :865 存在且持 `gateway` 字段 ✓,OcrSettings :904 确无 `__post_init__`（计划"新增"表述准确）✓。**缺口**：归一化 stall_after_s 的返回路径未定义（现状返回 `float|None`)，二元组返回会炸 test_config.py:1184 的 `is None` 断言，与批次 E 冲突（见 B2)；早退须改写为"两阈值皆 None 才早退"（见 B2 附带）。
+
+**8. 默认关闭回归 — 论证成立。** T1 恒传 None(retry.py:275 等）✓、入口门第一分支逐字保留 ✓;stall 序列无条件记录（content_event=None 只跳过 set，不跳过时间戳）→ 流式 ≥2 chunk 恒填 0.0/0.0 或实际值、非流式/<2 恒 None——**计量独立于对冲开关正是 P1 意图，设计与计划一致** ✓。TransportResult 新字段不破坏回归门：test_openai_compat.py 无相等断言、无 asdict/fields 计数（grep 实证）✓;CallStats 新字段默认 None 且无 `== CallStats` 断言 ✓。**字面例外**:B1/N1 所列硬编码计数断言与 test_config.py:1184 是批次 E"不改一行既有断言"的真实例外，计划应显式登记而非被实施者发现。
+
+### 发现列表
+
+| # | 级别 | 位置 | 问题 | 修法 |
+| --- | --- | --- | --- | --- |
+| B1 | 阻断（事实错误，修法小） | plan §2.3 #8;tests/unit/test_hedge.py:121-133 | RecordingEmitter.emit_attempt 是显式全签名 fake（收 8 个 kw，无 `**kwargs`);T3 后 `_emit` 显式转发 `stall_ms=`/`stall_count=` → TypeError,test_hedge.py 全部成功路径用例红，且违反批次 D/E "1.3.7 既有断言一字不改"承诺。"新参默认 None"的论证只护调用方，护不住被调 fake | §2.3 #8 拆两行：test_backpressure.py:233(`*args, **kwargs`）真零改动；test_hedge.py:122 列入 T3 同步清单（加 `stall_ms=None, stall_count=None` 两 kw，与 T1 fake 签名同步同款处置）；批次 E 措辞澄清"fake 签名同步不属于断言改动" |
+| B2 | 阻断（契约占位，违反计划自设标准） | plan §3.5 守卫行；config.py:772-849;test_config.py:1171-1190 | 计划要求 "RetryMW 传 stall_after_s=归一化值"，但归一化值如何出 check_hedge_assembly 未定义（§3 自称"可执行定义，禁止占位")；最自然的二元组返回炸 test_config.py:1184 的 `is None` 断言，与批次 E 直接冲突。附带：§3.5"同 after is None 既有早退形态"字面执行会让仅 stall 配置绕过守卫②③④（批次 D 能抓住，但属误导） | §3.5 钉死返回契约（建议 `tuple[float\|None, float\|None]` 或等值命名结果，config.py:384 与 client.py:252 两处随之解构）;test_config.py:1174/:1184 列入 T4 同步清单；早退条件改写为"两阈值皆 None 才早退"；批次 E 例外登记本处 + B1 + N1 |
+| N1 | 建议 | test_ports.py:313、test_telemetry.py:748（连带 :650/:743/:756 注释文本） | 两处硬编码计数断言（`len(params)-1 == 36`、`len(physical) == 37`）未列入批次 C 清单；T3 验收门会自愈，但破坏"清单即全量"承诺 | 补入批次 C 扩展点（36→38、37→39)，注释文本顺手同步 |
+| N2 | 建议 | plan §2.1/§8 行号表 | `_attempt_hedged` :371-530 实为 :415-531；另有 5 处 ±1-6 漂移 | 执行前以 grep 复核为准（§6 已有此纪律），修正 §2.1 表防误锚 |
+| N3 | 建议 | plan T4 先红清单 | "键未识 ValueError" 不准确：3 段未识键被 config.py:431 静默跳过，实际红因是 AttributeError/TypeError | 措辞修正即可，红成立 |
+| N4 | 建议 | middleware/telemetry.py:368 | docstring "组装 36 字段" 未列入计数同步范围（ports.py:280/sqlite.py:146/schema.py:8 已覆盖） | T3 顺手同步，防计数漂移 |
+| N5 | 建议 | tests/unit/test_hedge.py:150 `_harness(stall_window_s=300.0)` | 既有 `stall_window_s`(StallClock 预算）与新 `stall_after_s` 命名相邻，新文件复制设施时易混 | test_stall_hedge.py 设施复用时加注释区隔两概念 |
+
+**Merge verdict: OK with notes** — B1/B2 修计划文本（均为小时级，不改任何设计语义）后即可按书执行；TDD 门对全部 N 项有自愈能力。