Add K1e answer replay harness

docs/RAG.md

@@ -77,7 +77,44 @@ Chroma 同步会删除 replacement index 中不存在的 ID，避免删除、重
 
 当前 K1 corpus 上的门控指标仍属于 `record_only`。即使小样本上 answerable supported rate 和 unanswerable block rate 达到 1.0，也不能直接升级为长期不可回退阈值，必须继续用更大真实语料和真实模型 replay 验证泛化。
 
-## 5. Stable capability boundary
+## 5. Adaptive multi-source coverage
+
+复合学习问题不能简单地“每个来源只取一个 chunk”，也不能为了多样性随机塞入更多来源。K1d 使用**非回退的自适应来源覆盖**：
+
+1. 先执行普通 top-K 检索；
+2. 保留普通 top-K 中已经出现的所有唯一来源；
+3. 只删除同一来源占据的重复槽位；
+4. 对明确的复合问题提取有限 facet；
+5. 只有 facet 的 champion 来源尚未出现时，才使用重复槽位补充该来源。
+
+因此 K1d 的硬约束是：**adaptive path 不得丢失 raw top-K 已召回的唯一来源。** 普通单来源问题不启用该策略，保持原排序行为。
+
+当前确定性 K1 合同要求：
+
+- multi-source recall@K `>= 0.9`；
+- multi-source precision@K `>= 0.7`；
+- adaptive overall recall 不得低于 raw Hybrid recall；
+- answerable supported rate 与 unanswerable block rate 不得回退；
+- forbidden / stale source leakage 保持为 0。
+
+这些阈值约束当前 fixture 上的回归，不代表更大真实语料已经证明同样性能。
+
+## 6. Real-provider answer replay contract
+
+确定性 extractive lower bound 只能验证检索和评测合同，不能代表真实模型回答质量。K1e 因此单独定义 real-provider replay：
+
+- 复用 Study Agent 现有 Provider owner 和模型档位，不创建平行的 Provider 配置体系；
+- 使用同一 K1 corpus、evidence manifest、local-knowledge 检索、K1b 资格过滤、K1c sufficiency 和 K1d adaptive coverage；
+- 默认只回放 answer-quality gold cases，检索层继续由完整 K1 retrieval suite 负责；
+- 报告记录 corpus fingerprint、prompt-template fingerprint、case prompt fingerprint、Provider profile、model name、endpoint fingerprint、latency 和 Provider 返回的 token usage；
+- 原始 API key 和 raw endpoint 不得写入报告；
+- raw replay artifact 默认写入 gitignored `output/`，不能无审查进入版本库。
+
+provenance 不能由任意测试对象自行声明。只有生产 `OpenAICompatibleReplayProvider` adapter 才能被 runner 标记为 `real_provider`；其他实现即使伪造同名字符串，也只能记录为 `synthetic_test`。
+
+真实 Provider 不可用时必须显式记录 `provider_unavailable` 或 `partial_failure`，不得生成或补齐伪造质量分数。当前 harness 是否已具备、某次真实 replay 是否已实际执行，属于进度信息，以 `PROJECT_STATUS.md` 为准。
+
+## 7. Stable capability boundary
 
 当前稳定能力包括：
 
@@ -93,6 +130,8 @@ Chroma 同步会删除 replacement index 中不存在的 ID，避免删除、重
 - 默认持久化 JSON index；
 - citation-first context formatting；
 - evidence sufficiency / refusal boundary；
+- non-regressive adaptive multi-source coverage；
+- real-provider replay harness 与 provenance schema；
 - 可选 Chroma adapter；
 - OpenAI-compatible embedding provider；
 - duplicate suppression、source diversity、metadata filters；
@@ -116,7 +155,7 @@ Chroma 同步会删除 replacement index 中不存在的 ID，避免删除、重
 
 这些项目的当前状态以 `PROJECT_STATUS.md` 为准。
 
-## 6. Quality evaluation contract
+## 8. Quality evaluation contract
 
 RAG 质量评测复用同一套 `src/rag/eval.py` 检索评测域，不另建平行指标系统。K1 的确定性本地 corpus 同时包含干净查询、改写、多来源、相似主题干扰、旧版本和不可回答问题。
 
@@ -150,17 +189,27 @@ source-level nDCG 只在某个来源第一次出现时给予 relevance gain。
 - required source coverage；
 - stale revision / forbidden-source leakage。
 
-确定性 CI baseline 使用检索片段拼成 extractive lower bound，只验证评测合同、检索证据和失败暴露链路；只有 sufficiency=`supported` 才构造该 lower-bound answer。**不得解释为生产模型真实回答质量**。真实模型或 Provider replay 必须单独标识运行来源、模型配置和成本。
+确定性 CI baseline 使用检索片段拼成 extractive lower bound，只验证评测合同、检索证据和失败暴露链路；只有 sufficiency=`supported` 才构造该 lower-bound answer。**不得解释为生产模型真实回答质量**。
 
