docs: document net generation time and mid-stream stall hedging

.env.example

@@ -80,6 +80,13 @@ LLM_CIRCUIT_BREAKER_COOLDOWN=60          # 或 LLM__BREAKER__COOLDOWN_S
 # ── 「挂起 vs 慢生成」物理不可分,建议取源 p50 的数倍)。对冲向异源并发再发一次,走完整限流/熔断准入,
 # ── 拿不到配额静默放弃。成本含义: 开启即用配额换延迟——触发窗口内 in-flight 翻倍,输家被取消后按 est
 # ── 保留预扣(不喂熔断),且输家可能已被上游计费、取消止不住。须与 CALL_DEADLINE_S 组合时强制阈值 < 期限 ──
+# LLM__STREAM__STALL_THRESHOLD_MS=1000   # 中段沉默计量阈值(毫秒,缺省 1000):相邻增量 chunk 间隔严格大于它才计入
+# ── stall_ms/stall_count 并从 generation_ms 净口径中扣除;仅改计量口径,不改任何行为 ──
+# LLM__HEDGE__STALL_AFTER_S=             # 中段沉默对冲触发阈值(秒);缺省不设 = 关闭(仅流式 chat 生效)
+# ── 语义: 主路首 token 之后相邻增量 chunk 沉默超此阈值 → 向异源并发再发一路;独立于 HEDGE__AFTER_S 生效,
+# ── 仅设它且请求非流式时逐字走单路。成本: 下游实测沉默 >20s 占 19.0%,触发率远高于首 token 对冲——
+# ── 开启即用配额换延迟,输家可能已被上游计费;无业界公开先例(超业界现状能力)。守卫: ≥ 最小源有效
+# ── inter-token 超时(对冲窗永不开)或 ≥ CALL_DEADLINE_S → 装配期 ValueError;单源 scope 仅 warning ──
 
 # ══ 装配选择(PGW_*)══
 PGW_LIMITER_BACKEND=memory               # memory | redis(redis 需 REDIS_URL;多进程 worker 必须 redis)

CHANGELOG.md

@@ -1,5 +1,52 @@
 # Changelog
 
