encryption/aead: document why XChaCha20-Poly1305 stays on RustCrypto

Record the security decision so no future session naively "wires the AEAD
hot path through ndarray::simd::chacha20_keystream" and ends up hand-
composing HChaCha20 + Poly1305 + the AEAD framing (the roll-your-own-AEAD
footgun). The accelerated keystream primitive is trusted and available for
raw-stream use sites that already own a vetted MAC; this authenticated AEAD
is not one of them and keeps the vetted RustCrypto XChaCha20Poly1305.

Doc-only; encryption crate 23/23 green.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01K6pT32kk6pnuAAqR3JiYqu

Author: claude

crates/encryption/src/aead.rs

@@ -5,6 +5,19 @@
 //! is no counter state to persist or synchronise between a browser tab
 //! and a server. Callers normally use [`crate::envelope`], which manages
 //! nonce generation and layout; this module is the raw primitive.
+//!
+//! ## Deliberately NOT hand-composed from `ndarray::simd::chacha20_keystream`
+//!
+//! `ndarray` now ships a hardware-accelerated ChaCha20 keystream
+//! (`ndarray::simd::chacha20_keystream`, AVX-512 / wasm128, byte-parity-proven
+//! against RustCrypto). It is tempting to swap this AEAD's keystream to that
+//! primitive for speed — **do not.** XChaCha20-Poly1305 is not just a keystream:
+//! it is HChaCha20 subkey derivation + the Poly1305 one-time-key + MAC framing +
+//! the AAD/length encoding. Re-wiring only the keystream means re-implementing
+//! that authenticated composition by hand, which is exactly the "roll your own
+//! AEAD" footgun the stack forbids. The vetted RustCrypto `XChaCha20Poly1305`
+//! construction stays here. The accelerated primitive is for *raw-stream* use
+//! sites whose caller already owns a vetted MAC/framing — not this module.
 
 use chacha20poly1305::aead::{Aead, KeyInit, Payload};
 use chacha20poly1305::{Key, XChaCha20Poly1305, XNonce};