# EXP-3D-CAJU-HEADROOM-V1 预注册协议（CAJU-V1 Gate 0）

## 0. 范围

- 本实验只做 CAJU-V1 的 Gate 0：在 Core B 现有引擎上，检验是否存在值得学习的更新动作差异，也就是"是否存在动态动作空间"。
- Gate 1（残差 + JEPA 特征 → 效用 MLP）有两个前提：Gate 0 通过，并且存在真正的 JEPA 预测表征。审计结论是 `JEPA_FEATURE_STATUS=NOT_IMPLEMENTED`（见 `jepa_feature_contract.md`），所以本轮不可能检验或宣称 JEPA 的独立贡献。Gate 2（AC-JEPA）不执行。
- 锁定前没有读取任何 CAJU 片段的查询或历史视角真值，也没有计算任何动作效用。锁定前只运行了建根目录、几何封存（不读目标深度）、单元测试和一个根目录外的单片段排练（只看耗时和显存，不读真值）。

## 1. 审计结论（详见 `code_audit.md`）

- **Core B 的 GPU 部分**：V1 锁定的 `ds_eval.py`（sha256 `36b05c49…`），参数为 `--model ZS --scale-max 0.1 --arms CACHE TTT --ttt-mult 1 --ttt-steps 100`。
- **CACHE**：发布版 DepthSplat（re10k+dl3dv base，高斯尺度上限 0.1），输入 3 个上下文帧加 4 个流帧，测量的平面深度注入为最终的上下文深度。
- **TTT**：
  - 优化对象只有高斯状态的增量：位置、每个高斯特征基内的逐轴对数尺度（旋转固定）、不透明度 logit、SH DC 和高阶 SH。网络权重冻结。
  - 优化器为 Adam，eps 1e-15，每个片段新建。学习率是 3DGS 默认值 × 1。
  - 损失 = 7 帧有效测量像素上原始渲染深度的相对 L1 + 0.5 × RGB L1。
  - 损失出现非有限值时，状态回退到 CACHE。
- **读出**：
  - ray = depth_z / α / cos；
  - F7 = α ≥ 0.5 处取 ray，其余取 R7；
  - CORE_B = sqrt(R7 × F7)，两者下限 1e-6。
  - R7 = 7 帧测量深度的 1 像素 z-buffer 重投影取并集，再做冻结的调和填充。填充常数 2.3736 m，与 V3 相同。
- **旧接口**：早期项目的 `fuse_down` / `complete_down` 快权重写入只存在于旧的 carrier 模块，Core B 不经过它们。

## 2. 数据

- **来源**：ARKitScenes Training 折，`outputs/EXP-3D-RGBD-ARKIT-DATA-V1/manifest_arkit_trainval.json`。共 190 条记录，每条记录是一个场所（physical_scene_id），每条 16 帧。
- **划分**：
  - **CAJU_PILOT**：8 个 DEV 场所，16 个片段。只做工程检查，不进入任何正式统计。
  - **CAJU_SEL**：16 个 TRAIN 场所，32 个片段。只用来选择最佳固定动作。
  - **CAJU_EVAL**：34 个 TRAIN 场所，68 个片段。在这里测量 oracle headroom。
  - **选择规则**：182 个 TRAIN 场所 ID 排序后，用 `random.Random(20261014)` 打乱。前 16 个归 SEL，接下来 34 个归 EVAL，其余 132 个不动，保留给可能的后续阶段。
  - **CAJU_COMPAT**：V3 锁中的前两个 ARKIT_SYSTEM3 扫描（4 个片段）。只用于把本实验的引擎与 V3 已封存的 CACHE / TTT_m1 预测对比，不读真值。
- **历史暴露**：
  - TRAIN 场所曾用于训练逆向 JEPA 变体（JA、JC、JN、JK、JO，以及 502 扫描集合中的 JL / JOL）和 GA carrier。
  - DEV 场所曾作为这些训练的开发监控（CTX 臂，cap 3.0）。
  - 这些场所都没有用 Core B（发布权重，CACHE / TTT）评测过；发布版 DepthSplat 没有见过 ARKitScenes。
  - 因此本实验数据属于训练/开发数据，不是 fresh test，也不声称独立外部验证。
- **受保护数据**：受保护的 Hypersim final holdout 不打开，`FINAL_HOLDOUT_TOUCHED=false`。

## 3. 片段

- **片段**：每条记录 × 角色（A、B）。
- **帧的分工**：
  - **上下文**：角色帧，A 为 0, 1, 2，B 为 0, 3, 4。
  - **流**：`stream_frame_ids`，从空闲帧中均匀取 4 帧，两个角色共用，通常是 5, 8, 10, 13。
  - **查询**：`primary_query`，即 14、15，晚于所有到达帧。
  - **历史视角**：流没有用到的空闲帧，通常是 6, 7, 9, 11, 12。它们从未被测量过，都位于第一个和最后一个流帧之间。
