docs: define progressive person fusion route

PROJECT_CONTEXT.md

@@ -19,6 +19,7 @@ recall, without hurting addressed responses or yield behavior.
 
 | Need | Authoritative file |
 |---|---|
+| Progressive feature-fusion implementation route | [docs/progressive_feature_fusion_route_2026-09-02.md](docs/progressive_feature_fusion_route_2026-09-02.md) |
 | Current hypotheses, experiment gates and stopping rules | [`docs/omni_speaker_floor_experiment_plan_2026-08-30.md`](docs/omni_speaker_floor_experiment_plan_2026-08-30.md) |
 | Novelty boundary and claim restrictions | [`docs/multiparty_egocentric_floor_gap_audit_2026-08-30.md`](docs/multiparty_egocentric_floor_gap_audit_2026-08-30.md) |
 | Code/data map and current blocker | This file |
@@ -60,10 +61,13 @@ semantic event ground truth.
 2. **P1:** probe aggregate activity and per-person active-speaker grounding;
    compare correct, wrong-person and time-shifted visual inputs.
 3. **P2:** re-evaluate `G`, `G+A`, `G+A+pooled-V` under the frozen event protocol.
-4. **P3:** train an anonymous person-wise causal side branch with matched
+4. **P3:** begin the progressive person-fusion route with Frame-set Attention,
-   temporal-capacity controls.
+   then add spatial or track-temporal structure only after its controls pass.
 5. **P4:** attempt person-memory adapter/Thinker LoRA only if P1/P3 pass.
 
+The detailed architecture, controls and stopping gates for P3 are frozen in
+[the progressive feature-fusion route](docs/progressive_feature_fusion_route_2026-09-02.md).
+
 ## Stable data contracts
 
 ### Time and labels

docs/README.md

@@ -7,10 +7,11 @@ implemented or validated.
 
 | Document | Role |
 |---|---|
+| [progressive_feature_fusion_route_2026-09-02.md](progressive_feature_fusion_route_2026-09-02.md) | Gated route from pooled local evidence to Frame-set Attention, temporal person memory and Thinker adapters |
 | [`omni_speaker_floor_experiment_plan_2026-08-30.md`](omni_speaker_floor_experiment_plan_2026-08-30.md) | Current hypotheses, experiment gates, main table and stopping rules |
 | [`multiparty_egocentric_floor_gap_audit_2026-08-30.md`](multiparty_egocentric_floor_gap_audit_2026-08-30.md) | Novelty boundary, closest work and restricted claims |
 
-These two files supersede earlier documents when discussing the paper's main
+These documents supersede earlier documents when discussing the paper's main
 question. They do not supersede verified implementation details in code and
 tests.
 

docs/progressive_feature_fusion_route_2026-09-02.md