-运行：
+确定性基线运行：
 
 ```bash
 python tools/run_rag_quality_baseline.py --output rag-quality-baseline.json
 ```
 
-CI 始终上传 `rag-quality-baseline` artifact。当前 baseline 为 `record_only`：不以分数阈值阻断合并，但 corpus 使用 SHA-256 fingerprint，并由 checked-in baseline snapshot 固定当前语料、资格 manifest、门控结果和关键指标。算法、corpus 或 evidence manifest 变化导致指标变化时，必须显式更新 snapshot，避免不同证据集合被悄悄当成同一基线比较。
+真实 Provider replay 运行：
+
+```bash
+python tools/run_rag_provider_replay.py \
+  --provider-profile <profile> \
+  --model-profile pro
+```
+
+真实 replay 的默认原始报告位于 `output/rag-provider-replay.json`。只有实际 Provider 调用成功且报告 `status=completed` 时，才能讨论该次模型质量；`synthetic_test`、`provider_unavailable` 和 `partial_failure` 都不能被描述成完成的真实模型 benchmark。
+
+CI 始终上传 `rag-quality-baseline` artifact。确定性 baseline 继续使用 corpus SHA-256 fingerprint 和 checked-in snapshot 固定语料、资格 manifest、门控结果和关键指标；K1d 另有不可回退质量合同。算法、corpus 或 evidence manifest 变化导致指标变化时，必须显式更新 snapshot，避免不同证据集合被悄悄当成同一基线比较。
 
-## 7. Module map
+## 9. Module map
 
 | Module | Responsibility |
 |---|---|
@@ -171,14 +220,16 @@ CI 始终上传 `rag-quality-baseline` artifact。当前 baseline 为 `record_on
 | `src/rag/backends.py` | vector backend contract 与 adapter |
 | `src/rag/query_plan.py` | pedagogy-aware private query planning |
 | `src/rag/sufficiency.py` | retrieval 后的 evidence sufficiency / refusal 决策 |
+| `src/rag/source_coverage.py` | 复合问题的非回退 adaptive multi-source coverage |
 | `src/rag/eval.py` | 检索质量、scenario 与 stale-source 评测 |
 | `src/rag/answer_eval.py` | 回答可信度与引用支持评测 |
+| `src/rag/provider_replay.py` | real/synthetic provenance、Provider replay 与 usage/latency 报告 |
 | `src/application/rag_service.py` | RagRun application orchestration |
 | `src/repositories/rag_repository.py` | durable RagRun 和 index-state persistence |
 | `src/api/routes/rag_routes.py` | FastAPI adapter |
 | `frontend/src/features/rag/*` | React controller 与资料/来源展示层 |
 
-## 8. Invariants
+## 10. Invariants
 
 1. 删除、重建或资格变更后的非 active chunk 不得从任何普通 active retrieval backend 返回。
 2. 必需阶段失败不得激活新 index version。
@@ -187,8 +238,11 @@ CI 始终上传 `rag-quality-baseline` artifact。当前 baseline 为 `record_on
 5. backend-vector 返回值必须再次受当前 active chunk identity 约束，不能信任外部 backend 的旧状态。
 6. `uncertain / insufficient` retrieval candidate 只能保留在 debug，不能作为普通 answer evidence 或用户 citation。
 7. retrieval constraint 只用于模型私有规划，不得被披露成来源。
-8. `local_hash` 不得被描述为生产语义 embedding。
-9. 检索证据默认私有，只有 disclosure policy 允许的完整 evidence unit 进入模型回答。
-10. RAG 候选、采用证据和 UI 引用计数必须保持一致。
-11. 运行状态、错误和部分成功必须进入 durable RagRun，不用普通日志替代产品状态。
-12. deterministic baseline 的 corpus fingerprint、sufficiency summary 或 snapshot 指标变化必须显式进入代码审查，不能静默覆盖。
+8. adaptive source coverage 不得丢失 raw top-K 已召回的唯一来源。
+9. `local_hash` 不得被描述为生产语义 embedding。
+10. 检索证据默认私有，只有 disclosure policy 允许的完整 evidence unit 进入模型回答。
+11. RAG 候选、采用证据和 UI 引用计数必须保持一致。
+12. 运行状态、错误和部分成功必须进入 durable RagRun，不用普通日志替代产品状态。
+13. deterministic baseline 的 corpus fingerprint、sufficiency summary 或 snapshot 指标变化必须显式进入代码审查，不能静默覆盖。
+14. synthetic replay 无论对象如何自报，都不得标记为 completed real-provider benchmark。
+15. real-provider report 不得持久化 API key 或 raw endpoint；未完成调用不得补造质量分数。