docs: record the telemetry pool semantics and ownership rule

ARCHITECTURE 7.8 gains the pool resource semantics, the two-sentence
failure verdict and the two config keys; the ownership rule lands in a
new 4.5 because it is a cross-subsystem discipline, not a telemetry
convention. CHANGELOG leads with the three items downstream must read
first: the 3.12 floor, the connection count going from 10 per client to
on demand, and aclose no longer closing injected components.

.env.example

@@ -71,6 +71,23 @@ PGW_TELEMETRY_BACKEND=none               # sqlite | postgres | none(必填)
 #                                               # sqlite 则是下游自己的本地文件(runs/*.db):没有 DBA、没有迁移工具、
 #                                               # 没有第二个系统碰它,ALTER 是毫秒级元数据操作,强加手工 SQL 步骤是净损失。
 # PGW_TELEMETRY_PG_DSN=postgresql://user:pass@host:5432/polygateway  # postgres 时必填;严禁指向在用业务库(实验室约定: 专用库 polygateway)
+# PGW_TELEMETRY_PG_POOL_MAX=4                   # postgres 遥测池的连接上限,须 >= 1;缺省 4。**闲时占 0 条**——
+#                                               # 池按需建连(min_size=0),不预占;这一格是忙时的天花板,不是常驻量。
+#                                               # 调参口径(以实测为准,不要按 pool_max/RTT 估算):跨内网 RTT ≈ 123ms 的
+#                                               # 实验室 PG 上,pool_max=4 实测约 **15.6 行/秒**(50 行并发批耗时 3.2s),
+#                                               # 即每条连接约 4 行/秒 —— 一次 INSERT 的实际往返比一次 `SELECT 1` 重一倍,
+#                                               # 按单次 RTT 估会乐观一倍。要放大就按这个实测值线性折算(pool_max=8 ≈ 31 行/秒)。
+#                                               # 缺省 4 在缺省 5s 预算下能吞下约 50 行的突发(余量约 1.5 倍);超预算的行被丢弃
+#                                               # 并计入 telemetry_status.dropped_rows —— 丢一条遥测好过拖垮业务调用。
+#                                               # 什么时候该调大: 单进程遥测写入并发经常超过 4(高频短调用、批量并发),
+#                                               # 或多个 client 显式共享同一个 recorder(并发在这里汇聚,应按 client 数放大)。
+# PGW_TELEMETRY_PG_WRITE_TIMEOUT_S=5.0          # 一次遥测写入的硬预算(秒),须 > 0;缺省 5.0。同时用作建连、
+#                                               # acquire 与「准备 + 取连接 + 执行」整段的上界:超时即丢弃该行,
+#                                               # 绝不让遥测无界地挂在业务路径上。实测参考: 稳态写入 123ms、
+#                                               # 首次写入含建连 513ms —— 5s 对正常路径是极宽松的上限,它防的是
+#                                               # 池满排队与后端假死这类"不会自己结束"的等待。
+#                                               # 与之配套的两个不可配内部常量: 连接释放上界 1s(超时即 terminate)、
+#                                               # 环境级降级的冷却期 60s(到期自动重试一次,成功即恢复)。
 # PGW_TELEMETRY_TEXT_CAP=2000                   # 遥测落库正文的字符上限,须 > 0;**不设 = 不截断**(缺省,逐字节留全文)。
 #                                               # 作用于 messages 的每条文本 content、多模态 text part、response 与 thinking;
 #                                               # 超出部分头部保留、尾部换成 `…(略 N 字)`。多模态 image_url 的 sha256 摘要不受影响。