# EXP-3D-RGBD-COMPLETION-V11 修正记录

## Amendment 1：浮点舍入导致的颜色越界（2026-09-29 19:5x，远端时间）

写于查看任何 V11 结果之前。除了下文的诊断，我只看过训练损失和步数：DEV 曲线、checkpoint 选择、DEV 指标与 EVAL-V3 都没有读取。EVAL-V3 此时尚未运行。

### 发生了什么

- **失败：** 冻结的训练在每个 checkpoint 步用 DEV 评价选择 checkpoint，其中指标函数（`statistics._rgb`）要求渲染颜色严格在 [0, 1] 内。
  - C1（宽度 32）seed 20260928 在第 5000 步失败；
  - C1 seed 20260930 在第 6000 步失败；
  - 报错都是 `ValueError: RGB must be in [0, 1]`。
- **冻结规则的后果：** 这类 Python 错误不自动重试；主变体失败，实验停止。runner 于 19:33 停止，C0 的 3 个训练和 C1 seed 20260929 都已正常完成。
- **诊断（`audit/amendment1_rgb_range_diagnostic.json`）：**
  - 做法：重新加载出错的两个 checkpoint，只渲染 DEV 上下文视角的颜色并统计其范围，不计算任何指标，不读取任何 query 帧。
  - 结果：48 个上下文视角中，两次都只有 1 个视角越界（ai_032_001，角色 B，帧 5），分别有 7 个和 2 个值等于 1.0000001192。
  - 这正好比 1 大一个 float32 最小单位（2⁻²³ ≈ 1.2×10⁻⁷）：渲染器把各采样点的颜色加权求和，再加上背景，这个求和的舍入偏差所致。没有 NaN，训练没有发散。更宽的 carrier 会把亮面的颜色推到接近饱和，所以只有宽度 32 的变体遇到这个问题。

### 修正

- **截断规则：** 新增 `clip_rounding`（`src/mcss/mechanism_pilot/rgbd_completion_evaluation_amend1.py`），作用于渲染颜色。
  - 超出 [0, 1] 不超过 1×10⁻⁶（约 8 个 float32 最小单位）时，截回 [0, 1]；
  - 超出更多时仍然报错；
  - 非有限值原样交给冻结的有限性检查；
  - 完全在 [0, 1] 内的输出原样返回，逐位不变。
- **修改范围：** 评价模块只在两次渲染调用外包一层 `clip_rounding`，其余代码与冻结版本逐字相同。
  - 训练、DEV 评价与 runner 的新脚本（`*_amend1.py`）与冻结版本只差评价模块的导入或脚本名；
  - 测试 `tests/test_rgbd_completion_amend1.py` 检查了这一点，以及截断规则本身。
- **不受影响的部分：** 冻结文件都没有修改。EVAL-V3 阶段只渲染深度，收尾脚本对保存下来的（已截断的）颜色用冻结的指标函数重算，都不受影响。
- **事前试跑：** 在出错的两个 checkpoint 上试跑了修正后的评价，两次都完成；试跑输出没有读取，已直接删除。

### 重跑

- **存档：** 失败的两个训练作为第 2 次尝试存入 `audit/failed_attempts/`，事故类型为 `amendment1_rgb_float_rounding`；原来的 `training_failures.json` 同样移入该目录。
- **重跑方式：** 用修正后的训练脚本从头重跑，其余配置完全相同，计入原有的重跑预算。
- **逐位复现检查：** 在 CPU 上训练是确定性的，所以重跑必须与失败的那次逐位相同：
  - seed 20260928 的前 5000 行训练记录；
  - seed 20260930 的全部 6000 行训练记录；
  - 不相同就停止。
- **已完成的 4 个训练：** 不重跑。它们的 DEV 曲线由冻结的评价计算，没有遇到越界；修正后的评价对这些值会给出逐位相同的结果。
- **后续流程：** 与冻结的 runner 相同，包括 DEV 选择、诊断、参照、统计、复现审计、EVAL-V3 的封存、打分与分析，以及收尾。其中 DEV 选择的评价改用修正后的评价模块。