"""Wrappers around every SuperHugeAAD envelope decoder with one interface.

    dec.fit(train_trials, val_trials, meta)   train on the training datasets only
    dec.features(trial) -> (A, B0, B1)         per-sample arrays; evidence r_s = mean_f corr(A_f, Bs_f) in a window
    dec.lookahead_s                            future data used per output sample (s), for label stamping

Linear decoders use the package classes (update/fit) wherever they run at corpus scale; deviations are noted.
DNNs use the package backbone + the RegressionInterface output head (EinMix -> 1 feature), trained with a
contrastive Pearson loss (-r(attended) + r(ignored)) on 5-s windows.
"""
from __future__ import annotations

import importlib
import math
import time

import numpy as np
import torch
import yaml
from einops.layers.torch import EinMix

from common_exp import CFG, EXP, FS, ROOT

L = CFG["linear"]
D = CFG["dnn"]
DEV = torch.device("cuda" if torch.cuda.is_available() else "cpu")


def _t(x):
    return torch.from_numpy(np.ascontiguousarray(x, dtype=np.float32))


def _targets(tr):
    """(T, 2 streams, F) DNN targets per D['targets']: 'env' = the prep's envelope, 'onset' = half-wave rectified
    first difference of it (causal: t and t-1 only), 'delta'/'theta' = causal band-passed envelope, 'glim'/'mask' =
    causal band-passed envelope where the talker is clearly louder than the other / not (build_glimpse.py)."""
    feats = []
    for f in D.get("targets", ["env"]):
        if f == "env":
            env = tr["env"]
            # Optional causal band-limit on the env target (decoder-sw3 FALLBACK_BAND / --set band_env_hz_lo/hi).
            # Distinct from named delta/theta target features (already tried as speech banks).
            lo, hi = D.get("band_env_hz_lo"), D.get("band_env_hz_hi")
            if lo is not None and hi is not None:
                from scipy.signal import butter, sosfilt
                env = sosfilt(
                    butter(2, [float(lo), float(hi)], "bandpass", fs=FS, output="sos"),
                    env.astype(np.float64), axis=0,
                ).astype(np.float32)
            feats.append(env)
        elif f in ("delta", "theta"):                         # envelope modulation bands, CAUSAL band-pass
            from scipy.signal import butter, sosfilt
            lo, hi = (1.0, 4.0) if f == "delta" else (4.0, 8.0)
            b = sosfilt(butter(2, [lo, hi], "bandpass", fs=FS, output="sos"), tr["env"].astype(np.float64), axis=0)
            feats.append(b.astype(np.float32))                # no trial-level normalisation (see below)
        elif f in ("glim", "mask", "dom", "orel", "odiff", "ediff"):                           # build_glimpse.py: glimpsed / masked part, causal
            feats.append(tr[f])
        elif f == "onset":
            # No full-trial z-score here: the rules exempt the full-trial z-score only ONCE per pipeline (already
            # used on the envelope). Loss and evidence are Pearson correlations per window, which are invariant to a
            # trial-level affine rescaling, so dropping it changes nothing numerically.
            feats.append(np.maximum(0.0, np.diff(tr["env"], axis=0, prepend=tr["env"][:1])))
    return np.stack(feats, -1).astype(np.float32)


def _att_tgt(tr):
    """Attended / ignored DNN targets: (T,) each for one target (unchanged behaviour), (T, F) for several."""
    Y = _targets(tr)
    idx = np.arange(len(Y))
    a = tr["att"].astype(int)[: len(Y)]
    ya, yi = Y[idx, a], Y[idx, 1 - a]
    return (ya[:, 0], yi[:, 0]) if ya.shape[1] == 1 else (ya, yi)


def _att_env(tr):
    idx = np.arange(len(tr["env"]))
    a = tr["att"].astype(int)
    return tr["env"][idx, a], tr["env"][idx, 1 - a]


# =====================================================================================================================
# Linear decoders
# =====================================================================================================================
class BackwardWF:
    """superhuge.model.linear.WienerFilter (Ledoit-Wolf covariance, EEG lags 0-400 ms, as the official baseline)."""
    name = "wf"
    lookahead_s = L["wf_lags"][1]

    def __init__(self, C):
        from superhuge.model.linear import WienerFilter
        self.m = WienerFilter(lags=L["wf_lags"], l2=0.0, use_lwcov=True, fs=FS, window_length=1, num_channels=C)

    def fit(self, train, val, meta):
        for tr in train:
            ya, _ = _att_env(tr)
            self.m.update(_t(tr["eeg"])[None], _t(ya)[None, :, None, None])
        self.m.fit()

    def reconstruct(self, tr):
        with torch.no_grad():
            y, _ = self.m.predict(_t(tr["eeg"])[None], _t(tr["env"])[None, :, None, :])
        return y[0, :, 0].numpy()

    def features(self, tr):
        y = self.reconstruct(tr)
        return y, tr["env"][:, 0], tr["env"][:, 1]


class PerSubjectWF(BackwardWF):
    """superhuge.model.linear.PerSubjectWienerFilter: Rxx estimated per subject, averaged across subjects."""
    name = "wf_persubject"

    def __init__(self, C):
        from superhuge.model.linear import PerSubjectWienerFilter
        self.m = PerSubjectWienerFilter(lags=L["wf_lags"], l2=0.0, use_lwcov=True, fs=FS, window_length=1, num_channels=C)

    def fit(self, train, val, meta):
        for tr, (dsid, sid) in zip(train, meta):
            ya, _ = _att_env(tr)
            self.m.update(_t(tr["eeg"])[None], _t(ya)[None, :, None, None],
                          meta={"dataset_id": torch.tensor([dsid]), "subject_id": torch.tensor([sid])})
        self.m.fit()


class RiemannWF(BackwardWF):
    """Riemannian Wiener filter. DEVIATION: the package class stores one p x p matrix per SAMPLE (infeasible at corpus
    scale), so Rxx = Riemannian (affine-invariant) mean of the per-SUBJECT lagged covariances, rxy = mean over subjects."""
    name = "wf_riemann"

    def __init__(self, C):
        from superhuge.model.linear import WienerFilter
        self.m = WienerFilter(lags=L["wf_lags"], l2=0.0, use_lwcov=False, fs=FS, window_length=1, num_channels=C)

    def fit(self, train, val, meta):
        from pyriemann.geometry.mean import mean_riemann
        stats = {}
        for tr, key in zip(train, meta):
            ya, _ = _att_env(tr)
            X = self.m.lag_and_flatten(_t(tr["eeg"])[None], "batch time lag channel -> (batch time) (lag channel)",
                                       self.m.cfg.lag_start_samples, self.m.cfg.lag_end_samples).double()
            s = stats.setdefault(key, [0, 0, 0])
            s[0] = s[0] + X.T @ X
            s[1] = s[1] + X.T @ _t(ya).double()[:, None]
            s[2] += len(X)
        R = np.array([(v[0] / v[2]).numpy() for v in stats.values()])
        p = R.shape[1]
        R = R + L["l2_rel"] * np.trace(R, axis1=1, axis2=2)[:, None, None] / p * np.eye(p)[None]
        Rm = mean_riemann(torch.from_numpy(R)).numpy()      # torch input: pyriemann 0.12 needs .mT (numpy >= 2)
        r = np.mean([(v[1] / v[2]).numpy() for v in stats.values()], 0)
        self.m.weights = torch.from_numpy(np.linalg.solve(Rm, r)).float()
        self.m._fitted = True


class ForwardWF:
    """superhuge.model.linear.ForwardWienerFilter (encoding model EEG(t) from envelope(t-0.4..t)); fitted with the package
    class. DEVIATION: its predict() has an invalid einops pattern, so predictions are computed from its fitted weights.
    Evidence: mean over channels of corr(EEG, predicted EEG from stream s). Uses no future data."""
    name = "wf_forward"
    lookahead_s = 0.0

    def __init__(self, C):
        from superhuge.model.linear import ForwardWienerFilter
        self.C = C
        self.m = ForwardWienerFilter(lags=L["fwd_lags"], l2=0.0, fs=FS, num_features=1, num_channels=C)

    def fit(self, train, val, meta):
        for tr in train:
            ya, _ = _att_env(tr)
            self.m.update(_t(tr["eeg"])[None], _t(ya)[None, :, None, None])
        # relative ridge instead of the absolute l2 (the statistics are sums over millions of samples)
        n = self.m._n_samples
        Rxx, Rxy = self.m.Rxx / n, self.m.Rxy / n
        p = Rxx.shape[0]
        Rxx = Rxx + L["l2_rel"] * torch.trace(Rxx) / p * torch.eye(p)
        self.W = torch.linalg.solve(Rxx, Rxy)                     # (lag*1, C)

    def features(self, tr):
        out = []
        for s in (0, 1):
            e = _t(tr["env"][:, s])[None, :, None]
            X = self.m.lag_and_flatten(e, "batch time lag channel -> (batch time) (lag channel)",
                                       self.m.cfg.lag_start_samples, self.m.cfg.lag_end_samples)
            out.append((X @ self.W).numpy())
        return tr["eeg"], out[0], out[1]


class CCADec:
    """superhuge.model.linear.CCA: lagged EEG (0-400 ms) vs lagged envelope (-250..0 ms), 3 components.
    Evidence: mean over components of corr(EEG projection, envelope projection of stream s)."""
    name = "cca"
    lookahead_s = L["cca_x_lags"][1]

    def __init__(self, C):
        from superhuge.model.linear import CCA
        self.m = CCA(x_lags=L["cca_x_lags"], y_lags=L["cca_y_lags"], l2=0.0, num_components=L["cca_components"],
                     fs=FS, num_channels=C, num_audio_features={"env": 1})

    def fit(self, train, val, meta):
        for tr in train:
            ya, _ = _att_env(tr)
            self.m.update(_t(tr["eeg"])[None], _t(ya)[None, :, None, None])
        self.m.fit()

    def features(self, tr):
        with torch.no_grad():
            xp, yp = self.m.predict(_t(tr["eeg"])[None], _t(tr["env"])[None, :, None, :])
        return xp[0].numpy(), yp[0, :, :, 0].numpy(), yp[0, :, :, 1].numpy()