+## 未发布
+
+流式中段沉默的计量与应对(issue #27 / #28):`generation_ms` 口径重定义为**净生成时间**(扣除所有超阈值中段沉默)并配 `stall_ms`/`stall_count` 归因字段与遥测两列;另加一条**默认关闭**的中段沉默对冲(主路首 token 之后相邻增量 chunk 间隔超阈值时,向异源并发再发一次)。两键均不设时行为逐字等于 1.3.7(默认关闭回归门: 既有 unit/contracts 全套件语义断言一行未改)。
+
+### 行为变更: `generation_ms` 口径重定义(1.3.7 墙钟 → 本版净生成时间)
+
+> [!WARNING]
+> **同一字段,两版口径不同。** 1.3.7 的 `generation_ms` 是赢家那次 transport 调用的完整**墙钟**(中段沉默全部计入);本版起是**净生成时间** = 墙钟 − Σ(所有 > `{SCOPE}__STREAM__STALL_THRESHOLD_MS` 的相邻增量 chunk 沉默),**仍含 TTFT 与尾部**(末 chunk → 流结束归活跃侧,墙钟基底口径的有意选择)。还原公式: **墙钟 = `generation_ms + stall_ms`**(`stall_ms` 为 None 时墙钟 = `generation_ms`)。
+
+语义突变在一般情形下违反「字段只增不删不改名」精神,本次由人类以「窗口期最小代价」裁决放行(2026-09-11),依据三行: 该字段 1.3.7(2026-09-10)才引入、**发布仅 2 天**;**消费者唯一**(提出本需求的下游 Terminal-Bench,三参考项目均未消费);**遥测 DB 从未存过** `generation_ms`,无历史账本纵向断裂。字段名「裸生成时间」原本承诺的就是净口径,本次重定义是兑现名字而非推翻承诺。`max_inter_token_ms`(单次最大相邻间隔)原语义一字不动——它与 `generation_ms` 是两个口径,不能互算。
+
+| 项 | 口径 |
+| --- | --- |
+| 计入沉默的间隔 | 相邻**增量 chunk**(`content` 或 `reasoning_content` 均计,与看门狗/首 token 活性口径一致)间隔**严格大于**阈值(恰好等于不减);空 chunk / usage 帧 / SSE keepalive 不计时;chunk 边界是传输/解析缓冲产物而非 token 边界,本口径不假装是 ITL |
+| `stall_ms: int \| None` | 赢家路超阈值中段沉默总额(毫秒);与 `stall_count` **成对报告**(只报净数无法行动) |
+| `stall_count: int \| None` | 超阈值相邻间隔个数 |
+| None 条款(照 vLLM 排除条款) | 非流式 / 增量 chunk <2 → 两字段 None 且 `generation_ms` **不退减**(= 原墙钟);None = 「无沉默观测」而非 0,下游预算公式以 `stall_ms is None` 为分支条件 |
+| 对冲赢家 | 三值全部取**赢家路**;已完成但落选的对冲输家其沉默在其 attempt 遥测行(可按 `logical_call_id` join 还原);被取消的输家无 TransportResult、`hedge_cancelled` 行 stall 恒 None |
+| 与业界基准口径的区隔 | NVIDIA TTFT/ITL/E2EL 与 vLLM 的基准口径**均不扣除**沉默——扣沉默是本库自造口径,与基准数字比较时不得混用 |
+
+### 遥测两列(纯增量,可空)
+
+遥测表 `llm_calls` 末尾追加 `stall_ms` / `stall_count` 两**可空**列(INSERT 字段 36 → 38,物理列 37 → 39),落库值与 `CallStats` 快照同源(retry 层已取整的 int)。旧行 NULL 不回填(NULL 表达「补列之前根本没记过这件事」);auto 档幂等补列(先探测后 ALTER),manual 档按现有列裁剪写入并点名缺列,补列 SQL 由 `telemetry_schema_sql()` 自取。`generation_ms` **仍不进遥测列**——要墙钟用 `latency_ms` 或 `generation_ms + stall_ms` 还原。`TelemetryRecorder.record_llm_call` 协议同步加两个**无默认值** keyword-only 参数: 自建 recorder 未跟进会在**装配期**被形状闸当场拒绝(不是运行期静默丢行),`**fields` 形态不受影响;`emit_cache_hit` / `emit_terminal_failure` 与失败/取消 attempt 行两列恒 NULL。
+
+### 中段沉默对冲(默认关闭;无业界公开先例)
+
+新键 `{SCOPE}__HEDGE__STALL_AFTER_S`: 主路**首 token 之后**相邻增量 chunk 间隔超此阈值 → 向异源并发再发一路,先回者赢、输家取消。编排/记账/遥测全部复用 1.3.7 对冲语义(异源排除、完整准入、拿不到配额静默放弃、`hedge_cancelled` 遥测行、两败只计一次重试预算)。**诚实标注: 业界对中段沉默的落地形态收敛为「看门狗掐流 → 重试」,「中段沉默触发并发副本」在任何主流网关/库中均无公开先例**——本能力属超业界现状能力,启用前请理解其语义。
+
+**请先读这三句**:
+
+| # | 承诺 | 展开 |
+| --- | --- | --- |
+| 1 | **默认关闭,开启即用配额换延迟** | 不设该键时行为逐字等于 1.3.7。下游实测(Terminal-Bench 4407 次成功调用)沉默 >20s 占 **19.0%**——触发率远高于首 token 对冲(ttft >20s 仅 3/4407),开启后约两成调用会在触发窗口内 in-flight 翻倍 |
+| 2 | **输家可能已被上游计费,取消止不住** | 与 1.3.7 同一性质: 输家按 est 保留预扣(闸内保守记账,不是上游真实计费的计量);取消止得住等待,止不住上游已经烧掉的钱。对账靠 `hedge_cancelled` 遥测行按 `logical_call_id` join |
+| 3 | **独立于 `HEDGE__AFTER_S` 生效,仅流式 chat** | 两阈值各自独立,可独设可组合;仅设 `STALL_AFTER_S` 时首 token 前的沉默**不触发**(窗在首 token 到达后才开);仅设它且请求非流式 → 逐字走单路(中段沉默无非流式概念,等价未配置);Embedding/OCR scope 配了任一对冲键 → 装配期 warning 后静默退化 |
+
+**与看门狗的交互及不对称声明(运维「挂起率」统计须知)**: 主路沉默超 `INTER_TOKEN_TIMEOUT_S` 被看门狗掐死 → 照常进 Transient 重试链并**喂熔断失败计数**(1.3.6 起既有语义),对冲路已在跑时本轮不因主路之死而败(等副路裁定,主路 attempt 记账照常);对冲输家被取消 → **不喂**熔断(1.3.7 已批准语义)。同为源沉默事件、两种处置,本版不改任一。
+
+### 配置面
+
+| 键 | 值域 | 缺省 | 守卫 |
+| --- | --- | --- | --- |
+| `{SCOPE}__STREAM__STALL_THRESHOLD_MS` | 正整数毫秒 | **1000** | 仅改计量口径,不改任何行为;调整接口三层同权(env 键 / `GatewaySettings.stall_threshold_ms` / `GatewayClient(stall_threshold_ms=...)`),无 per-call 覆盖,不做自适应(防与对冲阈值耦出反馈环) |
+| `{SCOPE}__HEDGE__STALL_AFTER_S` | 有限正数秒 | **未设 = 关闭** | 装配守卫: `≥ min over sources of (inter_token_timeout_s or timeout_s)`(有效最小值,对冲窗永不开)→ **ValueError**;`≥ call_deadline_s` → ValueError;单源 scope 设阈值 → warning 允许 |
+
+`GatewayClient(...)` 直传 `hedge_stall_after_s` / `stall_threshold_ms` 两 keyword-only 参数走同一份装配守卫;`from_settings`/`from_env` 照常透传。
+
 ## 1.3.7(2026-09-10)
 
 给 chat 链路加了一条**默认关闭**的长尾对冲(issue #24):一次尝试挂起超过阈值时,并发向**另一个等价源**再发一次,先回者赢、输家取消。另给 `CallStats` 追加三个字段,其中 `generation_ms`(裸生成时间)对四条链路全部生效,与是否开启对冲无关。

README.md

@@ -18,12 +18,13 @@
 | 背压与判死 | 配额满与熔断开路**各自**可选等待或快速失败(`QUOTA_FULL` / `CIRCUIT_OPEN`,两键不可互相替代);等待期按双条件判死(本地非生产性等待与全局无进展**同时**超窗)。stall 窗口只计**非生产性**等待(429 退避/配额轮询/熔断冷却),与 `TIMEOUT_S` 无耦合 |
 | 调用期限 | 一次逻辑调用可选一条**墙钟硬边界**(`{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-生成时间口径与中段沉默对冲) |
 | 响应缓存 | Redis/内存;key 含 model + messages 摘要 + namespace(缓存隔离单位)+ salt + 采样参数 + 请求级推理档位(同 messages 跑 low 与 max 不互相命中),多模态 content 先摘要再 hash(防毒化);可 per-call 绕过(科研重采样) |
 | 流式看门狗 | TTFT / inter-token / 总超时三层活性;thinking token 刷活性不计结果;截断流(缺 `[DONE]`)判瞬时不入缓存 |
 | 推理可观测性 | "这次到底推理没推理"由多信号裁定(推理正文压倒 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` 与遥测落库 |
-| 遥测与成本 | 每次调用(含缓存命中与失败)必录 36 字段;三类行(`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`——赢家那次 transport 调用的墙钟,排除准入排队/退避/触发前等待,与 `total_latency_ms` 的差值即「在等不在生成」——与对冲计数 `hedges` / `hedge_won`),重试、换源、结构化重问、embedding 分批共享同一逻辑 ID;每次**领域失败**另落一条 `terminal_failure` 行,失败调用数从此是一条 `WHERE event_kind = 'terminal_failure'`,详见[1.3.5 逻辑调用统计与失败诊断](#135-逻辑调用统计与失败诊断) |
+| 遥测与成本 | 每次调用(含缓存命中与失败)必录 38 字段;三类行(`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、不建索引** |
 | 遥测表治理 | `llm_calls` 是**下游的表**:PG 侧缺省**不再自动 `ALTER` 补列**(`PGW_TELEMETRY_SCHEMA_MODE` 三态,不设则 sqlite→auto、postgres→manual),manual 档点名缺列并按现有列裁剪写入;`telemetry_schema_sql(backend)` 自取可粘进迁移文件的建表/补列 SQL;`PGW_TELEMETRY_TEXT_CAP` 限正文长度(**不设 = 存全文**);保留期与访问控制走[生产部署 DDL 模板](#生产部署-ddl-模板postgresql)加 `tools/telemetry_retention.py` |
@@ -111,6 +112,33 @@ stats.total_latency_ms             # 含缓存 IO、退避、准入等待、重
 
 自建 `TelemetryRecorder` 的下游请同步补齐这 10 个 keyword-only 无默认值参数(或改成 `**fields` 形态),并同步自己的 schema 与 INSERT 字段。装配期形状闸只能证明形状能被接受,证不了函数体真的落这些列。
 
+## 1.3.8 生成时间口径与中段沉默对冲
+
+> [!WARNING]
+> **`generation_ms` 自 1.3.8 起是净生成时间,不再是墙钟。** 同一字段两版口径不同(放行依据:字段发布仅 2 天、消费者唯一、遥测无账本,人类「窗口期最小代价」裁决);1.3.7 的墙钟值 = 本版的 `generation_ms + stall_ms`。两段口径的存量快照不可直接纵比。
+
+### `generation_ms` 口径表
+
+| 项 | 口径 |
+| --- | --- |
+| 定义 | **净生成时间** = 赢家那次 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 is None` 分支条件 | 非流式 / 增量 chunk <2 → 两字段 None 且 `generation_ms` **不退减**;None = 「无沉默观测」而非 0,下游预算公式以此为分支条件 |
+| 与基准口径的区隔 | NVIDIA TTFT/ITL/E2EL 与 vLLM 的基准口径**均不扣除**沉默——扣沉默是本库自造口径,与基准数字比较时不得混用 |
+
+`max_inter_token_ms`(单次最大相邻间隔)原语义不变,与 `generation_ms` 是两个口径、不可互算。沉默归因同批进遥测表 `stall_ms`/`stall_count` 两**可空**列(INSERT 字段 36 → 38,旧行 NULL 不回填);`generation_ms` 本身仍不落库,墙钟用上式还原。对冲场景三值全部取**赢家路**:落选输家的沉默在其 attempt 遥测行(可按 `logical_call_id` join),被取消输家的 `hedge_cancelled` 行 stall 恒 NULL。
+
+### 配置表(两键,均仅 chat 生效)
+
+| 键 | 值域 | 缺省 | 守卫与调整接口 |
+| --- | --- | --- | --- |
+| `{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);运维「挂起率」统计须知不对称:看门狗掐死**喂**熔断失败计数,对冲输家取消**不喂**熔断。
+
 ## 安装
 
 发布在实验室 Gitea PyPI(公开包,匿名可装):

research-wiki/ARCHITECTURE.md

@@ -501,6 +501,10 @@ flowchart TB
 
 指数退避 + jitter: `delay = min(base * 2^attempt, max_delay) * uniform(0.5, 1.5)`,与 `Retry-After` 提示取较大值。**单层重试原则**: 库内只有 RetryMW 一层重试;Video-Tree/GovDoc 现存的"治理层重试 + Agent 步级二次重试"双层结构(异常集合不同、职责重叠)不复制——业务侧如需任务级重试,自行在库外包,且语义是"任务重试"不是"调用重试"。
 
+**生成时间净口径与沉默归因(2026-09-11,1.3.8,issue #27;设计 `designs/2026-09-11-streaming-stall-design.md` §4)**: `CallStats.generation_ms` 自 1.3.8 起为**净生成时间** = 赢家那次 transport 调用墙钟 − Σ(所有 > `stall_threshold_ms`(默认 1000,`SourceConfig` 字段,env 键 / `GatewaySettings` 字段 / 构造 kwarg 三层可调,无 per-call 覆盖)的相邻**增量 chunk**(`content` 或 `reasoning_content` 均计,与看门狗活性口径一致;空 chunk/usage 帧/SSE keepalive 不计时)沉默,**仍含 TTFT 与尾部**(末 chunk→流结束归活跃侧,墙钟基底口径的有意选择);1.3.7 的墙钟口径由 `generation_ms + stall_ms` 还原,语义突变经人类"窗口期最小代价"裁决放行(字段发布仅 2 天/消费者唯一/遥测无账本)。归因两字段 `stall_ms`/`stall_count`(沉默总额/超阈值相邻间隔个数,成对报告——Gregg off-CPU 原则);非流式/增量 chunk <2 → None 且不退减(None = 无沉默观测,下游以 `stall_ms is None` 分支);对冲输家的沉默不进赢家快照(落选者在其 attempt 遥测行,被取消者 `hedge_cancelled` 行恒 None)。**换算唯一处纪律(N8)**: TransportResult 携带未取整 `float` stall 值,取整与净额计算(`net = max(0, wall_ms − int(stall_ms or 0))`,clamp 防御)全库只在 retry 层一处,各实现不得另取整;钟同源(N4)——沉默序列(transport `time.monotonic`)与墙钟(retry 注入 `now`,生产即 `time.monotonic`)同钟,FakeClock 测试配自控 stall 值的假 transport。观测原语: transport 热路径只做"记时间戳 + set `content_event`",一切计量与触发判定在热路径外从该序列派生。扣沉默是库自造口径,NVIDIA/vLLM 基准口径均不扣沉默,不得混写。
+
+**中段沉默对冲(2026-09-11,1.3.8,issue #28;设计同上 §5)**: `{SCOPE}__HEDGE__STALL_AFTER_S`(默认关闭)与 1.3.7 `{SCOPE}__HEDGE__AFTER_S` **两阈值独立生效**(可独设可组合);`_past_hedge_window` 为**两阶段触发窗**——阶段 1 首 token 前: AFTER_S 已设才计时触发(仅设 stall 时此阶段不触发,但仍须等首 token 到达才进阶段 2,否则 pre-TTFT 沉默会被 stall 窗误吞);阶段 2 首 token 后: STALL_AFTER_S 循环等待 `content_event`,超时到期复检 `is_set()` 防 chunk 与超时同 pass 误触发、check→clear 之间无 await、每轮自建 waiter 并逐字保留 waiter 收口 + `cancelling()` 穿透纪律;仅设 stall 且请求非流式 → `__call__` 入口门逐字走单路(中段沉默无非流式概念)。触发后编排/记账/遥测全复用 1.3.7(异源、完整准入、准入失败静默放弃、输家取消 est 保留不喂熔断、`hedge_cancelled` 行、两败计一次预算);对冲路 `content_event` 恒 None(v1 不梯次)。**与看门狗的交互**: 主路沉默超 `inter_token_timeout_s` 被掐死时,对冲路已在跑 → 本轮超级尝试不因主路之死而败(等副路裁定),attempt 级记账(breaker `record_failure`/`attempt_fails`/遥测 error 行)照常。**不对称声明(N9)**: 看门狗掐死**喂**熔断失败(1.3.6 起既有语义)vs 对冲输家取消**不喂**熔断(1.3.7 已批准语义)——同为源沉默事件不同处置,本版不改任一,运维"挂起率"统计须知此不对称。装配硬守卫: `stall_after_s ≥ min over sources of (inter_token_timeout_s or timeout_s)`(有效值,对冲窗永不开)或 `≥ call_deadline_s` → ValueError;单源 scope → warning 允许;Embedding/OCR scope 配任一对冲键 → `__post_init__` warning(B4,装配期可证明纯非流式;chat 的流式性是 per-call 参数,装配期无信号,故 chat 侧无此 warning)。**诚实标注: 中段沉默触发并发副本无业界公开先例**(主流收敛为看门狗掐流 → 重试),属超业界现状能力,人类已明确接受。
+
 ### 7.3 限流
 
 **语义契约**(两后端同一套): `try_acquire(source, est_tokens) -> Permit | 拒绝(含等待提示)`;`Permit.settle(actual_usage)` 按实际 usage 结算(预扣保守入场,多退少补);`Permit.release()` 在 finally 必然执行;permit 带 TTL 租约防进程死亡泄漏。
@@ -562,7 +566,9 @@ flowchart TB
 
 ### 7.8 遥测与成本
 
-**必录字段**(继承三项目 15 字段规范;当前 36 个 INSERT 字段,物理表列 37 = 36 + 数据库自填的 `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**。
+**必录字段**(继承三项目 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**。
+
+**`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` 还原。
 
 **`sampling` 列(2026-07-31,issue #4,端口 20 → 21)**: 列语义 = 「调用方采样意图 ⊎ 生效源 `extra_body`」的 canonical JSON,空则 NULL。**不含**结构化注入的 `response_format`——列名是采样参数,schema 不是,且数 KB schema 逐行落库会让审计表无谓膨胀。三个 emit 入口口径必须各自定死,否则同一列在不同行含义不同: `emit_attempt`(RetryMW 调用,**唯一**有生效源者)并上 `source.extra_body`;`emit_cache_hit` / `emit_terminal_failure`(前者由 TelemetryMW 最外层调用,后者自 1.3.5 起由三个 client 的公开边界经 `emit_terminal_once` 统一写出)无 source 可言,只记调用级——与 `model`/`source_name` 在终态行置空是同一先例,且缓存命中行无损(`sampling` 已进缓存 key,能命中即意味调用级参数与历史那次逐字相同)。三者统一读 `request.sampling` 而非 `request.overlay`(后者在 RetryMW 处已被结构化注入污染、在 TelemetryMW 处未被污染,直接用必然三行分叉)。OCR/embedding 路径因决策 G 剥离 `extra_body`,该列恒 NULL。
 

research-wiki/ROADMAP.md

@@ -70,6 +70,8 @@
 
 **已交付增补(2026-09-10)**: 长尾对冲(issue #24,1.3.7)——chat 单路并发对冲,触发=流式首 token 未至/非流式纯时长阈值,异源走完整准入,默认关闭;`CallStats` 增 `generation_ms`(裸生成时间)/`hedges`/`hedge_won`。设计 designs/2026-09-10-24-hedged-requests-design.md(人类已批准 H1-H8),实施 plans/2026-09-10-24-hedged-requests.md。后续储备:梯次多路对冲(H5 预留)、分位数触发、embedding/OCR 对冲(现不做)。
 
+**已交付增补(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 对冲(现不做)。
+
 ## 7. 开放决策依赖
 
 | 决策 | 阻塞点 | 需拍板时间 |

research-wiki/findings/2026-09-11-streaming-stall-validation.md

@@ -0,0 +1,89 @@
+---
+type: finding
+node_id: finding:2026-09-11-streaming-stall-validation
+title: "1.3.8 流式中段沉默:净口径与中段对冲验证报告"
+date: 2026-09-14
+---
+
+# 1.3.8 流式中段沉默:净口径与中段对冲验证报告
+
+> 计划:`research-wiki/plans/2026-09-11-streaming-stall.md`;设计:`research-wiki/designs/2026-09-11-streaming-stall-design.md`(人类已批准 + 独立审查补遗 B1-B4/N1-N9 全处置)。
+> 分支 `feature/1.3.8-streaming-stall`;基线 main `a28d944`(1.3.7)+ 设计/计划提交 `97de410`/`6f3a620`;代码提交 `901a193`(T1)/`53bcf43`(T2)/`e0b0be0`(T3)/`2ac05a2`(T4),文档提交见本文件 git 历史。
+> 所有命令在 `PolyGateway` conda 环境执行,未接管道(退出码不失真)。
+
+## 1. 红绿证据索引
+
+证据目录 `tests/outputs/138/{t1,t2,t3,t4}`(不提交,本地留存)。与 137 惯例不同,138 日志**未逐文件落 `EXIT_CODE=` 行**;退出码由日志内 `conda ... failed` ERROR 行(红)与 pytest 汇总行(绿)佐证,如实登记。
+
+| 任务 | 相位 | 证据文件 | 结果与失败形态 |
+| --- | --- | --- | --- |
+| T1 端口事件 + stall 原语 | 红(批次 A) | `t1/red-batch-a.log` | exit≠0:收集期 `ImportError: cannot import name '_stall_from_chunk_times'`(纯函数不存在,非断言值不符) |
+| T1 | 绿(批次 A) | `t1/green-batch-a.log` | 260 passed(test_openai_compat + test_types) |
+| T1 | 绿(unit 全套) | `t1/green-unit.log` | 1602 passed,既有断言一行未改 |
+| T2 净口径记账 | 红(批次 B) | `t2/red-batch-b.log` | exit≠0:6 failed——`CallStats`/`_CallContext` 字段缺失、`generation_ms` 仍得墙钟值、两败轮归因未置 None |
+| T2 | 绿(批次 B) | `t2/green-batch-b.log` | 40 passed |
+| T2 | 绿(unit / unit+contracts) | `t2/green-unit.log` / `t2/green-unit-contracts.log` | 1608 passed / 1669 passed, 17 skipped |
+| T3 遥测两列 | 红(批次 C) | `t3/red-batch-c.log` | exit≠0:14 failed, 224 passed——24 处 AssertionError(冻结清单先扩即红:列数 36≠38、列序末两位、DDL 首现顺序、占位符数)+ 装配闸/落行断言未实现形态 |
+| T3 | 绿(批次 C) | `t3/green-batch-c.log` | 238 passed |
+| T3 | 绿(unit+contracts) | `t3/green-unit.log` | 1673 passed, 17 skipped |
+| T4 中段对冲 + 配置守卫 | 红(批次 D) | `t4/red-batch-d.log` | exit≠0:16 failed, 153 passed——9×`TypeError: RetryMW.__init__() got an unexpected keyword argument 'stall_after_s'`、2×`AttributeError: 'GatewaySettings' object has no attribute ...`、键未识时 `STREAM` 段被当源(`['qwen_1','stream_1'] == ['qwen_1']`)、守卫未抛/默认值未生效断言,均为未实现形态 |
+| T4 | 绿(批次 D,首轮) | `t4/green-batch-d-first.log` | 169 passed(与红相位 16+153 总量一致) |
+| T4 | 绿(unit / contracts) | `t4/green-unit.log` / `t4/green-contracts.log` | 1688 passed, 17 skipped / 61 passed, 17 skipped(批次 E 默认关闭回归门:既有语义断言一行未改,例外仅为计划登记的签名/清单同步) |
+| T4 | lint | `t4/lint.log` | `make lint` 通过,ruff 全绿,import-linter Contracts: 1 kept, 0 broken |
+| T1 期 ruff 先红 | 红 | `t1/ruff.log` | 1 error(`strict=` 缺显式值),T2 起 `ruff.log` 转 All checks passed |
+
+## 2. 批次与提交映射
+
+| 提交 | 计划任务 | 覆盖批次(计划 §5) | 关键断言 |
+| --- | --- | --- | --- |
+| `901a193` | T1 观测原语与端口契约 | A | 流式每增量 chunk 置位 content_event;reasoning chunk 计活性;非流式永不置位;None 不观测行为不变;漏传必填 kw 即 TypeError;stall 纯函数(超阈累计/恰等不减/<2 返回 None/尾部不计/空帧不计时);`SourceConfig.stall_threshold_ms` 默认 1000 且 0/负/bool 拒 |
+| `53bcf43` | T2 净口径记账 | B | 两字段默认 None 旧构造不炸;`generation_ms == wall − stall` 且还原公式成立;clamp 负值归零;stall None 不退减;两败轮归因 None |
+| `e0b0be0` | T3 遥测两列 | C | 冻结清单 38 列与列序/DDL/占位符同源;SQLite 落行两列恰为传入值;auto_migrate 幂等补列(二次初始化);manual 档点名两条新 ALTER;取消输家行 stall 恒 None;装配闸三负例照旧绿 |
+| `2ac05a2` | T4 中段对冲 + 守卫 | D、E | 首 token 后沉默触发对冲且赢家净口径;同 pass 复检防误触发;四格独立矩阵;仅 stall+非流式退单路;看门狗掐死主路对冲路存活且记账照常;两败计一次预算;stall 等待中外部取消穿透无残留;对冲路 content_event 恒 None;阈值三层可调;STREAM 保留段;四守卫(有效最小值/deadline 冲突 ValueError、单源 warning、Embedding/OCR B4 warning) |
+
+## 3. 实测核对(文档承诺 vs 运行实测,T5 交付时本会话复核)
+
+| 承诺 | 核对方式 | 实测结果 |
+| --- | --- | --- |
+| `CallStats` 两新字段默认值 | `CallStats(logical_call_id='x', attempts=1, total_latency_ms=5)` 仅旧参构造 | `generation_ms=0`、`hedges=0`、`hedge_won=False`、`stall_ms=None`、`stall_count=None`,构造不炸 |
+| 协议字段数 | `inspect.signature(TelemetryRecorder.record_llm_call)` | 38 参(36 → 38,含 self 不计) |
+| 遥测列 | `telemetry/schema.py::COLUMNS` | `len == 38`,末两位 `('stall_ms', 'stall_count')` |
+| 两键缺省与三层 | `GatewaySettings.from_env(env=...)` 注入单源最小 env | 不设两键 → `stall_threshold_ms=1000`、`hedge_stall_after_s=None`,且已分发进 SourceConfig(1000);设 `LLM__STREAM__STALL_THRESHOLD_MS=250`/`LLM__HEDGE__STALL_AFTER_S=8` → 250/8.0 |
+| 值域校验落点 | `dataclasses.replace(src, stall_threshold_ms=0)` | `ValueError: SourceConfig.stall_threshold_ms 必须是正整数`(replace 触发 `__post_init__` 重跑,校验只此一处) |
+| 版本号不动 | `pyproject.toml` 与 `src/polygateway/__init__.py` | 两处均 1.3.7,本计划不 bump、不 tag、不发布 |
+
+## 4. 验收命令与退出码(T1–T4 各卡)
+
+| 任务 | 验收命令(均 `conda run -n PolyGateway`,禁接管道) | 结果 |
+| --- | --- | --- |
+| T1 | `pytest tests/unit/test_openai_compat.py tests/unit/test_types.py -q` → `pytest tests/unit -q` | 260 passed → 1602 passed,exit 0 |
+| T2 | `pytest tests/unit/test_types.py tests/unit/test_retry.py -q` → `pytest tests/unit tests/contracts -q` | 批次 40 passed → 1669 passed, 17 skipped,exit 0 |
+| T3 | `pytest tests/unit/test_telemetry.py tests/unit/test_ports.py tests/unit/test_hedge.py -q` → `pytest tests/unit tests/contracts -q` | 238 passed → 1673 passed, 17 skipped,exit 0 |
+| T4 | `pytest tests/unit/test_stall_hedge.py tests/unit/test_config.py -q` → `pytest tests/unit tests/contracts -q` → `make lint` | 169 passed → 1688+61 passed,exit 0;lint 通过 |
+
+合并前验收门(计划 §6:全套件 + slow 交集子集 + 整分支审查 + verifier)**不在 T5 范围**,随合并/发布流程执行;结果届时补记本节或另文。
+
+## 5. 豁免索引(未跑项与去向)
+
+| 未跑项 | 理由 | 去向 |
+| --- | --- | --- |
+| PG 实库遥测迁移用例(`tests/integration/test_postgres_telemetry.py`) | 执行期无沙箱可跑(计划 §7 阻塞矩阵已登记此情形);批次 C 的 SQLite 幂等用例(二次初始化)保留未删,PG 侧 `_EXPECTED_COLUMNS` 冻结清单已同步扩展 | **发布门 slow 交集补跑**(CLAUDE.md §4.4.1 第 4 步;本 diff 触及 telemetry schema,PG 实库形态在交集内) |
+| `tests/e2e/` 与 Redis 时间语义变体(slow) | T1–T4 未动 `streaming.py`/限流 Lua/`Permit` 端口/`backends/**`;但 diff 触及 retry(结算/取消/编排)与公开入口 `complete` 签名 | 发布门按 diff 交集选子集:**Redis 时间语义变体 + 真实网关冒烟届时在交集内**(计划 §6 门 3 已登记) |
+| `test_thinking_live.py` 全模型能力矩阵 | 本 diff 零触碰 `thinking.py`/能力注册表/相关 e2e 设施 | 按 2026-09-10 生效的交集规则**豁免**,复用 1.3.7 已登记的有效矩阵证据,不外推到已变化路径 |
+
+## 6. T4 worker 超时恢复实录(提交链完整性说明)
+
+T4 由前台委派 worker 执行,worker 在收尾阶段(证据落盘后、提交前)会话超时失联。处置:父会话复核 `tests/outputs/138/t4/` 五份证据(red-batch-d 16 红形态均为未实现错误、green-batch-d-first 169 passed 与红相位总量一致、green-unit 1688 / green-contracts 61 全绿、lint 1 kept 0 broken)并核对工作区 diff 精确命中计划 §2.1 表定五文件(`client.py`/`config.py`/`retry.py`/`test_config.py`/`test_stall_hedge.py`,无越界改动)后,代为提交 `2ac05a2`。**教训沉淀**:委派任务的提交动作与证据落盘之间隔着一个会话生命周期,证据先行落盘(计划 §1 证据纪律)使本次恢复无需重跑任何测试。
+
+## 7. 残余复述(设计/计划已批准口径)
+
+| 项 | 口径 |
+| --- | --- |
+| 中段对冲无业界公开先例 | 调研 §A3 结论,CHANGELOG/README/ARCHITECTURE 三处诚实标注;2A 看门狗链仍是不启用对冲时的默认行为 |
+| `generation_ms` 语义突变 | 人类「窗口期最小代价」裁决放行的例外(字段发布仅 2 天/消费者唯一/遥测无账本);披露义务已在 T5 三处文档落地 |
+| 复检竞速窗口 | N3① 复检 `is_set()` 只能把误触发窗口收窄到同一事件循环 pass,不能归零——已是设计批准的最强形态 |
+| 挂起率统计的不对称 | 看门狗掐死喂熔断 vs 对冲输家取消不喂(1.3.6/1.3.7 各自既有语义,本版不改任一);运维侧统计须知 |
+
+## 8. 结论
+
+T1–T4 全部行为变更具备先红后绿证据(§1),默认关闭回归门成立(批次 E:unit 1688 + contracts 61 全绿,既有语义断言一行未改),lint 与 import-linter 契约通过;文档承诺经运行实测核对(§3)。版本 bump、tag、发布与 slow 交集子集**不在本计划内**,按 CLAUDE.md §4.4.1 另行执行(发布时按 §5 豁免索引补跑交集项)。