Move the upstream SpecAugment masking from a Lightning callback
(neuralbench's SpecAugmentCallback, registered as a forward hook on
``model.spectrogram``) into ``EMG2QwertyNet`` itself as a parameter-free
``_SpecAugment`` submodule that runs only in ``train()`` mode. Constructor
flag ``spec_augment=False`` (default) installs an ``nn.Identity`` so the
state-dict layout and existing checkpoints stay untouched; setting
``spec_augment=True`` exposes the paper-recipe knobs (``n_time_masks``,
``time_mask_param``, ``n_freq_masks``, ``freq_mask_param``,
``spec_augment_prob``) and applies the mask in-place between the
log-spectrogram and the per-channel BatchNorm. Masking remains IID per
``(sample x band)`` and shared across the electrodes within a band, with
mask value set to the per-window mean (matches the upstream callback).

Adds three regression tests: train/eval determinism contrast, identity
default, and constructor argument validation.

Add ``return_features: bool = False`` to ``EMG2QwertyNet.forward`` so
the encoder can drop into neuroai's
``DownstreamWrapperModel(model_output_key="features")`` (and any other
caller following the BIOT / signal-JEPA convention) without needing a
custom forward hook.

When ``True``, ``forward`` returns
``{"features": (batch, T_out, num_features), "cls_token": None}`` —
the output of the TDS-Conv encoder, batch-first, before
``self.final_layer``. ``cls_token`` is fixed to ``None`` because
TDS-Conv has no ``[CLS]``; the key is kept for parity with the rest of
the family. Default ``False`` keeps the existing
``(batch, T_out, n_outputs)`` emissions tensor untouched, so existing
CTC training loops, tests, and ``get_output_shape`` are unaffected.

Adds a regression test pinning the dict layout, the batch-first
``(B, T_out, num_features)`` shape, and the invariant that applying
``self.final_layer`` to the returned features reproduces the default
emissions.

…e flag

Re-audited upstream emg2qwerty (Meta, NeurIPS 2024) before locking in
the previous Codex-driven rewrite. Two fixes here.

1. SpecAugment masking semantics — revert band-sharing.

   ``emg2qwerty/transforms.py:SpecAugment.__call__`` applies SpecAugment
   as a *dataset-level* transform on a single sample shaped
   ``(T, bands, electrodes, freq)``. After ``movedim(0, -1)`` the input
   is 4-D ``(bands, electrodes, freq, T)`` and ``torchaudio``'s
   ``iid_masks=True`` samples one mask per leading axis index — i.e.
   per ``(band, electrode)`` pair, with each electrode in a band drawing
   its own mask. The previous neuralbench callback's ``(B*num_bands,
   electrodes, freq, T)`` reshape produced the same per-``(sample × band
   × electrode)`` independence; only its comment was wrong. The Codex
   review's claim that the paper recipe is band-shared and the original
   was "32× too aggressive" doesn't match the upstream code.

   The previous commit's manual band-shared masking (one mask per
   ``(sample × band)``, broadcast over all 16 electrodes) was therefore
   16× *less* aggressive than the paper. Replace it with a direct
   ``torchaudio.transforms.TimeMasking(iid_masks=True)`` /
   ``FrequencyMasking(iid_masks=True)`` call on the 5-D
   ``(B, num_bands, electrodes, freq, T_spec)`` tensor (no
   reshape gymnastics, no manual masking). ``mask_along_axis_iid``
   draws one mask per leading-axis triple, so the result is per-
   ``(B × num_bands × electrodes)`` independence — exactly the upstream
   recipe scaled to a batched tensor. ``mask_value=spec.mean()``
   stays a 0-D on-device tensor; ``torchaudio`` handles ``Tensor``
   ``mask_value`` natively (``torch.where`` path), so there is still no
   host round-trip on GPU. Update the test contract to assert
   per-``(B, band, electrode)`` independence — i.e. that masking is
   NOT band-shared — and pin it deterministically by monkeypatching
   ``torch.randint``.

2. ``return_feature`` (init kwarg, BIOT-style) for config-driven wrappers.

   Confirmed via direct trace that ``DownstreamWrapper.build`` calls
   ``model(**dummy_batch)`` with no runtime kwargs — and
   ``build_dummy_batch`` only seeds the first forward parameter. So the
   runtime ``return_features=True`` (plural) flag added in 3a831aa is
   inert when neuroai's wrapper drives the model from YAML
   (``model(x)`` returns the emissions tensor; ``tensor["features"]``
   raises). Mirror :class:`BIOT`'s legacy contract: a ``return_feature``
   (singular) constructor kwarg makes ``forward`` return a
   ``(emissions, features)`` tuple by default, so a YAML such as
   ``kwargs: {return_feature: true}`` + ``model_output_key: 1`` picks up
   the ``(B, T_out, num_features)`` encoder representation without a
   call-site change. Runtime ``return_features=True`` still wins (returns
   the dict) for programmatic users; both round-trip via
   ``get_config`` / ``from_config`` and ``get_output_shape`` keeps
   reporting the emissions shape regardless of which flag is set.

``[park2019specaug]_`` is defined only in the EMG2QwertyNet docstring,
not in ``whats_new.rst`` — Sphinx reports an undefined-citation error
when building the changelog. Replace with an inline parenthetical
("Park et al., Interspeech 2019") so the entry stands on its own.

5 tests (211 lines) → 2 tests (87 lines) with the same contracts.
``test_emg2qwerty_spec_augment_contract`` folds the disabled-default
``nn.Identity`` check, the constructor validation, the train/eval
mutation contrast, the per-(B, band, electrode) independence assertion,
the parameter-free state-dict invariant, and the ``from_config`` round-trip
into one. The mock-patched mask-count helper is hoisted out of the
function body and the per-electrode independence loop is replaced by a
vectorised flatten-and-compare. ``test_emg2qwerty_feature_flags`` covers
all three forward paths (default tensor, runtime dict, init tuple) plus
runtime-wins-over-init, ``get_config`` round-trip, and
``get_output_shape`` invariants in one pass over a shared input.

No behaviour change in the model. All 6 emg2qwerty tests still pass.

- Lazy ``features`` materialisation. ``forward`` was always calling
  ``encoded.transpose(0, 1).contiguous()`` even on the default
  emissions-only path, paying an extra transpose + copy per training
  step regardless of whether the caller set either feature flag. Move
  the transpose into the two branches that actually return the
  features tensor; the default path now stays identical to pre-flag
  behaviour.

- Device-aware RNG in ``_SpecAugment``. The probabilistic gate
  (``torch.rand((), device="cpu").item() >= self.prob``) and the
  mask-count draws (``torch.randint(n+1, ())``) defaulted to CPU,
  which mixed CPU RNG with the device-side RNG that ``torchaudio``'s
  ``mask_along_axis_iid`` uses internally — ``torch.cuda.manual_seed``
  alone would make the gate non-deterministic. Route both through
  ``x.device`` so a single device-appropriate seed reproduces the
  whole augmentation. The ``.item()`` calls are still required for
  the Python ``if``/``range`` bounds (control-flow sync is
  unavoidable).