# Causal EEG–envelope cross-attention

## Envelope-only follow-up (abandoned)

The residual `env_xattn` run below stayed at chance. This follow-up measured the speaker-swap logit, dropped the EEG residual inside `_EnvCrossBlock`, and started one LODO run. It was stopped after 50 steps because the train loss was still 0.6939. No fold was scored. AVGC H, UHD H, and AASD accuracy are unchanged from the residual run.

### Swap test

CPU, seed 0, batch 8, 10 s (320 frames), random EEG and two random envelope streams. The logit is the same antisymmetric head as `DirectNet`: per-window z-score of the speech, linear readout, uniform time pool, `g(EEG, A, B) - g(EEG, B, A)`. Swapping the speakers negates that logit, so the swap-delta is twice the absolute logit.

| Wiring | mean abs logit | mean abs swap-delta |
|---|---:|---:|
| Residual block (the failed run) | 3.275e-2 | 6.550e-2 |
| Envelope attention only (this edit) | 1.207e-1 | 2.413e-1 |

The residual path was not a hard zero (~1e-6). Dropping the skip made the swap-delta about 3.7 times larger. The causal mask is a strict upper triangle: future attention weights are 0 and each row sums to 1. `kv_proj` receives a nonzero CUDA gradient. The head does read the attention output.

Attention at init is the uniform causal distribution. Entropy of the first block is 4.760, against `ln(320) - 1 = 4.768`. Zeroing the EEG changes the envelope-only logit by only 2.645e-2, while swapping the speakers changes it by 2.413e-1. Almost all of the swap signal is a function of the speech and does not use the EEG query. A speech-only antisymmetric logit does not say which speaker the EEG matches, so binary cross-entropy stays at ln 2.

### Code change

`_EnvCrossBlock.forward` in `decoders.py`. The query is still the causal conv of the EEG, and the keys and values are still `env`, `onset`, and `dom` of both speakers. The bool causal mask is unchanged. The block used to return `q + Attn(q, speech)`. It now returns `Attn(q, speech)` plus the position-wise FFN of that attention, with no EEG skip. Prep stays `eaP_n5_t60`, augmentation stays `sw2`.

`direct_classifier.py` stops the process when `ABORT_IF_CHANCE=1` and the first 50 steps of epoch 0 still have mean train loss above 0.689. That check is off unless the variable is set.

### Command

```bash
cd /root/disk_3tb/eeg-thao
export GLIMPSE_THR=norm PYTHONDONTWRITEBYTECODE=1 PYTHONUNBUFFERED=1 OMP_NUM_THREADS=8 MKL_NUM_THREADS=8 ABORT_IF_CHANCE=1
PY=/root/disk_3tb/EEG-sAAD-Grand-Challenge-Training-Dataset/.venv/bin/python
# inside flock on multi_agent_opt/gpu.lock, after the swap test printed above
$PY -u direct_classifier.py --prep eaP_n5_t60 --window-s 10 --backbone env_xattn \
  --min-epochs 4 --max-epochs 4 --train-seed 0 --p-switch 0.5 \
  --aug-set clf_p_switch2=0.5 --tag _w10_env_xattn_envonly_s0
```

Log: `experiments/env_xattn_envonly_run.log`. Held-out AVGC, step 50 train loss 0.6939. Exit 3. No checkpoint and no `results/direct_clf__eaP_n5_t60_w10_env_xattn_envonly_s0.json`. External AASD and Carta were not run.

### Metrics versus the references

`stem_ms96` is the train reference. `linear_hp30` is the external reference. The envelope-only run has no HMM scores. The residual `env_xattn` row is the previous 1000-step run, not a new measurement.

| Set | env_xattn residual H | Acc | envonly H | Acc | stem_ms96 H | Acc | linear_hp30 H | Acc |
|---|---:|---:|---:|---:|---:|---:|---:|---:|
| AVGC | 0.4844 | 51.42 | not scored | | 0.7945 | 74.06 | | |
| DTU | 0.5713 | 49.25 | not scored | | 0.9061 | 89.85 | | |
| KUL | 0.5049 | 48.38 | not scored | | 0.8755 | 82.33 | | |
| UHD | 0.4840 | 50.23 | not scored | | 0.8407 | 79.47 | | |
| USTC | 0.5379 | 49.64 | not scored | | 0.9219 | 86.36 | | |
| mean of 5 | 0.5165 | 49.78 | not scored | | 0.8677 | 82.42 | 0.7899 | 69.21 |
| AASD | 0.6055 | 49.62 | not scored | | 0.6158 | 51.54 | 0.6422 | 53.12 |
| Carta2026 | 0.5183 | 51.44 | not scored | | 0.5695 | 51.03 | 0.6520 | 60.54 |

AVGC H, UHD H, and AASD accuracy did not move.

## Residual run (scored, chance)

One new body, never trained before that run. It does not meet any open target. Train loss stayed at 0.693 and frame accuracy stayed at 0.50, so the network did not leave chance.

Headline HMM is the classifier default `p_stay=0.998`. Emissions are the Gaussian fit on the other LODO folds. AASD and Carta labels were not used to train or to choose `p_stay`.

H is the official harmonic mean as a fraction. Acc is subject-mean sample accuracy in percent after the HMM.

## Code and command

