[提案] 展示层忠实化:EvidenceLedger 证据契约 + 确定性提交门禁(收敛 #21 / #22 的统一优先级)

[justDance-everybody]

TL;DR(不同角色 30 秒读懂)

DeepGraph 的计算层是可靠的(真执行 + 诚实统计,连不显著的负结果也如实给出 verdict)。当前短板在展示/写作层:它会引入证据不支持的内容,把本来可信的结果"毁容"。本提案把展示层降级为忠实播报员——只渲染已验证证据,并补上确定性提交门禁。

• 给维护者: 把 下一个改进方向的建议：严格产出完整性 —— 可验证性准入 + 结果绑定 + 提交硬校验 #21(产出完整性诊断)和 [Maintenance] 分支主线收敛与归档建议：以 main 为历史主线、吸收 master 内容 #22(分支收敛 + 计算/展示运行架构)收敛成一条统一的执行优先级,供拍板。
• 给贡献者: 一批边界清晰、可独立 PR 的确定性检查任务(最便宜的先做,误杀率极低)。
• 给使用者/观察者: 产出里每个数字都能回溯到一次已验证计算,显著性由数值判定而非措辞。

1. 背景

本 issue 建立在两个既有讨论之上,并提出收敛后的新优先级:

• 下一个改进方向的建议：严格产出完整性 —— 可验证性准入 + 结果绑定 + 提交硬校验 #21(严格产出完整性) 已诊断出核心问题:evidence_gate / result_interpreter / require_submission_ready() 等 grounding 模块该有的都有,但门"建好了没真正闭环"——合成数字、未解析引用、自相矛盾正文仍会漏进稿件。本提案采纳 下一个改进方向的建议：严格产出完整性 —— 可验证性准入 + 结果绑定 + 提交硬校验 #21 的建议 2/3 作为执行项,建议 1(选题层可验证性准入)列为长期目标。
• [Maintenance] 分支主线收敛与归档建议：以 main 为历史主线、吸收 master 内容 #22(分支收敛 + 运行架构) 给出了两条工程原则:计算与展示/资产应分离(计算可弹性、资产/展示要稳定),以及改动走收敛分支、验证后并回、未确认不强推。本提案的落地姿态遵循这两条。

一句话定位:#21 说了"门没闭环",#22 说了"计算/展示要分离、改动要稳"。本 issue 把两者合到一个根因上——展示层越权做了计算层的判断——并给出统一的修复顺序。

2. 现状观察(客观、工程化)

当前渲染产出中可观察到以下模式(均为展示层问题,与计算层无关):

#	现象	典型表现
a	未解析引用	正文/参考出现 ?、Table ??、Figure ?? 等未渲染占位
b	生图脚手架泄漏	caption / 正文混入生成指令或内部 plumbing 文本
c	跨 run 身份串台	标题、front-matter、图注与本稿锁定主题不符(混入其它 run 的方法名/概念)
d	模板 boilerplate 重复	同一句在 Related Work 等处复读多次
e	显著性子串判定	paper_completeness.py:591 用 "p=" in p_text 判显著——p = 1.0(完全不显著)因含 p= 子串即被判为"有显著性"

3. 根因

以上都指向同一件事:展示层在做本应属于计算层的判断(例如"是否显著"应读 result_interpreter 已算出的 verdict,而不是在渲染阶段靠子串/模板拼)。缺的是一条**"计算 → 展示"的强制契约**:展示层只能渲染已验证证据,不能新增、改写或自行判定。

4. 提议

1. EvidenceLedger 作单一事实源:计算层写入已验证字段(p / CI / verdict / 可回溯数字);展示层只能引用 ledger 里的字段,任何数字可回溯;result_interpreter 的 verdict(refuted / supported)强制约束 abstract / conclusion 的措辞(采纳 下一个改进方向的建议：严格产出完整性 —— 可验证性准入 + 结果绑定 + 提交硬校验 #21 建议 2)。
2. 修 line 591:子串判定 → 数值 p < α,并与 verdict 绑定。
3. require_submission_ready() 变真 block,补四个确定性硬检查(采纳 下一个改进方向的建议：严格产出完整性 —— 可验证性准入 + 结果绑定 + 提交硬校验 #21 建议 3),任一命中即 fail 禁止出稿:未解析引用 / 脚手架泄漏 / 跨 run 串台 / 模板复读。

5. 建议的新优先级顺序(供大家讨论)

• P0 · 确定性硬检查(最便宜,当周可上) —— 纯确定性、误杀率极低,先合,立即止住"一眼假"产出。
• P1 · EvidenceLedger 契约 + 591 数值修复 + verdict 绑定 —— 立起"计算→展示"契约。
• P2 · 展示层全面降级为播报员 —— manuscript_generation 从"写数"重构成"取数"(下一个改进方向的建议：严格产出完整性 —— 可验证性准入 + 结果绑定 + 提交硬校验 #21 建议 2 的完整落地)。
• 长期 · 选题层可验证性准入(下一个改进方向的建议：严格产出完整性 —— 可验证性准入 + 结果绑定 + 提交硬校验 #21 建议 1)。

6. 工程姿态

• 门禁化,非破坏性删除;换源 / 改名优先于删。
• 改动走收敛分支、验证通过后并回主线、未确认不强推(遵循 [Maintenance] 分支主线收敛与归档建议：以 main 为历史主线、吸收 master 内容 #22)。
• 每个功能配具体验收用例 + 验收标准,逐功能验收通过才算完成。

7. Checklist

• 认可"展示层越权"这一根因定位
• P0 四个确定性检查 —— 是否接受 PR
• P1 EvidenceLedger 契约边界 + 591 数值修复
• P2 manuscript_generation 重构范围确认
• require_submission_ready() 行为:命中合成/未解析/串台/复读时硬 fail,而非告警
• 长期(下一个改进方向的建议：严格产出完整性 —— 可验证性准入 + 结果绑定 + 提交硬校验 #21 建议 1)选题层可验证性准入方向是否认可

[justDance-everybody]

展示层忠实化 · 执行计划(Epic)

这条把 #21/#22 收敛后的结论落成可执行计划。本 issue 是 Epic,只放整体目标 + 共享上下文 + 子任务链接;具体改动/验收/夹具在各子 issue 里,一个功能一个 issue、做完测完关一个。

整体目标

把 DeepGraph 的展示/写作层从"自己拼数字、自己判显著"降级为忠实播报员——只渲染计算层已验证的证据。计算层(GPU 跑实验)不在本计划改动范围。

架构与依赖

        计算层(不改)  agents/result_interpreter.py
        产出 verdict / p_value / effect_size / confidence(=1-p) / repro_ci / kept_ci
                    │  组装
                    ▼
        ┌───────────────────────────────┐
        │  EvidenceLedger(唯一事实源)     │
        └───────────────┬───────────────┘
                        │ 只读(不许从渲染文本 parse 数字)
        ┌───────────────┼───────────────┐
        ▼               ▼               ▼
   M1 显著性数值     M4 可回溯校验     M2 四个确定性检查(对已渲染 main_tex)
                                       │
                                       ▼
                               M3 接入 paper_orchestra_pipeline.py:1843 渲染门禁
                                  任一命中 → ok=False,禁出稿

子任务

PR	issue	内容	依赖
PR-1	#24	M1 显著性数值修复 + EvidenceLedger 最小结构	—
PR-2	#27	M4 EvidenceLedger full traceability checker	blocked by #24
PR-3	#25	M2 四个确定性检查(未解析/脚手架/串台/复读)	—
PR-4	#28	M3 接入渲染门禁(1843)	blocked by #25
PR-5	#26	M5 计算/展示依赖边界测试	—

建议顺序:PR-1 → PR-2;PR-3 → PR-4;PR-5 可并行。每个子 issue 自包含,只回这条 Epic 取下面的共享上下文。

Agent Execution Contract

不要求也不鼓励一次性做完。每个子 issue = 一个收敛 PR,必须遵守:

1. 先新增失败测试与反例夹具,再实现代码。
2. 每个 PR 只做对应 milestone 的最小必要改动。
3. 不删除、不弱化现有测试、门禁、blocker、forbidden terms。
4. 不修改无关模块,不做顺手重构。
5. 不引入 GPU / model / network 依赖到展示层 import 路径。
6. 渲染逻辑不得从已渲染文本 parse 数字来生成结论;只有验证器 assert_traceable 可以从 tex 抽取数字,用于反向校验数字是否有 ledger 来源。
7. 每个 PR 描述列出:changed files / tests added / tests run / before-after behavior / known non-goals。

代码定位(file:line / 字段名 / 挂载点)已按当前仓库版本核对;若行号漂移,以函数名、字段名、挂载点语义为准,不得因行号变化改变任务目标。

EvidenceLedger Schema(共享,PR-1/PR-2 都用)

单一事实源。计算层写,展示层只读。展示层渲染的任何数字都必须能在此找到来源字段。字段与现有产出对齐(result_interpreter packet + benchmark_artifacts 的 per_method/seed_variance),标 [new] 的为新增。

{
  "schema_version": "1.0",
  "run_id": "string",          // 用于跨 run 串台检测(M2-c)
  "claim_id": "string",
  "metric": "exact_match",     // = per_method 内层 metric key
  "alpha": 0.05,               // [new] 显著性阈值;默认 0.05;env DEEPGRAPH_SIGNIFICANCE_ALPHA 可覆盖
  "verdict": "confirmed|refuted|inconclusive|reproduced",
  "p_value": 0.0123,           // permutation
  "effect_size": 0.045,
  "confidence": 0.9877,        // = 1 - p_value(不是 CI)
  "repro_ci": [0.01, 0.08],    // bootstrap 95% CI;_bootstrap_ci(ci=0.95)
  "kept_ci":  [0.00, 0.07],
  "per_method": {              // 键为方法名字符串
    "<candidate>": {"exact_match": 0.705, "n": 200},
    "<baseline>":  {"exact_match": 0.655, "n": 200}
  },
  "seed_variance": {           // 均值/标准差/逐种子在此(不在 per_method)
    "<candidate>": {"mean": 0.705, "std": 0.012,
                    "per_seed": {"0": 0.71, "1": 0.70}}  // 形状 = {seed: mean}
  },
  "seeds": [0, 1, 2],          // has_multi_seed 判定读 len(seeds)>=3
  "provenance": {"code_commit": "string", "dataset": "string", "command": "string"}  // [new]
}

注意:不存在 confidence_interval{low,high,level} 字段——真实 CI 是 repro_ci/kept_ci 两个数组;confidence 是 1-p_value、不是 CI。per_method 内层是 {<metric>: value, "n": int},均值/标准差/逐种子在 seed_variance.<method> 下;per_seed 形状是 {seed: mean}。

Test Execution Protocol

每个子 PR 的执行顺序:

1. 改动前先跑回归基线:pytest tests/test_pipeline_contracts.py、pytest tests/test_vnext_manuscript.py
2. 新增本 milestone 的失败测试与反例夹具
3. 实现最小必要改动
4. 跑本 milestone 测试
5. 再跑一次回归基线
6. PR 描述贴出实际执行的命令与结果

若仓库有更准确的测试命令,可替换上面的命令,但必须体现这个顺序。

Non-goals

• 不改计算层统计方法
• 不重新跑 GPU benchmark
• 不引入新的 LLM 调用
• 不重构 paper pipeline 架构
• 不新增 synthetic / mocked compute backend
• 不支持模块化 LaTeX \input{content/conclusion} 的跨文件 traceability
• 不改变 require_submission_ready() 的证据侧语义
• 不处理 M1 中 :699 的存在性检查语义

工程姿态(遵循 #22)

门禁化非破坏删除 · 收敛分支 · 验证通过再并回 · 未经维护者确认不强推主线。

[Protocol-zero-0]

Epic 已交付:5 个子任务(#24/#27/#25/#28/#26)经 PR #29 squash-merge 进 master(2026-06-06,HEAD 44ecc31),验收用例与回归基线全绿。关闭。