Add causal oracle person information screen

docs/README.md

@@ -24,6 +24,7 @@ tests.
 | [`ego4d_encoder_only.md`](ego4d_encoder_only.md) | Preparing and running the Ego4D encoder-only comparison |
 | [`ego4d_local_baselines.md`](ego4d_local_baselines.md) | Previewing Ego4D boxes, extracting local features and running 8-GPU jobs |
 | [`easycom_track_gru_residual.md`](easycom_track_gru_residual.md) | Matched pooled-to-track GRU experiment, causal identity contract and L20 commands |
+| [`easycom_oracle_information.md`](easycom_oracle_information.md) | Causal oracle per-person speaking-history upper bound and Session-12 screening commands |
 
 ## Design history and implementation options
 

docs/easycom_oracle_information.md

@@ -0,0 +1,100 @@
+# EasyCom causal oracle-person information screen
+
+## Question
+
+Before training a heavier visual grounding model, test whether perfect
+participant-resolved **past** speaking activity contains useful information for
+future wearer activity beyond the frozen Omni state and recent mixed audio.
+This is an information upper-bound experiment, not a deployable input setting.
+
+## Causal contract
+
+- The task grid remains 5 Hz. State row `t` has cutoff `(t+1)/5` seconds.
+- Oracle bin `t` summarizes transcript frames in
+  `[t/5,(t+1)/5)` and is therefore completely observed at that cutoff.
+- Each person vector stores the last 2 seconds of binary activity followed by
+  a visibility/availability mask. Activity is exposed only in bins where that
+  participant was visible according to the provided boxes. No future bin,
+  future wearer state, transcript text or `Target_of_Speech` value is input.
+- Only non-wearer participant IDs present in the latest provided-box frame
+  strictly before the cutoff receive slots. IDs route annotations during
+  preparation but are not exposed as embeddings to the head.
+- Transcript-derived wearer/others activity must match `target_perframe` by
+  default. Any mismatch fails closed instead of being silently tolerated.
+- Oracle sidecars use `easycom-oracle-person-history-v1` and are accepted only
+  by the explicit `oracle-frame-set-attention` mode. Normal local-feature
+  loading rejects them because they use speech labels.
+
+## Conditions
+
+| Condition | Information exposed | Purpose |
+|---|---|---|
+| `audio` | Omni `G` plus the existing recent local audio `A` | deployable baseline |
+| `visibility-only` | current visible-person set, but all activity bits are zero | parameter/person-count control |
+| `aggregate-visible` | one OR-pooled history over currently visible people | aggregate floor-information upper bound |
+| `per-person` | one correct activity history per currently visible participant | main oracle information test |
+| `shuffled-id` | preserves the number active at every lag but independently reassigns activity between people | destroys identity continuity |
+| `delayed` | correct per-person histories delayed by 1 second | destroys current temporal alignment without future leakage |
+
+The decisive comparison is `per-person` against `aggregate-visible`,
+`shuffled-id` and `delayed`, not only against `audio`. A gain over `audio` alone
+could come from perfect aggregate VAD rather than person continuity.
+
+## Remote preparation and one-seed Session-12 screen
+
+The source local sidecars provide only mixed audio and the visibility/box
+timeline. Their learned visual vectors are not copied into the oracle input.
+
+```bash
+cd /data1/yfzx/wangx/Code/icassp2027-experiment
+
+export DATASET_ROOT=/data1/yfzx/wangx/Datasets/easycom/extracted_easycom
+export FEATURE_ROOT=/data1/yfzx/wangx/Datasets/easycom/omni_features/open_stream_2fps_8s_last4_stack
+export TARGET_ROOT=/data1/yfzx/wangx/Datasets/easycom/easycom_target_frame
+export LOCAL_ROOT=/data1/yfzx/wangx/Datasets/easycom/omni_features/local_qwen_1s_encoded_tf4576
+export ORACLE_ROOT=/data1/yfzx/wangx/Datasets/easycom/omni_features/oracle_person_history_2s
+export CHECKPOINT_ROOT=checkpoints/easycom_oracle_information_4ep
+export RESULT_ROOT=results/easycom_oracle_information_4ep
+
+CUDA_VISIBLE_DEVICES=0 bash run_easycom_oracle_information.sh all 0
+```
+
+`all` prepares the five oracle conditions, trains on Sessions 4--11, selects
+the checkpoint on Session 12, runs Session-12 inference and prints the standard
+dense AP/mAP screen. It deliberately does not run Sessions 1--3.
+
+If preparation reports any transcript/target mismatch, stop and inspect it.
+Do not raise `--max-label-mismatch-rows` merely to make the run continue.
+
+## Follow-up
+
+If `per-person` is consistently better on Session 12, add seeds 1 and 2 using
+the already prepared sidecars:
+
+```bash
+CUDA_VISIBLE_DEVICES=0 bash run_easycom_oracle_information.sh screen 1 2
+```
+
+Only after freezing the method and event evaluator should selected variants be
+run once on Sessions 1--3:
+
+```bash
+VARIANTS="audio aggregate-visible per-person shuffled-id delayed" \
+CUDA_VISIBLE_DEVICES=0 \
+bash run_easycom_oracle_information.sh test 0 1 2
+```
+
+## Interpretation
+
+- `per-person > aggregate-visible` and `per-person > shuffled-id`: speaker
+  continuity has information value; proceed to learned causal ASD/tracks.
+- `aggregate-visible > audio`, but no per-person advantage: perfect aggregate
+  activity helps, but the current target does not justify an identity claim.
+- oracle conditions do not improve: do not spend the main GPU budget on a more
+  complex person encoder until the task/head/evaluator is reconsidered.
+- oracle improves but learned Qwen face features do not: this supports a
+  speaker-grounding bottleneck and motivates EgoASD-like AV evidence.
+
+Dense 10-horizon mAP is only a screening signal. The publication claim still
+requires the frozen competing-risk-censored entry/yield evaluator and matched
+wearer-onset-recall false-entry analysis.