- **到达观测**：7 帧（3 个上下文加 4 个流帧）的 RGB、测量深度和相机。查询和历史视角只提供相机，用来渲染预测。
- **控制器的信息边界**：将来的控制器不能看到未来查询的相机，也不能看到任何未来的 RGB 或深度。

## 4. 动作（锁定）

| 动作 | TTT 步数 | 状态 |
|---|---|---|
| A0 OFF | 0 | CACHE 状态，不做优化 |
| A1 SHORT | 10 | 同一条 TTT 轨迹的第 10 步状态 |
| A2 FULL | 100 | 第 100 步状态，即 Core B |

- **同一起点**：三个动作都从同一个 CACHE 状态出发。SHORT 是 FULL 轨迹的只读快照：快照只做 no-grad 渲染，不影响后续轨迹。
- **TTT 不变**：TTT 的数学与 V1 的 `ds_eval.ttt` 逐行一致。
- **失败回退**：损失非有限时按 V1 的规则回退到 CACHE。失败发生在第 10 步之前时，SHORT 和 FULL 都回退；之后只有 FULL 回退。
- **读出**：所有动作都用冻结的 Core B 读出。
- **引擎检查**：在试点阶段做，时间在锁定之后、正式回放之前。
  1. 在前 4 个 PILOT 片段上，用 V1 自己的 `ttt` 独立运行 10 步和 100 步，各运行两次，得到运行间非确定性的底线。回放得到的 SHORT / FULL 与之相差，不得超过 2 × 底线 + 1e-6。
  2. CACHE 编码两次，检查编码器是否确定。
  3. 在 CAJU_COMPAT 上，把本引擎的 OFF / FULL 与 V3 封存的 CACHE / TTT_m1 比较。
  4. 效用层面，同样用 2 × 底线 + 1e-6 的标准检查。
- **检查失败时**：在正式回放之前，以修订记录的形式修复。

## 5. 效用、成本与损害

- **损失与效用**：
  - 每个查询算 CORE_B 读出在有效真值像素上的 AbsRel。片段损失 L(a) 是两个查询的平均。
  - 质量效用 U(a) = L(OFF) − L(a)，所以 U(OFF) = 0。
- **成本 C(a)**：TTT 优化步数，分别为 0、10、100。另外报告 CUDA 同步后的实测秒数。GPU 是共享的，秒数有噪声，不进入任何判定。
- **损害 H(a)**：分两部分，单独报告。
  - **历史视角**：H_hist(a) = L_hist(a) − L_hist(OFF)，即历史视角上 CORE_B AbsRel 的增加（> 0 为损害）。
  - **已观测可靠区域**：7 帧中 OFF 已经覆盖、并且归一化深度误差 ≤ 5% 的像素。报告这些像素的误差增量，以及被破坏的像素占比（不再覆盖，或误差超过 5%）。
- **净效用**：目前没有可辩护的成本系数和损害系数，所以取 λ_c = λ_h = 0，主判定只用质量效用。成本用质量—计算 Pareto 曲线体现，损害单独报告。不做事后调权重。
- **统计单位**：场所，每个场所一个扫描。场所值是两个角色片段的平均。

## 6. 策略

| 策略 | 定义 |
|---|---|
| FIX | 最佳固定动作：在 CAJU_SEL 上场所平均效用最高的动作，平局取更便宜的。选择结果写入 `fixed_action_selection.json`，记录哈希后才允许读 CAJU_EVAL 的真值。 |
| ORACLE | 逐片段 oracle：事后为每个片段选效用最高的动作（平局取更便宜的）。这是事后上界，不可部署。 |
| XORACLE（主判定） | 交叉查询 oracle：用一个查询的效用选动作，在另一个查询上评价，两个方向取平均。它去掉了"利用单个查询帧的特异性"带来的乐观偏差，更接近只看片段级信息的选择器能达到的上限。 |
| VORACLE | 场所 oracle：同一场所的两个角色用同一个动作（事后选择）。 |
| XROLE | 交叉角色：用一个角色的效用选动作，在另一个角色上评价。 |
| SUFFICIENT / XSUFFICIENT | 最省充分策略：在效用不低于 U(FIX) − 0.0005 的动作里选最便宜的。XSUFFICIENT 是交叉查询版本，用于计算节省分支。 |

## 7. Gate 0 判定（锁定）

**主判定 `QUALITY_HEADROOM_SUPPORTED`**：在 CAJU_EVAL 的场所上看 XORACLE − FIX，以下四条全部满足：
1. 均值 ≥ 0.0010 AbsRel。这是实用最小值：在真实数据上，Core B 读出中 FULL 相对 OFF 的全部收益约为 0.003，0.001 大约是它的三分之一。
2. 场所 bootstrap（项目统一实现，10,000 次，seed 20260928）的 95% CI 下界 > 0。
3. 每个留一场所均值都 > 0。
4. 正贡献中 top-1 场所的占比 ≤ 0.5。