class FBCCADec:
    """superhuge.model.linear.FilterbankCCA: FIR filter bank (lengths 2-32 samples) on EEG and envelope, 3 components.
    Its conv uses padding='same' (non-causal): lookahead = half the longest filter = 0.5 s.
    DEVIATION: fit() re-implemented around the package solver because update() never counts samples (fit -> NaN)."""
    name = "fbcca"
    lookahead_s = (max(L["fbcca_ir_lengths"]) // 2) / FS

    def __init__(self, C):
        from superhuge.model.linear import FilterbankCCA
        self.m = FilterbankCCA(fs=FS, impulse_response_lengths=L["fbcca_ir_lengths"], num_components=L["fbcca_components"],
                               num_channels=C, num_audio_features={"env": 1})

    def fit(self, train, val, meta):
        from superhuge.model.linear.regression.fb_cca import canonical_correlation_analysis
        n = 0
        for tr in train:
            ya, _ = _att_env(tr)
            self.m.update(_t(tr["eeg"])[None], _t(ya)[None, :, None, None])
            n += len(ya)
        # PACKAGE BUG: FilterbankCCA.update() never increments _n_samples, so its fit() divides by 0 (NaN covariance).
        # Same CCA solver on the correctly normalised covariance (float64, tiny relative ridge).
        cov = (self.m.Rxyxy / n).double()
        p = cov.shape[0]
        cov = cov + 1e-6 * torch.trace(cov) / p * torch.eye(p, dtype=cov.dtype)
        wx, wy = canonical_correlation_analysis(cov_matrix=cov, num_features_x=self.m.cfg.num_channels * len(L["fbcca_ir_lengths"]),
                                                reg_strength=1e-5, num_components=self.m.cfg.num_components)
        self.m.weight_x, self.m.weight_y = wx.float(), wy.float()
        self.m._fitted = True

    def features(self, tr):
        with torch.no_grad():
            out = []
            for s in (0, 1):
                xp, yp = self.m.predict(_t(tr["eeg"])[None], _t(tr["env"][:, s])[None, :, None, None])
                out.append(yp.numpy())
        return xp.numpy(), out[0], out[1]


# =====================================================================================================================
# DNN decoders
# =====================================================================================================================
MODEL_CFG = f"{ROOT}/baselines/python/SuperHugeAAD/train/configs/models/"


class VLAAIwsPatched(torch.nn.Module):
    """VLAAI_ws with a minimal fix. The package class raises NameError ('_' undefined) because a weight-shared block
    cannot take num_channels inputs in block 1 and num_kernels[-1] afterwards. Fix: 1x1 input projection
    C -> num_kernels[-1], then the shared block from the package."""

    def __init__(self, *, nb_blocks, extractor_args, output_context_kernel_size, use_skip=True, dropout=0.0, **kw):
        super().__init__()
        from superhuge.model.pure_cnn.vlaai import vlaai_block
        k = extractor_args.num_kernels[-1]
        self.proj = torch.nn.Conv1d(kw["num_channels"], k, 1)
        self.block = vlaai_block(num_kernels=extractor_args.num_kernels, kernel_sizes=extractor_args.kernel_sizes,
                                 output_context_kernel_size=output_context_kernel_size, num_channels=k,
                                 time_dim=kw["fs"] * kw["window_length"], drouput=dropout)
        self.nb_blocks, self.use_skip = nb_blocks, use_skip

    def forward(self, x):
        x = self.proj(x.transpose(1, 2))
        h = x
        for i in range(self.nb_blocks):
            if self.use_skip and i > 0:
                h = h + x
            h = self.block(h)
        return h.transpose(1, 2)


MODEL_OVERRIDES = {}   # name -> dict of model_args overriding the package yaml (debug / ablations); empty by default


class ADT(torch.nn.Module):
    """ADT-style decoder (auditory decoding transformer; Xu et al. 2024, PMC11489951), re-implemented:
    spatio-temporal convolution front-end, learned positional embedding, transformer layers whose attention is
    ANTICAUSAL-BANDED: output time t attends only to EEG times t .. t + resp (the brain responds AFTER the sound),
    resp = 0.5 s. The causal read-out of DNNDec still limits every output to <= 0.75 s of future EEG."""

    def __init__(self, C, W, d=64, heads=4, layers=2, ff=128, dropout=0.1, resp_s=0.5):
        super().__init__()
        self.front = torch.nn.Sequential(
            torch.nn.Conv1d(C, d, 9, padding=4), torch.nn.GELU(), torch.nn.Dropout(dropout),
            torch.nn.Conv1d(d, d, 9, padding=4), torch.nn.GELU())
        self.pos = torch.nn.Parameter(torch.zeros(1, W, d))
        layer = torch.nn.TransformerEncoderLayer(d, heads, ff, dropout, batch_first=True, norm_first=True)
        self.enc = torch.nn.TransformerEncoder(layer, layers)
        t = torch.arange(W)
        r = int(resp_s * FS)
        allowed = (t[None, :] >= t[:, None]) & (t[None, :] <= t[:, None] + r)   # query t -> keys t..t+r
        self.register_buffer("mask", ~allowed)                                   # True = masked

    def forward(self, x):                                       # (B, W, C) -> (B, W, d)
        h = self.front(x.transpose(1, 2)).transpose(1, 2) + self.pos[:, : x.shape[1]]
        return self.enc(h, mask=self.mask[: x.shape[1], : x.shape[1]])


class _PreLNFFTBlock(torch.nn.Module):
    """FastSpeech feed-forward transformer block with pre-layer normalisation (HappyQuokka): x + MHA(LN(x)), then
    x + Conv1d(k1) -> ReLU -> Conv1d(k2) of LN(x); dropout on both residual branches."""

    def __init__(self, d, d_inner, heads, kernels, dropout):
        super().__init__()
        self.ln1, self.ln2 = torch.nn.LayerNorm(d), torch.nn.LayerNorm(d)
        self.att = torch.nn.MultiheadAttention(d, heads, dropout=0.1, batch_first=True)
        self.w1 = torch.nn.Conv1d(d, d_inner, kernels[0], padding=kernels[0] // 2)
        self.w2 = torch.nn.Conv1d(d_inner, d, kernels[1], padding=kernels[1] // 2)
        self.drop = torch.nn.Dropout(dropout)

    def forward(self, x):
        h = self.ln1(x)
        x = x + self.drop(self.att(h, h, h, need_weights=False)[0])
        h = self.ln2(x).transpose(1, 2)
        return x + self.drop(self.w2(torch.relu(self.w1(h))).transpose(1, 2))


class _GRUGatedFFN(torch.nn.Module):
    """Position-wise FFN whose residual is a GRU update gate.

    The candidate output projection and the gate weights start at zero and the
    gate bias at -2, so each block starts as attention only. The gate has to
    open before the FFN can change the residual stream.
    """

    def __init__(self, d, mult=2, dropout=0.1):
        super().__init__()
        self.fc1 = torch.nn.Linear(d, mult * d)
        self.fc2 = torch.nn.Linear(mult * d, d)
        self.gate = torch.nn.Linear(d, d)
        self.drop = torch.nn.Dropout(dropout)
        torch.nn.init.zeros_(self.fc2.weight)
        torch.nn.init.zeros_(self.fc2.bias)
        torch.nn.init.zeros_(self.gate.weight)
        torch.nn.init.constant_(self.gate.bias, -2.0)

    def forward(self, x):
        cand = self.drop(self.fc2(torch.nn.functional.gelu(self.fc1(x))))
        return torch.sigmoid(self.gate(x)) * cand


class _GRUFFNBlock(torch.nn.Module):
    """Pre-norm self-attention, then a GRU-gated FFN.

    Attention is over the classifier window only. That window already ends at
    the 0.75 s causal limit used by DirectNet, the same budget as ADT.
    """

    def __init__(self, d, heads, dropout):
        super().__init__()
        self.ln1 = torch.nn.LayerNorm(d)
        self.att = torch.nn.MultiheadAttention(d, heads, dropout=dropout, batch_first=True)
        self.ln2 = torch.nn.LayerNorm(d)
        self.ff = _GRUGatedFFN(d, dropout=dropout)
        self.drop = torch.nn.Dropout(dropout)

    def forward(self, x):
        h = self.ln1(x)
        x = x + self.drop(self.att(h, h, h, need_weights=False)[0])
        return x + self.ff(self.ln2(x))


class GRUFFNTransformer(torch.nn.Module):
    """EEG backbone: linear channel embed, learned positions, GRU-gated blocks.

    This is the direct-classifier body. It is not the logit-stream encoder, not
    ADT's anticausal band, and not HappyQuokka's convolutional FFN.
    """

    def __init__(self, C, W, d=96, heads=4, layers=2, dropout=0.1):
        super().__init__()
        if d % heads != 0:
            raise ValueError(f"d={d} not divisible by heads={heads}")
        self.proj = torch.nn.Linear(C, d)
        self.pos = torch.nn.Parameter(torch.zeros(1, W, d))
        torch.nn.init.normal_(self.pos, std=0.02)
        self.blocks = torch.nn.ModuleList([_GRUFFNBlock(d, heads, dropout) for _ in range(layers)])
        self.ln = torch.nn.LayerNorm(d)

    def forward(self, x):                                       # (B, W, C) -> (B, W, d)
        h = self.proj(x) + self.pos[:, : x.shape[1]]
        for block in self.blocks:
            h = block(h)
        return self.ln(h)


class HappyQuokka(torch.nn.Module):
    """HappyQuokka (Piao et al., ICASSP 2023 Auditory EEG Challenge, regression winner; official code
    github.com/jkyunnng/HappyQuokka_system_for_EEG_Challenge): pre-conv (kernel 7) -> 8 pre-LN FFT blocks
    (d_model 128, d_inner 1024, 2 heads, FFN conv kernels (9, 1), dropout 0.3) -> linear (the Net head here).
    No positional encoding (as the original). DEVIATIONS: no subject global conditioner (LODO subjects are unseen;
    subject IDs may not be inputs); trained with this benchmark's losses (contrastive / Pearson) instead of
    -Pearson + 0.2 L1; full attention inside the window, the causal read-out of DNNDec keeps <= 0.75 s future."""

    def __init__(self, C, d=128, d_inner=1024, heads=2, layers=8, kernels=(9, 1), dropout=0.3):
        super().__init__()
        self.pre = torch.nn.Conv1d(C, d, 7, padding=3)
        self.blocks = torch.nn.ModuleList([_PreLNFFTBlock(d, d_inner, heads, kernels, dropout) for _ in range(layers)])

    def forward(self, x):                                       # (B, W, C) -> (B, W, d)
        h = self.pre(x.transpose(1, 2)).transpose(1, 2)
        for b in self.blocks:
            h = b(h)
        return h


class _DepthwiseConvModule(torch.nn.Module):
    """Conformer convolution module: pointwise GLU, depthwise temporal conv, pointwise out.

    Kernel 15 is about 0.5 s at 32 Hz. Padding keeps the window length. This sits
    inside the block, after attention, and is not the dilated stem used in front
    of the logit transformer.
    """

    def __init__(self, d, k=15, dropout=0.1):
        super().__init__()
        if k % 2 == 0:
            raise ValueError("conv kernel must be odd so the window length stays put")
        self.pw1 = torch.nn.Linear(d, 2 * d)
        self.dw = torch.nn.Conv1d(d, d, k, padding=k // 2, groups=d)
        self.norm = torch.nn.BatchNorm1d(d)
        self.pw2 = torch.nn.Linear(d, d)
        self.drop = torch.nn.Dropout(dropout)

    def forward(self, x):
        a, b = self.pw1(x).chunk(2, dim=-1)
        h = (a * torch.sigmoid(b)).transpose(1, 2)
        h = torch.nn.functional.silu(self.norm(self.dw(h))).transpose(1, 2)
        return self.drop(self.pw2(h))


class _ConvAttnBlock(torch.nn.Module):
    """Pre-norm attention, depthwise temporal conv, then a position-wise FFN."""

    def __init__(self, d, heads, dropout):
        super().__init__()
        self.ln1 = torch.nn.LayerNorm(d)
        self.att = torch.nn.MultiheadAttention(d, heads, dropout=dropout, batch_first=True)
        self.ln2 = torch.nn.LayerNorm(d)
        self.conv = _DepthwiseConvModule(d, dropout=dropout)
        self.ln3 = torch.nn.LayerNorm(d)
        self.ff = torch.nn.Sequential(
            torch.nn.Linear(d, 2 * d), torch.nn.GELU(), torch.nn.Dropout(dropout),
            torch.nn.Linear(2 * d, d))
        self.drop = torch.nn.Dropout(dropout)

    def forward(self, x):
        h = self.ln1(x)
        x = x + self.drop(self.att(h, h, h, need_weights=False)[0])
        x = x + self.conv(self.ln2(x))
        return x + self.drop(self.ff(self.ln3(x)))


class ConvAttnTransformer(torch.nn.Module):
    """EEG backbone with a depthwise-conv module inside each transformer block.

    Same width as gru_ffn (d=96, 4 heads, 2 layers) so the comparison is the
    block. Not HappyQuokka (that FFN is two convolutions and there is no
    depthwise GLU module) and not the logit-stream dilated stem.
    """

    def __init__(self, C, W, d=96, heads=4, layers=2, dropout=0.1):
        super().__init__()
        if d % heads != 0:
            raise ValueError(f"d={d} not divisible by heads={heads}")
        self.proj = torch.nn.Linear(C, d)
        self.pos = torch.nn.Parameter(torch.zeros(1, W, d))
        torch.nn.init.normal_(self.pos, std=0.02)
        self.blocks = torch.nn.ModuleList([_ConvAttnBlock(d, heads, dropout) for _ in range(layers)])
        self.ln = torch.nn.LayerNorm(d)

    def forward(self, x):                                       # (B, W, C) -> (B, W, d)
        h = self.proj(x) + self.pos[:, : x.shape[1]]
        for block in self.blocks:
            h = block(h)
        return self.ln(h)


class _PreNormTFBlock(torch.nn.Module):
    """Plain pre-norm Transformer block: MHSA then position-wise FFN.

    No GRU gate (gru_ffn), no depthwise GLU (conv_attn / Conformer), no Macaron
    half-FFN. Dense residual stream for DirectNet temporal pooling.
    """

    def __init__(self, d, heads, dropout, ffn_mult=4):
        super().__init__()
        self.ln1 = torch.nn.LayerNorm(d)
        self.att = torch.nn.MultiheadAttention(d, heads, dropout=dropout, batch_first=True)
        self.ln2 = torch.nn.LayerNorm(d)
        hid = int(ffn_mult * d)
        self.ff = torch.nn.Sequential(
            torch.nn.Linear(d, hid), torch.nn.GELU(), torch.nn.Dropout(dropout),
            torch.nn.Linear(hid, d))
        self.drop = torch.nn.Dropout(dropout)

    def forward(self, x, mask=None):
        h = self.ln1(x)
        x = x + self.drop(self.att(h, h, h, attn_mask=mask, need_weights=False)[0])
        return x + self.drop(self.ff(self.ln2(x)))


class DirectTransformer(torch.nn.Module):
    """Causal patched Transformer as DirectNet body (ALREADY_TRIED §C1 open slot).

    Causal Conv1d patch embed over EEG + speech (env/onset/dom of both streams,
    same channel-concat as vlaai_ws), then L× pre-norm MHSA+FFN with a strict
    upper-triangle causal mask → dense (B, W, d) for the DirectNet temporal
    head. Random-init shapes ≠ vlaai; not a warm start. Distinct from gru_ffn /
    conv_attn / EEG Conformer / ATCNet / HappyQuokka / ADT / WaveNet / Mamba.
    """

    def __init__(self, C, W, d=64, heads=4, layers=4, patch_k=15, ffn_mult=4,
                 dropout=0.2, causal=True):
        super().__init__()
        if d % heads != 0:
            raise ValueError(f"d={d} not divisible by heads={heads}")
        if patch_k < 1:
            raise ValueError("patch_k must be >= 1")
        self.patch = _CausalConv1d(C, d, patch_k)
        self.patch_gn = torch.nn.GroupNorm(min(8, d), d)
        self.pos = torch.nn.Parameter(torch.zeros(1, W, d))
        torch.nn.init.normal_(self.pos, std=0.02)
        self.drop = torch.nn.Dropout(dropout)
        self.blocks = torch.nn.ModuleList([
            _PreNormTFBlock(d, heads, dropout, ffn_mult=ffn_mult) for _ in range(layers)])
        self.ln = torch.nn.LayerNorm(d)
        self.causal = bool(causal)
        if self.causal:
            # True = future key blocked (PyTorch bool attn_mask).
            self.register_buffer(
                "causal_mask", torch.triu(torch.ones(W, W, dtype=torch.bool), diagonal=1))

    def forward(self, x):                                       # (B, W, C) -> (B, W, d)
        t = x.shape[1]
        h = self.patch(x)                                       # (B, W, d), causal pad
        h = self.drop(torch.nn.functional.gelu(
            self.patch_gn(h.transpose(1, 2)))).transpose(1, 2)
        h = h + self.pos[:, :t]
        mask = self.causal_mask[:t, :t] if self.causal else None
        for block in self.blocks:
            h = block(h, mask)
        return self.ln(h)


class _CausalConv1d(torch.nn.Module):
    """Left-padded Conv1d. Output at t uses inputs at t-k+1..t only."""

    def __init__(self, cin, cout, k):
        super().__init__()
        self.k = k
        self.conv = torch.nn.Conv1d(cin, cout, k)

    def forward(self, x):                                       # (B, W, C) -> (B, W, cout)
        h = torch.nn.functional.pad(x.transpose(1, 2), (self.k - 1, 0))
        return self.conv(h).transpose(1, 2)


class _EnvCrossBlock(torch.nn.Module):
    """Pre-norm causal cross-attention (EEG query, speech key/value) plus a position-wise FFN."""

    def __init__(self, d, heads, dropout):
        super().__init__()
        self.ln_q = torch.nn.LayerNorm(d)
        self.ln_kv = torch.nn.LayerNorm(d)
        self.att = torch.nn.MultiheadAttention(d, heads, dropout=dropout, batch_first=True)
        self.ln_ff = torch.nn.LayerNorm(d)
        self.ff = torch.nn.Sequential(
            torch.nn.Linear(d, 2 * d), torch.nn.GELU(), torch.nn.Dropout(dropout),
            torch.nn.Linear(2 * d, d))
        self.drop = torch.nn.Dropout(dropout)

    def forward(self, q, kv, mask):
        h, m = self.ln_q(q), self.ln_kv(kv)
        # No EEG residual. q is the same tensor in both speaker orders, so
        # q + Attn cancels in the antisymmetric logit and the envelope term
        # that remains is too small to leave chance. The block output is the
        # causal attention over the envelopes (plus its position-wise FFN).
        attn = self.drop(self.att(h, m, m, attn_mask=mask, need_weights=False)[0])
        return attn + self.drop(self.ff(self.ln_ff(attn)))


class EnvCrossAttn(torch.nn.Module):
    """Direct-classifier body: causal EEG queries attend to both speakers' envelopes.

    DirectNet concatenates (EEG, stream A, stream B) on the channel axis and keeps
    the antisymmetric logit g(EEG, A, B) - g(EEG, B, A). This module splits that
    tensor: a causal convolution of the EEG is the query, and env/onset/dom of the
    two speakers are the keys and values. The mask blocks every future frame.
    The attention block does not add the EEG query back, so the linear head reads
    the envelope attention rather than a residual that cancels across speaker order.
    Not a logit remixer, not gru_ffn self-attention, and not conv_attn.
    """

    def __init__(self, C, W, n_eeg=58, d=96, heads=4, layers=2, dropout=0.1, k=9):
        super().__init__()
        if d % heads != 0:
            raise ValueError(f"d={d} not divisible by heads={heads}")
        n_speech = C - n_eeg
        if n_speech < 2 or n_speech % 2:
            raise ValueError(f"expected EEG plus an even speech width, got C={C} n_eeg={n_eeg}")
        self.n_eeg = n_eeg
        self.q_conv = _CausalConv1d(n_eeg, d, k)
        self.kv_proj = torch.nn.Linear(n_speech, d)
        self.pos = torch.nn.Parameter(torch.zeros(1, W, d))
        torch.nn.init.normal_(self.pos, std=0.02)
        self.blocks = torch.nn.ModuleList([_EnvCrossBlock(d, heads, dropout) for _ in range(layers)])
        self.ln = torch.nn.LayerNorm(d)
        # True marks a future key. PyTorch treats a bool attn_mask as "do not attend".
        self.register_buffer("causal", torch.triu(torch.ones(W, W, dtype=torch.bool), diagonal=1))

    def forward(self, x):                                       # (B, W, C) -> (B, W, d)
        eeg, speech = x[..., :self.n_eeg], x[..., self.n_eeg:]
        t = eeg.shape[1]
        q = self.q_conv(eeg) + self.pos[:, :t]
        kv = self.kv_proj(speech)
        mask = self.causal[:t, :t]
        for block in self.blocks:
            q = block(q, kv, mask)
        return self.ln(q)


class _ATCNetTCNBlock(torch.nn.Module):
    """Dilated causal TCN residual used inside ATCNet (Altaheri et al.)."""

    def __init__(self, channels, kernel, dilation, dropout):
        super().__init__()
        self.pad = (kernel - 1) * dilation
        self.conv = torch.nn.Conv1d(channels, channels, kernel, dilation=dilation, padding=self.pad)
        self.bn = torch.nn.GroupNorm(8, channels)
        self.drop = torch.nn.Dropout(dropout)

    def forward(self, x):                                       # (B, C, T) -> (B, C, T)
        h = self.conv(x)
        if self.pad:
            h = h[..., : -self.pad]
        return x + self.drop(torch.nn.functional.elu(self.bn(h)))


class ATCNet(torch.nn.Module):
    """ATCNet (Altaheri et al., 2022) as a dense DirectNet backbone.

    Paper stack: temporal conv front → multi-head self-attention → TCN residuals.
    The MI EEGNet Conv2d+electrode-collapse front left the antisymmetric auditory
    logit at chance (smoke 100 steps); a Conv1d front at full time resolution
    learns (same smoke). Still ATCNet blocks, adapted to (B, W, C)→(B, W, d)
    with C = EEG+speech. Not vlaai_ws / ADT / Conformer / EEG-TCNet.
    """

    def __init__(self, C, W, F1=64, depth_mult=1, kern_length=64, pool=1,
                 n_heads=4, tcn_filters=64, tcn_depth=2, tcn_kernel=4,
                 dropout=0.2, d_out=64):
        super().__init__()
        d = int(F1 * depth_mult)
        self.front = torch.nn.Conv1d(C, d, kern_length, padding=kern_length // 2, bias=False)
        self.front_gn = torch.nn.GroupNorm(8, d)
        self.drop = torch.nn.Dropout(dropout)
        self.attn = torch.nn.MultiheadAttention(d, n_heads, dropout=dropout, batch_first=True)
        self.attn_ln = torch.nn.LayerNorm(d)
        self.tcn_in = torch.nn.Conv1d(d, tcn_filters, 1)
        self.tcn = torch.nn.ModuleList([
            _ATCNetTCNBlock(tcn_filters, tcn_kernel, dilation=2 ** i, dropout=dropout)
            for i in range(tcn_depth)])
        self.out = torch.nn.Linear(tcn_filters, d_out)
        self.out_ln = torch.nn.LayerNorm(d_out)

    def forward(self, x):                                       # (B, W, C) -> (B, W, d)
        t = x.shape[1]
        h = self.drop(torch.nn.functional.elu(
            self.front_gn(self.front(x.transpose(1, 2)))[..., :t])).transpose(1, 2)
        a = self.attn_ln(h)
        h = h + self.attn(a, a, a, need_weights=False)[0]
        h = self.tcn_in(h.transpose(1, 2))
        for block in self.tcn:
            h = block(h)
        return self.out_ln(self.out(h.transpose(1, 2)))


class _ConformerBlock(torch.nn.Module):
    """Macaron Conformer block: ½FFN → MHSA → depthwise conv → ½FFN (Song/Gulati)."""

    def __init__(self, d, heads, dropout, conv_k=15):
        super().__init__()
        self.ff1_ln = torch.nn.LayerNorm(d)
        self.ff1 = torch.nn.Sequential(
            torch.nn.Linear(d, 2 * d), torch.nn.GELU(), torch.nn.Dropout(dropout),
            torch.nn.Linear(2 * d, d), torch.nn.Dropout(dropout))
        self.attn_ln = torch.nn.LayerNorm(d)
        self.attn = torch.nn.MultiheadAttention(d, heads, dropout=dropout, batch_first=True)
        self.attn_drop = torch.nn.Dropout(dropout)
        self.conv_ln = torch.nn.LayerNorm(d)
        self.conv = _DepthwiseConvModule(d, k=conv_k, dropout=dropout)
        self.ff2_ln = torch.nn.LayerNorm(d)
        self.ff2 = torch.nn.Sequential(
            torch.nn.Linear(d, 2 * d), torch.nn.GELU(), torch.nn.Dropout(dropout),
            torch.nn.Linear(2 * d, d), torch.nn.Dropout(dropout))
        self.out_ln = torch.nn.LayerNorm(d)

    def forward(self, x):
        x = x + 0.5 * self.ff1(self.ff1_ln(x))
        h = self.attn_ln(x)
        x = x + self.attn_drop(self.attn(h, h, h, need_weights=False)[0])
        x = x + self.conv(self.conv_ln(x))
        x = x + 0.5 * self.ff2(self.ff2_ln(x))
        return self.out_ln(x)


class EEGConformer(torch.nn.Module):
    """EEG Conformer (Song et al., 2022) as a dense DirectNet backbone.

    Patch embedding is a temporal Conv1d over channel-concatenated EEG+speech
    (C = 58+2F). No MI-style electrode-collapse: that front left ATCNet at chance
    under antisymmetric speaker-order training. Conformer encoder blocks follow
    Macaron ½FFN→MHSA→depthwise-conv→½FFN. Output stays at full window length
    for the DirectNet temporal head. Not vlaai_ws / ATCNet / conv_attn / EEG-TCNet.
    """

    def __init__(self, C, W, d=64, heads=4, layers=4, patch_k=25, conv_k=15, dropout=0.2):
        super().__init__()
        if d % heads != 0:
            raise ValueError(f"d={d} not divisible by heads={heads}")
        if patch_k % 2 == 0:
            raise ValueError("patch_k must be odd to keep window length")
        self.patch = torch.nn.Conv1d(C, d, patch_k, padding=patch_k // 2, bias=False)
        self.patch_gn = torch.nn.GroupNorm(8, d)
        self.drop = torch.nn.Dropout(dropout)
        self.pos = torch.nn.Parameter(torch.zeros(1, W, d))
        torch.nn.init.normal_(self.pos, std=0.02)
        self.blocks = torch.nn.ModuleList([
            _ConformerBlock(d, heads, dropout, conv_k=conv_k) for _ in range(layers)])
        self.ln = torch.nn.LayerNorm(d)

    def forward(self, x):                                       # (B, W, C) -> (B, W, d)
        t = x.shape[1]
        h = self.drop(torch.nn.functional.elu(
            self.patch_gn(self.patch(x.transpose(1, 2)))[..., :t])).transpose(1, 2)
        h = h + self.pos[:, :t]
        for block in self.blocks:
            h = block(h)
        return self.ln(h)


class EEGTCNet(torch.nn.Module):
    """EEG-TCNet (Ingolfsson et al., 2020) as a dense DirectNet backbone.

    Paper stack: compact EEGNet-style front + TCN residuals (no self-attention;
    ATCNet adds MHSA). MI EEGNet Conv2d+electrode-collapse stayed at chance under
    antisymmetric auditory training (ATCNet smoke); use Conv1d front at full time
    resolution then dilated causal TCN. Output (B, W, d) for the DirectNet head.
    Not vlaai_ws / ATCNet / Conformer.
    """

    def __init__(self, C, W, F1=64, kern_length=64, tcn_filters=64, tcn_depth=3,
                 tcn_kernel=4, dropout=0.2, d_out=64):
        super().__init__()
        self.front = torch.nn.Conv1d(C, F1, kern_length, padding=kern_length // 2, bias=False)
        self.front_gn = torch.nn.GroupNorm(8, F1)
        self.drop = torch.nn.Dropout(dropout)
        self.tcn_in = torch.nn.Conv1d(F1, tcn_filters, 1)
        self.tcn = torch.nn.ModuleList([
            _ATCNetTCNBlock(tcn_filters, tcn_kernel, dilation=2 ** i, dropout=dropout)
            for i in range(tcn_depth)])
        self.out = torch.nn.Linear(tcn_filters, d_out)
        self.out_ln = torch.nn.LayerNorm(d_out)

    def forward(self, x):                                       # (B, W, C) -> (B, W, d)
        t = x.shape[1]
        h = self.drop(torch.nn.functional.elu(
            self.front_gn(self.front(x.transpose(1, 2)))[..., :t]))
        h = self.tcn_in(h)
        for block in self.tcn:
            h = block(h)
        return self.out_ln(self.out(h.transpose(1, 2)))


def _gn_groups(f):
    for g in (8, 5, 4, 2, 1):
        if f % g == 0:
            return g
    return 1


class TSception(torch.nn.Module):
    """TSception (Ding et al.) as a dense DirectNet backbone.

    Multi-scale temporal inception: parallel Conv1d kernels at ~0.5/0.25/0.125 s
    (Ding et al. TNSRE), concatenated → BN/LeakyReLU → local AvgPool (stride 1).
    Spatial/channel inception: parallel pointwise mixers (full + bottleneck).
    Two T→S stages → dense (B, W, d) for the antisymmetric DirectNet head.
    No electrode-collapse, no stride>1 pool (MI fronts stayed at chance).
    Distinct from ATCNet / Conformer / Shallow / Deep / WaveNet / EEG-TCNet /
    Mamba / vlaai / FIR-fb / Morlet residual→vlaai.
    """

    def __init__(self, C, W, F1=32, scales_s=(0.5, 0.25, 0.125),
                 pool=8, dropout=0.5, d_out=64):
        super().__init__()
        kerns = tuple(max(3, int(round(float(s) * FS))) for s in scales_s)
        self.kerns = kerns
        n_sc = len(kerns)
        # T-inception 1: multi-scale temporal on EEG+speech concat
        self.t1 = torch.nn.ModuleList([
            torch.nn.Conv1d(C, F1, k, padding=k // 2, bias=False) for k in kerns])
        cin_t1 = F1 * n_sc
        self.bn_t1 = torch.nn.GroupNorm(_gn_groups(cin_t1), cin_t1)
        self.pool1 = torch.nn.AvgPool1d(pool, stride=1, padding=pool // 2)
        # S-inception 1: full mix + half-width bottleneck, concat
        self.s1_full = torch.nn.Conv1d(cin_t1, F1, 1, bias=False)
        self.s1_half = torch.nn.Conv1d(cin_t1, F1, 1, bias=False)
        cin_s1 = 2 * F1
        self.bn_s1 = torch.nn.GroupNorm(_gn_groups(cin_s1), cin_s1)
        # T-inception 2
        self.t2 = torch.nn.ModuleList([
            torch.nn.Conv1d(cin_s1, F1, k, padding=k // 2, bias=False) for k in kerns])
        cin_t2 = F1 * n_sc
        self.bn_t2 = torch.nn.GroupNorm(_gn_groups(cin_t2), cin_t2)
        self.pool2 = torch.nn.AvgPool1d(pool, stride=1, padding=pool // 2)
        # S-inception 2
        self.s2_full = torch.nn.Conv1d(cin_t2, F1, 1, bias=False)
        self.s2_half = torch.nn.Conv1d(cin_t2, F1, 1, bias=False)
        cin_s2 = 2 * F1
        self.bn_s2 = torch.nn.GroupNorm(_gn_groups(cin_s2), cin_s2)
        self.act = torch.nn.LeakyReLU(0.2, inplace=True)
        self.drop = torch.nn.Dropout(dropout)
        self.out = torch.nn.Linear(cin_s2, d_out)
        self.out_ln = torch.nn.LayerNorm(d_out)

    def _tception(self, h, branches, bn, pool, t):
        parts = [b(h)[..., :t] for b in branches]
        z = torch.cat(parts, dim=1)
        z = self.act(bn(z))
        return pool(z)[..., :t]

    def _sception(self, h, full, half, bn, t):
        z = torch.cat([full(h), half(h)], dim=1)[..., :t]
        return self.act(bn(z))

    def forward(self, x):                                       # (B, W, C) -> (B, W, d)
        t = x.shape[1]
        h = x.transpose(1, 2)
        h = self._tception(h, self.t1, self.bn_t1, self.pool1, t)
        h = self._sception(h, self.s1_full, self.s1_half, self.bn_s1, t)
        h = self._tception(h, self.t2, self.bn_t2, self.pool2, t)
        h = self._sception(h, self.s2_full, self.s2_half, self.bn_s2, t)
        h = self.drop(h).transpose(1, 2)
        return self.out_ln(self.out(h))


class ShallowConvNet(torch.nn.Module):
    """ShallowConvNet (Schirrmeister et al., 2017) as a dense DirectNet backbone.

    Classic: temporal conv → square → local average pool → log → dense.
    MI Conv2d+electrode-collapse fronts left ATCNet/EEGNet at chance under
    antisymmetric auditory training; keep Conv1d at full time resolution over
    channel-concatenated EEG+speech (C=58+2F). Pool stride 1 preserves W for
    the DirectNet temporal head. Not vlaai_ws / ATCNet / Conformer / EEG-TCNet.
    """

    def __init__(self, C, W, n_filters=40, kern=25, pool=75, dropout=0.5, d_out=64):
        super().__init__()
        if kern % 2 == 0:
            raise ValueError("kern must be odd to keep window length")
        self.temp = torch.nn.Conv1d(C, n_filters, kern, padding=kern // 2, bias=False)
        self.bn = torch.nn.GroupNorm(8, n_filters)
        # Local mean pool with same length (classic shallow uses stride>1 collapse).
        self.pool = torch.nn.AvgPool1d(pool, stride=1, padding=pool // 2)
        self.drop = torch.nn.Dropout(dropout)
        self.out = torch.nn.Linear(n_filters, d_out)
        self.out_ln = torch.nn.LayerNorm(d_out)

    def forward(self, x):                                       # (B, W, C) -> (B, W, d)
        t = x.shape[1]
        h = self.bn(self.temp(x.transpose(1, 2)))[..., :t]
        h = h * h                                               # square nonlinearity
        h = self.pool(h)[..., :t]
        h = torch.log(torch.clamp(h, min=1e-6))
        h = self.drop(h).transpose(1, 2)
        return self.out_ln(self.out(h))


class DeepConvNet(torch.nn.Module):
    """DeepConvNet (Schirrmeister et al., 2017) as a dense DirectNet backbone.

    Classic: stacked temporal conv blocks with ELU + max-pool + dropout.
    Dense adaptation: Conv1d blocks at full time resolution (no electrode collapse;
    max-pool stride 1). Filter schedule 25→50→100→200. Output (B, W, d).
    Not ShallowConvNet / ATCNet / EEG-TCNet / vlaai_ws.
    """

    def __init__(self, C, W, filters=(25, 50, 100, 200), kern=10, pool=3,
                 dropout=0.5, d_out=64):
        super().__init__()
        def _gn_groups(f):
            for g in (8, 5, 4, 2, 1):
                if f % g == 0:
                    return g
            return 1

        self.blocks = torch.nn.ModuleList()
        c_in = C
        for i, f in enumerate(filters):
            block = [
                torch.nn.Conv1d(c_in, f, kern, padding=kern // 2, bias=False),
                torch.nn.GroupNorm(_gn_groups(f), f),
                torch.nn.ELU(),
            ]
            if i < len(filters) - 1:
                block += [
                    torch.nn.MaxPool1d(pool, stride=1, padding=pool // 2),
                    torch.nn.Dropout(dropout),
                ]
            self.blocks.append(torch.nn.ModuleList(block))
            c_in = f
        self.drop = torch.nn.Dropout(dropout)
        self.out = torch.nn.Linear(filters[-1], d_out)
        self.out_ln = torch.nn.LayerNorm(d_out)

    def forward(self, x):                                       # (B, W, C) -> (B, W, d)
        t = x.shape[1]
        h = x.transpose(1, 2)
        for block in self.blocks:
            for layer in block:
                h = layer(h)
                if isinstance(layer, (torch.nn.Conv1d, torch.nn.MaxPool1d)):
                    h = h[..., :t]
        h = self.drop(h).transpose(1, 2)
        return self.out_ln(self.out(h))


class EEGNet(torch.nn.Module):
    """Lawhern EEGNet (2018) as a dense DirectNet backbone.

    Classic stack: temporal Conv2d → depthwise spatial Conv over channels →
    separable temporal (depthwise + pointwise) → dense features.
    Dense adaptations for antisymmetric auditory DirectNet (ATCNet MI front
    with electrode-collapse + aggressive pool stayed at chance):
      - no AvgPool stride>1 (keep full window length W)
      - trim convolutions to W; Linear F2→d_out per time step → (B, W, d)
    Input C = EEG+speech (58+2F). Spatial depthwise spans all C (speech
    participates in the spatial mix). Not ATCNet / Conformer / Shallow /
    DeepConvNet / EEG-TCNet / vlaai_ws.
    """

    def __init__(self, C, W, F1=16, D=2, F2=None, kern=64, sep_kern=16,
                 dropout=0.5, d_out=64):
        super().__init__()
        F2 = int(F2) if F2 is not None else int(F1 * D)
        self.C, self.F1, self.D, self.F2 = C, F1, D, F2
        # (B, 1, C, T) temporal filters shared across channels
        self.temp = torch.nn.Conv2d(1, F1, (1, kern), padding=(0, kern // 2), bias=False)
        self.bn1 = torch.nn.BatchNorm2d(F1)
        # Depthwise spatial: each of F1 maps → D spatial filters spanning C
        self.spatial = torch.nn.Conv2d(F1, F1 * D, (C, 1), groups=F1, bias=False)
        self.bn2 = torch.nn.BatchNorm2d(F1 * D)
        # Separable temporal: depthwise then pointwise (Lawhern)
        self.sep_dw = torch.nn.Conv2d(
            F1 * D, F1 * D, (1, sep_kern), padding=(0, sep_kern // 2),
            groups=F1 * D, bias=False)
        self.sep_pw = torch.nn.Conv2d(F1 * D, F2, (1, 1), bias=False)
        self.bn3 = torch.nn.BatchNorm2d(F2)
        self.drop = torch.nn.Dropout(dropout)
        self.out = torch.nn.Linear(F2, d_out)
        self.out_ln = torch.nn.LayerNorm(d_out)

    def forward(self, x):                                       # (B, W, C) -> (B, W, d)
        t = x.shape[1]
        h = x.transpose(1, 2).unsqueeze(1)                      # (B, 1, C, T)
        h = torch.nn.functional.elu(self.bn1(self.temp(h)[..., :t]))
        h = torch.nn.functional.elu(self.bn2(self.spatial(h)))  # (B, F1*D, 1, T)
        h = self.drop(h)
        h = self.sep_dw(h)[..., :t]
        h = torch.nn.functional.elu(self.bn3(self.sep_pw(h)))
        h = self.drop(h)
        h = h.squeeze(2).transpose(1, 2)                        # (B, T, F2)
        return self.out_ln(self.out(h))


class _WaveNetBlock(torch.nn.Module):
    """Gated dilated causal residual (WaveNet; van den Oord et al., 2016).

    filter=tanh(W_f * x), gate=σ(W_g * x); residual + skip. Left-pad only so
    output length equals input (dense DirectNet temporal head).
    """

    def __init__(self, channels, kernel, dilation, dropout):
        super().__init__()
        self.pad = (kernel - 1) * dilation
        self.filter = torch.nn.Conv1d(
            channels, channels, kernel, dilation=dilation, padding=self.pad)
        self.gate = torch.nn.Conv1d(
            channels, channels, kernel, dilation=dilation, padding=self.pad)
        self.res = torch.nn.Conv1d(channels, channels, 1)
        self.skip = torch.nn.Conv1d(channels, channels, 1)
        self.drop = torch.nn.Dropout(dropout)

    def forward(self, x):                                       # (B, C, T) -> (B, C, T), skip
        h_f = self.filter(x)
        h_g = self.gate(x)
        if self.pad:
            h_f = h_f[..., : -self.pad]
            h_g = h_g[..., : -self.pad]
        z = torch.tanh(h_f) * torch.sigmoid(h_g)
        z = self.drop(z)
        return x + self.res(z), self.skip(z)


class WaveNet(torch.nn.Module):
    """Causal WaveNet (gated dilated residual stacks) as a dense DirectNet backbone.

    Dilations 1,2,4,...,64 (one cycle by default). Classic tanh⊗σ gates + residual
    and skip paths; no electrode-collapse, no stride>1 pooling — output stays
    (B, W, d) for the antisymmetric temporal head.
    Distinct from EEG-TCNet (ELU TCN, dilations ≤4), ATCNet (MHSA+TCN), and
    Conformer / Shallow / Deep / EEGNet / vlaai_ws.
    """

    def __init__(self, C, W, channels=64, kernel=3, dilations=(1, 2, 4, 8, 16, 32, 64),
                 cycles=1, dropout=0.2, d_out=64):
        super().__init__()
        if kernel < 2:
            raise ValueError("WaveNet kernel must be >= 2")
        self.start = torch.nn.Conv1d(C, channels, 1)
        self.blocks = torch.nn.ModuleList()
        for _ in range(int(cycles)):
            for d in dilations:
                self.blocks.append(_WaveNetBlock(channels, kernel, int(d), dropout))
        self.post = torch.nn.Sequential(
            torch.nn.ReLU(),
            torch.nn.Conv1d(channels, channels, 1),
            torch.nn.ReLU(),
            torch.nn.Dropout(dropout),
        )
        self.out = torch.nn.Linear(channels, d_out)
        self.out_ln = torch.nn.LayerNorm(d_out)

    def forward(self, x):                                       # (B, W, C) -> (B, W, d)
        h = self.start(x.transpose(1, 2))
        skips = 0
        for block in self.blocks:
            h, s = block(h)
            skips = skips + s
        h = self.post(skips)
        return self.out_ln(self.out(h.transpose(1, 2)))


class _MambaBlock(torch.nn.Module):
    """Pre-norm residual Mamba (mamba_ssm) + optional tiny FFN."""

    def __init__(self, d, d_state=16, d_conv=4, expand=2, dropout=0.2, ffn_mult=2):
        super().__init__()
        from mamba_ssm import Mamba
        self.ln1 = torch.nn.LayerNorm(d)
        self.mamba = Mamba(d_model=d, d_state=d_state, d_conv=d_conv, expand=expand)
        self.drop1 = torch.nn.Dropout(dropout)
        self.ln2 = torch.nn.LayerNorm(d)
        hid = int(d * ffn_mult)
        self.ffn = torch.nn.Sequential(
            torch.nn.Linear(d, hid),
            torch.nn.GELU(),
            torch.nn.Dropout(dropout),
            torch.nn.Linear(hid, d),
        )
        self.drop2 = torch.nn.Dropout(dropout)

    def forward(self, x):                                       # (B, T, d) -> (B, T, d)
        x = x + self.drop1(self.mamba(self.ln1(x)))
        x = x + self.drop2(self.ffn(self.ln2(x)))
        return x


class MambaDirect(torch.nn.Module):
    """Mamba SSM stack as a dense DirectNet backbone (classifier body).

    Channel-concat EEG+speech → linear project → N pre-norm Mamba(+FFN) blocks →
    dense (B, W, d). Uses installed `mamba_ssm` (not decoder-only SuperHuge SSMamba,
    which needs subject IDs / mel reconstruction heads). Distinct from WaveNet /
    ATCNet / Conformer / EEG-TCNet / Shallow / Deep / EEGNet / vlaai_ws.
    """

    def __init__(self, C, W, d=64, layers=4, d_state=16, d_conv=4, expand=2,
                 dropout=0.2, d_out=64, ffn_mult=2):
        super().__init__()
        self.in_proj = torch.nn.Linear(C, d)
        self.blocks = torch.nn.ModuleList([
            _MambaBlock(d, d_state=d_state, d_conv=d_conv, expand=expand,
                        dropout=dropout, ffn_mult=ffn_mult)
            for _ in range(int(layers))])
        self.out_ln = torch.nn.LayerNorm(d)
        self.out = torch.nn.Linear(d, d_out) if d != d_out else torch.nn.Identity()
        if d != d_out:
            self.final_ln = torch.nn.LayerNorm(d_out)
        else:
            self.final_ln = torch.nn.Identity()

    def forward(self, x):                                       # (B, W, C) -> (B, W, d)
        h = self.in_proj(x)
        for block in self.blocks:
            h = block(h)
        h = self.out_ln(h)
        return self.final_ln(self.out(h))


class XCorrMatched(torch.nn.Module):
    """Causal multi-lag EEG↔envelope cross-correlation DirectNet backbone.

    Input (B, W, n_eeg + 2·Fs) = concat(EEG, stream-A feats, stream-B feats).
    g matches EEG to the *first* stream's envelope (DirectNet antisymmetry then
    yields match(A)−match(B)). Pipeline:
      1. Linear spatial compress EEG → n_comp (default 16; "PCA-16" slot)
      2. Instantaneous products EEG[t]·env[t−τ] for τ=0..max_lag (~0..250 ms)
      3. Causal local average (smooth) over ~smooth_ms
      4. 1–2 causal temporal Conv1d blocks → dense (B, W, d_out)

    Not vlaai / ATCNet / Conformer / EEGNet / Shallow / Deep / WaveNet / Mamba /
    TFDirect / SE / graph / channel-mask / FIR-fb.
    """

    def __init__(self, C, W, n_eeg=58, n_comp=16, max_lag_ms=250, smooth_ms=250,
                 cnn_channels=64, cnn_blocks=2, cnn_kern=9, dropout=0.2, d_out=64,
                 light_init=True):
        super().__init__()
        if C <= n_eeg:
            raise ValueError(f"XCorrMatched C={C} needs n_eeg={n_eeg} + 2·Fs speech")
        n_speech = C - n_eeg
        if n_speech % 2 != 0:
            raise ValueError(f"XCorrMatched speech width {n_speech} not even (2 streams)")
        self.n_eeg = int(n_eeg)
        self.Fs = n_speech // 2
        self.n_comp = int(n_comp)
        max_lag = max(0, int(round(float(max_lag_ms) * FS / 1000.0)))
        self.n_lags = max_lag + 1
        smooth = max(1, int(round(float(smooth_ms) * FS / 1000.0)))
        if smooth % 2 == 0:
            smooth += 1
        self.smooth_k = smooth
        self.smooth_pad = smooth - 1  # causal left pad
        if cnn_kern % 2 == 0:
            raise ValueError("cnn_kern must be odd")
        self.cnn_pad = cnn_kern - 1
        self.proj = torch.nn.Linear(self.n_eeg, self.n_comp, bias=False)
        # Depthwise causal smoother over (n_comp * n_lags) feature maps
        self.smooth = torch.nn.Conv1d(
            self.n_comp * self.n_lags, self.n_comp * self.n_lags, smooth,
            groups=self.n_comp * self.n_lags, bias=False)
        with torch.no_grad():
            self.smooth.weight.fill_(1.0 / float(smooth))
        self.smooth.weight.requires_grad_(False)
        feat_ch = self.n_comp * self.n_lags
        blocks = []
        c_in = feat_ch
        n_blocks = max(1, int(cnn_blocks))
        for i in range(n_blocks):
            c_out = int(cnn_channels)
            blocks.append(torch.nn.Conv1d(c_in, c_out, cnn_kern, bias=False))
            g = 8 if c_out % 8 == 0 else (4 if c_out % 4 == 0 else 1)
            blocks.append(torch.nn.GroupNorm(g, c_out))
            blocks.append(torch.nn.GELU())
            if dropout > 0:
                blocks.append(torch.nn.Dropout(dropout))
            c_in = c_out
        self.cnn = torch.nn.ModuleList(blocks)
        self.out = torch.nn.Linear(c_in, d_out)
        self.out_ln = torch.nn.LayerNorm(d_out)
        if light_init:
            # Small random init so early logits stay near 0 but gradients flow.
            torch.nn.init.normal_(self.proj.weight, std=0.02)
            for m in self.cnn:
                if isinstance(m, torch.nn.Conv1d):
                    torch.nn.init.normal_(m.weight, std=0.02)
            torch.nn.init.normal_(self.out.weight, std=0.02)
            torch.nn.init.zeros_(self.out.bias)

    def _lagged_env(self, env):
        """env (B, W) → (B, W, n_lags) with causal delays τ=0..n_lags-1."""
        parts = [env]
        for tau in range(1, self.n_lags):
            parts.append(torch.nn.functional.pad(env[:, :-tau], (tau, 0)))
        return torch.stack(parts, dim=-1)

    def forward(self, x):                                       # (B, W, C) -> (B, W, d)
        B, T, _ = x.shape
        eeg = x[..., :self.n_eeg]
        # First stream after EEG is the candidate attended (DirectNet order)
        env = x[..., self.n_eeg]                                # envelope = feature 0 of stream A
        e = self.proj(eeg)                                      # (B, T, n_comp)
        env_lags = self._lagged_env(env)                        # (B, T, n_lags)
        # Instantaneous multi-lag products → (B, T, n_comp * n_lags)
        xc = e.unsqueeze(-1) * env_lags.unsqueeze(2)
        xc = xc.reshape(B, T, self.n_comp * self.n_lags).transpose(1, 2)
        xc = torch.nn.functional.pad(xc, (self.smooth_pad, 0))
        h = self.smooth(xc)[..., :T]
        for layer in self.cnn:
            if isinstance(layer, torch.nn.Conv1d):
                h = torch.nn.functional.pad(h, (self.cnn_pad, 0))
                h = layer(h)[..., :T]
            else:
                h = layer(h)
        h = h.transpose(1, 2)
        return self.out_ln(self.out(h))


class FBExtraVLAAI(torch.nn.Module):
    """Causal EEG filterbank residual → vlaai_ws (Path B for eegnet-seed).

    Input is standard (B,W,58+2F). In-network FIR approx of order-2 Butterworth
    banks 1–3/3–5/5–7/7–9 Hz (depthwise Conv1d, causal pad). Zero-init mix:
    eeg = raw + mix(banks) so training starts as plain vlaai_ws. Avoids C=290
    trial expansion that OOM'd; distinct from filterbank-only C=232 (chance).
    """

    BANDS = ((1.0, 3.0), (3.0, 5.0), (5.0, 7.0), (7.0, 9.0))

    def __init__(self, C, W, n_raw=58, n_bands=4, fir_taps=65):
        super().__init__()
        if n_bands != len(self.BANDS):
            raise ValueError(f"n_bands={n_bands} != {len(self.BANDS)}")
        if fir_taps % 2 == 0:
            raise ValueError("fir_taps must be odd")
        n_speech = C - n_raw
        if n_speech < 0:
            raise ValueError(f"FBExtraVLAAI C={C} < n_raw={n_raw}")
        self.n_raw = n_raw
        self.fir_taps = fir_taps
        self.pad = fir_taps - 1  # causal
        # Depthwise FIR: one filter per (band, channel)
        self.fir = torch.nn.Conv1d(
            n_raw * n_bands, n_raw * n_bands, fir_taps,
            groups=n_raw * n_bands, bias=False)
        with torch.no_grad():
            from scipy.signal import butter, firwin
            w = torch.zeros_like(self.fir.weight)
            for bi, (lo, hi) in enumerate(self.BANDS):
                # firwin bandpass; causal by left-padding zeros in forward
                taps = firwin(fir_taps, [lo, hi], pass_zero=False, fs=float(FS))
                taps = torch.tensor(taps[::-1].copy(), dtype=w.dtype)  # conv correlation
                for c in range(n_raw):
                    w[bi * n_raw + c, 0, :] = taps
            self.fir.weight.copy_(w)
        self.fir.weight.requires_grad_(False)
        self.mix = torch.nn.Conv1d(n_raw * n_bands, n_raw, 1, bias=True)
        torch.nn.init.zeros_(self.mix.weight)
        torch.nn.init.zeros_(self.mix.bias)
        from superhuge.model.pure_cnn import ExtractorParams
        common = dict(fs=FS, window_length=int(W / FS), num_channels=n_raw + n_speech,
                      num_audio_features={"env": 1})
        self.bb = VLAAIwsPatched(
            nb_blocks=int(D.get("model_blocks", 3)),
            extractor_args=ExtractorParams(
                kernel_sizes=[3, 7, 11, 15],
                num_kernels=[int(D.get("model_kernels", 64))],
                num_layers=3),
            output_context_kernel_size=17,
            dropout=D.get("model_dropout", 0.0),
            **common)

    def forward(self, x):                                       # (B, W, 58+2F)
        raw, sp = x[..., :self.n_raw], x[..., self.n_raw:]
        # Repeat EEG for each band, apply depthwise FIR with causal pad
        B, T, _ = raw.shape
        h = raw.transpose(1, 2)                                 # (B, 58, T)
        h = h.repeat(1, len(self.BANDS), 1)                     # (B, 58*4, T)
        h = torch.nn.functional.pad(h, (self.pad, 0))
        banks = self.fir(h)[..., :T]                            # (B, 232, T)
        delta = self.mix(banks).transpose(1, 2)                 # (B, T, 58)
        e = raw + delta
        y = self.bb(torch.cat([e, sp], -1))
        return y[0] if isinstance(y, (tuple, list)) else y


def _complex_morlet_taps(n_taps: int, f0: float, fs: float, n_cycles: float = 5.0):
    """Unit-energy complex Morlet (real, imag) for causal FIR approx of CWT.

    Centered support; caller left-pads for causality. Distinct from Butterworth
    FIR banks in FBExtraVLAAI.
    """
    if n_taps % 2 == 0:
        raise ValueError("n_taps must be odd")
    half = n_taps // 2
    t = np.arange(-half, half + 1, dtype=np.float64) / float(fs)
    sigma_t = n_cycles / (2.0 * math.pi * f0)
    gauss = np.exp(-0.5 * (t / sigma_t) ** 2)
    # π^{-1/4} Gaussian × complex exponential (Torrence & Compo / classic Morlet)
    psi = (math.pi ** -0.25) * gauss * np.exp(1j * 2.0 * math.pi * f0 * t)
    psi = psi - np.mean(psi)  # near-admissible (zero mean)
    psi = psi / (np.sqrt(np.sum(np.abs(psi) ** 2)) + 1e-12)
    return psi.real.astype(np.float32), psi.imag.astype(np.float32)


class WaveletFBExtraVLAAI(torch.nn.Module):
    """Causal complex-Morlet (CWT-approx) multi-scale bank residual → vlaai_ws.

    Frozen depthwise FIR taps = real+imag Morlet at center freqs
    {1.5, 3.0, 5.0, 7.5} Hz (n_cycles≈5). Zero-init 1×1 mix:
        eeg = raw + mix(banks)
    so step-0 ≡ plain vlaai_ws (SPK remaps into bb.bb.*). NOT Butterworth
    1–3/3–5/5–7/7–9 FIR (`fb_vlaai`).
    """

    # Speech-band scales (Hz); wavelet shape, not Butterworth cutoffs.
    F0_HZ = (1.5, 3.0, 5.0, 7.5)
    N_CYCLES = 5.0

    def __init__(self, C, W, n_raw=58, n_scales=4, fir_taps=97, n_cycles=None):
        super().__init__()
        if n_scales != len(self.F0_HZ):
            raise ValueError(f"n_scales={n_scales} != {len(self.F0_HZ)}")
        if fir_taps % 2 == 0:
            raise ValueError("fir_taps must be odd")
        n_speech = C - n_raw
        if n_speech < 0:
            raise ValueError(f"WaveletFBExtraVLAAI C={C} < n_raw={n_raw}")
        self.n_raw = n_raw
        self.n_scales = n_scales
        self.n_parts = 2  # real + imag
        self.n_banks = n_scales * self.n_parts
        self.fir_taps = fir_taps
        self.pad = fir_taps - 1
        n_cyc = float(self.N_CYCLES if n_cycles is None else n_cycles)
        n_dw = n_raw * self.n_banks
        self.fir = torch.nn.Conv1d(
            n_dw, n_dw, fir_taps, groups=n_dw, bias=False)
        with torch.no_grad():
            w = torch.zeros_like(self.fir.weight)
            for si, f0 in enumerate(self.F0_HZ):
                re, im = _complex_morlet_taps(fir_taps, f0, FS, n_cycles=n_cyc)
                # Conv1d correlates; reverse taps like FBExtraVLAAI.
                re_t = torch.from_numpy(re[::-1].copy())
                im_t = torch.from_numpy(im[::-1].copy())
                for c in range(n_raw):
                    # bank layout: [s0_re_c0..c57, s0_im_c0..c57, s1_re..., ...]
                    w[si * 2 * n_raw + c, 0, :] = re_t
                    w[si * 2 * n_raw + n_raw + c, 0, :] = im_t
            self.fir.weight.copy_(w)
        self.fir.weight.requires_grad_(False)
        self.mix = torch.nn.Conv1d(n_dw, n_raw, 1, bias=True)
        torch.nn.init.zeros_(self.mix.weight)
        torch.nn.init.zeros_(self.mix.bias)
        from superhuge.model.pure_cnn import ExtractorParams
        common = dict(fs=FS, window_length=int(W / FS), num_channels=n_raw + n_speech,
                      num_audio_features={"env": 1})
        self.bb = VLAAIwsPatched(
            nb_blocks=int(D.get("model_blocks", 3)),
            extractor_args=ExtractorParams(
                kernel_sizes=[3, 7, 11, 15],
                num_kernels=[int(D.get("model_kernels", 64))],
                num_layers=3),
            output_context_kernel_size=17,
            dropout=D.get("model_dropout", 0.0),
            **common)

    def forward(self, x):                                       # (B, W, 58+2F)
        raw, sp = x[..., :self.n_raw], x[..., self.n_raw:]
        B, T, _ = raw.shape
        h = raw.transpose(1, 2)                                 # (B, 58, T)
        h = h.repeat(1, self.n_banks, 1)                        # (B, 58*8, T)
        h = torch.nn.functional.pad(h, (self.pad, 0))
        banks = self.fir(h)[..., :T]                            # (B, 464, T)
        delta = self.mix(banks).transpose(1, 2)                 # (B, T, 58)
        e = raw + delta
        y = self.bb(torch.cat([e, sp], -1))
        return y[0] if isinstance(y, (tuple, list)) else y


class SpeechResidVLAAI(torch.nn.Module):
    """Zero-init residual FiLM on speech (env/onset/dom) only → vlaai_ws.

    EEG channels are never modified (identity path). Speech path:
      h = GELU(depthwise causal Conv1d(sp))
      gamma, beta = zero-init pointwise Conv1d(h)  → (2 · n_speech)
      sp' = sp * (1 + gamma) + beta
    At step 0: gamma=beta=0 ⇒ sp'=sp ⇒ forward ≡ plain vlaai_ws (SPK remaps
    into ``bb.bb.*``). Distinct from FIR/Morlet/FBCNet EEG banks and from
    stem_ms96 speech-AdaLN (LayerNorm FiLM on logit stem).
    """

    def __init__(self, C, W, n_raw=58, speech_kern=65, speech_hid=None):
        super().__init__()
        if speech_kern % 2 == 0:
            raise ValueError("speech_kern must be odd")
        n_speech = C - n_raw
        if n_speech <= 0:
            raise ValueError(f"SpeechResidVLAAI C={C} <= n_raw={n_raw}")
        self.n_raw = n_raw
        self.n_speech = n_speech
        self.speech_kern = int(speech_kern)
        self.pad = self.speech_kern - 1
        hid = int(speech_hid) if speech_hid is not None else n_speech
        # Depthwise temporal context on speech only (learnable).
        self.dw = torch.nn.Conv1d(
            n_speech, n_speech, self.speech_kern, groups=n_speech, bias=True)
        torch.nn.init.kaiming_uniform_(self.dw.weight, a=math.sqrt(5))
        torch.nn.init.zeros_(self.dw.bias)
        self.pw = torch.nn.Conv1d(n_speech, hid, 1, bias=True)
        torch.nn.init.kaiming_uniform_(self.pw.weight, a=math.sqrt(5))
        torch.nn.init.zeros_(self.pw.bias)
        # Zero-init FiLM readout → identity residual at step 0.
        self.film = torch.nn.Conv1d(hid, 2 * n_speech, 1, bias=True)
        torch.nn.init.zeros_(self.film.weight)
        torch.nn.init.zeros_(self.film.bias)
        from superhuge.model.pure_cnn import ExtractorParams
        common = dict(fs=FS, window_length=int(W / FS), num_channels=n_raw + n_speech,
                      num_audio_features={"env": 1})
        self.bb = VLAAIwsPatched(
            nb_blocks=int(D.get("model_blocks", 3)),
            extractor_args=ExtractorParams(
                kernel_sizes=[3, 7, 11, 15],
                num_kernels=[int(D.get("model_kernels", 64))],
                num_layers=3),
            output_context_kernel_size=17,
            dropout=D.get("model_dropout", 0.0),
            **common)

    def forward(self, x):                                       # (B, W, 58+2F)
        raw, sp = x[..., :self.n_raw], x[..., self.n_raw:]
        # Speech FiLM residual; EEG untouched.
        h = sp.transpose(1, 2)                                  # (B, Fs*2, T)
        h = torch.nn.functional.pad(h, (self.pad, 0))
        h = torch.nn.functional.gelu(self.dw(h)[..., :sp.shape[1]])
        h = torch.nn.functional.gelu(self.pw(h))
        gb = self.film(h)                                       # (B, 2Fs, T)
        gamma, beta = gb.chunk(2, dim=1)
        sp2 = sp * (1.0 + gamma.transpose(1, 2)) + beta.transpose(1, 2)
        y = self.bb(torch.cat([raw, sp2], -1))
        return y[0] if isinstance(y, (tuple, list)) else y


class TRFPathBVLAAI(torch.nn.Module):
    """Frozen speech-envelope TRF as gated additive side features → vlaai_ws (Path B).

    Train-only ridge TRF ``env(t)≈Σ_τ EEG(t+τ)·W_τ`` is frozen as a buffer. Inside
    the window we reconstruct ``ŷ``, build per-frame TRF↔speech correlation-proxy
    features (ŷ, ŷ·env0, ŷ·env1, causal-EWMA of products), project them onto the
    speech channel axis, and add with a **learned gate initialized nonzero**
    (default 0.25) — deliberately **not** identity@0.

    Distinct from:
      * speech-resid-spk — FiLM with **zero-init** γ/β (identity@0)
      * Path A TRF / band/dual/dss — frozen lag-bank scores as HMM emissions alone
      * trf-sw2-fuse — post-hoc soft/hard blend of Path A evidence ↔ Acc tip
    """

    N_SIDE = 5  # ŷ, ŷe0, ŷe1, ewma(ŷe0), ewma(ŷe1)

    def __init__(self, C, W, n_raw=58, max_lag=None, gate0=0.25):
        super().__init__()
        n_speech = C - n_raw
        if n_speech <= 0:
            raise ValueError(f"TRFPathBVLAAI C={C} <= n_raw={n_raw}")
        self.n_raw = int(n_raw)
        self.n_speech = int(n_speech)
        self.F = n_speech // 2  # per-stream speech features (env/onset/dom → 3)
        if self.F * 2 != n_speech:
            raise ValueError(f"n_speech={n_speech} not even (two streams)")
        L = int(max_lag) if max_lag is not None else int(round(0.4 * FS))  # 400 ms @ FS
        self.max_lag = L
        # Frozen TRF bank (L+1, C_eeg); start as zeros until set_trf_weights.
        self.register_buffer("trf_W", torch.zeros(L + 1, n_raw), persistent=True)
        self.register_buffer("trf_ready", torch.tensor(False), persistent=True)
        # Gate init ≠ 0 → Path B injection active at step 0 (≠ speech-resid identity).
        self.gate = torch.nn.Parameter(torch.tensor(float(gate0)))
        self.proj = torch.nn.Conv1d(self.N_SIDE, n_speech, 1, bias=True)
        torch.nn.init.xavier_uniform_(self.proj.weight)
        torch.nn.init.zeros_(self.proj.bias)
        from superhuge.model.pure_cnn import ExtractorParams
        common = dict(fs=FS, window_length=int(W / FS), num_channels=n_raw + n_speech,
                      num_audio_features={"env": 1})
        self.bb = VLAAIwsPatched(
            nb_blocks=int(D.get("model_blocks", 3)),
            extractor_args=ExtractorParams(
                kernel_sizes=[3, 7, 11, 15],
                num_kernels=[int(D.get("model_kernels", 64))],
                num_layers=3),
            output_context_kernel_size=17,
            dropout=D.get("model_dropout", 0.0),
            **common)

    def set_trf_weights(self, W):
        """Load frozen train-only TRF weights; W shape (n_lags, C_eeg)."""
        W = np.asarray(W, np.float32)
        if W.ndim != 2 or W.shape[1] != self.n_raw:
            raise ValueError(f"TRF W shape {W.shape} expected (*, {self.n_raw})")
        L = W.shape[0] - 1
        if L + 1 != self.trf_W.shape[0]:
            self.register_buffer(
                "trf_W",
                torch.zeros(L + 1, self.n_raw, device=self.trf_W.device, dtype=self.trf_W.dtype),
                persistent=True)
            self.max_lag = L
        with torch.no_grad():
            self.trf_W.copy_(torch.from_numpy(W).to(self.trf_W.device, self.trf_W.dtype))
            self.trf_ready.fill_(True)

    def _trf_predict(self, eeg):
        """ŷ(t)=Σ_τ EEG(t+τ)·W_τ with zero future-pad (B,T,C) → (B,T)."""
        B, T, _C = eeg.shape
        L = self.trf_W.shape[0] - 1
        # Unfold future-lagged EEG: (B, T, L+1, C)
        xp = torch.nn.functional.pad(eeg.transpose(1, 2), (0, L))  # (B,C,T+L)
        # gather slices via as_strided-free stack
        parts = [xp[:, :, τ:τ + T].transpose(1, 2) for τ in range(L + 1)]  # each (B,T,C)
        stacked = torch.stack(parts, dim=2)  # (B,T,L+1,C)
        return torch.einsum("btlc,lc->bt", stacked, self.trf_W)

    @staticmethod
    def _causal_cummean(x):
        """Running mean along time; x (B,T) → (B,T)."""
        cs = torch.cumsum(x, dim=1)
        t = torch.arange(1, x.shape[1] + 1, device=x.device, dtype=x.dtype)
        return cs / t.unsqueeze(0)

    def forward(self, x):                                       # (B, W, 58+2F)
        raw, sp = x[..., :self.n_raw], x[..., self.n_raw:]
        # Speech envs = first feature of each stream (DirectNet order A then B).
        env0 = sp[..., 0]
        env1 = sp[..., self.F]
        if bool(self.trf_ready.item()):
            yhat = self._trf_predict(raw)
        else:
            yhat = raw.new_zeros(raw.shape[0], raw.shape[1])
        # Per-window z-score ŷ for scale stability across trials.
        mu = yhat.mean(dim=1, keepdim=True)
        sd = yhat.std(dim=1, keepdim=True).clamp_min(1e-4)
        yz = (yhat - mu) / sd
        ye0 = yz * env0
        ye1 = yz * env1
        side = torch.stack(
            [yz, ye0, ye1, self._causal_cummean(ye0), self._causal_cummean(ye1)],
            dim=1)                                              # (B,5,T)
        delta = self.proj(side).transpose(1, 2)                 # (B, T, n_speech)
        sp2 = sp + self.gate * delta
        y = self.bb(torch.cat([raw, sp2], -1))
        return y[0] if isinstance(y, (tuple, list)) else y


class TempAttnVLAAI(torch.nn.Module):
    """Zero-init causal temporal MHSA residual AFTER SPK-init vlaai_ws blocks.

    EEG+speech concat goes through plain ``VLAAIwsPatched`` (SPK remaps into
    ``bb.bb.*``). Then one pre-norm causal MHSA residual on the temporal feature
    map ``(B, T, K)``:

      h = bb(x)
      h' = h + drop(out_proj(MHSA(LN(h))))

    ``MultiheadAttention.out_proj`` is zero-init ⇒ residual ≡ 0 at step 0 ⇒
    forward ≡ plain vlaai_ws. Distinct from speech FiLM (SpeechResidVLAAI),
    SE/graph/channel-mask, Conformer full replace, FIR/Morlet/FBCNet banks,
    and stem ALiBi/RoPE.
    """

    def __init__(self, C, W, n_raw=58, heads=4, dropout=0.0, attn_dropout=0.0):
        super().__init__()
        n_speech = C - n_raw
        if n_speech < 0:
            raise ValueError(f"TempAttnVLAAI C={C} < n_raw={n_raw}")
        self.n_raw = n_raw
        self.n_speech = n_speech
        from superhuge.model.pure_cnn import ExtractorParams
        k = int(D.get("model_kernels", 64))
        common = dict(fs=FS, window_length=int(W / FS), num_channels=n_raw + n_speech,
                      num_audio_features={"env": 1})
        self.bb = VLAAIwsPatched(
            nb_blocks=int(D.get("model_blocks", 3)),
            extractor_args=ExtractorParams(
                kernel_sizes=[3, 7, 11, 15],
                num_kernels=[k],
                num_layers=3),
            output_context_kernel_size=17,
            dropout=D.get("model_dropout", 0.0),
            **common)
        if k % int(heads) != 0:
            raise ValueError(f"kernels={k} not divisible by heads={heads}")
        self.ln = torch.nn.LayerNorm(k)
        self.attn = torch.nn.MultiheadAttention(
            k, int(heads), dropout=float(attn_dropout), batch_first=True)
        # Zero-init out_proj ⇒ MHSA residual is identity at step 0.
        torch.nn.init.zeros_(self.attn.out_proj.weight)
        if self.attn.out_proj.bias is not None:
            torch.nn.init.zeros_(self.attn.out_proj.bias)
        self.drop = torch.nn.Dropout(float(dropout))
        # True = future key blocked (PyTorch bool attn_mask).
        self.register_buffer(
            "causal_mask", torch.triu(torch.ones(W, W, dtype=torch.bool), diagonal=1),
            persistent=False)

    def forward(self, x):                                       # (B, W, 58+2F)
        y = self.bb(x)
        h = y[0] if isinstance(y, (tuple, list)) else y         # (B, T, K)
        t = h.shape[1]
        z = self.ln(h)
        mask = self.causal_mask[:t, :t]
        delta, _ = self.attn(z, z, z, attn_mask=mask, need_weights=False)
        return h + self.drop(delta)


class SpeechXAttnVLAAI(torch.nn.Module):
    """Cross-attn decoder: EEG latents as Q, speech-envelope tokens as KV.

    Pipeline (SPK warm-start friendly):
      h = VLAAIwsPatched(eeg‖speech)          # EEG latents (SPK → bb.bb.*)
      tok = Linear(speech) + causal DW context # speech-env/onset/dom tokens
      h' = h + drop(MHCA(LN(h), LN(tok), LN(tok)))  # causal cross-attn
    ``MultiheadAttention.out_proj`` is zero-init ⇒ residual ≡ 0 @step 0 ⇒
    forward ≡ plain vlaai_ws (learns unlike from-scratch ``env_xattn``).

    Novelty vs closed peers:
      * temp-attn-spk — temporal SELF-attn (Q=K=V=h), no speech KV stream
      * speech-resid  — additive FiLM/gate on speech BEFORE VLAAI
      * aux-env-spk   — aux envelope MSE loss, no cross-attn decoder
      * env_xattn     — from-scratch EEG-conv Q, chance (no SPK / no residual)
    """

    def __init__(self, C, W, n_raw=58, heads=4, dropout=0.0, attn_dropout=0.0,
                 speech_kern=9):
        super().__init__()
        n_speech = C - n_raw
        if n_speech <= 0:
            raise ValueError(f"SpeechXAttnVLAAI C={C} <= n_raw={n_raw}")
        if speech_kern % 2 == 0:
            raise ValueError("speech_kern must be odd")
        self.n_raw = int(n_raw)
        self.n_speech = int(n_speech)
        self.speech_kern = int(speech_kern)
        self.pad = self.speech_kern - 1
        from superhuge.model.pure_cnn import ExtractorParams
        k = int(D.get("model_kernels", 64))
        common = dict(fs=FS, window_length=int(W / FS), num_channels=n_raw + n_speech,
                      num_audio_features={"env": 1})
        self.bb = VLAAIwsPatched(
            nb_blocks=int(D.get("model_blocks", 3)),
            extractor_args=ExtractorParams(
                kernel_sizes=[3, 7, 11, 15],
                num_kernels=[k],
                num_layers=3),
            output_context_kernel_size=17,
            dropout=D.get("model_dropout", 0.0),
            **common)
        if k % int(heads) != 0:
            raise ValueError(f"kernels={k} not divisible by heads={heads}")
        # Speech token encoder: depthwise causal context → project to K dims.
        self.sp_dw = torch.nn.Conv1d(
            n_speech, n_speech, self.speech_kern, groups=n_speech, bias=True)
        torch.nn.init.kaiming_uniform_(self.sp_dw.weight, a=math.sqrt(5))
        torch.nn.init.zeros_(self.sp_dw.bias)
        self.sp_proj = torch.nn.Linear(n_speech, k)
        torch.nn.init.xavier_uniform_(self.sp_proj.weight)
        torch.nn.init.zeros_(self.sp_proj.bias)
        self.ln_q = torch.nn.LayerNorm(k)
        self.ln_kv = torch.nn.LayerNorm(k)
        self.attn = torch.nn.MultiheadAttention(
            k, int(heads), dropout=float(attn_dropout), batch_first=True)
        # Zero-init out_proj ⇒ cross-attn residual is identity at step 0.
        torch.nn.init.zeros_(self.attn.out_proj.weight)
        if self.attn.out_proj.bias is not None:
            torch.nn.init.zeros_(self.attn.out_proj.bias)
        self.drop = torch.nn.Dropout(float(dropout))
        self.register_buffer(
            "causal_mask", torch.triu(torch.ones(W, W, dtype=torch.bool), diagonal=1),
            persistent=False)

    def _speech_tokens(self, sp):
        """(B, T, n_speech) → (B, T, K) causal speech-env tokens."""
        h = sp.transpose(1, 2)                                  # (B, Fs, T)
        h = torch.nn.functional.pad(h, (self.pad, 0))
        h = torch.nn.functional.gelu(self.sp_dw(h)[..., :sp.shape[1]])
        return self.sp_proj(h.transpose(1, 2))                  # (B, T, K)

    def forward(self, x):                                       # (B, W, 58+2F)
        raw_sp = x
        sp = x[..., self.n_raw:]
        y = self.bb(raw_sp)
        h = y[0] if isinstance(y, (tuple, list)) else y         # (B, T, K) EEG latents
        t = h.shape[1]
        tok = self._speech_tokens(sp)                           # speech KV
        q, kv = self.ln_q(h), self.ln_kv(tok)
        mask = self.causal_mask[:t, :t]
        delta, _ = self.attn(q, kv, kv, attn_mask=mask, need_weights=False)
        return h + self.drop(delta)


class FBCNetSPK(torch.nn.Module):
    """FBCNet-style multi-band parallel spatial+temporal → shared vlaai_ws (SPK).

    Mane et al. inspiration: frozen causal FIR filter-bank views (1–3/3–5/5–7/7–9 Hz),
    then per-band Spatial Conv1d (C→C, identity-init) + depthwise Temporal Conv
    (delta-init), then each view (band_eeg ‖ speech) through ONE shared
    VLAAIwsPatched; soft-mix over bands (uniform init).

    Distinct from:
      - FBExtraVLAAI / WaveletFBExtraVLAAI residual (raw+mix → single forward)
      - C=232 filterbank-only stack, EEGNet DWS, TSception, ATCNet, Conformer

    SPK DirectNet remaps into `bb.*` (shared VLAAI); spatial/temporal/FIR/mix
    stay missing under strict=False.
    """

    BANDS = ((1.0, 3.0), (3.0, 5.0), (5.0, 7.0), (7.0, 9.0))

    def __init__(self, C, W, n_raw=58, n_bands=4, fir_taps=65, temp_kern=25,
                 dropout=0.0):
        super().__init__()
        if n_bands != len(self.BANDS):
            raise ValueError(f"n_bands={n_bands} != {len(self.BANDS)}")
        if fir_taps % 2 == 0:
            raise ValueError("fir_taps must be odd")
        if temp_kern % 2 == 0:
            raise ValueError("temp_kern must be odd")
        n_speech = C - n_raw
        if n_speech < 0:
            raise ValueError(f"FBCNetSPK C={C} < n_raw={n_raw}")
        self.n_raw = n_raw
        self.n_bands = n_bands
        self.fir_taps = fir_taps
        self.pad = fir_taps - 1
        # Depthwise frozen FIR: one filter per (band, channel)
        self.fir = torch.nn.Conv1d(
            n_raw * n_bands, n_raw * n_bands, fir_taps,
            groups=n_raw * n_bands, bias=False)
        with torch.no_grad():
            from scipy.signal import firwin
            w = torch.zeros_like(self.fir.weight)
            for bi, (lo, hi) in enumerate(self.BANDS):
                taps = firwin(fir_taps, [lo, hi], pass_zero=False, fs=float(FS))
                taps = torch.tensor(taps[::-1].copy(), dtype=w.dtype)
                for c in range(n_raw):
                    w[bi * n_raw + c, 0, :] = taps
            self.fir.weight.copy_(w)
        self.fir.weight.requires_grad_(False)
        # Per-band FBCNet spatial (channel mix) + temporal (depthwise) — identity/delta
        self.spatial = torch.nn.ModuleList([
            torch.nn.Conv1d(n_raw, n_raw, 1, bias=True) for _ in range(n_bands)])
        self.temporal = torch.nn.ModuleList([
            torch.nn.Conv1d(n_raw, n_raw, temp_kern, padding=temp_kern // 2,
                            groups=n_raw, bias=True) for _ in range(n_bands)])
        with torch.no_grad():
            for spa, tmp in zip(self.spatial, self.temporal):
                spa.weight.zero_()
                for c in range(n_raw):
                    spa.weight[c, c, 0] = 1.0
                spa.bias.zero_()
                tmp.weight.zero_()
                mid = temp_kern // 2
                tmp.weight[:, 0, mid] = 1.0
                tmp.bias.zero_()
        self.band_logit = torch.nn.Parameter(torch.zeros(n_bands))
        self.drop = torch.nn.Dropout(dropout)
        from superhuge.model.pure_cnn import ExtractorParams
        common = dict(fs=FS, window_length=int(W / FS), num_channels=n_raw + n_speech,
                      num_audio_features={"env": 1})
        self.bb = VLAAIwsPatched(
            nb_blocks=int(D.get("model_blocks", 3)),
            extractor_args=ExtractorParams(
                kernel_sizes=[3, 7, 11, 15],
                num_kernels=[int(D.get("model_kernels", 64))],
                num_layers=3),
            output_context_kernel_size=17,
            dropout=D.get("model_dropout", 0.0),
            **common)

    def _band_eeg(self, raw):
        """(B,T,C) → list of n_bands bandpassed+spatially/temporally filtered EEG."""
        B, T, _ = raw.shape
        h = raw.transpose(1, 2).repeat(1, self.n_bands, 1)          # (B, C*n, T)
        h = torch.nn.functional.pad(h, (self.pad, 0))
        banks = self.fir(h)[..., :T]                                # (B, C*n, T)
        outs = []
        for bi in range(self.n_bands):
            e = banks[:, bi * self.n_raw:(bi + 1) * self.n_raw]     # (B, C, T)
            e = self.spatial[bi](e)
            e = self.temporal[bi](e)[..., :T]
            outs.append(self.drop(e).transpose(1, 2))               # (B, T, C)
        return outs

    def forward(self, x):                                           # (B, W, 58+2F)
        raw, sp = x[..., :self.n_raw], x[..., self.n_raw:]
        bands = self._band_eeg(raw)
        w = torch.softmax(self.band_logit, dim=0)
        # Sequential band forwards through shared VLAAI (memory-friendly)
        out = None
        for bi, eeg_b in enumerate(bands):
            y = self.bb(torch.cat([eeg_b, sp], -1))
            y = y[0] if isinstance(y, (tuple, list)) else y
            out = y * w[bi] if out is None else out + y * w[bi]
        return out


def _mel_filterbank(n_fft, n_mels, fs, fmin=1.0, fmax=None):
    """Triangular mel filterbank (n_mels, n_freq) for rfft bins of size n_fft."""
    n_freq = n_fft // 2 + 1
    fmax = float(fs) / 2.0 if fmax is None else float(fmax)
    fmin = max(0.0, float(fmin))

    def hz_to_mel(f):
        return 2595.0 * np.log10(1.0 + np.asarray(f, dtype=np.float64) / 700.0)

    def mel_to_hz(m):
        return 700.0 * (10.0 ** (np.asarray(m, dtype=np.float64) / 2595.0) - 1.0)

    m_lo, m_hi = hz_to_mel(fmin), hz_to_mel(fmax)
    m_pts = np.linspace(m_lo, m_hi, int(n_mels) + 2)
    f_pts = mel_to_hz(m_pts)
    bins = np.floor((n_fft + 1) * f_pts / float(fs)).astype(int)
    bins = np.clip(bins, 0, n_freq - 1)
    fb = np.zeros((int(n_mels), n_freq), dtype=np.float32)
    for i in range(int(n_mels)):
        left, center, right = bins[i], bins[i + 1], bins[i + 2]
        if center == left:
            center = min(left + 1, n_freq - 1)
        if right == center:
            right = min(center + 1, n_freq - 1)
        for j in range(left, center):
            fb[i, j] = (j - left) / float(center - left)
        for j in range(center, right):
            fb[i, j] = (right - j) / float(right - center)
    s = fb.sum(axis=1, keepdims=True)
    s[s < 1e-8] = 1.0
    return fb / s


class SpecViT(torch.nn.Module):
    """EEG → causal STFT/Mel spectrogram patches → tiny ViT → dense (B, W, d).

    Acc front-end (non-vlaai). Pipeline:
      1. Spatial Linear EEG → n_comp
      2. Causal per-sample STFT (left-pad, hop=1) → power → mel filterbank → log1p
      3. Flatten (n_comp × n_mels) + speech feats → Linear patch embed
      4. L× causal pre-norm MHSA+FFN (same block as TFDirect) → (B, W, d_out)

    Distinct from TFDirect (time-domain Conv1d patch), Conformer, FBCNet /
    FIR/Morlet residual→vlaai, TSception, WaveNet, Mamba, Shallow/Deep/EEGNet.
    """

    def __init__(self, C, W, n_eeg=58, d=64, heads=4, layers=2, n_comp=8,
                 n_fft=16, n_mels=12, ffn_mult=2, dropout=0.2, d_out=64,
                 fmin=1.0, fmax=None):
        super().__init__()
        if C <= n_eeg:
            raise ValueError(f"SpecViT C={C} needs n_eeg={n_eeg} + 2·Fs speech")
        n_speech = C - n_eeg
        if n_speech % 2 != 0:
            raise ValueError(f"SpecViT speech width {n_speech} not even")
        if d % heads != 0:
            raise ValueError(f"d={d} not divisible by heads={heads}")
        if n_fft < 4:
            raise ValueError("n_fft must be >= 4")
        self.n_eeg = int(n_eeg)
        self.n_comp = int(n_comp)
        self.n_fft = int(n_fft)
        self.n_mels = int(n_mels)
        self.spatial = torch.nn.Linear(self.n_eeg, self.n_comp, bias=False)
        win = torch.hann_window(self.n_fft, periodic=True)
        self.register_buffer("stft_win", win, persistent=False)
        fb = _mel_filterbank(self.n_fft, self.n_mels, FS, fmin=fmin, fmax=fmax)
        self.register_buffer("mel_fb", torch.from_numpy(fb), persistent=False)  # (M, F)
        in_dim = self.n_comp * self.n_mels + n_speech
        self.patch = torch.nn.Linear(in_dim, d)
        self.pos = torch.nn.Parameter(torch.zeros(1, W, d))
        torch.nn.init.normal_(self.pos, std=0.02)
        self.drop = torch.nn.Dropout(dropout)
        self.blocks = torch.nn.ModuleList([
            _PreNormTFBlock(d, heads, dropout, ffn_mult=ffn_mult)
            for _ in range(int(layers))])
        self.ln = torch.nn.LayerNorm(d)
        self.out = torch.nn.Linear(d, d_out) if d != d_out else torch.nn.Identity()
        self.out_ln = torch.nn.LayerNorm(d_out) if d != d_out else torch.nn.Identity()
        self.register_buffer(
            "causal_mask", torch.triu(torch.ones(W, W, dtype=torch.bool), diagonal=1),
            persistent=False)
        # Mild init so early logits stay near 0 but gradients flow.
        torch.nn.init.normal_(self.spatial.weight, std=0.02)
        torch.nn.init.normal_(self.patch.weight, std=0.02)
        torch.nn.init.zeros_(self.patch.bias)
        if isinstance(self.out, torch.nn.Linear):
            torch.nn.init.normal_(self.out.weight, std=0.02)
            torch.nn.init.zeros_(self.out.bias)

    def _causal_mel(self, eeg):
        """eeg (B, W, n_comp) → log-mel (B, W, n_comp * n_mels), hop=1 causal STFT."""
        B, T, C = eeg.shape
        # (B, C, T) left-pad then unfold → (B, C, T, n_fft)
        h = torch.nn.functional.pad(eeg.transpose(1, 2), (self.n_fft - 1, 0))
        frames = h.unfold(-1, self.n_fft, 1) * self.stft_win
        spec = torch.fft.rfft(frames, n=self.n_fft, dim=-1)
        power = spec.real.square() + spec.imag.square()          # (B, C, T, F)
        mel = torch.einsum("bctf,mf->bctm", power, self.mel_fb)  # (B, C, T, M)
        logmel = torch.log1p(mel.clamp_min(0.0))
        return logmel.permute(0, 2, 1, 3).reshape(B, T, C * self.n_mels)

    def forward(self, x):                                       # (B, W, C) -> (B, W, d)
        t = x.shape[1]
        eeg = self.spatial(x[..., :self.n_eeg])
        mel = self._causal_mel(eeg)
        speech = x[..., self.n_eeg:]
        h = self.patch(torch.cat([mel, speech], dim=-1))
        h = self.drop(h + self.pos[:, :t])
        mask = self.causal_mask[:t, :t]
        for block in self.blocks:
            h = block(h, mask)
        return self.out_ln(self.out(self.ln(h)))


def build_backbone(name, C, W):
    from superhuge.model.pure_cnn import ExtractorParams
    common = dict(fs=FS, window_length=int(W / FS), num_channels=C, num_audio_features={"env": 1})
    if name == "adt":
        return ADT(C, W)
    if name == "happyquokka":
        return HappyQuokka(C, **MODEL_OVERRIDES.get(name, {}))
    if name == "gru_ffn":
        return GRUFFNTransformer(
            C, W,
            d=int(D.get("model_d", 96)),
            heads=int(D.get("model_heads", 4)),
            layers=int(D.get("model_layers", 2)),
            dropout=float(D.get("model_dropout", 0.1)))
    if name == "conv_attn":
        return ConvAttnTransformer(
            C, W,
            d=int(D.get("model_d", 96)),
            heads=int(D.get("model_heads", 4)),
            layers=int(D.get("model_layers", 2)),
            dropout=float(D.get("model_dropout", 0.1)))
    if name == "env_xattn":
        return EnvCrossAttn(
            C, W,
            d=int(D.get("model_d", 96)),
            heads=int(D.get("model_heads", 4)),
            layers=int(D.get("model_layers", 2)),
            dropout=float(D.get("model_dropout", 0.1)))
    if name == "atcnet":
        return ATCNet(
            C, W,
            F1=int(D.get("model_F1", 64)),
            depth_mult=int(D.get("model_depth", 1)),
            kern_length=int(D.get("model_kern", 64)),
            pool=int(D.get("model_pool", 1)),
            n_heads=int(D.get("model_heads", 4)),
            tcn_filters=int(D.get("model_tcn_filters", 64)),
            tcn_depth=int(D.get("model_tcn_depth", 2)),
            tcn_kernel=int(D.get("model_tcn_kernel", 4)),
            dropout=float(D.get("model_dropout", 0.2)),
            d_out=int(D.get("model_d", 64)))
    if name == "conformer":
        return EEGConformer(
            C, W,
            d=int(D.get("model_d", 64)),
            heads=int(D.get("model_heads", 4)),
            layers=int(D.get("model_layers", 4)),
            patch_k=int(D.get("model_patch_k", 25)),
            conv_k=int(D.get("model_conv_k", 15)),
            dropout=float(D.get("model_dropout", 0.2)))
    if name == "eegtcnet":
        return EEGTCNet(
            C, W,
            F1=int(D.get("model_F1", 64)),
            kern_length=int(D.get("model_kern", 64)),
            tcn_filters=int(D.get("model_tcn_filters", 64)),
            tcn_depth=int(D.get("model_tcn_depth", 3)),
            tcn_kernel=int(D.get("model_tcn_kernel", 4)),
            dropout=float(D.get("model_dropout", 0.2)),
            d_out=int(D.get("model_d", 64)))
    if name == "tsception":
        scales = D.get("model_scales_s", (0.5, 0.25, 0.125))
        if isinstance(scales, str):
            scales = tuple(float(x) for x in scales.split(","))
        return TSception(
            C, W,
            F1=int(D.get("model_F1", 32)),
            scales_s=tuple(scales),
            pool=int(D.get("model_pool", 8)),
            dropout=float(D.get("model_dropout", 0.5)),
            d_out=int(D.get("model_d", 64)))
    if name == "shallow":
        return ShallowConvNet(
            C, W,
            n_filters=int(D.get("model_F1", 40)),
            kern=int(D.get("model_kern", 25)),
            pool=int(D.get("model_pool", 75)),
            dropout=float(D.get("model_dropout", 0.5)),
            d_out=int(D.get("model_d", 64)))
    if name == "deep":
        return DeepConvNet(
            C, W,
            filters=tuple(D.get("model_filters", (25, 50, 100, 200))),
            kern=int(D.get("model_kern", 10)),
            pool=int(D.get("model_pool", 3)),
            dropout=float(D.get("model_dropout", 0.5)),
            d_out=int(D.get("model_d", 64)))
    if name == "eegnet":
        return EEGNet(
            C, W,
            F1=int(D.get("model_F1", 64)),
            D=int(D.get("model_depth", 2)),
            F2=D.get("model_F2", None),
            kern=int(D.get("model_kern", 64)),
            sep_kern=int(D.get("model_sep_kern", 16)),
            dropout=float(D.get("model_dropout", 0.5)),
            d_out=int(D.get("model_d", 64)))
    if name == "wavenet":
        dil = D.get("model_dilations", (1, 2, 4, 8, 16, 32, 64))
        if isinstance(dil, str):
            dil = tuple(int(x) for x in dil.split(","))
        return WaveNet(
            C, W,
            channels=int(D.get("model_channels", D.get("model_d", 64))),
            kernel=int(D.get("model_kern", 3)),
            dilations=tuple(dil),
            cycles=int(D.get("model_cycles", 1)),
            dropout=float(D.get("model_dropout", 0.2)),
            d_out=int(D.get("model_d", 64)))
    if name == "mamba":
        return MambaDirect(
            C, W,
            d=int(D.get("model_d", 64)),
            layers=int(D.get("model_layers", 4)),
            d_state=int(D.get("model_d_state", 16)),
            d_conv=int(D.get("model_d_conv", 4)),
            expand=int(D.get("model_expand", 2)),
            dropout=float(D.get("model_dropout", 0.2)),
            d_out=int(D.get("model_d_out", D.get("model_d", 64))),
            ffn_mult=float(D.get("model_ffn_mult", 2)))
    if name == "tf_direct":
        return DirectTransformer(
            C, W,
            d=int(D.get("model_d", 64)),
            heads=int(D.get("model_heads", 4)),
            layers=int(D.get("model_layers", 4)),
            patch_k=int(D.get("model_patch_k", 15)),
            ffn_mult=float(D.get("model_ffn_mult", 4)),
            dropout=float(D.get("model_dropout", 0.2)),
            causal=bool(D.get("model_causal", True)))
    if name == "spec_vit":
        return SpecViT(
            C, W,
            n_eeg=int(D.get("model_n_eeg", 58)),
            d=int(D.get("model_d", 64)),
            heads=int(D.get("model_heads", 4)),
            layers=int(D.get("model_layers", 2)),
            n_comp=int(D.get("model_n_comp", 8)),
            n_fft=int(D.get("model_n_fft", 16)),
            n_mels=int(D.get("model_n_mels", 12)),
            ffn_mult=float(D.get("model_ffn_mult", 2)),
            dropout=float(D.get("model_dropout", 0.2)),
            d_out=int(D.get("model_d_out", D.get("model_d", 64))),
            fmin=float(D.get("model_fmin", 1.0)),
            fmax=D.get("model_fmax", None))
    if name == "fb_vlaai":
        return FBExtraVLAAI(
            C, W,
            n_raw=int(D.get("model_n_raw", 58)),
            n_bands=int(D.get("model_n_bands", 4)))
    if name == "wavelet_fb_vlaai":
        return WaveletFBExtraVLAAI(
            C, W,
            n_raw=int(D.get("model_n_raw", 58)),
            n_scales=int(D.get("model_n_scales", 4)),
            fir_taps=int(D.get("model_fir_taps", 97)),
            n_cycles=D.get("model_n_cycles", None))
    if name == "speech_resid_spk":
        return SpeechResidVLAAI(
            C, W,
            n_raw=int(D.get("model_n_raw", 58)),
            speech_kern=int(D.get("model_speech_kern", 65)),
            speech_hid=D.get("model_speech_hid", None))
    if name == "trf_pathb_sw2":
        return TRFPathBVLAAI(
            C, W,
            n_raw=int(D.get("model_n_raw", 58)),
            max_lag=D.get("model_trf_max_lag", None),
            gate0=float(D.get("model_trf_gate0", 0.25)))
    if name == "temp_attn_spk":
        return TempAttnVLAAI(
            C, W,
            n_raw=int(D.get("model_n_raw", 58)),
            heads=int(D.get("model_heads", 4)),
            dropout=float(D.get("model_attn_drop", 0.0)),
            attn_dropout=float(D.get("model_attn_dropout", 0.0)))
    if name == "speech_xattn_dec":
        return SpeechXAttnVLAAI(
            C, W,
            n_raw=int(D.get("model_n_raw", 58)),
            heads=int(D.get("model_heads", 4)),
            dropout=float(D.get("model_attn_drop", 0.0)),
            attn_dropout=float(D.get("model_attn_dropout", 0.0)),
            speech_kern=int(D.get("model_speech_kern", 9)))
    if name == "fbcnet_spk":
        return FBCNetSPK(
            C, W,
            n_raw=int(D.get("model_n_raw", 58)),
            n_bands=int(D.get("model_n_bands", 4)),
            fir_taps=int(D.get("model_fir_taps", 65)),
            temp_kern=int(D.get("model_temp_kern", 25)),
            dropout=float(D.get("model_fb_dropout", 0.0)))
    if name == "xcorr":
        return XCorrMatched(
            C, W,
            n_eeg=int(D.get("model_n_eeg", 58)),
            n_comp=int(D.get("model_n_comp", 16)),
            max_lag_ms=float(D.get("model_max_lag_ms", 250)),
            smooth_ms=float(D.get("model_smooth_ms", 250)),
            cnn_channels=int(D.get("model_cnn_channels", D.get("model_d", 64))),
            cnn_blocks=int(D.get("model_cnn_blocks", 2)),
            cnn_kern=int(D.get("model_cnn_kern", 9)),
            dropout=float(D.get("model_dropout", 0.2)),
            d_out=int(D.get("model_d", 64)),
            light_init=bool(D.get("model_light_init", True)))
    if name == "vlaai_ws":
        # size sweep (--set model_blocks=N model_kernels=K): a changed size needs its own pretrained network
        return VLAAIwsPatched(nb_blocks=int(D.get("model_blocks", 4)),
                              extractor_args=ExtractorParams(kernel_sizes=[3, 7, 11, 15], num_kernels=[int(D.get("model_kernels", 64))],
                                                             num_layers=3),
                              output_context_kernel_size=17, dropout=D.get("model_dropout", 0.0), **common)
    cfgname = {"vlaai": "vlaai", "simple_cnn": "simple_cnn", "lsm_cnn": "lsm_cnn", "deformer": "deformer",
               "deformer_ws": "rebok_deformer", "ssmamba": "ssmamba"}[name]
    c = yaml.safe_load(open(MODEL_CFG + cfgname + ".yaml"))["init_args"]
    mod, cls = c["model_class"].rsplit(".", 1)
    args = dict(c["model_args"])
    if isinstance(args.get("extractor_args"), dict) and "class_path" in args["extractor_args"]:
        args["extractor_args"] = ExtractorParams(**args["extractor_args"]["init_args"])
    args.update(MODEL_OVERRIDES.get(name, {}))
    if name == "ssmamba":
        args["use_subject_embedding"] = False          # subject IDs may not be inputs
    if name == "deformer_ws":
        args.update(window_length=int(W / FS), fs=FS, time_dim=W, num_electrodes=C)
    return getattr(importlib.import_module(mod), cls)(**{**args, **{k: v for k, v in common.items() if k not in args}})


class Net(torch.nn.Module):
    def __init__(self, name, C, W):
        super().__init__()
        self.name = name
        self.backbone = build_backbone(name, C, W).to(DEV)
        with torch.no_grad():
            o = self._bb(torch.zeros(1, W, C, device=DEV))
        self.F = len(D.get("targets", ["env"]))
        self.head = (EinMix("b t c -> b t f", weight_shape="c f", c=o.shape[-1], f=self.F)
                     if (o.shape[-1] != 1 or self.F > 1) else torch.nn.Identity())

    def _bb(self, x):
        if self.name == "ssmamba":
            y = self.backbone(x, {"subject_id": torch.ones(x.shape[0], dtype=torch.long, device=x.device)})
        else:
            y = self.backbone(x)
        return y[0] if isinstance(y, (tuple, list)) else y

    def forward(self, x):
        y = self.head(self._bb(x))
        return y[..., 0] if self.F == 1 else y                     # (B, W) or (B, W, F)


def infonce(y, Ya, Yi, tau):
    """InfoNCE over the batch: for window i the positive is its attended target, negatives are its ignored target
    and the attended targets of all other windows in the batch. Similarity = Pearson over time, logits = sim / tau.
    y, Ya, Yi: (B, W) or (B, W, F); the loss is averaged over targets F."""
    if y.dim() == 2:
        y, Ya, Yi = y[..., None], Ya[..., None], Yi[..., None]
    z = lambda a: (a - a.mean(1, keepdim=True)) / (a.std(1, keepdim=True) * np.sqrt(a.shape[1]) + 1e-8)
    zy, za, zi = z(y), z(Ya), z(Yi)
    sim = torch.einsum("btf,ctf->fbc", zy, za)                           # (F, B, B) corr(y_b, att_c)
    neg = torch.einsum("btf,btf->fb", zy, zi)[..., None]                 # (F, B, 1) corr(y_b, ign_b)
    logits = torch.cat([sim, neg], -1) / tau
    target = torch.arange(y.shape[0], device=y.device).expand(y.shape[-1], -1)
    return torch.nn.functional.cross_entropy(logits.reshape(-1, logits.shape[-1]), target.reshape(-1))


def pearson(a, b):
    a = a - a.mean(1, keepdim=True)
    b = b - b.mean(1, keepdim=True)
    return (a * b).sum(1) / torch.sqrt((a * a).sum(1) * (b * b).sum(1) + 1e-8)


def pearson_masked(a, b, m):
    """Pearson over time, using only samples where mask m (B, W) is 1. a, b are (B, W) or (B, W, F)."""
    single = a.dim() == 2
    if single:
        a, b = a.unsqueeze(-1), b.unsqueeze(-1)
    m = m.unsqueeze(-1).to(a.dtype)
    n = m.sum(1, keepdim=True).clamp(min=1.0)
    ac = (a - (a * m).sum(1, keepdim=True) / n) * m
    bc = (b - (b * m).sum(1, keepdim=True) / n) * m
    r = (ac * bc).sum(1) / torch.sqrt((ac * ac).sum(1) * (bc * bc).sum(1) + 1e-8)
    return r.squeeze(-1) if single else r


def seg_switch_contrastive(y, Ya, Yi, p, post_w, rng, p2=0.0, min_gap=None):
    """Train-only contrastive loss with one (or two) synthetic switches inside the window.

    With probability p, a cut in the middle 60% swaps the attended and ignored targets afterwards. With probability
    p2 among those switched windows, a second cut ≥ min_gap samples later flips back (decoder-sw3 denser multi-switch;
    default min_gap = 2 s). Segments are Pearson-averaged; the post-first-cut region is weighted by post_w. Windows
    without a cut keep the full-window contrastive loss. y, Ya, Yi: (B, W) or (B, W, F)."""
    B, W = y.shape[:2]
    do = rng.random(B) < float(p)
    lo, hi = int(round(0.2 * W)), int(round(0.8 * W))
    if hi <= lo or not do.any():
        r = -pearson(y, Ya) + pearson(y, Yi)
        return (r.mean(-1) if r.dim() > 1 else r).mean()
    gap = int(min_gap) if min_gap is not None else int(round(2.0 * FS))
    cut = np.full(B, W, np.int64)
    cut2 = np.full(B, W + 1, np.int64)   # past end → no second flip
    n_do = int(do.sum())
    cut[do] = rng.integers(lo, hi, n_do)
    if float(p2) > 0 and n_do:
        do2_local = rng.random(n_do) < float(p2)
        for j, i in enumerate(np.flatnonzero(do)):
            if not do2_local[j]:
                continue
            a = int(cut[i]) + gap
            # leave ≥0.2·W after the second cut so the flip-back segment is usable
            b = int(round(0.8 * W))
            if a < b:
                cut2[i] = int(rng.integers(a, b))
    loss_full = -pearson(y, Ya) + pearson(y, Yi)
    if loss_full.dim() > 1:
        loss_full = loss_full.mean(-1)
    idx = torch.arange(W, device=y.device)
    cut_t = torch.as_tensor(cut, device=y.device)
    cut2_t = torch.as_tensor(cut2, device=y.device)
    # parity of switches so far: True = swapped vs original attended/ignored
    swapped = (idx[None, :] >= cut_t[:, None]) & (idx[None, :] < cut2_t[:, None])
    do_t = torch.as_tensor(do, device=y.device)
    swap = swapped & do_t[:, None]
    if y.dim() == 3:
        swap = swap.unsqueeze(-1)
    Ya_s, Yi_s = torch.where(swap, Yi, Ya), torch.where(swap, Ya, Yi)
    # weight: pre-first-cut = 1, everything after first cut = post_w (incl. flip-back)
    post = idx[None, :] >= cut_t[:, None]
    pre_m, post_m = (~post).to(y.dtype), post.to(y.dtype)
    loss_pre = -pearson_masked(y, Ya_s, pre_m) + pearson_masked(y, Yi_s, pre_m)
    loss_post = -pearson_masked(y, Ya_s, post_m) + pearson_masked(y, Yi_s, post_m)
    if loss_pre.dim() > 1:
        loss_pre, loss_post = loss_pre.mean(-1), loss_post.mean(-1)
    w = float(post_w)
    loss_seg = (loss_pre + w * loss_post) / (1.0 + w)
    return torch.where(do_t, loss_seg, loss_full).mean()


def _grid_pos(names):
    """Approximate 2-D scalp grid (row, column) from 10-10 labels: letters -> anterior-posterior row, number -> lateral
    column (odd = left, even = right, z = midline). Enough to find neighbouring electrodes (no mne installed)."""
    import re
    rows = {"FP": 0, "AF": 1, "F": 2, "FC": 3, "FT": 3, "C": 4, "T": 4, "CP": 5, "TP": 5, "P": 6, "PO": 7, "O": 8,
            "CB": 9, "I": 9}
    out = []
    for n in names:
        m = re.match(r"([A-Z]+)(\d+|Z)$", n.upper())
        let, num = m.group(1), m.group(2)
        col = 0.0 if num == "Z" else (-(int(num) + 1) / 2 if int(num) % 2 else int(num) / 2)
        out.append((rows.get(let, rows.get(let[:1], 4)), col))
    return np.array(out, float)


def apply_overrides(pairs, aug_pairs=()):
    """Hyper-parameter search: --set key=value overrides config dnn (lr, weight_decay, batch_size, model_dropout, ...),
    --aug-set key=value overrides the augmentation dict (noise, p_chan, p_cluster, ...). Call after D['augment'] is set."""
    num = lambda v: int(v) if v.lstrip("-").isdigit() else float(v)
    for kv in pairs or ():
        k, v = kv.split("=")
        D[k] = num(v)
    if aug_pairs:
        D["augment"] = dict(D.get("augment") or {})
        for kv in aug_pairs:
            k, v = kv.split("=")
            D["augment"][k] = num(v)


def _dataset_of(key):
    return key.split("-subject-")[0]


# ---- adversarial domain loss (D['adv'] = 'dataset' | 'subject'): a domain classifier on the time-pooled backbone features
# behind a gradient-reversal layer (DANN); the backbone is pushed to make dataset / subject unpredictable
class _GRL(torch.autograd.Function):
    @staticmethod
    def forward(ctx, x, lam):
        ctx.lam = lam
        return x.view_as(x)

    @staticmethod
    def backward(ctx, g):
        return -ctx.lam * g, None


def domain_ids(trials, kind):
    """Domain label per training trial: 'dataset' (corpus dataset or the external set) or 'subject'."""
    def name(k):
        if "-subject-" in k:
            return k.split("-subject-")[0] if kind == "dataset" else k.split("-trial-")[0]
        return k.split("_")[0] if kind == "dataset" else k.rsplit("_", 1)[0]
    names = [name(t["key"]) for t in trials]
    uniq = sorted(set(names))
    return np.array([uniq.index(n) for n in names]), len(uniq)


class AdvHead(torch.nn.Module):
    def __init__(self, d, n):
        super().__init__()
        self.net = torch.nn.Sequential(torch.nn.Linear(2 * d, 128), torch.nn.ReLU(), torch.nn.Linear(128, n))

    def forward(self, f, lam):                                   # f: backbone features (B, W, d)
        return self.net(_GRL.apply(torch.cat([f.mean(1), f.std(1)], -1), lam))


def adv_lambda(step):
    """DANN schedule: 0 -> D['adv_lambda'] over the first D['adv_ramp_epochs'] epochs."""
    p = min(1.0, step / (D.get("adv_ramp_epochs", 5) * D["steps_per_epoch"]))
    return D.get("adv_lambda", 0.05) * (2.0 / (1.0 + math.exp(-10.0 * p)) - 1.0)



class DNNDec:
    def __init__(self, name, C, log=print, mode="causal"):
        self.name, self.C, self.log = name, C, log
        self.W = int(D["window_s"] * FS)
        self.hop = int(D["infer_hop_s"] * FS)
        self.fut = int(D["causal_future_s"] * FS)
        # label stamping of the evidence windows (score.py): a window ending on the read-out grid at t_end only needs
        # EEG < t_end + fut (its last hop block [t_end - hop, t_end) is read from the window ending at t_end + fut),
        # although a single output sample uses up to fut + hop = 0.75 s of future (leakage_test.py)
        self.lookahead_s = D.get("evidence_lookahead_s", (self.fut + self.hop) / FS)
        assert self.lookahead_s >= self.fut / FS and int(CFG["evidence"]["hop_s"] * FS) % self.hop == 0 \
            and int(CFG["evidence"]["win_s"] * FS) % self.hop == 0, "evidence windows must end on the read-out grid"
        self.offline_lookahead_s = (self.W - self.W // 4) / FS  # 3.75 s (reference only, violates the rule)
        torch.manual_seed(D.get("train_seed", CFG["seed"]))   # --train-seed (step 0)
        self.net = Net(name, C, self.W).to(DEV)

    def _augment(self, X, rng):
        """Training-only augmentation (D['augment'], off by default), per window, in place on X (n, W, C):
        spectral tilt (p_tilt of the windows, exponent within +-tilt), channel mask (p_chan_mask of the windows, each channel dropped with p_chan), per-channel gain (log-uniform
        within +-gain), additive Gaussian noise (std noise, data are z-scored), zero prefix (p_zero_prefix of the
        windows get their first 1..pos0 samples zeroed, as the zero padding at a trial start at inference)."""
        A = D.get("augment") or {}
        n, W, C = X.shape
        C0 = 58 if C % 58 == 0 else C                       # electrodes; C = C0 x feature groups (e.g. + gamma)
        if A.get("p_tilt", 0) > 0:
            # spectral tilt: amplitude spectrum x (f / f0)^alpha, alpha ~ U(-tilt, tilt) per window (all channels alike:
            # a subject / device difference in the spectral slope), f0 = 3 Hz (centre of the 1-9 Hz band), RMS kept
            sel = np.flatnonzero(rng.random(n) < A["p_tilt"])
            if len(sel):
                f = np.fft.rfftfreq(W, 1.0 / FS)
                al = rng.uniform(-A.get("tilt", 0.5), A.get("tilt", 0.5), (len(sel), 1, 1))
                g = (np.clip(f, 0.5, 12.0) / 3.0)[None, :, None] ** al
                Y = np.fft.irfft(np.fft.rfft(X[sel], axis=1) * g, n=W, axis=1)
                r = X[sel].std(1, keepdims=True) / np.maximum(Y.std(1, keepdims=True), 1e-8)
                X[sel] = (Y * np.where(X[sel].std(1, keepdims=True) > 0, r, 0.0)).astype(np.float32)
        if A.get("p_chan_mask", 0) > 0:
            sel = rng.random(n) < A["p_chan_mask"]
            m = (rng.random((sel.sum(), 1, C0)) > A.get("p_chan", 0.2)).astype(np.float32)
            X[sel] *= np.tile(m, (1, 1, C // C0))
        if A.get("gain", 0) > 0:
            g = np.exp(rng.uniform(-np.log1p(A["gain"]), np.log1p(A["gain"]), (n, 1, C))).astype(np.float32)
            X *= g
        if A.get("noise", 0) > 0:
            X += (A["noise"] * rng.standard_normal(X.shape)).astype(np.float32)
        if (A.get("p_cluster", 0) > 0 or A.get("p_spatial_mix", 0) > 0 or A.get("p_reref", 0) > 0) \
                and not hasattr(self, "_nbr"):
            from common import MONTAGES
            P = _grid_pos(MONTAGES[CFG["montage"]])
            self._nbr = np.argsort(((P[:, None] - P[None]) ** 2).sum(-1), 1)       # channels by distance
        if A.get("p_spatial_mix", 0) > 0 and C == self._nbr.shape[0]:
            # covariance augmentation 1: X <- X (I + eps N), N mixes each electrode with its k nearest neighbours
            k, sig = int(A.get("mix_k", 6)), float(A.get("mix_sigma", 0.15))
            for j in np.flatnonzero(rng.random(n) < A["p_spatial_mix"]):
                Mx = np.eye(C, dtype=np.float32)
                cols = self._nbr[:, 1:k + 1]                                       # (C, k) neighbours of each channel
                Mx[cols, np.repeat(np.arange(C)[:, None], k, 1)] += (sig * rng.uniform(-1, 1, (C, k))).astype(np.float32)
                X[j] = X[j] @ Mx
        if A.get("p_reref", 0) > 0 and C == self._nbr.shape[0]:
            # covariance augmentation 2: random partial re-reference to the mean of a random electrode cluster
            for j in np.flatnonzero(rng.random(n) < A["p_reref"]):
                grp = self._nbr[rng.integers(C), : int(rng.integers(1, A.get("reref_max", 8) + 1))]
                X[j] -= float(rng.uniform(0.5, 1.0)) * X[j][:, grp].mean(1, keepdims=True)
        if A.get("p_cluster", 0) > 0:                     # drop a cluster of neighbouring electrodes
            for j in np.flatnonzero(rng.random(n) < A["p_cluster"]):
                k = rng.integers(A.get("cluster_min", 3), A.get("cluster_max", 8) + 1)
                el = self._nbr[rng.integers(C0), :k]
                X[j][:, np.concatenate([el + g * C0 for g in range(C // C0)])] = 0.0
        if A.get("p_renorm", 0) > 0:                      # re-z-score with statistics of a random sub-segment
            for j in np.flatnonzero(rng.random(n) < A["p_renorm"]):
                L_ = rng.integers(FS, W + 1); a = rng.integers(0, W - L_ + 1)
                seg = X[j, a:a + L_]
                sd = seg.std(0); sd[sd == 0] = 1.0
                X[j] = (X[j] - seg.mean(0)) / sd
        if A.get("p_zero_prefix", 0) > 0:
            pos0 = self.W - self.fut - self.hop
            for j in np.flatnonzero(rng.random(n) < A["p_zero_prefix"]):
                X[j, :rng.integers(1, pos0 + 1)] = 0.0
        return X

    def _windows(self, trials, n, rng, aug=False):
        A = (D.get("augment") or {}) if aug else {}
        warp, lag = A.get("warp", 0.0), int(A.get("lag_jitter", 0))
        span = int(np.ceil(self.W * (1 + warp))) + 2 * lag      # longest raw segment a window may need
        lens = np.array([len(t["eeg"]) - span for t in trials])
        p = np.maximum(lens, 0).astype(float)
        if A.get("balance") == "dataset":                        # every training dataset equally often
            ds = np.array([_dataset_of(t["key"]) for t in trials])
            for d in np.unique(ds):
                p[ds == d] /= max(p[ds == d].sum(), 1e-9)
        p = p / p.sum()
        gf = D.get("group_frac") or {}
        if gf:                                                   # fixed sampling share per extra dataset (S2)
            grp = np.array([t.get("_grp", "") for t in trials])
            rest = ~np.isin(grp, list(gf))
            p[rest] *= (1 - sum(v for g, v in gf.items() if (grp == g).any())) / max(p[rest].sum(), 1e-12)
            for g, v in gf.items():
                if (grp == g).any():
                    p[grp == g] *= v / max(p[grp == g].sum(), 1e-12)
            p = p / p.sum()
        ti = rng.choice(len(trials), n, p=p)
        self._last_ti = ti                                        # trial of every window (adversarial domain loss)
        X = np.empty((n, self.W, self.C), np.float32)
        fshape = trials[0]["_ya"].shape[1:]                       # () for one target, (F,) for several
        Ya = np.empty((n, self.W) + fshape, np.float32)
        Yi = np.empty((n, self.W) + fshape, np.float32)
        for j, i in enumerate(ti):
            s = rng.integers(0, lens[i] + 1) + lag
            tr = trials[i]
            ya, yi = tr["_ya"], tr["_yi"]
            if warp > 0:                                        # same time warp for EEG and both envelopes
                Lr = int(round(self.W * (1 + rng.uniform(-warp, warp))))
                tq = np.linspace(0, Lr - 1, self.W)
                t0_, fr = np.floor(tq).astype(int), (tq - np.floor(tq))[:, None]
                t1_ = np.minimum(t0_ + 1, Lr - 1)
                d_ = rng.integers(-lag, lag + 1) if lag else 0   # EEG shifted vs envelope by d_ samples
                e = tr["eeg"][s + d_:s + d_ + Lr]
                X[j] = e[t0_] * (1 - fr) + e[t1_] * fr
                Ya[j] = ya[s:s + Lr][t0_] * (1 - fr[:, 0]) + ya[s:s + Lr][t1_] * fr[:, 0]
                Yi[j] = yi[s:s + Lr][t0_] * (1 - fr[:, 0]) + yi[s:s + Lr][t1_] * fr[:, 0]
            else:
                d_ = rng.integers(-lag, lag + 1) if lag else 0
                X[j] = tr["eeg"][s + d_:s + d_ + self.W]
                Ya[j], Yi[j] = ya[s:s + self.W], yi[s:s + self.W]
        if aug:
            X = self._augment(X, rng)
        return torch.from_numpy(X), torch.from_numpy(Ya), torch.from_numpy(Yi)

    def fit(self, train, val, meta):
        for tr in train + val:
            tr["_ya"], tr["_yi"] = _att_tgt(tr)
        rng = np.random.default_rng(D.get("train_seed", CFG["seed"]))
        Xv, Yav, Yiv = self._windows(val, D["val_windows"], rng)
        adv, step = None, 0
        params = list(self.net.parameters())
        if D.get("adv"):
            dom, n_dom = domain_ids(train, D["adv"])
            with torch.no_grad():
                d_feat = self.net._bb(torch.zeros(1, self.W, self.C, device=DEV)).shape[-1]
            adv = AdvHead(d_feat, n_dom).to(DEV)
            params += list(adv.parameters())
            self.log(f"  adversarial {D['adv']} loss: {n_dom} classes, lambda {D.get('adv_lambda', 0.05)}")
        if D.get("seg_switch", 0) > 0:
            self.log(f"  segment-switch loss: p={D['seg_switch']} p2={D.get('seg_switch2', 0)} "
                     f"post_weight={D.get('seg_post', 1)} min_gap_s={D.get('seg_min_gap_s', 2.0)}")
        opt = torch.optim.AdamW(params, lr=D["lr"], weight_decay=D["weight_decay"])
        sch = torch.optim.lr_scheduler.ReduceLROnPlateau(opt, mode="min", factor=0.5, patience=D["lr_patience"])
        best, bad, best_state = math.inf, 0, None
        warm = int(D.get("warmup_epochs", 0))    # epochs with linear LR ramp (lr/10 -> lr), no early stop / LR decay
        for ep in range(D["max_epochs"]):
            t0 = time.time()
            if ep < warm:
                for g in opt.param_groups:
                    g["lr"] = D["lr"] * (0.1 + 0.9 * ep / warm)
            elif ep == warm and warm > 0:
                for g in opt.param_groups:
                    g["lr"] = D["lr"]
            self.net.train()
            tl, da = [], []
            for _ in range(D["steps_per_epoch"]):
                X, Ya, Yi = self._windows(train, D["batch_size"], rng, aug=True)
                X, Ya, Yi = X.to(DEV), Ya.to(DEV), Yi.to(DEV)
                if adv is None:
                    y = self.net(X)
                else:
                    f = self.net._bb(X)
                    y = self.net.head(f)
                    y = y[..., 0] if self.net.F == 1 else y
                if D.get("loss", "contrastive") == "infonce":
                    loss = infonce(y, Ya, Yi, D.get("infonce_tau", 0.1))
                elif D.get("loss") == "pearson":                   # pretraining on single-speaker data (S1)
                    loss = -pearson(y, Ya).mean()
                elif D.get("seg_switch", 0) > 0:
                    gap = int(round(float(D.get("seg_min_gap_s", 2.0)) * FS))
                    loss = seg_switch_contrastive(
                        y, Ya, Yi, D["seg_switch"], D.get("seg_post", 1), rng,
                        p2=float(D.get("seg_switch2", 0) or 0), min_gap=gap)
                else:
                    loss = (-pearson(y, Ya) + pearson(y, Yi)).mean()
                tl.append(loss.item())
                if adv is not None:                               # the reversed gradient reaches the backbone scaled by lambda
                    dl = adv(f, adv_lambda(step))
                    dt = torch.from_numpy(dom[self._last_ti]).to(DEV)
                    loss = loss + torch.nn.functional.cross_entropy(dl, dt)
                    da.append((dl.argmax(1) == dt).float().mean().item())
                    step += 1
                opt.zero_grad()
                loss.backward()
                torch.nn.utils.clip_grad_norm_(params, 5.0)
                opt.step()
            self.net.eval()
            with torch.no_grad():
                vl = []
                for i in range(0, len(Xv), 256):
                    y = self.net(Xv[i:i + 256].to(DEV))
                    vl.append((-pearson(y, Yav[i:i + 256].to(DEV)) + pearson(y, Yiv[i:i + 256].to(DEV))).cpu())
                vl = torch.cat(vl).mean().item()
            if ep >= warm:
                sch.step(vl)
            self.log(f"    epoch {ep:02d} train {np.mean(tl):+.4f} val {vl:+.4f} ({time.time() - t0:.0f}s)"
                     + (f" [warm-up, lr {opt.param_groups[0]['lr']:.1e}]" if ep < warm else "")
                     + (f" | adversary acc {np.mean(da):.3f}" if da else ""))
            if vl < best - 1e-4:
                best, bad = vl, 0
                best_state = {k: v.detach().clone() for k, v in self.net.state_dict().items()}
            elif ep >= warm:
                bad += 1
                if bad >= D["patience"]:
                    break
        if best_state is not None:
            self.net.load_state_dict(best_state)
        self.net.eval()
        for tr in train + val:
            tr.pop("_ya", None)
            tr.pop("_yi", None)
        return best

    # ---------------------------------------------------------------------------------------------------------------
    # A1: end-to-end sequence training (2-state linear-chain CRF / HMM filter) on sequences with synthetic switches
    # ---------------------------------------------------------------------------------------------------------------
    def _sequences(self, trials, n, rng, aug=False):
        """n training sequences of D['seq_len_s'] s with their causal context: EEG (n, ctx + Ls + fut, C), targets of
        both streams (n, Ls, 2, F), attended column (n, Ls) and the synthetic-switch flag (n, Ls): with probability
        D['seq_p_switch'] the two streams swap roles at a uniform time (as generateSyntheticSwitches does at test)."""
        Ls, ctx = int(D["seq_len_s"] * FS), self.W - self.fut - self.hop
        need = ctx + Ls + self.fut
        lens = np.array([len(t["eeg"]) - need for t in trials])
        p = np.maximum(lens + 1, 0).astype(float)
        ti = rng.choice(len(trials), n, p=p / p.sum())
        X = np.empty((n, need, self.C), np.float32)
        Y = np.empty((n, Ls) + trials[0]["_Y"].shape[1:], np.float32)
        att, st = np.empty((n, Ls), np.int64), np.zeros((n, Ls), bool)
        for j, i in enumerate(ti):
            a = rng.integers(0, lens[i] + 1)
            tr = trials[i]
            X[j], Y[j], att[j] = tr["eeg"][a:a + need], tr["_Y"][a + ctx:a + ctx + Ls], tr["att"][a + ctx:a + ctx + Ls]
            if rng.random() < D["seq_p_switch"]:
                st[j, rng.integers(int(0.2 * Ls), int(0.8 * Ls)):] = True
        if aug:
            X = self._augment(X, rng)
        return torch.from_numpy(X), torch.from_numpy(Y), torch.from_numpy(att), torch.from_numpy(st)

    def _seq_loss(self, X, Y, att, st, v, kind):
        """Decoder on every 0.25-s hop of the sequences (the causal read-out of reconstruct()), per-target Pearson in
        1-s windows against both streams, evidence sign flipped in the synthetically switched windows, unary log-odds
        u = sum_f v_f (r0_f - r1_f), 2-state chain with p_stay. kind 'filter': cross-entropy of the causal FILTERING
        posterior (what is used at test); 'crf': negative log-likelihood of the whole state path (CRF).
        Returns (loss, filtering cross-entropy, filtering accuracy)."""
        B, Ls = Y.shape[0], Y.shape[1]
        pos0, EW = self.W - self.fut - self.hop, int(CFG["evidence"]["win_s"] * FS)
        win = X.unfold(1, self.W, self.hop).permute(0, 1, 3, 2).reshape(-1, self.W, self.C)     # (B * Ls/hop, W, C)
        y = self.net(win)[:, pos0:pos0 + self.hop]
        y = y.reshape(B, Ls, -1)                                                               # (B, Ls, F)
        uw = lambda a: a.unfold(1, EW, self.hop)                                               # (B, n, F, EW)

        def corr(a, b):
            a, b = a - a.mean(-1, keepdim=True), b - b.mean(-1, keepdim=True)
            return (a * b).sum(-1) / torch.sqrt((a * a).sum(-1) * (b * b).sum(-1) + 1e-8)
        yw = uw(y)
        d = corr(yw, uw(Y[:, :, 0])) - corr(yw, uw(Y[:, :, 1]))                                # (B, n, F)
        frac = lambda z: z.float().unfold(1, EW, self.hop).mean(-1) > 0.5
        wsw, a_w = frac(st), frac(att)
        u = (d * torch.where(wsw, -1.0, 1.0)[..., None] * v).sum(-1)                           # log-odds of column 0
        state = (a_w ^ wsw).long()                                                             # true attended column
        ls, lsw = math.log(D["seq_p_stay"]), math.log(1 - D["seq_p_stay"])
        un = torch.stack([u / 2, -u / 2], -1)                                                  # (B, n, 2)
        lp = torch.full((B, 2), math.log(0.5), device=u.device)
        logZ, post = 0.0, []
        for j in range(un.shape[1]):
            if j > 0:
                lp = torch.stack([torch.logaddexp(lp[:, 0] + ls, lp[:, 1] + lsw),
                                  torch.logaddexp(lp[:, 1] + ls, lp[:, 0] + lsw)], 1)
            lp = lp + un[:, j]
            c = torch.logsumexp(lp, 1, keepdim=True)
            logZ, lp = logZ + c[:, 0], lp - c
            post.append(lp)
        post = torch.stack(post, 1)                                                            # filtering log-posteriors
        ce = -post.gather(2, state[..., None])[..., 0].mean()
        acc = (post.argmax(-1) == state).float().mean()
        if kind == "crf":
            gold = un.gather(2, state[..., None])[..., 0].sum(1) + math.log(0.5) + \
                torch.where(state[:, 1:] == state[:, :-1], ls, lsw).sum(1)
            return ((logZ - gold) / un.shape[1]).mean(), ce, acc
        return ce, ce, acc

    def fit_sequence(self, train, val):
        """Phase 2 after fit(): fine-tune the decoder and the CRF unary weights v END-TO-END with a sequence loss on
        synthetic-switch sequences. Early stopping on the filtering cross-entropy of fixed validation sequences.
        Returns dict(v, p_stay) for score.py (--evidence-weights crf)."""
        kind = D["seq_loss"]
        need = int(D["seq_len_s"] * FS) + self.W - self.hop
        for tr in train + val:
            tr["_Y"] = _targets(tr)
        tr_ok, va_ok = [t for t in train if len(t["eeg"]) >= need], [t for t in val if len(t["eeg"]) >= need]
        rng = np.random.default_rng(D.get("train_seed", CFG["seed"]) + 7)
        # unary weights: free (scale and mix learned), or 'seq_v_norm': v = seq_v_init x softmax(theta), i.e. only the
        # MIX of the targets is learned and the total LLR scale stays that of the scoring HMM (the cross-entropy
        # otherwise shrinks the scale to calibrate the overlapping windows, which slows the filter down)
        th = torch.nn.Parameter(torch.zeros(self.net.F, device=DEV) if D.get("seq_v_norm")
                                else torch.full((self.net.F,), D["seq_v_init"] / self.net.F, device=DEV))
        vf = (lambda: D["seq_v_init"] * torch.softmax(th, 0)) if D.get("seq_v_norm") else (lambda: th)
        opt = torch.optim.AdamW([dict(params=self.net.parameters(), lr=D["seq_lr"]),
                                 dict(params=[th], lr=D["seq_v_lr"], weight_decay=0.0)], weight_decay=D["weight_decay"])
        Vb = [self._sequences(va_ok, D["seq_batch"], rng) for _ in range(D["seq_val_batches"])]

        def validate():
            self.net.eval()
            with torch.no_grad():
                r = [self._seq_loss(*[z.to(DEV) for z in b], vf(), kind) for b in Vb]
            return float(np.mean([x[1].item() for x in r])), float(np.mean([x[2].item() for x in r]))
        best, acc0 = validate()
        self.log(f"    seq[{kind}] start: val filter-CE {best:.4f} acc {acc0:.3f}  v {np.round(vf().detach().cpu().numpy(), 3)}")
        bad, best_state, best_v = 0, {k: x.detach().clone() for k, x in self.net.state_dict().items()}, vf().detach().clone()
        for ep in range(D["seq_epochs"]):
            t0, tl = time.time(), []
            self.net.train()
            for _ in range(D["seq_steps"]):
                b = [z.to(DEV) for z in self._sequences(tr_ok, D["seq_batch"], rng, aug=True)]
                loss = self._seq_loss(*b, vf(), kind)[0]
                opt.zero_grad()
                loss.backward()
                torch.nn.utils.clip_grad_norm_(self.net.parameters(), 5.0)
                opt.step()
                tl.append(loss.item())
            vl, va = validate()
            self.log(f"    seq[{kind}] epoch {ep:02d} train {np.mean(tl):.4f} val filter-CE {vl:.4f} acc {va:.3f} "
                     f"v {np.round(vf().detach().cpu().numpy(), 3)} ({time.time() - t0:.0f}s)")
            if vl < best - 1e-4:
                best, bad = vl, 0
                best_state, best_v = {k: x.detach().clone() for k, x in self.net.state_dict().items()}, vf().detach().clone()
            else:
                bad += 1
                if bad >= D["seq_patience"]:
                    break
        self.net.load_state_dict(best_state)
        self.net.eval()
        for tr in train + val:
            tr.pop("_Y", None)
        return dict(v=[float(x) for x in best_v.cpu().numpy()], p_stay=D["seq_p_stay"], val_ce=best)

    @torch.no_grad()
    def reconstruct(self, tr, mode="causal"):
        """causal : output sample u is read from the window ending at u + fut + (u mod hop) -> <= 0.75 s future.
        offline: centre quarter-to-three-quarters of windows at hop W/2 (reference; uses up to 3.75 s future)."""
        x = tr["eeg"].astype(np.float32)
        T = len(x)
        if mode == "causal":
            pos0 = self.W - self.fut - self.hop                    # first read position inside the window
            pad_l, pad_r = pos0, self.fut + self.hop
            step, take = self.hop, slice(pos0, pos0 + self.hop)
        else:
            q = self.W // 4
            pad_l, pad_r, step, take = q, self.W, self.W // 2, slice(q, q + self.W // 2)
        xp = np.concatenate([np.zeros((pad_l, self.C), np.float32), x, np.zeros((pad_r, self.C), np.float32)])
        starts = np.arange(0, T, step)
        F = self.net.F
        out = np.zeros((len(starts) * step,) + ((F,) if F > 1 else ()), np.float32)
        for i in range(0, len(starts), 512):
            s = starts[i:i + 512]
            X = torch.from_numpy(np.stack([xp[a:a + self.W] for a in s])).to(DEV)
            y = self.net(X)[:, take].cpu().numpy()
            out[i * step:(i + len(s)) * step] = y.reshape((-1,) + ((F,) if F > 1 else ()))
        return out[:T]

    def features(self, tr, mode="causal"):
        y = self.reconstruct(tr, mode)
        if self.net.F == 1:
            return y, tr["env"][:, 0], tr["env"][:, 1]
        Y = _targets(tr)                                            # evidence = mean correlation over targets
        return y, Y[:, 0, :], Y[:, 1, :]


LINEAR = {"wf": BackwardWF, "wf_persubject": PerSubjectWF, "wf_riemann": RiemannWF, "wf_forward": ForwardWF,
          "cca": CCADec, "fbcca": FBCCADec}
DNN = ["simple_cnn", "lsm_cnn", "vlaai", "vlaai_ws", "deformer", "deformer_ws", "ssmamba", "adt", "happyquokka"]


def make(name, C, log=print):
    if name in LINEAR:
        return LINEAR[name](C)
    return DNNDec(name, C, log)