docs/easycom_track_gru_residual.md

@@ -62,8 +62,14 @@ re-extraction.
 
 Runtime status (2026-09-07): the focused causal-history, exact-zero-gate and
 train/infer round-trip tests passed in 49.699 seconds on the remote PyTorch/L20
-environment. This verifies the code path, not model quality. The one-session
-GPU training smoke and full experiment remain unmeasured.
+environment. The subsequent matched four-epoch screen produced no meaningful
+change: Session-12 three-seed mean-mAP delta was `+0.01306 +/- 0.02368`
+percentage points, and the seed-0 Sessions-1--3 delta was `-0.00030` points.
+The selected residual gates remained between `-0.0015` and `+0.0108`. Because
+the zero scalar gate blocks the track branch's gradient at initialization, this
+run is classified as an optimization failure, not a clean negative result for
+track continuity. Exact values and caveats are archived in
+[`../results/easycom_track_gru_residual_4ep_2026-09-07/README.md`](../results/easycom_track_gru_residual_4ep_2026-09-07/README.md).
 
 ## Fair initialization
 
@@ -73,6 +79,14 @@ feature contract before copying the pooled path. By default those copied
 parameters are frozen. The residual gate starts at zero, so before optimization
 the track model must reproduce the pooled logits exactly, element for element.
 
+The measured screen exposed a defect in that parameterization. At a zero gate,
+the first-step gradient of every residual-branch parameter is also zero; only
+the scalar gate can move, and later branch gradients remain multiplied by its
+small value. A corrected follow-up should instead zero-initialize the final
+residual output layer and remove the scalar multiplier. That preserves exact
+pooled logits at initialization while allowing the output layer to receive a
+gradient immediately.
+
 The matched screening protocol is:
 
 - EasyCom Session 4--11: training;

docs/progressive_feature_fusion_route_2026-09-02.md

@@ -204,6 +204,13 @@ track GRU、G+A 对 track states 的 masked attention 以及零初始化 scalar
 实现、契约和命令见
 [`easycom_track_gru_residual.md`](easycom_track_gru_residual.md)。
 
+2026-09-07 的实测暴露了这个第一版参数化的优化缺陷：Session 12 三个 seed 的
+ten-horizon mean mAP 配对增量仅为 `+0.01306 +/- 0.02368` 个百分点，保存 checkpoint 的
+`tanh(gate)` 只有 `-0.0015` 到 `+0.0108`。零 gate 在第一步也会把 residual branch 的参数
+梯度乘为零，因此该结果不能用于否定 track continuity。下一版应删除 scalar gate、将
+residual 最后输出层零初始化，并在 dev 上记录 delta-logit、概率变化和非零梯度；详见
+[`结果记录`](../results/easycom_track_gru_residual_4ep_2026-09-07/README.md)。
+
 ## 8. F4：Person-conditioned audio/Omni history
 
 F4 让每个匿名人物分别读取已有的 5 Hz 因果历史：
@@ -279,11 +286,14 @@ README 必须写明 split、seed、checkpoint、输入特征版本、评测协
 
 ## 12. 最近执行顺序
 
-1. 用户当前选择先做 dense-AP model screen；运行 matched pooled 与
-   `track-gru-residual`，固定 Session 12 dev，不用测试集选历史长度。
-2. 若 track GRU 有稳定增益，补 broken-track、past-shift、no-ID 和 remove-person 控制；若
-   无增益，只在 dev 上比较 8/16/32 observations 后停止该分支。
-3. correct track 通过控制后，再实现 F4 person-conditioned audio/Omni history；否则回到
+1. 第一版 matched pooled/`track-gru-residual` dense-AP screen 已完成，但因 zero-gate
+   gradient blockage 判为优化失败，不是 track continuity 的有效阴性结果。
+2. 先用零初始化 residual 输出层修正梯度路径，只在 Session 12 做 seed-0 诊断；确认分支
+   实际改变 logits 后再跑三 seed。若修正后仍无增益，再决定是否比较 8/16/32
+   observations；不要根据已经查看过的 Sessions 1--3 seed-0 结果调参。
+3. 若修正后的 track GRU 有稳定增益，补 broken-track、past-shift、no-ID 和 remove-person
+   控制；若仍无增益则停止该分支。
+4. correct track 通过控制后，再实现 F4 person-conditioned audio/Omni history；否则回到
    对齐审计，不直接堆更深 interaction。
-4. 在形成论文事件结论前，仍须完成 P0 competing-risk censoring，并人工打印 response 与
+5. 在形成论文事件结论前，仍须完成 P0 competing-risk censoring，并人工打印 response 与
    yield 时间轴。当前事件结果只能称为 timing-derived proxy。