v0.3.0 step 4: type map + particle_type.target = "onehot"/"embedding"

Builds the shared top-N-plus-other PDG/material maps (pooling both primary
and secondary occurrences for PDG, directly targeting the meeting's
species-collapse failure mode) and wires up conditioning.{particle,material}
= "onehot" plus stage2_model.particle_type.target in ("onehot", "embedding")
end-to-end: setup-cache persistence, Stage2OneShot's type_head (flow/ddpm)
vs. folded+ST-Gumbel-relaxed adversarial slice (wgan), and the corresponding
CE/MSE training losses. particle_type.target = "physical" stays byte-for-byte
unchanged, keeping the v0.2 migration shim's bit-identical guarantee intact.
giant predict/rollout fail loudly on a onehot/embedding checkpoint until
full decode support lands in step 6.

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

tests/test_setup_cache.py

@@ -7,6 +7,7 @@ import pandas as pd
 import pytest
 
 from giant.data import setup_cache
+from giant.data.loader import TopNMap
 from giant.data.setup_cache import NormalizerEntry, SetupCache
 from giant.data.transforms import Normalizer
 
@@ -101,6 +102,32 @@ def test_save_load_round_trip(tmp_path):
     np.testing.assert_allclose(entry.energy_quantiles, [1.0, 2.0, 3.0])
 
 
+def test_save_load_round_trip_topn_maps(tmp_path):
+    data = _touch_parquet(tmp_path / "shard.parquet")
+    files = [data]
+
+    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}
+    )
+    cache.topn_maps[setup_cache.topn_key("material", 2)] = TopNMap(
+        class_map={"G4_AIR": 0, "PbWO4": 1}, other_members={}
+    )
+
+    setup_cache.save(data, files, cache)
+    loaded = setup_cache.load(data, files)
+
+    assert loaded is not None
+    pdg_m = loaded.topn_maps[setup_cache.topn_key("pdg", 3)]
+    assert pdg_m.class_map == {22: 0, 11: 1, 2212: 2}
+    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)
+
+    mat_m = loaded.topn_maps[setup_cache.topn_key("material", 2)]
+    assert mat_m.class_map == {"G4_AIR": 0, "PbWO4": 1}
+
+
 def test_load_missing_sidecar_returns_none(tmp_path):
     data = _touch_parquet(tmp_path / "shard.parquet")
     assert setup_cache.load(data, [data]) is None