fix(stage4): fail loudly on out-of-range and non-finite immunogenicity_score (LRF-1)

[Gavin-Borges]

Closes LRF-1. Gavin ruled hard-fail on the failure mode; this implements it, and then a three-lens adversarial review of this branch found three further defects, two of them in the work this branch had already published. All are fixed here.

The defect

immunogenicity_score is documented and consumed downstream as a [0, 1] probability - calibration, thresholding, the ranked CSV. Nothing enforced it.

models/xgb_50feature_integrated.joblib is an XGBClassifier with objective='rank:pairwise', whose predict_proba returns raw margins, not probabilities. Verified directly: it loads with n_features_in_=50 and returns column-1 values from -5.70 to 2.54. In results/local_test_sweep_2026-08-21/merged_leaderboard.csv a mode-50 sweep records mean_score between -4.38 and -4.20 across 40 rows (5 seeds x 8 panels), against rf+mode50's normal 0.686 to 0.702.

That run was still recorded as a success. The mechanism is checkable in tracked code rather than only in that ledger: scripts/batch_experiment_runner.py sets status = "SUCCESS" on the existence of a ranked CSV alone, with no check on the values inside it.

The fix

A range guard at the single point every scoring branch in functions/stage4_immunogenicity_scoring.py converges - after the joblib, PyTorch, prototype and degenerate-constant branches, and before calibration, thresholding and the ranked CSV write. Out-of-range and non-finite values raise RuntimeError naming the model path and the observed range.

No caller-side change was needed: batch_experiment_runner.py's except Exception is broad and pipeline.py's run_pipeline carries no try of its own, so the error propagates and the false SUCCESS becomes an honest FAILED: RuntimeError with the message in notes.

What the adversarial review changed

1. The guard passed NaN silently. (x < 0) | (x > 1) is False for NaN, so a NaN score flowed straight through to ranking - as undetectable downstream as the negative margin the guard exists to stop. Verified reachable rather than assumed: _load_pytorch_model divides by scaler_scale + 1e-10 with no finiteness check, and sigmoid(NaN) is NaN. The predicate is now ~np.isfinite(...) | (x < 0.0) | (x > 1.0), and the message reports the non-finite count separately from the observed finite range so min()/max() are never formatted over a NaN.

2. A false attribution in the CHANGELOG entry, retracted. It said api/main.py's guard was one "the register that raised this item described as ready-made". The register's LRF-1 row says no such thing - it prescribes only "a range assertion at the write boundary, not a retrain", and never mentions api/main.py. That phrase occurs once in the entire tree, in a session planning document that was itself correcting it. This is instance #5's exact shape from .claude/rules/third-party-claims.md: inherited from a planning doc and published without re-verification. The clause is removed rather than reattributed.

3. A compression hazard, corrected. The entry carried a bare -4.38 where the register measured -4.38 to -4.20 across 40 rows - rule 5 of that same file. It now states the range, cites the ledger, and replaces the unsourced status=SUCCESS assertion with the tracked-code mechanism above.

Tests

The original single test pinned neither half of the range check: its fixture is mixed (15 margins below 0, one above 1), so either clause alone still fired and both mutants survived. Caught by a mutation matrix, not by inspection.

• Parametrized onto each side separately (shift=-5.0 fully below 0, shift=+100.0 fully above 1), each with an in-test assertion that the fixture has not drifted off its side.
• New test_joblib_branch_raises_on_nan_score.
• New test_joblib_branch_accepts_exact_bounds - exact 0.0 and 1.0 are valid probabilities, pinning the strict </> against a <=/>= mutant.
• The raises test now also asserts no ranked CSV was written, pinning the guard's stated design point that it fires before any output.

Each of the three clauses is now individually pinned: deleting any one fails its test.

_FakeRankingModel was also made faithful - it now returns rows summing to 1.0 as the real ranker does, which is precisely what makes the bad output look probability-shaped on casual inspection.

Verification

• tests/test_stage4_scoring.py: 41 passed.
• Adjacent stage-4 / pipeline / API / CLI suites: 52 passed.
• Full local pre-push gate: all fast tests passed.
• ruff clean, mypy clean.
• Integrity harness unchanged at 150 PASS / 0 WARN / 2 FAIL / 7 SKIP (the two FAILs are the standing C1/C2 rulings).

Behaviour change, stated plainly

This turns a silent wrong value into a loud crash on a scoring path. That is the intended ruling. The mode-50 path that today reports status=SUCCESS while writing mean_score = -4.38 will now fail that trial explicitly. No certified or public number is affected - feature_mode=50 is documented "Experimental".