docs(test): semantic REPLACE fail-closed gray wiring evidence (unit + dev runtime ladder)

2026-09-25 23:24:33 +00:00
parent aee774b894
commit e2cfd88ac0
3 changed files with 76 additions and 4 deletions
@@ -53,11 +53,17 @@
 ## 三、计划

 1. [x] 分析（§一）
-2. [ ] 实现 §2（flags/allowlist/替换点/单测/sysadmin 目录）
-3. [ ] 工程门禁 + 候选集成 dev
-4. [ ] dev 运行时验收（真实链路 swap + 回滚 + allowlist 隔离）
+2. [x] 实现 §2（flags/allowlist/替换点/单测/sysadmin 目录；dev `cd1f846f`）
+3. [x] 工程门禁 + 候选集成 dev（含回滚残留修复 `6004494e`）
+4. [x] dev 运行时验收（替换/隔离/回滚无残留全 PASS；另修复 goose62 schema 漂移）
 5. [ ] 测试报告 + 矩阵行更新 + 收口清理

 ## 四、结果登记

-（完成后回填）
+- **review_state**: done（单测 8/8 + 工程门禁 + 既有密封负例保持）
+- **integration_state**: done（dev `cd1f846f` + `6004494e` --no-ff 候选集成）
+- **deployment**: dev_runtime_verified（阶梯验收后已恢复默认关闭；compose/env 默认不变）
+- **验证结论**: 见 [测试报告](../../test-reports/2026-09-26-chat-semantic-replace-test-report.md)
+- **过程修复**: ①回滚残留（displaced_narrative）；②dev localpg goose62 对象缺失按幂等 DDL 修复
+- **cleanup**: 本任务 worktree 按门禁清理
+- **remote_sync**: not_requested（本地 dev 前进，未 push）
@@ -0,0 +1,60 @@
+# 语义摘要 REPLACE fail-closed 灰度接线 测试报告
+
+## 一、测试背景 (Background)
+
+FEATURE-MATRIX `chat-semantic-replace` 行关闭条件：用户独立授权（本任务授权来源：用户会话指令明确要求完成本行，满足 Wave5 X-2 密封解封条件）+ fail-closed 灰度设计。此前 `SEMANTIC_SUMMARY_REPLACE` 密封不接线。
+
+## 二、测试目标 (Test Objectives)
+
+1. fail-closed：master 开而 allowlist 空 → 不替换任何会话；任一校验失败（模型错误/超长/stale watermark）→ deterministic 保留
+2. 灰度：仅 allowlist 会话在 shadow 报告 OK 且 served watermark 一致时替换 served Narrative；Facts/计数保持 deterministic
+3. 回滚安全：替换后关闭开关，下一轮确定性再生成不含语义残留
+4. digest（每日纪要）保持 advisory-only
+
+## 三、测试方案与环境 (Test Plan & Environment)
+
+- 单元：`internal/ctxmgr/semantic_replace_test.go`（7 用例：空 allowlist/命中/未命中/模型错误/超长/stale/flag 解析 + 回滚残留）
+- 工程：`arch-check --mode block`、`go vet ./...`、`go test -short ./...`（候选 `cd1f846f`、`6004494e`）
+- 运行时：本机 no-docker dev（`bin/agent-server` @ dev `6004494e`；PI Runner MiniMax-M2.7-highspeed；产品 PI no-tool summarizer 由组合根注入）
+- 过程修复：dev localpg 的 `chat_summaries.freshness_note/shadow_json` 与 `chat_summary_shadow_jobs` 缺失（goose 62 版本已记但对象缺失的 schema 漂移）——按 62 号幂等 Up DDL 修复并留档
+
+## 四、预期结果 (Expected Results)
+
+| 用例 | 预期 |
+|---|---|
+| 单测矩阵（7+1） | 全 PASS |
+| allowlist 会话溢出窗口 | source=semantic_replace、真实语义叙事、model=MiniMax |
+| 非 allowlist 会话 | source=deterministic |
+| 回滚（replace off + 新轮） | source=deterministic 且叙事无语义文本残留 |
+
+## 五、实际测试结果与判定 (Actual Results & Evaluation)
+
+### 5.1 单元/工程
+
+- `go test ./internal/ctxmgr/ -run SemanticReplace`：**8/8 PASS**（含回滚残留用例）
+- 既有密封负例 `TestSemanticSummary_ShadowOKKeepsDeterministic`（Replace:true 无 allowlist）保持 PASS——master 位单独打开不替换任何会话
+- sysadmin 目录断言更新为新契约（shadow/degraded + allowlist 键默认空）PASS；`arch-check`/`vet`/`-short` 全 PASS
+
+### 5.2 dev 运行时阶梯（[runtime-ladder.txt](./assets/2026-09-26-chat-semantic-replace/runtime-ladder.txt)）
+
+1. **替换**：`sess-csr-hit2`（allowlist）窗口溢出后 `source=semantic_replace`，served Narrative 为真实 MiniMax 语义叙事（“用户启动手持超声新项目…客户为华西医院，预算约500万…”），freshness_note 记录 `semantic_replace: narrative replaced from MiniMax-M2.7-highspeed` **PASS**
+2. **隔离**：同配置 `sess-csr-miss2` `source=deterministic`（shadow job 完成但未替换）**PASS**
+3. **回滚**：重启 `SEMANTIC_SUMMARY_REPLACE=false` + 新增 15 轮 → rev5 `source=deterministic`，叙事为规则叙事（“双方开展了研发立项与合规细节沟通…”）**无语义残留 PASS**
+
+### 5.3 过程缺陷与修复（运行时验证发现）
+
+- **回滚残留缺陷**：确定性生成器合并 prior served 叙事（`summarizer.go` narrativeParts 以 `oldSum.Narrative` 起始），替换后回滚会把语义文本带入后续确定性叙事。修复（dev `6004494e`）：替换时将被换下的确定性叙事存入 shadow 报告 `displaced_narrative`（随 `shadow_json` 持久化）；确定性合并遇 `source=semantic_replace` 优先取回 displaced 叙事。单测 `TestSemanticReplace_RollbackLeavesNoResidue` + 运行时阶梯 3 覆盖。
+
+## 六、自动化测试套件汇总 (Test Suite Execution)
+
+| 套件 | 结果 |
+|---|---|
+| `go test ./internal/ctxmgr/ ./internal/sysadmin/` | PASS |
+| `arch-check --mode block` / `go vet` / `go test -short ./...`（候选） | PASS |
+| dev 运行时阶梯（替换/隔离/回滚） | PASS |
+
+## 七、测试结论与后续优化建议 (Conclusion & Next Steps)
+
+**结论**：fail-closed 灰度设计已实现并经单元 + dev 真实链路验收——双开关（master + 会话 allowlist，默认全关）、四重前置校验（OK 报告/digest/watermark/长度）、Facts 与 digest 不变式、回滚无残留。默认关闭下零行为变化（负例保持）。FEATURE-MATRIX 行可升 `done`。
+
+**后续**：放量阶梯 `off → 白名单会话 → 更广`，各环境开启需单独授权；`chat_summaries` 无外部读端点，验证经 DB/内部状态，后续可在管理台补只读视图。
@@ -0,0 +1,6 @@
+   session_id   |    source     | revision |     model_version      |                                                                          narrative                                                                           | freshness 
+----------------+---------------+----------+------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------
+ sess-csr-hit2  | deterministic |        5 | MiniMax-M2.7-highspeed | 双方开展了研发立项与合规细节沟通；双方开展了研发立项与合规细节沟通；双方开展了研发立项与合规细节沟通；双方开展了研发立项与合规细节沟通；讨论了包装按出口标准 | 
+ sess-csr-miss2 | deterministic |        4 | MiniMax-M2.7-highspeed | 双方开展了研发立项与合规细节沟通；双方开展了研发立项与合规细节沟通；双方开展了研发立项与合规细节沟通；双方开展了研发立项与合规细节沟通                       | 
+(2 rows)
+