**计算节省分支 `COMPUTE_HEADROOM_SUPPORTED`**：只在主判定不成立时检查，以下全部满足：
- FIX 有成本；
- XSUFFICIENT 的平均步数 ≤ FIX 步数的 50%；
- 质量损失 FIX − XSUFFICIENT 的均值 ≤ 0.0003，且 CI 上界 ≤ 0.0005；
- 没有任何成本 ≤ FIX 50% 的固定动作已经在 0.0005 以内。如果只有这一条不满足，记为 `NOT_ESTABLISHED_FIXED_RULE_SUFFICES`，意思是固定规则就能省计算，不需要学习。

**其余情况**：`NOT_ESTABLISHED`，输出 `NO_USEFUL_DYNAMIC_ACTION_SPACE`，停止 Utility MLP。

**GATE1_ALLOWED**：只有 Gate 0 通过、并且 JEPA 特征存在时才为 true。本轮 JEPA 特征不存在，所以无论 Gate 0 结果如何都是 false。如果 Gate 0 通过，只允许准备 non-JEPA 预测器（B2–B4），并给出最小 JEPA 特征提取器的设计和训练成本，由用户决定是否继续。

## 8. 必须报告的次要量（描述性）

- **动作选择**：
  - oracle 中各动作的使用频率，以及 XORACLE 的选择频率；
  - OFF / SHORT / FULL 各自最优的片段比例；
  - 有益 / 有害更新的比例（|U| > 0.0005）；
  - FULL 相对 SHORT 的边际收益。
- **成本**：各动作的额外计算时间。
- **排序变化**：排序不同于众数排序的片段比例，以及同一场所两个角色最佳动作相同的比例。
- **质量—计算 Pareto**：固定动作及其随机混合，与逐片段 oracle 的前沿（同查询和交叉查询两种）比较，报告 5 / 10 / 25 / 50 / 100 步预算下的优势。
- **损害**：历史视角损害和已观测可靠区域损害。
- **残差分组**：按更新前残差（第 0 步的深度项）分三组。三分位点用 100 个正式片段算出，不涉及真值。报告每组内有益 / 中性 / 有害片段的分布。
- **特征相关性**：若干更新前特征与效用的 Spearman 相关，只作描述。
- **图**：图 1–5，依次是动作效用分布、oracle 对固定动作、Pareto、残差对效用、残差分组。Gate 1 的图不生成。

## 9. 信息契约与完整性（对应任务书第 13 节）

| 项 | 内容 | 检查方式 |
|---|---|---|
| 1 | 未来查询真值不进入任何动作 | 回放只读 7 个到达帧，每个片段审计所有打开的文件，封存中写明 `query_depth_read=false` |
| 2 | 未来查询真值不进入 JEPA 特征 | 没有 JEPA 特征 |
| 3 | 未来查询真值不进入预测器特征 | 更新前特征只来自 7 个到达帧（已审计） |
| 4 | 反事实分支来自同一初始状态 | OFF = CACHE；SHORT / FULL 是同一轨迹的第 10 / 100 步 |
| 5 | 各动作获得相同的到达观测 | 每个片段只编码一次 |
| 6 | OFF 保留正常缓存与融合 | OFF 是 7 视角 CACHE |
| 7 | R7 对所有动作相同 | 每个目标视角一个几何封存，所有动作共用 |
| 8 | TTT 只读到达帧 | 已审计 |
| 9 | 优化器状态不跨分支污染 | 每个片段新建 Adam；SHORT 是只读快照；与 V1 的独立运行做等价检查 |
| 10 | 扫描之间完整重置 | 每个片段重新编码，记录 CACHE 指纹 |
| 11 | 动作集合不随开发结果改变 | 动作集合在锁中 |
| 12 | opacity 阈值不随真值改变 | 阈值在锁中 |
| 13 | 同一场所的扫描不当作独立单位 | 统计单位是场所 |
| 14 | 部署时只执行所选动作 | Gate 0 不部署选择器，不适用 |
| 15 | 在线成本包含 JEPA 与 MLP | 本轮没有 JEPA / MLP，不适用 |
| 16 | 结果可由原始预测重建 | 打分从封存的 npz 重算；分析运行两次，逐字节一致 |

- **真值读取**：只经过 `TeacherAccess.query_depth` 读取，目的为 SEALED_QUERY_EVALUATION，并逐条记录。读取必须在该队列的所有封存完成之后。
- **测试**：单元测试覆盖片段规则、选择、读出、效用、oracle、Pareto、判定分支、文件审计、锁和阶段顺序，结果写入 `tests.json`。