@@ -0,0 +1,265 @@
+# 从 pooled local evidence 到逐人跨模态交融：渐进实验路线（2026-09-02）
+
+## 1. 目的和当前决策
+
+这份路线回答一个具体问题：
+
+> 在严格因果的 egocentric 多人对话中，如何逐步保留和利用可变数量人物的结构，使模型
+> 在相同 wearer 开口召回率下，减少 other-to-other 交谈期间的错误开口，同时不损害真正
+> wearer 接话和让话行为？
+
+当前实现把每帧人物 crop 的 Qwen visual encoder token 先平均为逐人向量，再对人物等权
+平均，最后对最近约 1 秒的有效帧平均。局部音频也被池化，之后与全局 Thinker state G
+拼接进入 MLP。这个基线计算简单，但会丢失：
+
+- 同一帧内有几个人以及哪一个人更相关；
+- 人与人之间的空间关系；
+- 同一匿名人物在多帧中的连续运动和说话状态；
+- 某个人与同期音频、Omni 历史之间的对应关系。
+
+因此，普通 pooling 保留为 F0 基线，不再把继续加深 pooled MLP 当作主方法。第一项新
+融合实验从 F1 Frame-set Attention 开始。后续模块只有在前一级通过预先定义的 gate 后
+才实施。
+
+这是一份实验设计，不代表 F1--F6 或 D1 已经实现或验证。
+
+## 2. 不可改变的实验条件
+
+所有阶段共同遵守：
+
+- 目标与全局 state 均为 5 Hz；第 t 行只能使用截止到 (t+1)/5 秒的媒体。
+- 视频人物特征若为 2 FPS，在 5 Hz 预测点选择时间不晚于 cutoff 的最新人物集合。
+- 不允许用未来帧插值；同一 2 FPS 人物集合可以供多个 5 Hz query 读取，但不能伪装成
+  新观测去重复更新时序状态。
+- EasyCom Session 4--12 为官方训练集，Session 1--3 为最终测试集。模型和阈值选择使用
+  训练集内部 calibration/dev；建议先固定 Session 12，训练使用 Session 4--11。
+- G 是可能已经融合音频、视频和语言上下文的 Thinker state，不能称为纯全局视觉。
+- 局部音频 A 始终直接进入最终预测头。即使它也参与 attention query，也不能只把 A
+  藏在 query 中，否则无法公平保留当前很强的 G+A 基线。
+- 人物数量用 mask 和 NULL person 处理，不通过截断后静默补零改变语义。
+- 所有新增模型与 G+A、pooled-V 以及参数量匹配的非结构化模型使用相同历史长度、
+  optimizer、epoch、seed 和有效样本。
+- 至少运行 3 个 seed，并保存逐事件或逐 session 输出，支持 paired bootstrap。
+
+当前事件 evaluator 尚缺 competing-risk censoring。正式训练选型前必须先完成 P0：
+
+- other offset 后的 response 窗口在下一次 other onset 处截止；
+- other onset 后的 yield 窗口在下一次 other offset 处截止。
+
+P0 修正前的 entry/yield 数值只能称为 timing-derived proxy，不得作为模块通过 gate 的
+最终依据。
+
+## 3. 总路线
+
+| 阶段 | 增量 | 核心问题 | 通过后才进入 |
+|---|---|---|---|
+| F0 | 当前 equal-person/equal-frame pool | 建立可复现起点 | F1 |
+| F1 | Frame-set Attention | 当前对话状态能否选择相关人物 | F2 |
+| F2 | Spatial person interaction | 人物相对位置是否提供额外多人线索 | F3 |
+| F3 | Track-temporal shared encoder | 匿名人物连续性是否必要 | F4 |
+| F4 | Person-conditioned AV history | 每个人读取音频和 Omni 历史是否改善 grounding | F5 |
+| F5 | 双向 person/audio interaction | 更深交互是否优于单向读取 | F6 |
+| F6 | Thinker person-memory adapter | 旁路证据能否安全接入 Omni 内部 | D1 |
+| D1 | 在线 detector + causal tracker | 部署管线与 provided-box 上限的差距 | 完整系统 |
+
+F1 是下一项实现。F2 及以后不并行堆叠，避免无法判断收益来自哪一层。
+
+## 4. F0：冻结现有 pooling 基线
+
+在同一训练协议下至少保留：
+
+| ID | 输入 | 作用 |
+|---|---|---|
+| B0 | G | 全局 Omni 表示 |
+| B1 | G + A | 当前强局部音频基线 |
+| B2 | G + pooled V | 普通视觉池化的边际作用 |
+| B3 | G + A + pooled V | 当前完整 pooling 基线 |
+| B4 | G + A + parameter-matched MLP | 排除收益仅来自更多参数 |
+
+还应保存以下视觉干预：
+
+- remove-V；
+- time-shift-V：只允许向过去错位，绝不能使用未来视觉；
+- wrong-clip-V 或 session 内无关时间的人物集合；
+- correct-V。
+
+如果 correct-V 与错位/错误视觉没有稳定差异，不能把 B3 的变化解释为视觉 grounding。
+
+## 5. F1：Frame-set Attention
+
+### 5.1 输入和数据结构
+
+预测时刻 t 使用：
+
+- G_t：5 Hz 全局 Thinker state；
+- A_t：截止到 t 的因果局部音频表示；
+- P_t = {p_t,i}：最新可用视频帧中 N_t 个逐人 visual encoder 特征；
+- M_t：人物有效 mask；
+- 一个学习的 NULL person，负责没有检测到人物或当前人物均不相关的情况。
+
+F1 不使用 track ID、不使用人物绝对身份 embedding，也不跨帧递归，因此对同一帧的人物
+排列天然不敏感。
+
+### 5.2 最小架构
+
+先把不同来源投影到共同维度 d，首轮建议 d=256、4 heads、单层 attention：
+
+    q_t = W_g LN(G_t) + W_a LN(A_t)
+    K_t = W_k LN([NULL; P_t])
+    V_t = W_v LN([NULL; P_t])
+    U_t = MHA(q_t, K_t, V_t, mask=M_t)
+    logits_t = Head([G_t, A_t, U_t, valid_bits])
+
+这里的语义是：G+A 描述当前 floor 和语境，作为 query 从当前可见人物集合中选择证据。
+人物是 key/value，而不是先被无条件平均。A 仍然直接进入 Head，保证对 B1 的公平比较。
+
+F1 暂不加入 bbox、track GRU、人物自注意力或 audio-to-person 反向 attention；这些都留给
+后续独立消融。
+
+### 5.3 空人物和可变人数
+
+- 始终保留 NULL person，因此全部人物无效时 attention 仍有确定输出。
+- 真实人物用 padding 加 mask 组成 batch；padding token 不得参与 softmax。
+- 不设固定身份 slot。若训练需要 max_people，只允许按确定、与标签无关的规则截断，并
+  报告截断比例。
+- 人物顺序改变后输出应在数值误差范围内不变，作为单元测试。
+
+### 5.4 严格因果映射
+
+对每个 5 Hz cutoff c_t：
+
+1. 找到 frame_time 小于或等于 c_t 的最新 local frame；
+2. 读取该帧 frame_offsets 范围内全部逐人 feature；
+3. 如果尚无帧，使用仅含 NULL person 的集合；
+4. 不允许 nearest-neighbor 选到 c_t 之后的帧；
+5. 记录 chosen_frame_time，测试所有 chosen_frame_time 小于或等于 cutoff。
+
+### 5.5 F1 必跑对照
+
+| ID | 模型或干预 | 回答的问题 |
+|---|---|---|
+| F1-a | G+A+Frame-set Attention | 主模型 |
+| F1-b | G+A+pooled V | 是否优于现有普通池化 |
+| F1-c | 参数匹配的 learned pooling/MLP | 是否只是参数或非线性增加 |
+| F1-d | correct set 换成 past-shifted set | 是否依赖正确时间 |
+| F1-e | correct set 换成 wrong-clip set | 是否依赖正确画面 |
+| F1-f | 随机排列同一 set | 验证 permutation invariance |
+| F1-g | remove person set，仅 NULL | 视觉是否真正被使用 |
+
+可额外训练逐人 active-speaker probe，但它只诊断人物和声音是否可对齐，不能替代 wearer
+floor-action 结果。
+
+### 5.6 F1 通过条件
+
+必须同时满足：
+
+1. correct F1 在训练内固定 dev 上稳定优于 B3 和参数匹配 F1-c；
+2. correct set 优于 past-shifted、wrong-clip 和 NULL 控制；
+3. 在相同 wearer onset recall 下，third-party false entry/min 下降；
+4. wearer 应接话时的 recall/latency 和 wearer yield 不出现有意义退化；
+5. 三个 seed 方向一致，paired session/event bootstrap 不显示收益完全由单一 session 驱动。
+
+如果只提高逐帧 mAP 而事件指标无变化，则记录为 representation gain，不进入复杂 spatial
+或 track 叙事。若 correct 与错误视觉没有差异，停止增加 attention 层，先审计 crop、
+时间对齐和 person feature。
+
+## 6. F2：加入空间人物交互
+
+只有 F1 通过后才加入：
+
+- 每人的归一化 bbox 几何：中心、宽高和面积；
+- 一层共享 person self-attention；
+- 可选相对几何 bias：dx、dy、宽高比的对数以及中心距离；
+- 再由同一个 G+A floor query 读取增强后的人物集合。
+
+关键对照为 F1、仅绝对 bbox、相对几何 bias 和错误 bbox。只有相对几何版本稳定优于这些
+对照，才可以主张模型利用了多人空间关系；否则保留更简单的 F1。
+
+## 7. F3：匿名 track-temporal 编码
+
+只有空间或 frame-set 证据成立后，才测试跨帧人物连续性：
+
+- 每条在线 track 维护共享参数的 causal GRU 或轻量 TCN；
+- track ID 只用于路由隐状态，不能成为可学习身份；
+- 只有新 2 FPS 帧到达时才更新一次，5 Hz 中间状态只读取最近缓存；
+- track 丢失超过固定 max_age 后重置，所有 reset 规则预先冻结；
+- 全局重命名 track ID 后预测必须不变。
+
+对照包括 frame-set、无 ID temporal pool、正确 track、打断连续性的 track 以及 past-shift。
+正确 track 必须优于无 ID 和打断 track，才能说明身份连续性有价值。
+
+## 8. F4：Person-conditioned audio/Omni history
+
+F4 让每个匿名人物分别读取已有的 5 Hz 因果历史：
+
+    C_A = MHA(H_person, A_history, A_history)
+    C_G = MHA(H_person, G_history, G_history)
+    H_prime = LN(H_person + tanh(alpha_A) C_A + tanh(alpha_G) C_G)
+
+alpha 从 0 初始化，使新分支开始时退化为已验证的人物表示。增强后的 H_prime 再由
+G+A floor query 读取。
+
+这里必须使用一段真实的 5 Hz token history，而不是对单个 pooled audio vector 做形式上
+的 attention。人物级 active-speaker 标签可以作为训练辅助监督，但人物声音标签永远不能
+作为推理输入。
+
+通过条件是 floor event 指标改善，而不只是 active-speaker probe 改善；同时 correct AV
+必须优于 audio-only、visual-only、错位 audio 和错位 visual。
+
+## 9. F5--F6：只在旁路证据充分后增加复杂度
+
+F5 可增加一次 audio query 到人物 memory 的反向读取，形成单块双向 interaction。必须和
+参数匹配 MLP、单向 F4、modality dropout 做比较。若收益不稳定，保留 F4。
+
+F6 才把验证过的人物 memory 通过零初始化 gate 接入 Thinker 上层，并比较：
+
+- 无人物 memory 的参数匹配 Thinker LoRA；
+- 冻结 Thinker 的 person-memory adapter；
+- adapter 加上层 LoRA。
+
+若 F6 不优于旁路，不为追求端到端表述牺牲可解释性，论文采用更简单的旁路模型。
+
+## 10. D1：实际在线检测与追踪
+
+方法验证阶段先使用数据集提供的 bbox/track，隔离融合能力。最终再替换为在线人脸或人物
+检测器加严格因果 tracker，并报告：
+
+- detection recall/coverage；
+- ID switch 和轨迹碎片；
+- max_people 截断比例；
+- P50/P95 单步延迟；
+- provided track 与 online track 的 floor 指标差距。
+
+论文可以把在线 detector/tracker 作为部署前端，但不能把 provided ID 的结果直接称为完整
+在线系统结果。
+
+## 11. 评价和记录规范
+
+P0 冻结后，主指标为：
+
+- third-party false entry/min at matched wearer onset recall，至少报告 R=0.7/0.8/0.9；
+- wearer onset event recall、precision 和 latency；
+- wearer yield event recall、precision 和 latency；
+- addressed-to-wearer recall/latency，仅用于有可靠 addressee 标注的 EasyCom 子集；
+- 0.2--2.0 秒逐帧 AP/mAP，作为 EgoSpeak 可比的次级指标。
+
+每阶段结果放在：
+
+    results/easycom_fusion_fN_<question>_<date>/
+      README.md
+      metrics.json or metrics.csv
+      run configuration and checkpoint references
+
+README 必须写明 split、seed、checkpoint、输入特征版本、评测协议和所有干预条件。最终
+测试集不能反向用于选择 attention 维度、heads、历史长度或 stopping gate。
+
+## 12. 最近执行顺序
+
+1. 完成并测试 P0 competing-risk censoring，人工打印至少一条 response 和 yield 时间轴。
+2. 扩展 local sidecar loader，使其在不破坏现有 pooled 加载路径的情况下返回逐帧人物
+   feature、offset 和 mask；测试成功、失败、空人物和越界路径。
+3. 实现 F1 最小 Frame-set Attention，不加入 bbox 或 track temporal。
+4. 单 session/短片 smoke：检查 shape、cutoff、chosen frame time、mask、空人物和排列
+   不变性。
+5. 在固定 train-internal dev 上运行 B1、B3、F1-a、F1-c、F1-d、F1-e 和 F1-g。
+6. F1 通过后才进入 F2；若未通过，优先审计人物 crop 和 AV 对齐，不继续堆模型。