Hook: `EnvCrossAttn` in `decoders.py`, selected by `--backbone env_xattn`. `DirectNet` is unchanged: it still concatenates EEG with the two speakers and forms the antisymmetric logit `g(EEG, A, B) - g(EEG, B, A)`.

Inside the body, a causal conv (kernel 9) of the 58 EEG channels is the query. `env`, `onset`, and `dom` of both speakers are one linear map to keys and values. Two pre-norm blocks (d=96, 4 heads) use a causal mask. A position-wise FFN follows each block.

```bash
cd /root/disk_3tb/eeg-thao
export GLIMPSE_THR=norm PYTHONDONTWRITEBYTECODE=1 PYTHONUNBUFFERED=1 OMP_NUM_THREADS=8 MKL_NUM_THREADS=8
PY=/root/disk_3tb/EEG-sAAD-Grand-Challenge-Training-Dataset/.venv/bin/python
# inside flock on multi_agent_opt/gpu.lock
$PY -u direct_classifier.py --prep eaP_n5_t60 --window-s 10 --backbone env_xattn \
  --min-epochs 4 --max-epochs 4 --train-seed 0 --p-switch 0.5 \
  --aug-set clf_p_switch2=0.5 --tag _w10_env_xattn_s0
$PY -u eval_external_clf.py --seed 0 --window-s 10 --prep eaP_n5_t60 --backbone env_xattn \
  --p-switch 0.5 --aug-set clf_p_switch2=0.5 --min-epochs 4 --set max_epochs=4 \
  --ref direct_clf__eaP_n5_t60_w10_env_xattn_s0 --tag _w10_env_xattn_s0
```

`GLIMPSE_THR=norm` is required: `dom` lives in `glimpsenorm`, and AASD/Carta only have that cache. Four epochs × 250 steps is 1000 steps per fold. Seed 0. Prep `eaP_n5_t60`, augmentation `sw2`. No SparrKULee init.

Log: `experiments/env_xattn_run.log`. Scores: `results/direct_clf__eaP_n5_t60_w10_env_xattn_s0.json`, `results/research/ext_clf_{AASD,Carta2026}_w10_env_xattn_s0_s0.json`.

## Metrics versus the current best

`stem_ms96` is the best train model. `linear_hp30` is the best external readout. Both are unchanged by this run.

| Set | env_xattn H | env_xattn Acc | stem_ms96 H | stem_ms96 Acc | linear_hp30 H | linear_hp30 Acc |
|---|---:|---:|---:|---:|---:|---:|
| AVGC | 0.4844 | 51.42 | 0.7945 | 74.06 | | |
| DTU | 0.5713 | 49.25 | 0.9061 | 89.85 | | |
| KUL | 0.5049 | 48.38 | 0.8755 | 82.33 | | |
| UHD | 0.4840 | 50.23 | 0.8407 | 79.47 | | |
| USTC | 0.5379 | 49.64 | 0.9219 | 86.36 | | |
| mean of 5 | 0.5165 | 49.78 | 0.8677 | 82.42 | 0.7899 | 69.21 |
| AASD | 0.6055 | 49.62 | 0.6158 | 51.54 | 0.6422 | 53.12 |
| Carta2026 | 0.5183 | 51.44 | 0.5695 | 51.03 | 0.6520 | 60.54 |

`linear_hp30` has no per-dataset train table in `CURRENT_BEST.md`; its train mean is the high-pass rescore. External `stem_ms96` numbers are the preset row from the unzipped v2 external CSV.

## Open targets

| Target | env_xattn |
|---|---|
| AVGC H≥0.85 and Acc≥78 | miss (0.4844 / 51.42) |
| UHD H≥0.85 | miss (0.4840; Acc 50.23 also misses 78) |
| DTU, KUL, USTC H≥0.85 and Acc≥78 | miss; all three are at chance |
| Mean of 5, H≥0.85 and Acc≥78 | miss (0.5165 / 49.78) |
| AASD H>0.63 and Acc>60 | miss (0.6055 / 49.62) |
| Carta H>0.63 and Acc>60 | miss (0.5183 / 51.44). The previous best, `linear_hp30`, still holds Carta |

## What the follow-up showed

Dropping the EEG residual was done, in `_EnvCrossBlock`, and then stopped. The swap-delta became healthy, and the train loss on real windows did not. Another 1000 steps of this same block is not justified: with uniform causal attention the antisymmetric logit is almost independent of the EEG, so it cannot name the attended speaker.

## Earlier bodies already scored

`gru_ffn` and `conv_attn` finished before this run. They are not part of the cross-attention result.

`conv_attn` (depthwise GLU kernel 15 inside each self-attention block, full early-stopping schedule): mean H 0.759 Acc 69.27. Per fold H/Acc: AVGC 0.711/65.88, DTU 0.810/72.15, KUL 0.755/69.41, UHD 0.745/69.72, USTC 0.776/69.18. AASD p_stay 0.998: H 0.634 Acc 52.1. Carta: H 0.623 Acc 58.0. `results/direct_clf__eaP_n5_t60_w10_conv_attn_s0.json`.

`gru_ffn`: mean H 0.669 Acc 61.69. AASD H 0.616 Acc 50.7. Carta H 0.582 Acc 53.2. `results/direct_clf__eaP_n5_t60_w10_gru_ffn_s0.json`.
