fix(biomedical-review): wire focal-BCE loss, schema validator, drop-stats, shuffled-label control

[rollroyces]

Summary

Five additive fixes from the 2026-09-21 biomedical review (see /Users/hermes/.hermes/cache/scratch/deepcatch_biomedical_review.md for the full review document). None change default behavior; all are opt-in flags so existing benchmark numbers are preserved.

Changes

A. SensAtSpecLoss wired into training loops (P0 from review)

src/foundation/losses.py defined a focal-BCE loss purpose-built for ultra-low VAF cohorts ("values in [10, 50] are good starting points for 0.1% VAF analytical cohorts"), but every training loop used F.cross_entropy. Wired focal-BCE as opt-in loss='sens_at_spec' in:

• CrossAttentionFusion (binary only; multi-class TOO stays CE)
• EarlyLateFusion (binary only)
• FoundationDownstream (binary only)

alpha_pos (default 20.0) and gamma (default 2.0) exposed. Invalid loss string raises ValueError at construction time.

B. Modality schema-fingerprint validator

FoundationDownstream.fit() now accepts validate_schema=True which runs _validate_modality_schema before training and raises ValueError on out-of-range per-row medians or negative values in non-negative modalities. Default off. MODALITY_SCHEMAS ships with generous bounds derived from HEALTHY_RANGES. Catches the silent-failure class where the model trains on noise.

C. CAFFCalculator.from_fragments drop-stats counter

Opt-in return_drop_stats=False parameter. When True, returns (per_arm_coverage, drop_stats) where drop_stats is {raw_chrom: n_dropped}. Default False preserves backward compat. Surfaces chrM/unplaced fragment counts that were silently dropped — biologically important because a sample with high mitochondrial contamination otherwise silently becomes a 39-arm template with all-1.0 coverage and reads as a healthy control.

F. Shuffled-label negative control for paired-design validation

real_tcga_validation.py gets --shuffled-label-control and --n-shuffles flags. Computes signal_to_artifact_ratio at TF=0.1% per the cfdna-early-detection-validation skill's diagnostic. Required for Nature Medicine / Cancer Discovery publication readiness. Default off to preserve existing benchmark numbers.

Test changes

13 new tests added (test/test_biomedical_review_fixes.py). Test count grows 66 → 79. All 79 targeted tests pass; 334/335 in broader suite pass (the foundation smoke test is a pre-existing flake on n=40 cohorts, confirmed to fail on main too — unrelated to this change).

What's NOT in this PR (deferred)

From the biomedical review, the following were intentionally deferred because they require more than a small additive fix:

• pretrained=True in FoundationDownstream still loads random-init unless a checkpoint exists (P0 P0 fixes + panel-based MRD benchmark + paper (v2.2.0) #2). Requires real-data pretraining work (separate PR in progress).
• gnn modality 1-D bottleneck (P1) — schema migration, breaks every checkpoint.
• Per-chromosome coverage profile refactor (Pillar 1 finding) — touches every DELFI caller.
• Multi-task head (cancer + TOO + modality quality) — architectural change.
• Sparse-aware LinearProjection for the panel-LLR modality — separate subagent task in progress.

Verification

cd ~/deepcatch
env -u PYTHONPATH ./.venv/bin/python -m pytest \
    test/test_biomedical_review_fixes.py \
    src/foundation/test_integration.py \
    --tb=short --timeout=60 -q
# Result: 79 passed, 11 warnings in 10.38s

env -u PYTHONPATH ./.venv/bin/python \
    real_tcga_validation.py --help | grep shuffled
# Result: --shuffled-label-control and --n-shuffles both appear in --help

🤖 Generated with Claude Code