docs: add M2 distributed design and record Q3 embedding decision

research-wiki/designs/m2-distributed.md

@@ -0,0 +1,34 @@
+---
+type: design
+node_id: design:m2-distributed
+title: "M2 分布式:Redis 治理后端+背压+Postgres 遥测+pricing+Embedding+压测 harness"
+date: 2026-07-21
+---
+
+# M2 分布式:Redis 治理后端+背压+Postgres 遥测+pricing+Embedding+压测 harness
+
+**正文**: `2026-07-20-m2-distributed-design.md`(本页为图谱节点,只记选定方案与否决备选)。
+
+## 选定方案与关键理由
+
+| 轴 | 选定 | 理由 |
+|---|---|---|
+| Redis 限流 | 单条六道闸 Lua 逐字移植(CHS scripts.py),key 前缀 `pgw:limit:` | 生产验证语义 + 保真成本最低 |
+| Redis 熔断 | 五操作 Lua 逐字移植(provider_gate),epoch 仅开断 +1;probe_ttl 显式配置 + 装配守卫 | 不动 M1 冻结的 BreakerConfig |
+| 契约测试 | conftest fixture 增 `redis` param + 真实 Redis(db3);时间语义用小 TTL 真实等待变体 | M1 预留接入方式,契约文件零改动 |
+| 背压 stall | 在 RetryMW `_on_no_runnable` wait 分支内做双条件判死 + poll jitter | 挂接点 M1 已预留,不新增洋葱层 |
+| Postgres 遥测 | DSN 自建 lazy 池(可注入 pool),失败静默降级,`ON CONFLICT DO NOTHING` | 与 SQLiteRecorder 对称;GovDoc taskrun 蓝本反转降级方向 |
+| pricing | JSON 价格表文件(`PGW_PRICING_PATH`)/dict 注入,零内置单价;计算点在 TelemetryEmitter | 中转网关计费非官方价,内置表必然过时(P5) |
+| Embedding | 独立 EmbeddingClient + 复用后端/错误分类/退避/冷却备忘/遥测 helper;async httpx、list[list[float]]、normalize 开关、必填 batch_size、可选 expected_dim 校验 | 零改 M1 冻结面 |
+| harness | `tools/soak/` 四组件(corpus/scenarios/run_soak/scoreboard),吃自身遥测狗粮 | findings/2026-07-20-m2-soak-workload.md 为准 |
+
+## 被否决的备选及原因
+
+- 限流 WATCH/MULTI 事务、每闸独立脚本+补偿:原子性碎裂/竞态风暴。
+- fakeredis 契约测试:不执行真实 Lua,违"Redis 测试用真实 Redis"规约。
+- 独立 BackpressureMW:改冻结洋葱层序。
+- probe_ttl 装配自动计算(CHS container 形态):改冻结配置形态,守卫同效。
+- Postgres 走 SQLAlchemy:重依赖违依赖极简。
+- pricing 内置默认价格表 / env 平铺单价键:过时默认值掩盖成本 / env 键名不友好。
+- Embedding 泛化中间件洋葱(G1):动冻结核心,gold-plating;塞 chat 洋葱(G3):类型欺骗。
+- GovDoc embedding 自研退避与 on_usage 回调、VT 同步接口:有意放弃,统一库治理栈与遥测。