feat(distill): CudaTrainerTeacher — real teacher backend (SPEC-DISTILL-001 Phase 1b, PMAT-693)

[noahgift]

Summary

Adds the real teacher backend SPEC-DISTILL-001 Phase 1b scopes: CudaTrainerTeacher wraps entrenar's CudaTransformerTrainer in inference-only mode and delegates logits_for_batch to forward_logits() per batch element.

Stacks on top of #1786 (Phase 1, the trait + FixtureTeacher). That PR must merge before this one to avoid a cherry-pick.

What this PR adds

#[cfg(feature = "cuda")]
pub struct CudaTrainerTeacher { /* wraps CudaTransformerTrainer */ }

impl CudaTrainerTeacher {
    pub fn for_inference(
        checkpoint_dir: impl AsRef<Path>,
        model_config: TransformerConfig,
    ) -> Result<Self> { ... }
}

impl TeacherLogitsProvider for CudaTrainerTeacher {
    fn vocab_size(&self) -> usize { ... }
    fn logits_for_batch(&mut self, input_ids: &[Vec<u32>])
        -> Result<Vec<Vec<f32>>> { ... }
}

New cuda feature on aprender-train-distill propagates to entrenar/cuda. Without the feature, only FixtureTeacher (Phase 1) is available — sufficient for unit tests but not for real training.

Defensive checks

• forward_logits returning None → EntrenarError::Internal with a clear "likely missing weights or CUDA init failure" message
• logits.len() != vocab_size → EntrenarError::Internal flagging TransformerConfig vs checkpoint vocab drift (the common silent failure mode for loaded-from-disk distillation runs)

Tests

All 6 teacher_provider tests pass under both --features (none) and --features cuda. Compile gates verified:

cargo check -p aprender-train-distill                  # clean
cargo check -p aprender-train-distill --features cuda  # clean

The CudaTrainerTeacher itself doesn't have a unit test that exercises the GPU path — that requires CUDA at test time. F-DISTILL-TEACHER-002 (the 1e-6 byte-parity falsifier) is integration-tested in Phase 4 (production run) and locally with apr run vs CudaTrainerTeacher.logits_for_batch parity scripts.

What's next

• Phase 2 — PMAT-694 (follow-up): wire CudaTransformerTrainer's KD-loss backward into the student path — replaces the remaining build_synthetic_logits call site for the student in pipeline.rs::train(). This is the work that actually starts producing trained student weights.
• Phases 3-6: per SPEC-DISTILL-001.

Test plan

• cargo check -p aprender-train-distill clean
• cargo check -p aprender-train-distill --features cuda clean
• All 6 teacher_provider tests pass under both feature gates
• All 41 aprender-train-distill lib tests pass
• Phase 4 integration parity (F-DISTILL-TEACHER-002): apr run logits vs CudaTrainerTeacher logits byte-equal within 1e-6 absolute

🤖 Generated with Claude Code

[noahgift]

Subsumed by #1797 squash-merge (chain-PR leapfrog pattern per memory rule). All content landed on main at aee8716.