Add class-balanced secondary particle-type loss (gitea #44)

The v0.3.0 pivot exists because the 2026-08-03 WGAN rollout benchmark
produced zero photon secondaries and ~4M hallucinated antineutrinos —
even with a correctly-sized top-N species vocabulary (gitea #29), plain
cross-entropy over a class distribution spanning orders of magnitude
still under-predicts rare-but-physical species.

stage2_model.particle_type.class_weighting = "none" | "inverse_freq"
(default "none", fully back-compat) weights the stage-2 type head's CE
loss (FlowDDPMStageTrainer._type_loss) by inverse class frequency,
normalized to mean 1 so switching it on doesn't rescale the type loss
against particle_type.lambda / the generator loss it's summed with.

The per-class counts the weighting needs don't already exist despite the
issue's premise: _topn_plus_other_map (giant/data/loader.py) previously
kept counts only for keys folded into "other", dropping the kept classes'
counts on the floor. TopNMap now carries class_counts (index -> count),
round-tripped through the setup-cache sidecar (format version bumped
3->4, since existing sidecars have none) and through checkpoints
(tolerantly — a pre-#44 checkpoint decodes to {}, since only training-time
loss weighting reads it, not inference).

Decisions made during planning (with the user): dropped "effective_num"
from the issue's proposed three-way enum (no beta hyperparameter to
design around) — final domain is "none" | "inverse_freq". Weights are
mean-1-normalized. validate_config rejects class_weighting != "none"
combined with particle_type.target != "onehot" or
stage2_model.generator == "wgan" (both have no class CE to weight),
following the #28/#30 dead-key-must-not-go-silent convention. Branch
fix/issue-44 off master.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

tests/test_setup_cache.py

@@ -99,7 +99,7 @@ def test_save_load_round_trip_topn_maps(tmp_path):
 
     cache = SetupCache.empty(files)
     cache.topn_maps[setup_cache.topn_key("pdg", 3)] = TopNMap(
-        class_map={22: 0, 11: 1, 2212: 2}, other_members={2212: 5}
+        class_map={22: 0, 11: 1, 2212: 2}, other_members={2212: 5}, class_counts={0: 100, 1: 50, 2: 5}
     )
     cache.topn_maps[setup_cache.topn_key("material", 2)] = TopNMap(
         class_map={"G4_AIR": 0, "PbWO4": 1}, other_members={}
@@ -114,9 +114,21 @@ def test_save_load_round_trip_topn_maps(tmp_path):
     assert pdg_m.other_members == {2212: 5}
     # key type is int (matches pdg_map's own key type), not str
     assert all(isinstance(k, int) for k in pdg_m.class_map)
+    # class_counts (gitea #44) round-trips too, keyed by class index (always
+    # int, independent of the pdg/material axis's own key type).
+    assert pdg_m.class_counts == {0: 100, 1: 50, 2: 5}
+    assert all(isinstance(k, int) for k in pdg_m.class_counts)
 
     mat_m = loaded.topn_maps[setup_cache.topn_key("material", 2)]
     assert mat_m.class_map == {"G4_AIR": 0, "PbWO4": 1}
+    assert mat_m.class_counts == {}
+
+
+def test_topnmap_from_json_missing_class_counts_defaults_empty():
+    """A checkpoint's topn map predating gitea #44 has no class_counts key at
+    all — must decode to {}, not raise, since inference never reads it."""
+    m = setup_cache.topnmap_from_json({"class_map": {"11": 0}, "other_members": {}}, axis="pdg")
+    assert m.class_counts == {}
 
 
 def test_topn_key_unknown_axis_raises():