feat: v8 factorized decoder cascade — Stage A acoustic model + Stage B conditioned vocoder

[stremtec]

Summary

Replaces the failed monolithic-GAN decoder with a two-stage streaming cascade split at the teacher's 50Hz waist. Stage A (AcousticModel) is a causal replica of the teacher's steps ①–⑤ plus supervised heads that regress mel/logF0/voicing/energy @150hz — this carries all the voice-conversion work. Stage B (ConditionedVocoder) is a causal Vocos-class conv vocoder conditioned on those 150Hz acoustic frames, trained adversarially (MPD + MRD with a mel anchor), with no speaker input. The factorization lets each stage be trained and gated independently (Stage B via copy-synthesis).

Motivation

The prior monolithic adversarial decoder produced non-speech output: 21.5 bits/frame of content conditioning is far below the densely-conditioned regime (mel @ ~10ms) where GAN vocoders are proven, so the generator had to adversarially invent all acoustics and the waveform at once. Splitting the problem — regression for "what should it sound like" (well-posed, stable) and a densely-conditioned GAN for "render it" (the proven regime) — removes that ill-posedness.

Type

• feat — new feature
• fix / refactor / perf / docs / ci / test / chore

Checklist

• Streaming invariance holds — tests/test_streaming_invariant.py passes (encoder unaffected)
• All tests pass — pytest not run this session (training job active; see Verification)
• Lint clean — ruff not run
• Type check clean — mypy not run
• Imports are intact — all 8 astrape.* modules import clean
• No look-ahead introduced — Stage A & B verified future → 0.00e+00
• Architecture doc — design captured in DECODER_V8_DESIGN.md (gitignored per repo *.md policy)

Verification

• Streaming invariance: tests/test_streaming_invariant.py — all passed (stem/encoder truncation/future-padding).
• Strict causality: python -m astrape.decoder_v8 — Stage A mel[:240] and Stage B wav both max_diff = 0.00e+00 on future-perturbation.
• Acoustic target causality: acoustics.py left-aligned framing — perturb-future test shows zero leakage on earlier frames (a centered STFT would silently add ~10ms look-ahead).
• Stage B training (in progress): frame_buzz_val 19 → ~8 dB, mel_sor_cos_val 0.91+, skip=0, stable GAN (d≈3.5, no collapse).

Notes for reviewers

• frame_buzz is a new required metric. HNR/flat_hi/centroid are broadband and blind to the 150Hz frame-rate comb + inter-harmonic valley-fill that made copy-synth "clean but off"; eval_perceptual.py adds harm_clarity + frame_buzz to catch it.
• iSTFT n_fft=882/hop=294 (67% overlap) is a deliberate choice: it suppresses the frame-rate buzz to ~GT level, whereas 50% overlap (588) re-creates it and 75% (1176) — though ideal on paper — is numerically untrainable on MPS (NaN gradients within ~5 steps, resistant to init/lr/warmup/eps fixes).
• Training stability: clamp(mag_log) before exp (avoids fp32 overflow → NaN grad) and --lr-warmup-steps are required; both added here.
• wave_cos is retired as a gate (phase-sensitive → ~0 even for good audio); mel_cos with content-alignment is the similarity gate.

🤖 Generated with Claude Code

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 789f2e9b12

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Return log magnitudes for the MCS distillation loss

train_decoder_mcs unpacks this return_spec=True value as p_mag_log and applies F.l1_loss(p_mag_log, t_mag_log) against the teacher's raw ISTFT-head log magnitudes. Returning the exponentiated/clamped mag here puts the student and teacher on different scales, so the advertised log-magnitude distillation target is wrong and will train the MCS decoder toward incompatible values; return mag_log here or take logs before the loss.

Useful? React with 👍 / 👎.