## 10. 计算预算

- **试点**：16 个片段，加上 4 个片段的参考运行（10 + 10 + 100 + 100 步），再加 4 个 COMPAT 片段。在 GPU 4 上与其他进程共用，估计 0.5–1 小时。
- **正式**：100 个片段，分 3 片。每个片段约 100 步 TTT 加 3 次读出，与其他进程分时，每片段约 2–3 分钟。合计约 1.5–2 小时墙钟、4–5 GPU 小时，每个进程显存约 6 GB。
- **限制**：只用 GPU 4（`cv_gpu_run.sh --with-others`）；不做任何训练；不下载数据。

## 11. 执行顺序

1. root
2. geometry
3. test
4. rehearsal（根目录外，1 个片段）
5. lock
6. pilot（GPU）
7. pilot-score
8. formal（GPU）
9. score：依次为 sel → eval → analyze（两次）→ finalize

## 12. 修订规则

- 锁定后的任何修改，都只能以 `audit/amendment_N.json` 加本文件末尾追加的方式记录，并且必须发生在读取任何正式真值之前。
- 锁定时的文本必须始终是当前文件的精确前缀。


## 修订 1（2026-10-14，在正式回放之前，没有读取任何正式真值）

**触发**：试点中，预测层面的引擎检查有两项未通过（见 `equivalence/equivalence_report.json`）：
- SHORT 快照与 V1 独立 10 步运行相比，单像素 depth_z 的最大差为 0.0033 m；阈值是 2 × 底线 + 1e-6，底线为 0.0014 m，阈值约 0.0029 m。
- CAJU_COMPAT 上，FULL 与 V3 封存的 TTT_m1 相比，单像素最大差为 0.353 m；阈值用的是 PILOT 场景的底线，2 × 0.145 m。

其余检查都通过了：
- OFF 与 V1、与 V3 都逐位一致；
- FULL 与独立运行的差异在底线以内；
- 效用层面三个动作都在 2 × 底线 + 1e-6 以内，例如 FULL 回放对独立运行最大 1.1e-5，独立运行之间 7.8e-6。

**诊断**：见 `audit/amendment_1/nondeterminism_diagnostic.py` 及其输出 `nondeterminism_diagnostic.json`，不读任何真值。
- **V1 的 TTT 在 GPU 上本身就不确定**。同一进程中两次独立运行，10 步后像素差均值 1.2e-7 m、最大 1.4e-3 m；100 步后均值 4.8e-4 m、最大 0.145 m。
- **回放与独立运行之间的差异分布，和两次独立运行之间的差异分布相同**：

  | 动作 | 指标 | 回放对独立运行 | 独立运行对独立运行 |
  |---|---|---|---|
  | SHORT | 像素差均值 | 1.19e-7 | 1.18e-7 |
  | SHORT | 像素差 p99 | 9.6e-7 | 1.2e-6 |
  | FULL | 像素差均值 | 4.66e-4 | 4.75e-4 |
  | FULL | 像素差 p99 | 6.5e-3 | 6.7e-3 |
  | SHORT | Core B 读出相对差均值 | 3.9e-8 | 4.1e-8 |
  | FULL | Core B 读出相对差均值 | 6.0e-5 | 6.0e-5 |
- **原检查的问题**：单像素最大值是极值统计，用一个极值去比另一个极值，本身很不稳定。COMPAT 的阈值又来自另外的场景，尺度不同。
- **COMPAT 的实际差异**：FULL 与 V3 的 Core B 相对差均值 1.7e-4、p99 2.4e-3，与运行间的非确定性同一量级；OFF 与 V3 逐位一致。

**决定**：
- **引擎**：不修改任何引擎代码。
- **检查结果**：预测层面的单像素最大值检查如实记为未通过。能否进入正式回放，改为同时看两项：
  1. 已预注册的效用层面检查，已全部通过；
  2. 本诊断的分布比较：回放对独立运行的 Core B 读出相对差，均值和 p99 不超过两次独立运行之间的 1.5 倍，且 OFF 与 V3 逐位一致。也已通过。
- **Gate 0 不变**：数据、动作、效用、策略、阈值、分析全部不变。
- **非确定性的影响**：运行间非确定性对单个片段效用的影响最多约 1e-5，比主判定阈值 0.001 和片段带宽 0.0005 小两个数量级以上，不可能制造或掩盖 headroom。
- **`caju_finalize.py`**：相应修改。完整性记录保留原始检查结果，加入本修订的分布检查；其余检查都通过时，状态记为 `PASS_WITH_AMENDMENT_1`。新的哈希记在 `audit/amendment_1.json`。
- **正式回放**：自动链在检查失败后按设计停止。正式回放在本修订记录之后手动启动，命令就是锁定的 `caju_jobs.sh formal`。