chore: update changelog for v0.3.4 [skip ci]

Reviewed-on: #72

.bumpversion.toml

@@ -0,0 +1,17 @@
+[tool.bumpversion]
+current_version = "0.3.4"
+parse = "(?P<major>\\d+)\\.(?P<minor>\\d+)\\.(?P<patch>\\d+)"
+serialize = ["{major}.{minor}.{patch}"]
+search = "{current_version}"
+replace = "{new_version}"
+regex = false
+allow_dirty = false
+commit = true
+tag = false
+message = "chore: bump version {current_version} -> {new_version} [skip ci]"
+pre_commit_hooks = ["uv lock", "git add uv.lock"]
+
+[[tool.bumpversion.files]]
+filename = "pyproject.toml"
+search = "version = \"{current_version}\""
+replace = "version = \"{new_version}\""

.gitea/workflows/ci.yml

@@ -88,6 +88,92 @@ jobs:
           name: coverage-report
           path: coverage.xml
 
+  bump-version:
+    name: Bump version, tag, and update changelog on merge to master
+    needs: [ruff-check, ruff-format, type-check, test]
+    if: github.ref == 'refs/heads/master' && github.event_name == 'push'
+    runs-on: ubuntu-latest
+    container:
+      image: docker.gitea.com/runner-images:ubuntu-latest
+      volumes:
+        - /srv/act-runner-cache/uv:/uv-cache
+    steps:
+      # CI_TOKEN needs write:repository scope (not just read) — this job
+      # pushes commits and tags to master, unlike ruff-check/ruff-format/
+      # type-check/test above, which only need to check out the repo.
+      - uses: actions/checkout@v4
+        with:
+          token: ${{ secrets.CI_TOKEN }}
+          fetch-depth: 0
+      - name: Check whether this push is a merge commit
+        id: merge_check
+        run: |
+          PARENTS=$(git rev-parse HEAD^@ | wc -l)
+          echo "HEAD has $PARENTS parent(s)"
+          if [ "$PARENTS" -ge 2 ]; then
+            echo "is_merge=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "is_merge=false" >> "$GITHUB_OUTPUT"
+          fi
+      - uses: astral-sh/setup-uv@v5
+        if: steps.merge_check.outputs.is_merge == 'true'
+        with:
+          enable-cache: false
+      - run: |
+          echo "UV_CACHE_DIR=/uv-cache" >> "$GITHUB_ENV"
+          echo "UV_LINK_MODE=copy" >> "$GITHUB_ENV"
+        if: steps.merge_check.outputs.is_merge == 'true'
+      - run: uv sync --extra cpu --extra dev
+        if: steps.merge_check.outputs.is_merge == 'true'
+      - name: Configure git identity
+        if: steps.merge_check.outputs.is_merge == 'true'
+        run: |
+          git config user.name "gitea-actions"
+          git config user.email "actions@git.larsbogner.de"
+      - name: Bump patch version if this merge didn't already bump it
+        if: steps.merge_check.outputs.is_merge == 'true'
+        run: |
+          OLD_VERSION=$(git show "${{ github.event.before }}:pyproject.toml" 2>/dev/null | grep -m1 '^version = ' | sed -E 's/version = "(.*)"/\1/')
+          CURRENT_VERSION=$(uv version --short)
+          if [ -z "$OLD_VERSION" ]; then
+            echo "Could not read pyproject.toml at github.event.before; falling back to HEAD^1"
+            OLD_VERSION=$(git show "HEAD^1:pyproject.toml" | grep -m1 '^version = ' | sed -E 's/version = "(.*)"/\1/')
+          fi
+          if [ "$OLD_VERSION" = "$CURRENT_VERSION" ]; then
+            echo "Version unchanged by this merge ($CURRENT_VERSION); bumping patch"
+            uv run bump-my-version bump patch --current-version "$CURRENT_VERSION"
+          else
+            echo "Branch already bumped the version ($OLD_VERSION -> $CURRENT_VERSION); skipping auto-bump"
+          fi
+      - name: Update changelog for the current version if not already tagged
+        if: steps.merge_check.outputs.is_merge == 'true'
+        run: |
+          VERSION=$(uv version --short)
+          TAG="v$VERSION"
+          if git rev-parse "$TAG" >/dev/null 2>&1; then
+            echo "Tag $TAG already exists; skipping changelog update"
+          else
+            uv run git-cliff --tag "$TAG" --unreleased --prepend CHANGELOG.md
+            git add CHANGELOG.md
+            if ! git diff --cached --quiet -- CHANGELOG.md; then
+              git commit -m "chore: update changelog for $TAG [skip ci]"
+            else
+              git restore --staged CHANGELOG.md
+            fi
+          fi
+      - name: Push commits and tag the current version
+        if: steps.merge_check.outputs.is_merge == 'true'
+        run: |
+          git push origin HEAD:master
+          VERSION=$(uv version --short)
+          TAG="v$VERSION"
+          if git rev-parse "$TAG" >/dev/null 2>&1; then
+            echo "Tag $TAG already exists"
+          else
+            git tag -a "$TAG" -m "$TAG"
+            git push origin "refs/tags/$TAG"
+          fi
+
   sync-version-on-tag:
     name: Sync project version with tag
     if: startsWith(github.ref, 'refs/tags/')

CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+## [0.3.4] - 2026-08-23
+
+### Added
+
+- Add giant model summary command [gitea #46](https://git.larsbogner.de/lars/giant/issues/46)
+
+- Add per-stage init_from/freeze [gitea #42](https://git.larsbogner.de/lars/giant/issues/42)
+
+- Add bf16 autocast to the training loop [gitea #47](https://git.larsbogner.de/lars/giant/issues/47)
+
+- Add class-balanced secondary particle-type loss [gitea #44](https://git.larsbogner.de/lars/giant/issues/44)
+
+
+### Changed
+
+- Implement stage2_model.stage1_context = "sampled" [gitea #41](https://git.larsbogner.de/lars/giant/issues/41)
+
+- Bump patch version to 0.3.3
+
+- Offset event_id across multi-shard reference reads in giant analyze [gitea #22](https://git.larsbogner.de/lars/giant/issues/22)
+
+- Auto-bump patch version, tag, and update changelog on merge to master [gitea #50](https://git.larsbogner.de/lars/giant/issues/50)
+
+- Document CI_TOKEN's write:repository scope requirement [gitea #50](https://git.larsbogner.de/lars/giant/issues/50)
+
+# Changelog

README.md

@@ -139,6 +139,7 @@ Useful flags on `giant train`:
 - `--router` / `--router-type` / `--n-experts` / `--router-axis` — MoE routing
 - `--wandb` — log per-epoch metrics to Weights & Biases (needs `uv sync --extra wandb`); metric names are `<stage>/<split>/<metric>` plus an unprefixed run-level tail, all derived from `giant/training/trainers.py` `MetricSpec`s
 - `--no-cache-setup` / `--rebuild-setup-cache` — control the setup-stage sidecar cache (vocab maps, event split, normalizer stats); `dwarf warm-cache` precomputes it
+- `--stage1-init-from`/`--stage2-init-from` (checkpoint `.pt`) + `--stage1-freeze`/`--stage2-freeze` — load a stage's weights from another checkpoint and never update them, so the other stage can be retrained alone against a fixed, known-good one while still producing a complete, rollout-capable checkpoint
 
 Config-file-only knobs (no CLI flag — use `--config config.toml`): `stage2_model.autoregressive.teacher_forcing`/`.history`, `stage2_model.particle_type.target`. v0.2 flat-schema configs and checkpoints load fine (auto-migrated).
 

cliff.toml

@@ -0,0 +1,52 @@
+# git-cliff configuration — see https://git-cliff.org/docs/configuration
+#
+# Commit messages in this repo aren't Conventional Commits; they're plain
+# imperative summaries like "Add class-balanced secondary particle-type loss
+# (gitea #44)". Parsing here is tuned to that convention rather than to
+# feat:/fix:-style prefixes.
+
+[changelog]
+header = "# Changelog\n\n"
+body = """
+{% if version %}\
+## [{{ version | trim_start_matches(pat="v") }}] - {{ timestamp | date(format="%Y-%m-%d") }}
+{% else %}\
+## [Unreleased]
+{% endif %}\
+{% for group, commits in commits | group_by(attribute="group") %}
+### {{ group | striptags | trim | upper_first }}
+{% for commit in commits %}
+- {{ commit.message | upper_first }}
+{% endfor %}
+{% endfor %}
+"""
+trim = true
+render_always = true
+postprocessors = []
+
+[git]
+conventional_commits = false
+filter_unconventional = false
+require_conventional = false
+split_commits = false
+# Keep only the commit subject (first line), then linkify "(gitea #N)".
+commit_preprocessors = [
+    { pattern = "(?s)\n.*", replace = "" },
+    { pattern = "\\(gitea #(\\d+)\\)", replace = "[gitea #${1}](https://git.larsbogner.de/lars/giant/issues/${1})" },
+]
+protect_breaking_commits = false
+commit_parsers = [
+    { message = "^Merge ", skip = true },
+    { message = "\\[skip ci\\]", skip = true },
+    { message = "^Add", group = "<!-- 0 -->Added" },
+    { message = "^(Fix|Clamp|Clip)", group = "<!-- 1 -->Fixed" },
+    { message = "^(Remove|Drop|Deprecate)", group = "<!-- 2 -->Removed" },
+    { message = ".*", group = "<!-- 3 -->Changed" },
+]
+filter_commits = false
+link_parsers = []
+use_branch_tags = false
+topo_order = false
+topo_order_commits = true
+sort_commits = "oldest"
+recurse_submodules = false

configs/baseline.toml

@@ -0,0 +1,129 @@
+# GIANT reference baseline (v0.3 schema).
+#
+# The fixed comparison point every future architecture variant is measured
+# against. Chosen so that each experimental axis the roadmap cares about
+# (routed trunk, WGAN generators, attention history, shared conditioning,
+# embedding/onehot conditioning) is a *single* edit away from this file.
+#
+# Rationale for the choices below, from the runs already on record
+# (analysis_runs/ + the `giant` W&B project):
+#
+#   * flow, not wgan, for both stages. Ranking the five existing rollouts by
+#     mean Jensen-Shannon divergence against the Geant4 reference, the plain
+#     non-routed flow model wins (0.172) over the routed flow runs
+#     (0.197/0.200) and both WGAN runs (0.218/0.234) — and it beats them by
+#     ~7x on per-event total deposited energy and by 3-10x on every
+#     per-PDG marginal. WGAN stays a variant, not the reference.
+#
+#   * no router. The routed runs are not better, and soft-mixing 10 small
+#     experts costs ~10x per-pass throughput at train time (29k samples/s vs
+#     the WGAN runs' 52-116k), which is what made those runs take ~110 h for
+#     30 epochs.
+#
+#   * hidden_dim 512 / 6 blocks per stage. The best-scoring rollout so far
+#     was hidden_dim 1024, but at 4x the trunk FLOPs of 512. 512/6 sits in
+#     the same weight class as the variants it will be compared against and
+#     leaves headroom to train it properly rather than cheaply.
+#
+#   * dropout 0.0. Training set is ~5e8 steps against <1e7 parameters;
+#     capacity overfitting is not the binding constraint, and every recent
+#     run used 0.0.
+#
+# Known weak spots this baseline is expected to *exhibit* (they are the
+# reason for the comparisons, not a reason to retune this file): every model
+# on record under-produces steps per event by ~2x (rollout ~7e4 vs Geant4
+# ~1.4e5) and secondaries per event by 2-3.5x (~2-3e4 vs 7.2e4), and n_sec
+# head accuracy sits at 0.863-0.867 regardless of size or objective.
+
+[meta]
+# REQUIRED. Without it config.migrate_config reads this file as v0.2 and
+# rewrites it from V02_FIXED_FACTS — silently forcing decoder = "one_shot",
+# particle_type.target = "physical" and the v0.2 default sizes, while still
+# passing validate_config.
+config_version = 3
+
+[conditioning]
+# Physical-property MLPs rather than learned vocab embeddings: computable for
+# any PDG code / material, which is what the held-out-species and
+# held-out-material generalization comparisons need.
+out_dim      = 128
+share_stages = false
+
+# n_layers = 2 rather than the v0.3 default of 1: v0.2's conditioning MLP was
+# always 2 deep (see _migration.V02_FIXED_FACTS), so this keeps the encoder
+# identical to the architecture that produced the results cited above.
+[conditioning.particle]
+type     = "physical"
+emb_dim  = 16
+n_layers = 2
+
+[conditioning.material]
+type     = "physical"
+emb_dim  = 16
+n_layers = 2
+
+[stage1_model]
+generator    = "flow"
+hidden_dim   = 512
+n_res_blocks = 6
+dropout      = 0.0
+
+[stage2_model]
+# The v0.3 pivot: autoregressive in descending-energy order with a
+# categorical species target, which is the agreed response to the 2026-08-03
+# secondary-species failure. Flow (not the schema default wgan) so the
+# baseline varies only the decoder relative to the best v0.2 result.
+#
+# COST, measured (RTX 4070, bs 4096, 10 ODE steps), not estimated:
+# sample.sample_secondaries_ar loops `for k in range(k_max)` unconditionally
+# — all 15 slots regardless of predicted n_sec — so a flow AR token costs
+# k_max * steps = 150 stage-2 calls per physics step. That makes this block
+# the dominant cost on both sides:
+#   training   flow AR 29.5k samp/s  vs flow one-shot 190.7k samp/s  (6.5x)
+#   inference  flow AR  8.5k step/s  vs flow one-shot  68.7k step/s  (8.1x)
+# Accepted deliberately: one-shot is the configuration whose secondary
+# species distribution failed, and that failure is what v0.3 exists to fix.
+decoder      = "autoregressive"
+generator    = "flow"
+hidden_dim   = 512
+n_res_blocks = 6
+dropout      = 0.0
+k_max        = 15
+
+[stage2_model.autoregressive]
+history         = "markov"
+teacher_forcing = "always"
+
+[stage2_model.particle_type]
+target = "onehot"
+# Decoupled from conditioning.particle.emb_dim (gitea #29). 32 classes + the
+# "other" bucket keeps essentially all real secondary species out of "other"
+# without making the head expensive.
+n_classes    = 32
+other_policy = "sample"
+
+[train]
+epochs        = 50
+# Sized for ONE NVIDIA L40S on deepthought2 (46068 MiB; the box has two, and
+# CLAUDE.md's shared-machine rule allows a single GPU). From a measured
+# linear fit of this exact config's training step on the local RTX 4070:
+#   peak reserved MiB = 0.9736 * batch_size + 115
+# so 36864 reserves ~36.0 GiB, i.e. 78% of the card, leaving ~10 GiB of
+# headroom for fragmentation and the CUDA context. Throughput is already
+# flat above bs~4096 on the 4070, so this is chosen for occupancy on the
+# larger card, not for step efficiency — and it sits next to the 43008/32768
+# of the runs lr = 3e-4 was proven at.
+batch_size    = 36864
+lr            = 3e-4
+warmup_epochs = 3
+weight_decay  = 0.01
+ema_decay     = 0.9999
+val_fraction  = 0.1
+num_workers   = 4
+seed          = 0
+# The marginal/KL pass is expensive (~5000 s on top of an epoch), so keep it
+# to every 10th epoch; the cheap per-epoch val loss still runs every epoch.
+validate_every = 10
+validate_steps = 10
+wandb          = true
+wandb_project  = "giant"

giant/analysis/reduce.py

@@ -29,8 +29,17 @@ from giant.constants import TERM_ESCAPED
 
 
 def _bin_expr(value: pl.Expr, lo: float, hi: float, nbins: int) -> pl.Expr:
-    """Uniform bin index of ``value`` over ``[lo, hi]`` into ``nbins`` bins."""
-    return ((value - lo) / (hi - lo) * nbins).floor().cast(pl.Int32).clip(0, nbins - 1)
+    """Uniform bin index of ``value`` over ``[lo, hi]`` into ``nbins`` bins.
+
+    Out-of-range values clamp into the edge bins, and the clamp deliberately
+    happens in f64 *before* the integer cast: a rollout is free to emit a wildly
+    out-of-range outlier (a step_length of 1e10 mm, say) or an inf, whose
+    unclamped bin index overflows i32 and makes the cast fail outright. NaN has
+    no edge to clamp to, so it becomes null and is dropped by the callers below
+    — the same thing ``np.histogram`` does with it.
+    """
+    idx = ((value - lo) / (hi - lo) * nbins).floor().clip(0, nbins - 1)
+    return pl.when(idx.is_nan()).then(None).otherwise(idx).cast(pl.Int32)
 
 
 def hist1d(
@@ -50,6 +59,7 @@ def hist1d(
     group = pl.lit(0, dtype=pl.Int64) if group is None else group
     res = (
         lf.select(group.alias("_g"), _bin_expr(value, lo, hi, nbins).alias("_b"))
+        .drop_nulls("_b")
         .group_by("_g", "_b")
         .agg(pl.len().alias("_n"))
         .collect(engine="streaming")
@@ -188,6 +198,7 @@ def profile_partial(
             _bin_expr(coord, lo, hi, nbins).alias("_b"),
             weight.alias("_w"),
         )
+        .drop_nulls("_b")
         .group_by("event_id", "_b")
         .agg(pl.col("_w").sum().alias("_ws"))
         .collect(engine="streaming")

giant/analysis/sources.py

@@ -40,6 +40,11 @@ from giant.constants import (
     TERM_MAX_STEPS,
     TERM_UNKNOWN_PDG,
 )
+from giant.data.loader import event_id_offset, find_parquet_files
+
+# Helper column name for the per-shard offset join in open_side; dropped before
+# the LazyFrame is returned, so it never leaks into a caller's schema.
+_SOURCE_PATH_COL = "__source_path"
 
 # The world-frame physical columns both sides share under identical names.
 PHYS_COLS: tuple[str, ...] = (
@@ -108,6 +113,22 @@ def open_side(source: str | Path | pl.LazyFrame, side: Side) -> pl.LazyFrame:
     reference file's upstream ROOT→parquet conversion don't agree on integer
     width, and an uncast mismatch only surfaces later as a ``pl.concat``
     ``SchemaError`` (e.g. in ``build_context``'s pdg-count merge).
+
+    The reference (a rollout's seed ``dataset``) may be a directory of parquet
+    shards, or a ``.manifest`` naming a subset, rather than a single file — each
+    such shard is a separate Geant4 job whose own ``event_id`` numbering
+    restarts from 0, so a multi-shard load offsets every shard's ids by
+    ``giant.data.loader.event_id_offset(file_index)`` to keep them globally
+    unique, exactly as the training/rollout data pipeline already does
+    (``giant/data/loader.py``). ``file_index`` comes from
+    ``find_parquet_files``'s deterministic ordering — the same list and
+    ordering ``giant rollout`` used (via ``_seed_from_data``) to offset the
+    rollout side's own ``event_id``s, so both sides agree on what an
+    ``event_id`` means. There is no overflow guard here (unlike
+    ``loader._offset_event_id``): checking it would cost an eager
+    ``event_id``-column read per shard in every condor compute job, and
+    ``giant rollout`` already ran that check over this exact file list when it
+    produced the seed.
     """
     if isinstance(source, pl.LazyFrame):
         return source.with_columns(pl.col("pdg").cast(pl.Int64))
@@ -116,9 +137,18 @@ def open_side(source: str | Path | pl.LazyFrame, side: Side) -> pl.LazyFrame:
         _check_rollout_metadata(path)
         lf = pl.scan_parquet(path)
     else:
-        # The reference (a rollout's seed `dataset`) may be a directory of
-        # parquet shards rather than a single file — scan them all.
-        lf = pl.scan_parquet(str(path / "**/*.parquet")) if path.is_dir() else pl.scan_parquet(path)
+        files = find_parquet_files(path)
+        if len(files) == 1:
+            lf = pl.scan_parquet(files[0])
+        else:
+            offsets = {str(p): event_id_offset(i) for i, p in enumerate(files)}
+            lf = (
+                pl.scan_parquet(files, include_file_paths=_SOURCE_PATH_COL)
+                .with_columns(
+                    pl.col("event_id") + pl.col(_SOURCE_PATH_COL).replace_strict(offsets, return_dtype=pl.Int64)
+                )
+                .drop(_SOURCE_PATH_COL)
+            )
     return lf.with_columns(pl.col("pdg").cast(pl.Int64))
 
 

giant/cli.py

@@ -41,6 +41,7 @@ from giant.data.transforms import (
 )
 from giant.checkpoint_io import CheckpointCompatibilityError, load_for_inference
 from giant.geometry import GeometryOracle
+from giant.materials import MATERIAL_PROPERTIES
 from giant.pipeline import run_train_job
 from giant.rollout import (
     L1DistCollector,
@@ -487,6 +488,36 @@ def train(
             help="WGAN-GP (--mode wgan only): critic depth for stage 2 (default: same as generator's n_res_blocks)",
         ),
     ] = None,
+    stage1_init_from: Annotated[
+        Optional[Path],
+        typer.Option(
+            "--stage1-init-from",
+            help="Checkpoint .pt to load stage 1's weights from before training starts "
+            "(gitea #42) — combine with --stage1-freeze to retrain stage 2 alone "
+            "against a fixed, known-good stage 1",
+        ),
+    ] = None,
+    stage1_freeze: Annotated[
+        Optional[bool],
+        typer.Option(
+            "--stage1-freeze/--no-stage1-freeze",
+            help="Never update stage 1's weights (requires --stage1-init-from, or --resume)",
+        ),
+    ] = None,
+    stage2_init_from: Annotated[
+        Optional[Path],
+        typer.Option(
+            "--stage2-init-from",
+            help="Checkpoint .pt to load stage 2's weights from before training starts (gitea #42)",
+        ),
+    ] = None,
+    stage2_freeze: Annotated[
+        Optional[bool],
+        typer.Option(
+            "--stage2-freeze/--no-stage2-freeze",
+            help="Never update stage 2's weights (requires --stage2-init-from, or --resume)",
+        ),
+    ] = None,
     val_fraction: Annotated[Optional[float], typer.Option("--val-fraction", "-f")] = None,
     seed: Annotated[
         Optional[int],
@@ -581,6 +612,14 @@ def train(
             "steps (default: 50); per-epoch metrics always log in full",
         ),
     ] = None,
+    precision: Annotated[
+        Optional[str],
+        typer.Option(
+            "--precision",
+            help="Training-step autocast precision: 'fp32' (default) or "
+            "'bf16'. No 'fp16' — see giant.training.amp.resolve_autocast",
+        ),
+    ] = None,
 ) -> None:
     """Train the GIANT surrogate model."""
     batch_size_auto = False
@@ -616,6 +655,7 @@ def train(
         "wandb_project": wandb_project,
         "wandb_run_name": wandb_run_name,
         "wandb_log_every": wandb_log_every,
+        "precision": precision,
         "hidden_dim": hidden_dim,
         "n_blocks": n_blocks,
         "dropout": dropout,
@@ -651,11 +691,15 @@ def train(
         "stage1_critic_n_res_blocks": stage1_critic_n_res_blocks,
         "stage2_critic_hidden_dim": stage2_critic_hidden_dim,
         "stage2_critic_n_res_blocks": stage2_critic_n_res_blocks,
+        "stage1_init_from": str(stage1_init_from) if stage1_init_from is not None else None,
+        "stage1_freeze": stage1_freeze,
+        "stage2_init_from": str(stage2_init_from) if stage2_init_from is not None else None,
+        "stage2_freeze": stage2_freeze,
     }
     overrides = gconfig.overrides_from_flags(flag_values)
 
     cfg = gconfig.merge_cli_overrides(gconfig.DEFAULT_CONFIG, config, overrides)
-    gconfig.validate_config(cfg)
+    gconfig.validate_config(cfg, resume=resume is not None)
     t = cfg["train"]
 
     _device = torch.device(device) if device else gconfig.auto_device()
@@ -690,6 +734,7 @@ def train(
 
     typer.echo(f"device:  {_device}")
     typer.echo(f"out_dir: {out_dir}")
+    typer.echo(f"precision: {t['precision']}")
 
     run_train_job(
         data=data,
@@ -735,6 +780,10 @@ def new_run(
     stage2_k_max: Annotated[Optional[int], typer.Option("--stage2-k-max")] = None,
     stage2_context_dim: Annotated[Optional[int], typer.Option("--stage2-context-dim")] = None,
     stage2_stage1_context: Annotated[Optional[Stage1Context], typer.Option("--stage2-stage1-context")] = None,
+    stage1_init_from: Annotated[Optional[Path], typer.Option("--stage1-init-from")] = None,
+    stage1_freeze: Annotated[Optional[bool], typer.Option("--stage1-freeze/--no-stage1-freeze")] = None,
+    stage2_init_from: Annotated[Optional[Path], typer.Option("--stage2-init-from")] = None,
+    stage2_freeze: Annotated[Optional[bool], typer.Option("--stage2-freeze/--no-stage2-freeze")] = None,
     conditioning: Annotated[Optional[Conditioning], typer.Option("--conditioning")] = None,
     router: Annotated[Optional[bool], typer.Option("--router/--no-router")] = None,
     router_type: Annotated[Optional[str], typer.Option("--router-type")] = None,
@@ -795,6 +844,10 @@ def new_run(
         "stage2_k_max": stage2_k_max,
         "stage2_context_dim": stage2_context_dim,
         "stage2_stage1_context": stage2_stage1_context.value if stage2_stage1_context is not None else None,
+        "stage1_init_from": str(stage1_init_from) if stage1_init_from is not None else None,
+        "stage1_freeze": stage1_freeze,
+        "stage2_init_from": str(stage2_init_from) if stage2_init_from is not None else None,
+        "stage2_freeze": stage2_freeze,
         "mode": mode.value if mode is not None else None,
         "stage1_generator": stage1_generator.value if stage1_generator is not None else None,
         "stage2_generator": stage2_generator.value if stage2_generator is not None else None,
@@ -854,6 +907,52 @@ def new_run(
     typer.echo(f"  giant train {data_arg} --config {config_path} --out {run_dir}")
 
 
+model_app = typer.Typer(
+    no_args_is_help=True,
+    help="Inspect a resolved model architecture without training.",
+)
+app.add_typer(model_app, name="model")
+
+
+@model_app.command("summary")
+def model_summary(
+    config: Annotated[
+        Optional[Path],
+        typer.Option("--config", "-c", help="TOML config file (default: built-in defaults)"),
+    ] = None,
+    pdg_vocab: Annotated[
+        int,
+        typer.Option(
+            "--pdg-vocab",
+            help="Placeholder PDG vocab size for conditioning.particle.type='embedding' "
+            "or a pdg/process router (no dataset attached to derive the real training vocab)",
+        ),
+    ] = 300,
+    mat_vocab: Annotated[
+        int,
+        typer.Option(
+            "--mat-vocab",
+            help="Placeholder material vocab size for conditioning.material.type='embedding' "
+            "or a process router (default: the number of known materials in giant.materials)",
+        ),
+    ] = len(MATERIAL_PROPERTIES),
+) -> None:
+    """Build the resolved model graph from a config with no dataset attached, and
+    print per-module parameter counts, trunk widths, which heads exist, and which
+    conditioning/stage1_model/stage2_model config keys actually shaped it."""
+    from giant.model.summary import render_summary, summarize_model
+
+    cfg = gconfig.merge_cli_overrides(gconfig.DEFAULT_CONFIG, config, {})
+    try:
+        gconfig.validate_config(cfg)
+    except ValueError as exc:
+        typer.echo(f"error: {exc}", err=True)
+        raise typer.Exit(1)
+
+    summary = summarize_model(cfg, pdg_vocab=pdg_vocab, mat_vocab=mat_vocab)
+    typer.echo(render_summary(summary))
+
+
 @app.command()
 def predict(
     data: Annotated[Path, typer.Argument(help="Parquet file or directory of parquet files")],
@@ -1043,8 +1142,12 @@ def predict(
             # A fresh v0.3.0 Stage1Model owns no n_sec_head —
             # sample_stage1 returns n_sec_pred=None then, so ask stage 2.
             n_sec_pred = resolve_n_sec(model, sec_decoder, cc, ck, stage1_norm, n_sec_pred)
-            sec_cont, sec_type, _sec_valid_pred = sample_stage2(sec_decoder, cc, ck, stage1_norm, n_sec_pred, steps)
-            n_sec_pred_np = n_sec_pred.cpu().numpy()
+            sec_cont, sec_type, sec_valid_pred = sample_stage2(sec_decoder, cc, ck, stage1_norm, n_sec_pred, steps)
+            # A stop-token decoder resolves n_sec_pred=None above — read the
+            # real count back off sec_valid_pred instead (a no-op round trip
+            # under every other n_sec.mode, where sec_valid_pred was built
+            # FROM n_sec_pred in the first place).
+            n_sec_pred_np = sec_valid_pred.sum(dim=-1).cpu().numpy()
 
         pred = stage1_norm.cpu().numpy()  # normalised
 

giant/cond_layout.py

@@ -0,0 +1,103 @@
+"""Single source of truth for the conditioning arrays' column layout (gitea #37).
+
+`cond_cont` and `cond_cat` are built in `giant.data.transforms` and consumed in
+`giant.model.encoders` / `giant.model.routers`. Their column order used to be
+written down independently on each side, kept in sync only by parallel comments
+— so getting it wrong produced silently mis-indexed columns rather than an
+exception, and adding a conditioning axis meant a coordinated multi-file edit.
+
+`CondLayout` owns that order. Both sides construct one from the same
+`conditioning.particle.type` / `conditioning.material.type` pair and read named
+slices off it, so the layout is stated exactly once. This module depends only on
+`giant.constants`, so both the data and model packages can import it.
+"""
+
+from dataclasses import dataclass
+from typing import ClassVar
+
+from giant.constants import COND_DIM, COND_DIM_BASE, MATERIAL_PHYS_DIM, PARTICLE_PHYS_DIM
+
+# The three per-axis conditioning modes. Mirrors giant.config.Conditioning,
+# which this module deliberately does not import (giant.config pulls in the
+# whole model package).
+AXIS_TYPES = ("physical", "embedding", "onehot")
+
+
+@dataclass(frozen=True)
+class CondLayout:
+    """Column layout of `cond_cont`/`cond_cat` for one (particle, material) mode pair.
+
+    `cond_cont` is unconditionally `COND_DIM` wide regardless of mode: the base
+    block, then the particle physical block, then the material physical block.
+    An axis that isn't `"physical"` gets its block zero-filled and never reads
+    it (see `giant.data.transforms._physical_cond_columns`), so the widths are
+    mode-independent and only the *meaning* of a block changes.
+
+    `cond_cat` is 2 to 4 wide. Columns `PDG_COL`/`MAT_COL` are always the dense
+    training-vocab index; an axis in `"onehot"` mode appends one more column
+    holding its top-N-plus-other class index, particle before material.
+    """
+
+    particle_type: str
+    material_type: str
+
+    # cond_cat's dense-vocab columns, present in every mode. Under
+    # "physical"/"onehot" they are a reporting/router convenience the
+    # ConditionEncoder never reads; under "embedding" they are the signal.
+    PDG_COL: ClassVar[int] = 0
+    MAT_COL: ClassVar[int] = 1
+
+    def __post_init__(self) -> None:
+        if self.particle_type not in AXIS_TYPES:
+            raise ValueError(f"unknown conditioning.particle.type {self.particle_type!r}")
+        if self.material_type not in AXIS_TYPES:
+            raise ValueError(f"unknown conditioning.material.type {self.material_type!r}")
+
+    @classmethod
+    def from_types(cls, particle_type: str, material_type: str) -> "CondLayout":
+        """Named constructor — the entry point both sides use."""
+        return cls(particle_type=particle_type, material_type=material_type)
+
+    # --- cond_cont ---------------------------------------------------------
+
+    @property
+    def base(self) -> slice:
+        """pre_pos(3), log(pre_E)(1), pre_dir(3), layer_id(1)."""
+        return slice(0, COND_DIM_BASE)
+
+    @property
+    def particle_phys(self) -> slice:
+        """log(mass), charge — see `giant.particles`."""
+        return slice(COND_DIM_BASE, COND_DIM_BASE + PARTICLE_PHYS_DIM)
+
+    @property
+    def material_phys(self) -> slice:
+        """Z_eff, A_eff, log(density), log(X0), log(lambda_int) — see `giant.materials`."""
+        start = COND_DIM_BASE + PARTICLE_PHYS_DIM
+        return slice(start, start + MATERIAL_PHYS_DIM)
+
+    @property
+    def cont_dim(self) -> int:
+        return COND_DIM
+
+    # --- cond_cat ----------------------------------------------------------
+
+    @property
+    def particle_topn_col(self) -> int | None:
+        """Column of the particle top-N class index, or `None` if not `"onehot"`."""
+        return self.MAT_COL + 1 if self.particle_type == "onehot" else None
+
+    @property
+    def material_topn_col(self) -> int | None:
+        """Column of the material top-N class index, or `None` if not `"onehot"`.
+
+        Comes after the particle top-N column when both axes are `"onehot"`.
+        """
+        if self.material_type != "onehot":
+            return None
+        return self.MAT_COL + (2 if self.particle_type == "onehot" else 1)
+
+    @property
+    def cat_dim(self) -> int:
+        """Total `cond_cat` width: 2, plus one column per `"onehot"` axis."""
+        return self.MAT_COL + 1 + (self.particle_type == "onehot") + (self.material_type == "onehot")

giant/config.py

@@ -15,6 +15,7 @@ import numpy as np
 import torch
 
 from giant._migration import V02_FIXED_FACTS, V02_MODEL_KEY_TO_STAGES, reject_legacy_router_expert_sizing
+from giant.model.history import HISTORY_REGISTRY
 
 
 class Conditioning(str, Enum):
@@ -336,6 +337,35 @@ class RouterConfig:
         }
 
 
+@dataclass(frozen=True)
+class TrunkConfig:
+    """`stage1_model.trunk`/`stage2_model.trunk`: selects the trunk's expert
+    *body* architecture from `giant.model.trunks.TRUNK_REGISTRY` (default
+    `"resmlp"` — today's only body, `input_proj -> ResBlock stack ->
+    out_proj`). Orthogonal to whether that body is mixed: mixing is still
+    controlled entirely by `router.enabled`/`router.n_experts` on the same
+    stage, unaffected by this block. A future body's own hyperparameters
+    (e.g. a transformer's `n_heads`/`n_layers`) would get their own sibling
+    field here, matching how `flow`/`ddpm`/`wgan` already coexist selected by
+    `generator`.
+
+    `block_conditioning` selects each body's conditioning-injection mechanism
+    from `giant.model.layers.BLOCK_REGISTRY` — `"add"` (default, today's
+    conditional-bias `ResBlock`, bit-identical to pre-gitea-#34 behaviour),
+    `"film"`, or `"adaln"`."""
+
+    type: str = "resmlp"
+    block_conditioning: str = "add"
+
+    @classmethod
+    def from_dict(cls, d: dict | None) -> "TrunkConfig":
+        d = d or {}
+        return cls(type=d.get("type", "resmlp"), block_conditioning=d.get("block_conditioning", "add"))
+
+    def to_dict(self) -> dict:
+        return {"type": self.type, "block_conditioning": self.block_conditioning}
+
+
 @dataclass(frozen=True)
 class Stage2RouterConfig(RouterConfig):
     # true: stage 2 shares stage 1's Router module instance, so expert i in
@@ -378,18 +408,27 @@ class Stage2RouterConfig(RouterConfig):
 class NSecConfig:
     # "head": a classifier over {0..k_max} on the condition encoding alone
     # (no diffusion noise), callable independently at inference.
-    # "stop_token": an EOS-style implicit stop — accepted by the schema but
-    # not implemented in v0.3.0 (see validate_config).
+    # "stop_token": an EOS-style per-slot stop head on the autoregressive
+    # secondary decoder (Stage2Autoregressive only — see validate_config),
+    # evaluated against the generated prefix instead of conditioning alone.
+    # Replaces n_sec_head entirely: the two are mutually exclusive, so this
+    # mode builds no n_sec_head and stage2_model.n_sec.lambda instead weights
+    # the stop head's BCE term.
     # "truth": take n_sec from ground truth — standalone stage-2 evaluation
     # only, never for rollout.
     mode: str = "head"
-    lambda_weight: float = 0.1  # dict key "lambda" — cross-entropy weight for the head
+    lambda_weight: float = 0.1  # dict key "lambda" — cross-entropy/BCE weight for the head
     # Which stage's module physically owns the n_sec_head weights: "stage2" (default,
     # fresh v0.3.0 runs — Stage2OneShot/Stage2Autoregressive builds it) or "stage1"
     # (a migrated v0.2 checkpoint — see network._migrate_legacy_model_config, whose
     # n_sec head was trained against Stage 1's own ConditionEncoder output and so has
     # to stay attached there, not just be labeled as such).
     owner: str = "stage2"
+    # mode="stop_token" only: how sample_secondaries_ar turns a slot's stop logit into a
+    # stop/continue decision. "greedy": sigmoid(logit) >= 0.5 (deterministic). "sample":
+    # a Bernoulli draw at sigmoid(logit) (a real sample from the learned length
+    # distribution, at the cost of an extra RNG draw per slot).
+    stop_sampling: str = "greedy"
 
     @classmethod
     def from_dict(cls, d: dict | None) -> "NSecConfig":
@@ -398,10 +437,16 @@ class NSecConfig:
             mode=d.get("mode", "head"),
             lambda_weight=d.get("lambda", 0.1),
             owner=d.get("owner", "stage2"),
+            stop_sampling=d.get("stop_sampling", "greedy"),
         )
 
     def to_dict(self) -> dict:
-        return {"mode": self.mode, "lambda": self.lambda_weight, "owner": self.owner}
+        return {
+            "mode": self.mode,
+            "lambda": self.lambda_weight,
+            "owner": self.owner,
+            "stop_sampling": self.stop_sampling,
+        }
 
 
 @dataclass(frozen=True)
@@ -423,6 +468,18 @@ class ParticleTypeConfig:
     # silently the same number). 0 = inherit conditioning.particle.emb_dim,
     # preserving pre-#29 behavior.
     n_classes: int = 0
+    # Class-balances the target = "onehot" cross-entropy loss against the
+    # secondary-species long tail (gitea #44: the failure mode motivating the
+    # v0.3.0 pivot was specifically a species collapse — zero photon
+    # secondaries, hallucinated antineutrinos). "none": plain CE (pre-#44
+    # behavior). "inverse_freq": CE weighted by 1/count per class,
+    # normalized to mean 1 across classes so lambda_weight doesn't need
+    # retuning when this is switched on. validate_config requires target =
+    # "onehot" and stage2_model.generator != "wgan" whenever this isn't
+    # "none" — "embedding"/"physical" have no class CE to weight, and the
+    # WGAN stage-2 path feeds its type slice to the critic via a
+    # straight-through Gumbel relaxation instead of a CE loss.
+    class_weighting: str = "none"
 
     @classmethod
     def from_dict(cls, d: dict | None) -> "ParticleTypeConfig":
@@ -432,6 +489,7 @@ class ParticleTypeConfig:
             lambda_weight=d.get("lambda", 1.0),
             other_policy=d.get("other_policy", "sample"),
             n_classes=d.get("n_classes", 0),
+            class_weighting=d.get("class_weighting", "none"),
         )
 
     def to_dict(self) -> dict:
@@ -440,6 +498,7 @@ class ParticleTypeConfig:
             "lambda": self.lambda_weight,
             "other_policy": self.other_policy,
             "n_classes": self.n_classes,
+            "class_weighting": self.class_weighting,
         }
 
 
@@ -486,11 +545,82 @@ class AutoregressiveConfig:
         }
 
 
+@dataclass(frozen=True)
+class HeadConfig:
+    """A single classifier head's shape — `n_sec_head`/`type_head` (gitea
+    #36 deduplicated their five identical hand-rolled
+    `Linear -> SiLU -> Linear` definitions into
+    `giant.model.layers.build_mlp_head`, which this config drives).
+    `hidden_ratio=0.5`/`depth=2` are the exact pre-#36 hardcoded values
+    (hidden width = `hidden_dim // 2`, one hidden layer), so omitting a
+    `heads` block — including every migrated v0.2 config — reproduces the
+    old architecture bit-for-bit."""
+
+    hidden_ratio: float = 0.5  # hidden width = round(hidden_dim * hidden_ratio)
+    depth: int = 2  # matches build_mlp_head's depth
+
+    @classmethod
+    def from_dict(cls, d: dict | None) -> "HeadConfig":
+        d = d or {}
+        return cls(hidden_ratio=d.get("hidden_ratio", 0.5), depth=d.get("depth", 2))
+
+    def to_dict(self) -> dict:
+        return {"hidden_ratio": self.hidden_ratio, "depth": self.depth}
+
+
+@dataclass(frozen=True)
+class Stage1HeadsConfig:
+    """Stage 1 only ever owns `n_sec_head`, and only for a migrated v0.2
+    checkpoint (`stage2_model.n_sec.owner = "stage1"`) — see
+    `Stage1Model`'s docstring."""
+
+    n_sec: HeadConfig = field(default_factory=HeadConfig)
+
+    @classmethod
+    def from_dict(cls, d: dict | None) -> "Stage1HeadsConfig":
+        d = d or {}
+        return cls(n_sec=HeadConfig.from_dict(d.get("n_sec")))
+
+    def to_dict(self) -> dict:
+        return {"n_sec": self.n_sec.to_dict()}
+
+
+@dataclass(frozen=True)
+class Stage2HeadsConfig:
+    """`n_sec` and `type` are independently configurable — n_sec accuracy
+    and secondary-species accuracy are separately known weak spots (gitea
+    #36)."""
+
+    n_sec: HeadConfig = field(default_factory=HeadConfig)
+    type: HeadConfig = field(default_factory=HeadConfig)
+
+    @classmethod
+    def from_dict(cls, d: dict | None) -> "Stage2HeadsConfig":
+        d = d or {}
+        return cls(n_sec=HeadConfig.from_dict(d.get("n_sec")), type=HeadConfig.from_dict(d.get("type")))
+
+    def to_dict(self) -> dict:
+        return {"n_sec": self.n_sec.to_dict(), "type": self.type.to_dict()}
+
+
 @dataclass(frozen=True)
 class Stage1ModelConfig:
     # false skips building/training stage 1 entirely. The resulting
     # checkpoint holds only stage 2 and cannot be rolled out.
     active: bool = True
+    # Checkpoint .pt to load this stage's weights from before training starts
+    # (its own "model"/"sec_decoder" key, not this run's own resume state) —
+    # "" means start from a fresh init. See `freeze` below for the partial-
+    # retrain use case this exists for (gitea #42).
+    init_from: str = ""
+    # true keeps this stage's weights exactly as loaded from `init_from` —
+    # forward/backward still run every batch (so its loss/grad_norm metrics
+    # stay meaningful, and a WGAN stage's critic still gets a real signal to
+    # report), but its optimizer never steps. Lets a rollout-capable
+    # checkpoint retrain only the *other* stage against a fixed, known-good
+    # one (gitea #42) — `validate_config` requires `init_from` to be set
+    # whenever this is true, unless the run is a `--resume`.
+    freeze: bool = False
     # "flow": conditional flow matching (~10 ODE steps at inference).
     # "ddpm": cosine-schedule diffusion baseline.
     # "wgan": WGAN-GP, single forward pass at inference.
@@ -509,12 +639,16 @@ class Stage1ModelConfig:
     ddpm: DdpmConfig = field(default_factory=DdpmConfig)
     wgan: Stage1WganConfig = field(default_factory=Stage1WganConfig)
     router: RouterConfig = field(default_factory=RouterConfig)
+    trunk: TrunkConfig = field(default_factory=TrunkConfig)
+    heads: Stage1HeadsConfig = field(default_factory=Stage1HeadsConfig)
 
     @classmethod
     def from_dict(cls, d: dict | None) -> "Stage1ModelConfig":
         d = d or {}
         return cls(
             active=d.get("active", True),
+            init_from=d.get("init_from", ""),
+            freeze=d.get("freeze", False),
             generator=d.get("generator", "flow"),
             hidden_dim=d.get("hidden_dim", 256),
             n_res_blocks=d.get("n_res_blocks", 6),
@@ -524,11 +658,15 @@ class Stage1ModelConfig:
             ddpm=DdpmConfig.from_dict(d.get("ddpm")),
             wgan=Stage1WganConfig.from_dict(d.get("wgan")),
             router=RouterConfig.from_dict(d.get("router")),
+            trunk=TrunkConfig.from_dict(d.get("trunk")),
+            heads=Stage1HeadsConfig.from_dict(d.get("heads")),
         )
 
     def to_dict(self) -> dict:
         return {
             "active": self.active,
+            "init_from": self.init_from,
+            "freeze": self.freeze,
             "generator": self.generator,
             "hidden_dim": self.hidden_dim,
             "n_res_blocks": self.n_res_blocks,
@@ -538,6 +676,8 @@ class Stage1ModelConfig:
             "ddpm": self.ddpm.to_dict(),
             "wgan": self.wgan.to_dict(),
             "router": self.router.to_dict(),
+            "trunk": self.trunk.to_dict(),
+            "heads": self.heads.to_dict(),
         }
 
 
@@ -546,6 +686,9 @@ class Stage2ModelConfig:
     # false trains stage 1 alone. giant rollout must then refuse the
     # checkpoint; giant predict still works.
     active: bool = True
+    # See Stage1ModelConfig.init_from/.freeze — same semantics, this stage.
+    init_from: str = ""
+    freeze: bool = False
     # "one_shot": predict all k_max slots simultaneously with padded slots
     # masked from the loss (v0.2 behaviour).
     # "autoregressive": emit one secondary at a time in descending-energy
@@ -568,6 +711,13 @@ class Stage2ModelConfig:
     # output, closing the train/inference gap at the cost of a sampling pass
     # per batch and a moving target early in training.
     stage1_context: str = "truth"
+    # Ramp for "sampled": P(condition on the ground-truth stage-1 outcome
+    # rather than a fresh sample), linearly interpolated from ctx_p_start
+    # (epoch 0) to ctx_p_end (the final epoch) — the same scheduled-sampling
+    # shape as autoregressive.tf_p_start/tf_p_end, so stage 2 doesn't chase a
+    # wildly moving stage-1 target in early epochs. Unread under "truth".
+    ctx_p_start: float = 1.0
+    ctx_p_end: float = 0.0
     n_sec: NSecConfig = field(default_factory=NSecConfig)
     particle_type: ParticleTypeConfig = field(default_factory=ParticleTypeConfig)
     autoregressive: AutoregressiveConfig = field(default_factory=AutoregressiveConfig)
@@ -575,12 +725,16 @@ class Stage2ModelConfig:
     ddpm: DdpmConfig = field(default_factory=DdpmConfig)
     wgan: Stage2WganConfig = field(default_factory=Stage2WganConfig)
     router: Stage2RouterConfig = field(default_factory=Stage2RouterConfig)
+    trunk: TrunkConfig = field(default_factory=TrunkConfig)
+    heads: Stage2HeadsConfig = field(default_factory=Stage2HeadsConfig)
 
     @classmethod
     def from_dict(cls, d: dict | None) -> "Stage2ModelConfig":
         d = d or {}
         return cls(
             active=d.get("active", True),
+            init_from=d.get("init_from", ""),
+            freeze=d.get("freeze", False),
             decoder=d.get("decoder", "autoregressive"),
             generator=d.get("generator", "wgan"),
             hidden_dim=d.get("hidden_dim", 256),
@@ -590,6 +744,8 @@ class Stage2ModelConfig:
             k_max=d.get("k_max", 15),
             context_dim=d.get("context_dim", 64),
             stage1_context=d.get("stage1_context", "truth"),
+            ctx_p_start=d.get("ctx_p_start", 1.0),
+            ctx_p_end=d.get("ctx_p_end", 0.0),
             n_sec=NSecConfig.from_dict(d.get("n_sec")),
             particle_type=ParticleTypeConfig.from_dict(d.get("particle_type")),
             autoregressive=AutoregressiveConfig.from_dict(d.get("autoregressive")),
@@ -597,11 +753,15 @@ class Stage2ModelConfig:
             ddpm=DdpmConfig.from_dict(d.get("ddpm")),
             wgan=Stage2WganConfig.from_dict(d.get("wgan")),
             router=Stage2RouterConfig.from_dict(d.get("router")),
+            trunk=TrunkConfig.from_dict(d.get("trunk")),
+            heads=Stage2HeadsConfig.from_dict(d.get("heads")),
         )
 
     def to_dict(self) -> dict:
         return {
             "active": self.active,
+            "init_from": self.init_from,
+            "freeze": self.freeze,
             "decoder": self.decoder,
             "generator": self.generator,
             "hidden_dim": self.hidden_dim,
@@ -611,6 +771,8 @@ class Stage2ModelConfig:
             "k_max": self.k_max,
             "context_dim": self.context_dim,
             "stage1_context": self.stage1_context,
+            "ctx_p_start": self.ctx_p_start,
+            "ctx_p_end": self.ctx_p_end,
             "n_sec": self.n_sec.to_dict(),
             "particle_type": self.particle_type.to_dict(),
             "autoregressive": self.autoregressive.to_dict(),
@@ -618,6 +780,8 @@ class Stage2ModelConfig:
             "ddpm": self.ddpm.to_dict(),
             "wgan": self.wgan.to_dict(),
             "router": self.router.to_dict(),
+            "trunk": self.trunk.to_dict(),
+            "heads": self.heads.to_dict(),
         }
 
 
@@ -651,6 +815,12 @@ class TrainConfig:
     # thousands of steps. Per-epoch metrics (the metrics.csv row) always log
     # in full.
     wandb_log_every: int = 50
+    # Training-step autocast dtype: "fp32" (default, no autocast) or "bf16".
+    # No "fp16" — GradScaler and the double-backward in
+    # giant.model.wgan.gradient_penalty don't mix well, and bf16 alone covers
+    # every training GPU in the fleet (Ampere and newer). See
+    # giant.training.amp.resolve_autocast (gitea #47).
+    precision: str = "fp32"
 
     @classmethod
     def from_dict(cls, d: dict | None) -> "TrainConfig":
@@ -672,6 +842,7 @@ class TrainConfig:
             wandb_project=d.get("wandb_project", "giant"),
             wandb_run_name=d.get("wandb_run_name", ""),
             wandb_log_every=d.get("wandb_log_every", 50),
+            precision=d.get("precision", "fp32"),
         )
 
     def to_dict(self) -> dict:
@@ -692,6 +863,7 @@ class TrainConfig:
             "wandb_project": self.wandb_project,
             "wandb_run_name": self.wandb_run_name,
             "wandb_log_every": self.wandb_log_every,
+            "precision": self.precision,
         }
 
 
@@ -728,6 +900,25 @@ class GiantConfig:
 DEFAULT_CONFIG: dict = GiantConfig().to_dict()
 
 
+def leaf_paths(node: dict, prefix: str = "") -> list[str]:
+    """Every dotted leaf path in a DEFAULT_CONFIG-shaped dict, e.g.
+    "stage1_model.router.n_experts". `[meta]` (run provenance, no schema
+    counterpart) is skipped at the top level, matching `validate_config_keys`.
+    Shared by `tests/test_config_consumed_keys.py` (the static per-identifier
+    audit) and `giant.model.summary` (the runtime per-config audit, gitea
+    #46) so both walk the exact same tree."""
+    paths = []
+    for key, value in node.items():
+        if prefix == "" and key == "meta":
+            continue
+        path = f"{prefix}.{key}" if prefix else key
+        if isinstance(value, dict):
+            paths.extend(leaf_paths(value, path))
+        else:
+            paths.append(path)
+    return paths
+
+
 def git_hash() -> str:
     try:
         return subprocess.check_output(["git", "rev-parse", "HEAD"], stderr=subprocess.DEVNULL).decode().strip()
@@ -945,6 +1136,7 @@ FLAG_SPECS: tuple[FlagSpec, ...] = (
     FlagSpec("wandb_project", ("train.wandb_project",)),
     FlagSpec("wandb_run_name", ("train.wandb_run_name",)),
     FlagSpec("wandb_log_every", ("train.wandb_log_every",)),
+    FlagSpec("precision", ("train.precision",)),
     # --hidden-dim/--n-blocks/--dropout are stage-1-only backward-compat
     # shorthands (they predate stage2_model having its own flags);
     # --stage1-* wins when both are given.
@@ -997,6 +1189,13 @@ FLAG_SPECS: tuple[FlagSpec, ...] = (
     FlagSpec("stage1_critic_n_res_blocks", ("stage1_model.wgan.critic_n_res_blocks",)),
     FlagSpec("stage2_critic_hidden_dim", ("stage2_model.wgan.critic_hidden_dim",)),
     FlagSpec("stage2_critic_n_res_blocks", ("stage2_model.wgan.critic_n_res_blocks",)),
+    # Partial-retrain (gitea #42): stage-scoped only, no shared alias — a
+    # shared "freeze both stages from the same file" flag has no sensible
+    # meaning (a checkpoint has one set of weights per stage).
+    FlagSpec("stage1_init_from", ("stage1_model.init_from",)),
+    FlagSpec("stage1_freeze", ("stage1_model.freeze",)),
+    FlagSpec("stage2_init_from", ("stage2_model.init_from",)),
+    FlagSpec("stage2_freeze", ("stage2_model.freeze",)),
 )
 
 
@@ -1229,7 +1428,7 @@ def merge_cli_overrides(
     return cfg
 
 
-def validate_config(cfg: dict) -> None:
+def validate_config(cfg: dict, *, resume: bool = False) -> None:
     """Cross-block validation the per-block schema can't express on its own.
 
     Raises ValueError with a clear message on the first violation found. Call
@@ -1237,6 +1436,10 @@ def validate_config(cfg: dict) -> None:
     these checks need to see across blocks, so they don't belong in
     `migrate_config` (which only ever sees one dict's own keys) or in any
     single block's defaults.
+
+    `resume=True` (only `giant train --resume` passes this) relaxes the
+    `stage{1,2}_model.freeze` -> `.init_from` requirement below: a resumed
+    frozen stage's weights come from the resume checkpoint, not `init_from`.
     """
     particle_type = _get_path(cfg, "conditioning.particle.type")
 
@@ -1249,7 +1452,34 @@ def validate_config(cfg: dict) -> None:
             f"{particle_type!r})"
         )
 
+    class_weighting = _get_path(cfg, "stage2_model.particle_type.class_weighting")
+    if class_weighting not in ("none", "inverse_freq"):
+        raise ValueError(
+            f"stage2_model.particle_type.class_weighting = {class_weighting!r} — must be 'none' or 'inverse_freq'"
+        )
+    if class_weighting != "none" and pt_target != "onehot":
+        raise ValueError(
+            "stage2_model.particle_type.class_weighting != 'none' requires "
+            f"stage2_model.particle_type.target = 'onehot' (there is no class "
+            f"cross-entropy to weight under target = {pt_target!r})"
+        )
+    if class_weighting != "none" and _get_path(cfg, "stage2_model.generator") == "wgan":
+        raise ValueError(
+            "stage2_model.particle_type.class_weighting != 'none' is "
+            "incompatible with stage2_model.generator = 'wgan' — that path "
+            "feeds the type slice to the critic via a straight-through "
+            "Gumbel relaxation instead of a class cross-entropy, so there is "
+            "nothing to weight"
+        )
+
     for stage_name in ("stage1_model", "stage2_model"):
+        if _get_path(cfg, f"{stage_name}.freeze") and not _get_path(cfg, f"{stage_name}.init_from") and not resume:
+            raise ValueError(
+                f"{stage_name}.freeze = true requires {stage_name}.init_from "
+                "to be set (or --resume) — freezing a randomly-initialized "
+                "model is almost certainly a mistake"
+            )
+
         router = _get_path(cfg, f"{stage_name}.router") or {}
         if router.get("enabled") and router.get("type") in ("pdg", "process") and particle_type == "physical":
             raise ValueError(
@@ -1268,19 +1498,53 @@ def validate_config(cfg: dict) -> None:
         )
 
     if _get_path(cfg, "stage2_model.n_sec.mode") == "stop_token":
+        if _get_path(cfg, "stage2_model.decoder") != "autoregressive":
+            raise ValueError(
+                "stage2_model.n_sec.mode = 'stop_token' requires "
+                "stage2_model.decoder = 'autoregressive' — there is no "
+                "per-token loop to stop under 'one_shot'"
+            )
+        if _get_path(cfg, "stage2_model.n_sec.owner") != "stage2":
+            raise ValueError(
+                "stage2_model.n_sec.mode = 'stop_token' requires "
+                "stage2_model.n_sec.owner = 'stage2' — a migrated v0.2 "
+                "checkpoint's stage-1 n_sec_head has no per-token "
+                "conditioning to hang an EOS decision off"
+            )
+
+    stop_sampling = _get_path(cfg, "stage2_model.n_sec.stop_sampling")
+    if stop_sampling not in ("greedy", "sample"):
+        raise ValueError(f"stage2_model.n_sec.stop_sampling = {stop_sampling!r} — must be 'greedy' or 'sample'")
+
+    precision = _get_path(cfg, "train.precision")
+    if precision not in ("fp32", "bf16"):
         raise ValueError(
-            "stage2_model.n_sec.mode = 'stop_token' is accepted by the schema "
-            "but not implemented in v0.3.0 — use 'head' (default) or 'truth' "
-            "(standalone stage-2 evaluation only, never for rollout)"
+            f"train.precision = {precision!r} — must be 'fp32' or 'bf16' "
+            "('fp16' is not supported: see giant.training.amp.resolve_autocast)"
         )
 
-    if _get_path(cfg, "stage2_model.stage1_context") == "sampled":
-        raise ValueError(
-            "stage2_model.stage1_context = 'sampled' is accepted by the schema "
-            "but not implemented — trainers.py always trains stage 2 against "
-            "the ground-truth stage-1 output; use 'truth' (default) instead "
-            "(see issues.md Issue 16 for the planned implementation)"
-        )
+    stage1_context = _get_path(cfg, "stage2_model.stage1_context")
+    if stage1_context not in ("truth", "sampled"):
+        raise ValueError(f"stage2_model.stage1_context = {stage1_context!r} — must be 'truth' or 'sampled'")
+    if stage1_context == "sampled":
+        if not (_get_path(cfg, "stage1_model.active") and _get_path(cfg, "stage2_model.active")):
+            raise ValueError(
+                "stage2_model.stage1_context = 'sampled' requires both "
+                "stage1_model.active and stage2_model.active = true — there is "
+                "no stage-1 model to sample from in a stage-2-only run"
+            )
+        ctx_p_start = _get_path(cfg, "stage2_model.ctx_p_start")
+        ctx_p_end = _get_path(cfg, "stage2_model.ctx_p_end")
+        for name, value in (("ctx_p_start", ctx_p_start), ("ctx_p_end", ctx_p_end)):
+            if not (0.0 <= value <= 1.0):
+                raise ValueError(f"stage2_model.{name} = {value} — must be in [0, 1]")
+        if ctx_p_start == 1.0 and ctx_p_end == 1.0:
+            raise ValueError(
+                "stage2_model.stage1_context = 'sampled' with ctx_p_start = "
+                "ctx_p_end = 1.0 always conditions on the ground truth — "
+                "identical to 'truth' but silently so; use 'truth' instead or "
+                "lower ctx_p_end"
+            )
 
     if (
         _get_path(cfg, "stage2_model.n_sec.mode") == "truth"
@@ -1306,8 +1570,10 @@ def validate_config(cfg: dict) -> None:
                 "AutoregressiveConfig.order's docstring)"
             )
         history = _get_path(cfg, "stage2_model.autoregressive.history")
-        if history not in ("markov", "attention"):
-            raise ValueError(f"stage2_model.autoregressive.history = {history!r} — must be 'markov' or 'attention'")
+        if history not in HISTORY_REGISTRY:
+            raise ValueError(
+                f"stage2_model.autoregressive.history = {history!r} — must be one of {sorted(HISTORY_REGISTRY)}"
+            )
         teacher_forcing = _get_path(cfg, "stage2_model.autoregressive.teacher_forcing")
         if teacher_forcing not in ("always", "scheduled", "never"):
             raise ValueError(
@@ -1400,6 +1666,10 @@ _OUT_DIR_NAME_CANDIDATES = [
         "particle_type_target",
         _path_candidate("stage2_model.particle_type.target", "pt-"),
     ),
+    ("stage1_trunk_type", _path_candidate("stage1_model.trunk.type", "s1t-")),
+    ("stage2_trunk_type", _path_candidate("stage2_model.trunk.type", "s2t-")),
+    ("stage1_block_cond", _path_candidate("stage1_model.trunk.block_conditioning", "s1bc-")),
+    ("stage2_block_cond", _path_candidate("stage2_model.trunk.block_conditioning", "s2bc-")),
     ("stage1_router", _router_candidate("stage1_model", "s1")),
     ("stage2_router", _router_candidate("stage2_model", "s2")),
     (
@@ -1436,6 +1706,8 @@ _OUT_DIR_NAME_CANDIDATES = [
     ),
     ("particle_conditioning", _conditioning_candidate("particle", "c")),
     ("material_conditioning", _conditioning_candidate("material", "m")),
+    ("stage1_freeze", _path_candidate("stage1_model.freeze", "s1frozen", formatter=lambda _: "")),
+    ("stage2_freeze", _path_candidate("stage2_model.freeze", "s2frozen", formatter=lambda _: "")),
     ("stage1_hidden_dim", _path_candidate("stage1_model.hidden_dim", "h")),
     ("stage2_hidden_dim", _path_candidate("stage2_model.hidden_dim", "s2h")),
     ("stage1_n_res_blocks", _path_candidate("stage1_model.n_res_blocks", "b")),

giant/data/loader.py

@@ -1,4 +1,4 @@
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Iterator
 
@@ -256,24 +256,32 @@ def _rank_by_frequency_from_files(files: list[Path], column: str, cast) -> dict:
     return counts
 
 
-def _topn_plus_other_map(counts: dict, n_classes: int) -> tuple[dict, dict]:
+def _topn_plus_other_map(counts: dict, n_classes: int) -> tuple[dict, dict, dict]:
     """Frequency-capped value->index map: the `n_classes - 1` most frequent
     keys get their own index; every rarer key is bucketed into a shared
     "other" index (`n_classes - 1`).
 
-    Returns `(class_map, other_members)` — `other_members` is `{key: count}`
-    for every key bucketed into "other" (the empirical within-bucket
-    distribution, for `other_policy = "sample"` at rollout).
+    Returns `(class_map, other_members, class_counts)` — `other_members` is
+    `{key: count}` for every key bucketed into "other" (the empirical
+    within-bucket distribution, for `other_policy = "sample"` at rollout);
+    `class_counts` is `{index: total_count}` for every resulting class index
+    (0-indexed; the "other" index's count is the sum of `other_members`),
+    the per-class frequencies `stage2_model.particle_type.class_weighting`
+    (gitea #44) needs and that would otherwise be dropped once `counts` is
+    collapsed into `class_map`.
     """
     ranked = sorted(counts, key=lambda k: counts[k], reverse=True)
     keep = ranked[: max(n_classes - 1, 0)]
     class_map = {k: i for i, k in enumerate(keep)}
+    class_counts = {i: counts[k] for i, k in enumerate(keep)}
     other_idx = n_classes - 1
     other_members: dict = {}
     for k in ranked[len(keep) :]:
         class_map[k] = other_idx
         other_members[k] = counts[k]
-    return class_map, other_members
+    if other_members:
+        class_counts[other_idx] = sum(other_members.values())
+    return class_map, other_members, class_counts
 
 
 def build_process_map_from_files(files: list[Path], n_experts: int) -> dict[str, int]:
@@ -287,7 +295,7 @@ def build_process_map_from_files(files: list[Path], n_experts: int) -> dict[str,
     fixed-width n_sec_head classifier.
     """
     counts = _rank_by_frequency_from_files(files, "process", str)
-    class_map, _ = _topn_plus_other_map(counts, n_experts)
+    class_map, _, _ = _topn_plus_other_map(counts, n_experts)
     return class_map
 
 
@@ -299,6 +307,11 @@ class TopNMap:
 
     class_map: dict
     other_members: dict
+    # {class_index: total_count} — see _topn_plus_other_map. Empty for a
+    # TopNMap decoded from a checkpoint/sidecar predating gitea #44; only
+    # stage2_model.particle_type.class_weighting reads it, and it raises
+    # loudly if it needs counts that aren't there (giant/training/trainers.py).
+    class_counts: dict = field(default_factory=dict)
 
 
 def build_topn_map_from_files(files: list[Path], column: str, n_classes: int, cast=str) -> TopNMap:
@@ -315,8 +328,8 @@ def build_topn_map_from_files(files: list[Path], column: str, n_classes: int, ca
     free during this same scan.
     """
     counts = _rank_by_frequency_from_files(files, column, cast)
-    class_map, other_members = _topn_plus_other_map(counts, n_classes)
-    return TopNMap(class_map=class_map, other_members=other_members)
+    class_map, other_members, class_counts = _topn_plus_other_map(counts, n_classes)
+    return TopNMap(class_map=class_map, other_members=other_members, class_counts=class_counts)
 
 
 def build_pdg_topn_map_from_files(files: list[Path], n_classes: int) -> TopNMap:
@@ -347,5 +360,5 @@ def build_pdg_topn_map_from_files(files: list[Path], n_classes: int) -> TopNMap:
         if has_sec:
             exploded = df["sec_pdg_list"].explode().dropna()
             _accumulate_value_counts(counts, exploded, int)
-    class_map, other_members = _topn_plus_other_map(counts, n_classes)
-    return TopNMap(class_map=class_map, other_members=other_members)
+    class_map, other_members, class_counts = _topn_plus_other_map(counts, n_classes)
+    return TopNMap(class_map=class_map, other_members=other_members, class_counts=class_counts)

giant/data/setup_cache.py

@@ -35,7 +35,10 @@ from giant.data.transforms import Normalizer, sorted_membership
 # v3: NormalizerEntry.energy_reservoir_sample (100k raw values) replaced by
 # energy_quantiles (a fixed ENERGY_QUANTILE_LEVELS-point quantile grid) — a
 # v2 sidecar has no such grid to fall back on, so it must be recomputed.
-_CACHE_FORMAT_VERSION = 3
+# v4: TopNMap gained class_counts (gitea #44, stage2_model.particle_type.
+# class_weighting) — a v3 sidecar's cached topn_maps have no counts, so they
+# must be rebuilt rather than silently cached with class_counts={}.
+_CACHE_FORMAT_VERSION = 4
 
 _DIMS = {
     "COND_DIM": COND_DIM,
@@ -131,6 +134,7 @@ def topnmap_to_json(m: TopNMap) -> dict:
     return {
         "class_map": {str(k): v for k, v in m.class_map.items()},
         "other_members": {str(k): v for k, v in m.other_members.items()},
+        "class_counts": {str(k): v for k, v in m.class_counts.items()},
     }
 
 
@@ -139,6 +143,11 @@ def topnmap_from_json(d: dict, axis: str) -> TopNMap:
     return TopNMap(
         class_map={cast(k): v for k, v in d["class_map"].items()},
         other_members={cast(k): v for k, v in d["other_members"].items()},
+        # Missing for a checkpoint's topn maps predating gitea #44 — {} is
+        # the correct decode there (inference never reads class_counts; only
+        # stage2_model.particle_type.class_weighting does, at train time, and
+        # it raises loudly if it needs counts a checkpoint doesn't have).
+        class_counts={int(k): v for k, v in d.get("class_counts", {}).items()},
     )
 
 

giant/data/transforms.py

@@ -3,6 +3,7 @@ from typing import NamedTuple
 
 import numpy as np
 
+from giant.cond_layout import CondLayout
 from giant.constants import K_MAX
 
 _EPS = 1e-8
@@ -13,6 +14,14 @@ _EPS = 1e-8
 # the conservation it slightly softens is physically negligible (~0.001%).
 _SIMPLEX_FLOOR = 1e-5
 
+# Upper clip for a raw predicted log_mass before inv_log_transform: exp(y)
+# must stay well inside float32 range (~3.4e38, i.e. y < ~88.7) or it
+# overflows to inf, which — like the negative-mass case below — blows up the
+# next log_transform call once that mass is fed back in as conditioning.
+# 80.0 leaves comfortable headroom while still being far beyond any physical
+# particle mass a converged model would ever predict.
+_LOG_MASS_MAX = 80.0
+
 
 def log_transform(x: np.ndarray, eps: float = _EPS) -> np.ndarray:
     x = np.asarray(x, dtype=np.float32)
@@ -684,27 +693,31 @@ def decode_secondaries(
     log_mass = sec_cont[:, :, 4]  # (N, K)
     charge = sec_cont[:, :, 5]  # (N, K)
 
-    # mass is non-negative by construction (inv_log_transform of a real
-    # number is always > 0); clip to 0 for padded/invalid slots rather than
-    # leaving a spurious small positive floor from the log inverse.
+    # log_mass is a raw model prediction, not itself the output of
+    # log_transform, so it can land far outside the range that round-trips
+    # cleanly through inv_log_transform: too negative and exp(log_mass)
+    # undershoots _EPS, making inv_log_transform go slightly negative; too
+    # positive and exp(log_mass) overflows float32 to inf. Either one then
+    # blows up the next log_transform call on this track's mass once it's
+    # fed back in as conditioning for a further rollout step
+    # (giant/rollout.py -> build_cond_features -> _physical_cond_columns).
+    # Clip to a range whose inverse is guaranteed finite and >= 0 before
+    # that can happen; clip to 0 separately for padded/invalid slots rather
+    # than leaving a spurious small positive floor.
+    log_mass = np.clip(log_mass, np.log(_EPS), _LOG_MASS_MAX)
     sec_mass = np.where(sec_valid, inv_log_transform(log_mass), 0.0).astype(np.float32)
     sec_charge = np.where(sec_valid, charge, 0.0).astype(np.float32)
 
     return sec_E, sec_dir_world, sec_mass, sec_charge, sec_valid
 
 
-def _physical_cond_columns(
-    data: dict[str, np.ndarray],
-    particle_conditioning: str,
-    material_conditioning: str,
-) -> np.ndarray:
+def _physical_cond_columns(data: dict[str, np.ndarray], layout: CondLayout) -> np.ndarray:
     """(N, PARTICLE_PHYS_DIM + MATERIAL_PHYS_DIM) physical conditioning columns.
 
     The particle and material blocks are gated independently and may mix
     freely — e.g. material `physical` with particle `embedding` — so e.g.
-    `particle_conditioning="embedding"` + `material_conditioning="physical"`
-    zero-fills only the particle columns and computes the material ones for
-    real.
+    `particle_type="embedding"` + `material_type="physical"` zero-fills only
+    the particle columns and computes the material ones for real.
 
     "embedding"/"onehot" zero-fill their block (cheap, and ConditionEncoder
     never reads these columns in either mode — so an unfilled
@@ -721,7 +734,7 @@ def _physical_cond_columns(
 
     n = len(next(iter(data.values())))
 
-    if particle_conditioning == "physical":
+    if layout.particle_type == "physical":
         from giant.particles import particle_phys_array
 
         if "mass" in data and "charge" in data:
@@ -730,12 +743,10 @@ def _physical_cond_columns(
         else:
             mass, charge = particle_phys_array(data["pdg"]).T
         particle_cols = np.column_stack([log_transform(mass), charge])
-    elif particle_conditioning in ("embedding", "onehot"):
-        particle_cols = np.zeros((n, PARTICLE_PHYS_DIM), dtype=np.float32)
     else:
-        raise ValueError(f"unknown conditioning.particle.type {particle_conditioning!r}")
+        particle_cols = np.zeros((n, PARTICLE_PHYS_DIM), dtype=np.float32)
 
-    if material_conditioning == "physical":
+    if layout.material_type == "physical":
         from giant.materials import material_properties_array
 
         z_eff, a_eff, density, x0, lambda_int = material_properties_array(data["material"]).T
@@ -748,14 +759,66 @@ def _physical_cond_columns(
                 log_transform(lambda_int),
             ]
         )
-    elif material_conditioning in ("embedding", "onehot"):
-        material_cols = np.zeros((n, MATERIAL_PHYS_DIM), dtype=np.float32)
     else:
-        raise ValueError(f"unknown conditioning.material.type {material_conditioning!r}")
+        material_cols = np.zeros((n, MATERIAL_PHYS_DIM), dtype=np.float32)
 
     return np.column_stack([particle_cols, material_cols]).astype(np.float32)
 
 
+def _build_cond_arrays(
+    data: dict[str, np.ndarray],
+    pdg_map: dict[int, int],
+    mat_map: dict[str, int],
+    layout: CondLayout,
+    pdg_topn_map: dict[int, int] | None,
+    mat_topn_map: dict[str, int] | None,
+) -> tuple[np.ndarray, np.ndarray]:
+    """The un-normalized `(cond_cont, cond_cat)` pair, in `layout`'s column order.
+
+    Both `build_cond_features` and `build_features` go through here, so the
+    column order — and everything that depends on it — is stated once. See
+    `giant.cond_layout.CondLayout` for the layout itself.
+    """
+    cond_cont = np.column_stack(
+        [
+            data["pre_pos"],
+            log_transform(data["pre_E"]),
+            data["pre_dir"],
+            data["layer_id"].astype(np.float32),
+        ]
+    ).astype(np.float32)  # (N, COND_DIM_BASE=8)
+    cond_cont = np.column_stack([cond_cont, _physical_cond_columns(data, layout)]).astype(
+        np.float32
+    )  # (N, COND_DIM=15)
+
+    # In "physical" mode cond_cat's first two columns are only a
+    # reporting/router convenience — ConditionEncoder never reads them
+    # (giant/model/encoders.py) — so a species/material outside the training
+    # vocab (the whole point of physical-property conditioning) gets a dummy
+    # index instead of raising. In "embedding" mode those columns ARE the
+    # conditioning signal, so an unmapped value must still raise loudly
+    # rather than silently misassign. In "onehot" mode they again go unread
+    # (the topN columns below are the real signal), so they're as permissive
+    # as "physical". Each axis's strictness is independent.
+    pdg_idx = _vectorized_map_lookup(data["pdg"], pdg_map, strict=layout.particle_type == "embedding")
+    mat_idx = _vectorized_map_lookup(data["material"], mat_map, strict=layout.material_type == "embedding")
+    # Which extra columns exist is the layout's call, not "did the caller
+    # happen to pass a map" — that's what used to let the producer and
+    # ConditionEncoder disagree. A map for a non-"onehot" axis is unused.
+    cat_cols = [pdg_idx, mat_idx]
+    if layout.particle_topn_col is not None:
+        if pdg_topn_map is None:
+            raise ValueError("conditioning.particle.type='onehot' needs pdg_topn_map")
+        cat_cols.append(_vectorized_map_lookup(data["pdg"], pdg_topn_map))
+    if layout.material_topn_col is not None:
+        if mat_topn_map is None:
+            raise ValueError("conditioning.material.type='onehot' needs mat_topn_map")
+        cat_cols.append(_vectorized_map_lookup(data["material"], mat_topn_map))
+    cond_cat = np.column_stack(cat_cols)  # (N, layout.cat_dim)
+
+    return cond_cont, cond_cat
+
+
 def build_cond_features(
     data: dict[str, np.ndarray],
     pdg_map: dict[int, int],
@@ -773,49 +836,16 @@ def build_cond_features(
     `material_conditioning="physical"` is a valid mix.
 
     `pdg_topn_map`/`mat_topn_map` (a top-N-plus-other `class_map`, see
-    `giant.data.loader.build_topn_map_from_files`) append extra `cond_cat`
-    columns read by `ConditionEncoder`'s `"onehot"` mode: pdg topN index at
-    column 2 (iff `pdg_topn_map` given), material topN index at column 3
-    (iff `mat_topn_map` given, after column 2 if both are). Only ever given when
-    the corresponding axis is `"onehot"`; `cond_cat` stays `(N, 2)` otherwise.
+    `giant.data.loader.build_topn_map_from_files`) supply the extra `cond_cat`
+    columns read by `ConditionEncoder`'s `"onehot"` mode, and are required
+    whenever the corresponding axis is `"onehot"`. See
+    `giant.cond_layout.CondLayout` for which columns exist where.
     """
-    cond_cont = np.column_stack(
-        [
-            data["pre_pos"],
-            log_transform(data["pre_E"]),
-            data["pre_dir"],
-            data["layer_id"].astype(np.float32),
-        ]
-    ).astype(np.float32)
-    cond_cont = np.column_stack(
-        [
-            cond_cont,
-            _physical_cond_columns(data, particle_conditioning, material_conditioning),
-        ]
-    ).astype(np.float32)
-
-    # In "physical" mode cond_cat's first two columns are only a
-    # reporting/router convenience — ConditionEncoder never reads them
-    # (giant/model/network.py) — so a species/material outside the training
-    # vocab (the whole point of physical-property conditioning) gets a dummy
-    # index instead of raising. In "embedding" mode those columns ARE the
-    # conditioning signal, so an unmapped value must still raise loudly
-    # rather than silently misassign. In "onehot" mode they again go unread
-    # (the topN columns below are the real signal), so they're as permissive
-    # as "physical". Each axis's strictness is independent.
-    pdg_strict = particle_conditioning == "embedding"
-    mat_strict = material_conditioning == "embedding"
-    pdg_idx = _vectorized_map_lookup(data["pdg"], pdg_map, strict=pdg_strict)
-    mat_idx = _vectorized_map_lookup(data["material"], mat_map, strict=mat_strict)
-    cat_cols = [pdg_idx, mat_idx]
-    if pdg_topn_map is not None:
-        cat_cols.append(_vectorized_map_lookup(data["pdg"], pdg_topn_map))
-    if mat_topn_map is not None:
-        cat_cols.append(_vectorized_map_lookup(data["material"], mat_topn_map))
-    cond_cat = np.column_stack(cat_cols)
+    layout = CondLayout.from_types(particle_conditioning, material_conditioning)
+    cond_cont, cond_cat = _build_cond_arrays(data, pdg_map, mat_map, layout, pdg_topn_map, mat_topn_map)
 
     if cond_normalizer is not None:
-        cond_cont = _cond_normalizer_transform(cond_cont, cond_normalizer, particle_conditioning, material_conditioning)
+        cond_cont = _cond_normalizer_transform(cond_cont, cond_normalizer, layout)
 
     return cond_cont, cond_cat
 
@@ -823,8 +853,7 @@ def build_cond_features(
 def _cond_normalizer_transform(
     cond_cont: np.ndarray,
     cond_normalizer: "Normalizer",
-    particle_conditioning: str,
-    material_conditioning: str,
+    layout: CondLayout,
 ) -> np.ndarray:
     """Apply ``cond_normalizer``, padding a legacy narrower normalizer if needed.
 
@@ -832,7 +861,7 @@ def _cond_normalizer_transform(
     8->15, ``giant/constants.py``) saved a ``COND_DIM_BASE``-wide (8) cond
     normalizer, fit before ``build_cond_features`` grew the extra physical
     columns. When NEITHER axis is "physical" those columns are never read by
-    ``ConditionEncoder`` (``giant/model/network.py``), so padding the missing
+    ``ConditionEncoder`` (``giant/model/encoders.py``), so padding the missing
     entries with mean=0/std=1 is a safe no-op that keeps such checkpoints
     usable under the current, always-``COND_DIM``-wide contract. If EITHER
     axis is "physical" its columns are load-bearing, so a mismatch there is a
@@ -843,14 +872,14 @@ def _cond_normalizer_transform(
     width = cond_cont.shape[-1]
     if mean.shape[-1] < width:
         physical_load_bearing = "physical" in (
-            particle_conditioning,
-            material_conditioning,
+            layout.particle_type,
+            layout.material_type,
         )
         if physical_load_bearing:
             raise ValueError(
                 f"cond normalizer has {mean.shape[-1]} columns, expected "
-                f"{width}, and particle_conditioning={particle_conditioning!r}/"
-                f"material_conditioning={material_conditioning!r} reads the "
+                f"{width}, and particle_conditioning={layout.particle_type!r}/"
+                f"material_conditioning={layout.material_type!r} reads the "
                 "physical columns directly — this checkpoint predates "
                 "physical-property conditioning and can't be safely padded; "
                 "retrain it under the current code."
@@ -928,7 +957,7 @@ def build_features(
         instead) for callers (normalizer fitting) that only read
         `sec_cont[:, :, 4:6]` and would otherwise discard that work.
 
-    pdg_topn_map/mat_topn_map: appended `cond_cat` columns for
+    pdg_topn_map/mat_topn_map: source of the extra `cond_cat` columns for
         `ConditionEncoder`'s `"onehot"` mode — see `build_cond_features`.
 
     sec_type_class_map: the map `sec_type_idx` is looked up against — a
@@ -959,29 +988,8 @@ def build_features(
     ).astype(np.float32)  # (N, 9)
 
     # Phase 2: conditioning drops n_sec and log(e_sec)
-    cond_cont = np.column_stack(
-        [
-            data["pre_pos"],
-            log_transform(data["pre_E"]),
-            data["pre_dir"],
-            data["layer_id"].astype(np.float32),
-        ]
-    ).astype(np.float32)  # (N, COND_DIM_BASE=8)
-    cond_cont = np.column_stack(
-        [
-            cond_cont,
-            _physical_cond_columns(data, particle_conditioning, material_conditioning),
-        ]
-    ).astype(np.float32)  # (N, COND_DIM=15)
-
-    pdg_idx = _vectorized_map_lookup(data["pdg"], pdg_map)
-    mat_idx = _vectorized_map_lookup(data["material"], mat_map)
-    cat_cols = [pdg_idx, mat_idx]
-    if pdg_topn_map is not None:
-        cat_cols.append(_vectorized_map_lookup(data["pdg"], pdg_topn_map))
-    if mat_topn_map is not None:
-        cat_cols.append(_vectorized_map_lookup(data["material"], mat_topn_map))
-    cond_cat = np.column_stack(cat_cols)  # (N, 2/3/4)
+    layout = CondLayout.from_types(particle_conditioning, material_conditioning)
+    cond_cont, cond_cat = _build_cond_arrays(data, pdg_map, mat_map, layout, pdg_topn_map, mat_topn_map)
 
     n_sec_raw = data["n_sec"].astype(np.int64)  # (N,) unclamped, for the valid-slot mask
 
@@ -1048,7 +1056,7 @@ def build_features(
         target_normalizer = Normalizer().fit(target_s1)
 
     if cond_normalizer is not None:
-        cond_cont = cond_normalizer.transform(cond_cont)
+        cond_cont = _cond_normalizer_transform(cond_cont, cond_normalizer, layout)
     if target_normalizer is not None:
         target_s1 = target_normalizer.transform(target_s1)
     if sec_phys_normalizer is not None:

giant/model/builders.py

@@ -15,6 +15,7 @@ from giant.model.models import (
     resolve_type_n_classes,
     stage2_trunk_sec_dim,
 )
+from giant.model.objectives import build_objective
 from giant.model.routers import Router, _build_router_from_cfg
 
 # ---------------------------------------------------------------------------
@@ -44,11 +45,10 @@ def build_models(model_config: dict) -> dict[str, nn.Module | None]:
     cfg = model_config if "stage1_model" in model_config else _migrate_legacy_model_config(model_config)
     pdg_vocab = cfg["pdg_vocab"]
     mat_vocab = cfg["mat_vocab"]
-    conditioning = cfg["conditioning"]
-    particle_cfg = conditioning["particle"]
-    material_cfg = conditioning["material"]
-    particle_conditioning = particle_cfg["type"]
-    conditioning_cfg = ConditioningConfig.from_dict(conditioning)
+    conditioning_cfg = ConditioningConfig.from_dict(cfg["conditioning"])
+    particle_cfg = conditioning_cfg.particle
+    material_cfg = conditioning_cfg.material
+    particle_conditioning = particle_cfg.type
     s1_spec = Stage1ModelConfig.from_dict(cfg["stage1_model"])
     s2_spec = Stage2ModelConfig.from_dict(cfg["stage2_model"])
     cond_out_dim = conditioning_cfg.out_dim
@@ -64,10 +64,11 @@ def build_models(model_config: dict) -> dict[str, nn.Module | None]:
         if s1_spec.router.enabled:
             stage1_router = _build_router_from_cfg(router_cfg, pdg_vocab, mat_vocab, particle_conditioning)
         generator = s1_spec.generator
+        objective = build_objective(generator)
         # wgan has no time_dim concept (no diffusion/flow time variable) —
         # matches the pre-dataclass .get("time_dim", 64) fallback, which
         # always hit its default for a wgan sub-block too.
-        time_dim = getattr(s1_spec, generator).time_dim if generator != "wgan" else 64
+        time_dim = getattr(s1_spec, generator).time_dim if objective.needs_time else 64
         n_sec_owner = s2_spec.n_sec.owner
         n_sec_head_k_max = s2_spec.k_max if n_sec_owner == "stage1" else None
         result["stage1"] = Stage1Model(
@@ -83,8 +84,11 @@ def build_models(model_config: dict) -> dict[str, nn.Module | None]:
             time_dim=time_dim,
             noise_dim=s1_spec.wgan.noise_dim,
             router=stage1_router,
+            trunk_type=s1_spec.trunk.type,
+            block_conditioning=s1_spec.trunk.block_conditioning,
             n_sec_head_k_max=n_sec_head_k_max,
             cond_enc=shared_cond_enc,
+            n_sec_head_cfg=s1_spec.heads.n_sec.to_dict(),
         )
 
     if s2_spec.active:
@@ -97,12 +101,14 @@ def build_models(model_config: dict) -> dict[str, nn.Module | None]:
             else:
                 stage2_router = _build_router_from_cfg(router_cfg, pdg_vocab, mat_vocab, particle_conditioning)
         generator = s2_spec.generator
+        objective = build_objective(generator)
         # wgan has no time_dim concept — see the matching comment in stage 1
         # above.
-        time_dim = getattr(s2_spec, generator).time_dim if generator != "wgan" else 64
+        time_dim = getattr(s2_spec, generator).time_dim if objective.needs_time else 64
         n_sec_owner = s2_spec.n_sec.owner
+        stop_token = s2_spec.n_sec.mode == "stop_token"
         k_max = s2_spec.k_max
-        particle_type_cfg = s2_spec.particle_type.to_dict()
+        particle_type_cfg = s2_spec.particle_type
 
         if decoder == "autoregressive":
             ar_cfg = s2_spec.autoregressive
@@ -121,16 +127,23 @@ def build_models(model_config: dict) -> dict[str, nn.Module | None]:
                 noise_dim=s2_spec.wgan.noise_dim,
                 k_max=k_max,
                 router=stage2_router,
-                build_n_sec_head=n_sec_owner != "stage1",
+                trunk_type=s2_spec.trunk.type,
+                block_conditioning=s2_spec.trunk.block_conditioning,
+                build_n_sec_head=n_sec_owner != "stage1" and not stop_token,
                 particle_type_cfg=particle_type_cfg,
                 history=ar_cfg.history,
                 attn_n_heads=ar_cfg.attn_n_heads,
                 attn_n_layers=ar_cfg.attn_n_layers,
                 cond_enc=shared_cond_enc,
+                n_sec_head_cfg=s2_spec.heads.n_sec.to_dict(),
+                type_head_cfg=s2_spec.heads.type.to_dict(),
+                build_stop_head=stop_token,
+                stop_sampling=s2_spec.n_sec.stop_sampling,
+                stop_head_cfg=s2_spec.heads.n_sec.to_dict(),
             )
         else:
             sec_dim = stage2_trunk_sec_dim(
-                particle_type_cfg, generator, k_max, resolve_type_n_classes(particle_type_cfg, particle_cfg["emb_dim"])
+                particle_type_cfg, generator, k_max, resolve_type_n_classes(particle_type_cfg, particle_cfg.emb_dim)
             )
             result["stage2"] = Stage2OneShot(
                 pdg_vocab=pdg_vocab,
@@ -148,9 +161,13 @@ def build_models(model_config: dict) -> dict[str, nn.Module | None]:
                 noise_dim=s2_spec.wgan.noise_dim,
                 k_max=k_max,
                 router=stage2_router,
+                trunk_type=s2_spec.trunk.type,
+                block_conditioning=s2_spec.trunk.block_conditioning,
                 build_n_sec_head=n_sec_owner != "stage1",
                 particle_type_cfg=particle_type_cfg,
                 cond_enc=shared_cond_enc,
+                n_sec_head_cfg=s2_spec.heads.n_sec.to_dict(),
+                type_head_cfg=s2_spec.heads.type.to_dict(),
             )
 
     return result
@@ -164,17 +181,16 @@ def build_critics(model_config: dict) -> dict[str, nn.Module | None]:
     cfg = model_config if "stage1_model" in model_config else _migrate_legacy_model_config(model_config)
     pdg_vocab = cfg["pdg_vocab"]
     mat_vocab = cfg["mat_vocab"]
-    conditioning = cfg["conditioning"]
-    particle_cfg = conditioning["particle"]
-    material_cfg = conditioning["material"]
-    conditioning_cfg = ConditioningConfig.from_dict(conditioning)
+    conditioning_cfg = ConditioningConfig.from_dict(cfg["conditioning"])
+    particle_cfg = conditioning_cfg.particle
+    material_cfg = conditioning_cfg.material
     cond_out_dim = conditioning_cfg.out_dim
     s1_spec = Stage1ModelConfig.from_dict(cfg["stage1_model"])
     s2_spec = Stage2ModelConfig.from_dict(cfg["stage2_model"])
 
     result: dict[str, nn.Module | None] = {"stage1": None, "stage2": None}
 
-    if s1_spec.active and s1_spec.generator == "wgan":
+    if s1_spec.active and build_objective(s1_spec.generator).is_adversarial:
         result["stage1"] = CriticModel(
             pdg_vocab=pdg_vocab,
             mat_vocab=mat_vocab,
@@ -188,11 +204,14 @@ def build_critics(model_config: dict) -> dict[str, nn.Module | None]:
             stage="stage1",
         )
 
-    if s2_spec.active and s2_spec.generator == "wgan":
+    if s2_spec.active and build_objective(s2_spec.generator).is_adversarial:
         k_max = s2_spec.k_max
-        particle_type_cfg = s2_spec.particle_type.to_dict()
+        particle_type_cfg = s2_spec.particle_type
         in_dim = stage2_trunk_sec_dim(
-            particle_type_cfg, "wgan", k_max, resolve_type_n_classes(particle_type_cfg, particle_cfg["emb_dim"])
+            particle_type_cfg,
+            s2_spec.generator,
+            k_max,
+            resolve_type_n_classes(particle_type_cfg, particle_cfg.emb_dim),
         )
         result["stage2"] = CriticModel(
             pdg_vocab=pdg_vocab,

giant/model/encoders.py

@@ -5,82 +5,63 @@ import torch
 import torch.nn as nn
 import torch.nn.functional as F
 
+from giant.cond_layout import CondLayout
+from giant.config import ConditioningAxisConfig
 from giant.constants import COND_DIM, COND_DIM_BASE, MATERIAL_PHYS_DIM, PARTICLE_PHYS_DIM
 from giant.model.layers import _make_axis_mlp
 
 
-def cat_col_layout(particle_type: str, material_type: str) -> tuple[int | None, int | None]:
-    """`cond_cat` column indices for each axis's top-N-onehot index, or
-    `None` if that axis isn't `"onehot"`.
-
-    Columns 0/1 are always the dense pdg/material vocab index. The particle
-    top-N column (if any) comes next, then the material top-N column (if
-    any) — `giant.data.transforms.build_cond_features`/`build_features`
-    append columns in this same order, so the two sides must never drift
-    apart.
-    """
-    col = 2
-    particle_col = None
-    if particle_type == "onehot":
-        particle_col = col
-        col += 1
-    material_col = None
-    if material_type == "onehot":
-        material_col = col
-        col += 1
-    return particle_col, material_col
-
-
 class ConditionEncoder(nn.Module):
     """Fuses continuous conditioning with particle/material identity.
 
     The particle and material axes are configured independently
-    (`particle_cfg`/`material_cfg`, each `{"type", "emb_dim", "n_layers"}`)
-    and may mix freely, e.g. material "physical" with particle "embedding".
-    Three modes per axis:
+    (`particle_cfg`/`material_cfg`, each a `ConditioningAxisConfig`) and may
+    mix freely, e.g. material "physical" with particle "embedding". Three
+    modes per axis:
       - "embedding": a learned `nn.Embedding` lookup, indexed by `cond_cat`'s
         dense training-vocab index. Memorizes the training menu.
       - "physical": an `n_layers`-deep MLP over the axis's raw physical
-        properties (already present in `cond_cont[:, COND_DIM_BASE:]` — see
+        properties (already present in `cond_cont`'s physical block — see
         giant.data.transforms.build_features), computable for any PDG code /
         material name rather than only ones seen in training.
       - "onehot": a fixed, unlearned one-hot vector over a top-N-plus-other
         class map (`giant.data.loader.build_topn_map_from_files`/
         `build_pdg_topn_map_from_files`), read from `cond_cat`'s extra
-        top-N-index column(s) — see `_cat_col_layout`.
+        top-N-index column(s).
+
+    Every column index/slice comes from `self.layout`
+    (`giant.cond_layout.CondLayout`), the same object the feature builders
+    lay the arrays out with, so the two sides cannot drift apart.
     """
 
     def __init__(
         self,
         pdg_vocab: int,
         mat_vocab: int,
-        particle_cfg: dict,
-        material_cfg: dict,
+        particle_cfg: ConditioningAxisConfig,
+        material_cfg: ConditioningAxisConfig,
         cont_dim: int = COND_DIM,
         out_dim: int = 128,
     ) -> None:
         super().__init__()
-        self.particle_cfg = dict(particle_cfg)
-        self.material_cfg = dict(material_cfg)
-        self._particle_topn_col, self._material_topn_col = cat_col_layout(particle_cfg["type"], material_cfg["type"])
+        self.particle_cfg = particle_cfg
+        self.material_cfg = material_cfg
+        # Also validates both axis types — an unknown one raises here.
+        self.layout = CondLayout.from_types(particle_cfg.type, material_cfg.type)
 
-        p_type = particle_cfg["type"]
-        p_emb_dim = particle_cfg["emb_dim"]
+        p_type = particle_cfg.type
+        p_emb_dim = particle_cfg.emb_dim
         if p_type == "embedding":
             self.pdg_emb = nn.Embedding(pdg_vocab, p_emb_dim)
         elif p_type == "physical":
-            self.particle_mlp = _make_axis_mlp(PARTICLE_PHYS_DIM, p_emb_dim, particle_cfg.get("n_layers", 1))
-        elif p_type != "onehot":
-            raise ValueError(f"unknown conditioning.particle.type {p_type!r}")
+            self.particle_mlp = _make_axis_mlp(PARTICLE_PHYS_DIM, p_emb_dim, particle_cfg.n_layers)
 
-        m_type = material_cfg["type"]
-        m_emb_dim = material_cfg["emb_dim"]
+        m_type = material_cfg.type
+        m_emb_dim = material_cfg.emb_dim
         if m_type == "embedding":
             self.mat_emb = nn.Embedding(mat_vocab, m_emb_dim)
         elif m_type == "physical":
-            self.material_mlp = _make_axis_mlp(MATERIAL_PHYS_DIM, m_emb_dim, material_cfg.get("n_layers", 1))
-        elif m_type != "onehot":
-            raise ValueError(f"unknown conditioning.material.type {m_type!r}")
+            self.material_mlp = _make_axis_mlp(MATERIAL_PHYS_DIM, m_emb_dim, material_cfg.n_layers)
 
         in_dim = COND_DIM_BASE + p_emb_dim + m_emb_dim
         self.mlp = nn.Sequential(
@@ -90,33 +71,31 @@ class ConditionEncoder(nn.Module):
         )
 
     def _particle_embed(self, cond_cont: torch.Tensor, cond_cat: torch.Tensor):
-        p_type = self.particle_cfg["type"]
+        p_type = self.particle_cfg.type
         if p_type == "embedding":
-            return self.pdg_emb(cond_cat[:, 0])
+            return self.pdg_emb(cond_cat[:, self.layout.PDG_COL])
         if p_type == "physical":
-            particle_phys = cond_cont[:, COND_DIM_BASE : COND_DIM_BASE + PARTICLE_PHYS_DIM]
-            return self.particle_mlp(particle_phys)
-        assert self._particle_topn_col is not None
+            return self.particle_mlp(cond_cont[:, self.layout.particle_phys])
+        assert self.layout.particle_topn_col is not None
         return F.one_hot(
-            cond_cat[:, self._particle_topn_col],
-            num_classes=self.particle_cfg["emb_dim"],
+            cond_cat[:, self.layout.particle_topn_col],
+            num_classes=self.particle_cfg.emb_dim,
         ).float()
 
     def _material_embed(self, cond_cont: torch.Tensor, cond_cat: torch.Tensor):
-        m_type = self.material_cfg["type"]
+        m_type = self.material_cfg.type
         if m_type == "embedding":
-            return self.mat_emb(cond_cat[:, 1])
+            return self.mat_emb(cond_cat[:, self.layout.MAT_COL])
         if m_type == "physical":
-            material_phys = cond_cont[:, COND_DIM_BASE + PARTICLE_PHYS_DIM :]
-            return self.material_mlp(material_phys)
-        assert self._material_topn_col is not None
+            return self.material_mlp(cond_cont[:, self.layout.material_phys])
+        assert self.layout.material_topn_col is not None
         return F.one_hot(
-            cond_cat[:, self._material_topn_col],
-            num_classes=self.material_cfg["emb_dim"],
+            cond_cat[:, self.layout.material_topn_col],
+            num_classes=self.material_cfg.emb_dim,
         ).float()
 
     def forward(self, cond_cont: torch.Tensor, cond_cat: torch.Tensor) -> torch.Tensor:
         pdg_e = self._particle_embed(cond_cont, cond_cat)
         mat_e = self._material_embed(cond_cont, cond_cat)
-        x = torch.cat([cond_cont[:, :COND_DIM_BASE], pdg_e, mat_e], dim=-1)
+        x = torch.cat([cond_cont[:, self.layout.base], pdg_e, mat_e], dim=-1)
         return self.mlp(x)

giant/model/history.py

@@ -1,5 +1,9 @@
 """History encoders — stage-2 autoregressive only. Self-contained, no
-dependency on any other `giant.model` submodule (issues.md Issue 8)."""
+dependency on any other `giant.model` submodule (issues.md Issue 8), except
+for the `HISTORY_REGISTRY`/`build_history` factory, which mirrors
+`giant.model.routers`'s `Router`/`ROUTER_REGISTRY` pattern (gitea #35)."""
+
+import inspect
 
 import torch
 import torch.nn as nn
@@ -9,19 +13,57 @@ class HistoryEncoder(nn.Module):
     """Interface for stage-2 autoregressive per-token history summaries:
     `forward(feat, has_prev) -> (B, K, out_dim)`, a single parallel pass over
     a full (teacher-forced) token sequence — used by training. `MarkovHistory`
-    and `AttentionHistory` are the two implementations. Inference
-    (`giant/sample.py`) generates one token at a
-    time and cannot afford `forward`'s per-step cost to be O(K) (attention
-    would then be O(K^2) over a rollout's k_max loop); encoders that need
-    incremental state for that path additionally implement `init_cache`/
-    `step` (see `AttentionHistory`) — `MarkovHistory` doesn't need to, since
-    its per-step cost is already O(1) (it only ever looks at the previous
-    token, not the full prefix)."""
+    and `AttentionHistory` are the two registered implementations (see
+    `HISTORY_REGISTRY`/`build_history`). Inference (`giant/sample.py`)
+    generates one token at a time and cannot afford `forward`'s per-step cost
+    to be O(K) (attention would then be O(K^2) over a rollout's k_max loop),
+    so this interface also declares `init_cache`/`step` for that incremental
+    path, with working O(1) defaults here (`init_cache` -> `None`, `step` ->
+    one `forward` call ignoring `cache`) — correct for any encoder whose
+    per-step cost is already O(1) (i.e. it only ever looks at the previous
+    token, not the full prefix), which is what `MarkovHistory` relies on.
+    `AttentionHistory` overrides both with real incremental-cache versions,
+    since its `forward` genuinely needs the full prefix."""
 
     def forward(self, feat: torch.Tensor, has_prev: torch.Tensor) -> torch.Tensor:
         raise NotImplementedError
 
+    def init_cache(self) -> object:
+        return None
 
+    def step(self, feat: torch.Tensor, has_prev: torch.Tensor, cache: object) -> tuple[torch.Tensor, object]:
+        return self.forward(feat, has_prev), cache
+
+
+HISTORY_REGISTRY: dict[str, type[HistoryEncoder]] = {}
+
+
+def register_history(name: str):
+    def decorator(cls: type[HistoryEncoder]) -> type[HistoryEncoder]:
+        HISTORY_REGISTRY[name] = cls
+        return cls
+
+    return decorator
+
+
+def build_history(name: str, in_dim: int, out_dim: int, **kwargs) -> HistoryEncoder:
+    """Factory: look up a `HistoryEncoder` subclass by name from the registry.
+
+    Every registered history type is fed the same `stage2_model.autoregressive`
+    kwargs; kwargs not declared by that type's constructor are silently
+    dropped, so per-type hyperparameters (e.g. `AttentionHistory`'s
+    `n_heads`/`n_layers`) can coexist in one config without special-casing —
+    mirrors `giant.model.routers.build_router`.
+    """
+    if name not in HISTORY_REGISTRY:
+        raise ValueError(f"unknown history type {name!r}; available: {sorted(HISTORY_REGISTRY)}")
+    cls = HISTORY_REGISTRY[name]
+    accepted = set(inspect.signature(cls.__init__).parameters) - {"self", "in_dim", "out_dim"}
+    filtered = {k: v for k, v in kwargs.items() if k in accepted}
+    return cls(in_dim, out_dim, **filtered)
+
+
+@register_history("markov")
 class MarkovHistory(HistoryEncoder):
     """Summarizes the previous secondary's own `(energy_fraction, direction,
     type_representation)` through one small MLP — the "markov" history:
@@ -90,6 +132,7 @@ class _CausalAttnBlock(nn.Module):
         return x, kv
 
 
+@register_history("attention")
 class AttentionHistory(HistoryEncoder):
     """Causal self-attention over the emitted-token prefix — the more
     expressive alternative to `MarkovHistory`'s fixed previous-token-only
@@ -137,16 +180,19 @@ class AttentionHistory(HistoryEncoder):
 
     def step(
         self,
-        token_feat: torch.Tensor,
+        feat: torch.Tensor,
         has_prev: torch.Tensor,
-        cache: list[torch.Tensor | None],
-    ) -> tuple[torch.Tensor, list[torch.Tensor | None]]:
-        """`token_feat`/`has_prev`: `(B, 1, in_dim)`/`(B, 1)` — the newest
-        token's own features (what would be `feat[:, k]` in `forward`).
+        cache: object,
+    ) -> tuple[torch.Tensor, object]:
+        """`feat`/`has_prev`: `(B, 1, in_dim)`/`(B, 1)` — the newest token's
+        own features (what would be `feat[:, k]` in `forward`). `cache`: the
+        `list[Tensor | None]` from `init_cache`/a previous `step` call (typed
+        `object` here to match `HistoryEncoder.step`'s base signature).
         Advances every block's cache by this position and returns this
         position's output (`(B, 1, out_dim)`, the correct history summary for
         the NEXT slot) plus the updated cache."""
-        x = self._embed(token_feat, has_prev)
+        assert isinstance(cache, list)
+        x = self._embed(feat, has_prev)
         new_cache: list[torch.Tensor | None] = []
         for block, kv in zip(self.blocks, cache):
             x, kv_new = block.step(x, kv)

giant/model/layers.py

@@ -42,6 +42,31 @@ def _make_axis_mlp(in_dim: int, emb_dim: int, n_layers: int) -> nn.Sequential:
     return nn.Sequential(*layers)
 
 
+def build_mlp_head(
+    in_dim: int, out_dim: int, hidden: int, depth: int = 2, act: type[nn.Module] = nn.SiLU
+) -> nn.Sequential:
+    """`depth`-layer MLP head (gitea #36) — factors out the n_sec_head/
+    type_head pattern duplicated five times across `giant.model.models`.
+
+    `depth=1` is a bare `Linear(in_dim, out_dim)` (no hidden layer/
+    activation); `depth>=2` is `Linear(in_dim, hidden) -> act -> [Linear
+    (hidden, hidden) -> act] * (depth-2) -> Linear(hidden, out_dim)` —
+    `depth=2` reproduces every pre-#36 n_sec_head/type_head exactly when
+    `hidden == hidden_dim // 2`. Mirrors `_make_axis_mlp`'s depth
+    convention above, but takes `hidden` and `out_dim` as independent
+    widths (n_sec_head/type_head's hidden width is not their output width,
+    unlike the particle/material axis MLPs)."""
+    if depth < 1:
+        raise ValueError(f"depth must be >= 1, got {depth}")
+    if depth == 1:
+        return nn.Sequential(nn.Linear(in_dim, out_dim))
+    layers: list[nn.Module] = [nn.Linear(in_dim, hidden), act()]
+    for _ in range(depth - 2):
+        layers += [nn.Linear(hidden, hidden), act()]
+    layers.append(nn.Linear(hidden, out_dim))
+    return nn.Sequential(*layers)
+
+
 class ContextAdapter(nn.Module):
     """Projects a stage's outcome (e.g. Stage 1's 9D target) down to a
     fixed-width context vector for a downstream stage's conditioning —
@@ -57,6 +82,26 @@ class ContextAdapter(nn.Module):
         return torch.tanh(self.proj(x))
 
 
+BLOCK_REGISTRY: dict[str, type[nn.Module]] = {}
+
+
+def register_block(name: str):
+    def decorator(cls: type[nn.Module]) -> type[nn.Module]:
+        BLOCK_REGISTRY[name] = cls
+        return cls
+
+    return decorator
+
+
+def build_block(name: str, dim: int, cond_dim: int, dropout: float = 0.0) -> nn.Module:
+    """Factory: look up a registered conditioning-injection block by name and
+    construct one instance — `trunk.block_conditioning` (gitea #34)."""
+    if name not in BLOCK_REGISTRY:
+        raise ValueError(f"unknown block conditioning type {name!r}; available: {sorted(BLOCK_REGISTRY)}")
+    return BLOCK_REGISTRY[name](dim, cond_dim, dropout)
+
+
+@register_block("add")
 class ResBlock(nn.Module):
     def __init__(self, dim: int, cond_dim: int, dropout: float = 0.0) -> None:
         super().__init__()
@@ -74,3 +119,66 @@ class ResBlock(nn.Module):
         h = self.dropout(h)
         h = self.linear2(h)
         return x + h
+
+
+@register_block("film")
+class FilmResBlock(nn.Module):
+    """FiLM conditioning (Perez et al. 2018): a per-channel scale+shift
+    modulates the normalized features, on top of the norm's own affine —
+    an *additional* modulation, unlike `AdaLNResBlock` below, which replaces
+    the norm's affine outright. `film_proj` is zero-initialized so
+    `gamma=beta=0` at construction — conditioning has no effect on the
+    output until training moves it, a stable starting point (though not a
+    literal identity block, since `linear1`/`linear2` aren't zero-init)."""
+
+    def __init__(self, dim: int, cond_dim: int, dropout: float = 0.0) -> None:
+        super().__init__()
+        self.norm = nn.LayerNorm(dim)
+        self.linear1 = nn.Linear(dim, dim)
+        self.film_proj = nn.Linear(cond_dim, 2 * dim)
+        nn.init.zeros_(self.film_proj.weight)
+        nn.init.zeros_(self.film_proj.bias)
+        self.act = nn.SiLU()
+        self.dropout = nn.Dropout(dropout)
+        self.linear2 = nn.Linear(dim, dim)
+
+    def forward(self, x: torch.Tensor, cond: torch.Tensor) -> torch.Tensor:
+        h = self.norm(x)
+        gamma, beta = self.film_proj(cond).chunk(2, dim=-1)
+        h = h * (1 + gamma) + beta
+        h = self.linear1(h)
+        h = self.act(h)
+        h = self.dropout(h)
+        h = self.linear2(h)
+        return x + h
+
+
+@register_block("adaln")
+class AdaLNResBlock(nn.Module):
+    """AdaLN-Zero conditioning (DiT, Peebles & Xie 2022): the norm's own
+    affine is replaced by a conditioning-derived scale/shift, and the
+    residual branch is scaled by a conditioning-derived gate. `adaln_proj`
+    is zero-initialized, so `scale=shift=gate=0` at construction — the block
+    is the exact identity function at init (`x + 0 * h' == x`), regardless
+    of `x`/`cond`."""
+
+    def __init__(self, dim: int, cond_dim: int, dropout: float = 0.0) -> None:
+        super().__init__()
+        self.norm = nn.LayerNorm(dim, elementwise_affine=False)
+        self.linear1 = nn.Linear(dim, dim)
+        self.adaln_proj = nn.Linear(cond_dim, 3 * dim)
+        nn.init.zeros_(self.adaln_proj.weight)
+        nn.init.zeros_(self.adaln_proj.bias)
+        self.act = nn.SiLU()
+        self.dropout = nn.Dropout(dropout)
+        self.linear2 = nn.Linear(dim, dim)
+
+    def forward(self, x: torch.Tensor, cond: torch.Tensor) -> torch.Tensor:
+        h = self.norm(x)
+        scale, shift, gate = self.adaln_proj(cond).chunk(3, dim=-1)
+        h = h * (1 + scale) + shift
+        h = self.linear1(h)
+        h = self.act(h)
+        h = self.dropout(h)
+        h = self.linear2(h)
+        return x + gate * h

giant/model/models.py

@@ -4,10 +4,12 @@
 import torch
 import torch.nn as nn
 
+from giant.config import ConditioningAxisConfig, HeadConfig, ParticleTypeConfig
 from giant.constants import CONT_SLOT_DIM, K_MAX, PARTICLE_PHYS_DIM, SEC_DIM, SEC_SLOT_DIM, X_DIM
 from giant.model.encoders import ConditionEncoder
-from giant.model.history import AttentionHistory, HistoryEncoder, MarkovHistory
-from giant.model.layers import ContextAdapter, ResBlock, SinusoidalEmbedding
+from giant.model.history import HistoryEncoder, build_history
+from giant.model.layers import ContextAdapter, ResBlock, SinusoidalEmbedding, build_mlp_head
+from giant.model.objectives import build_objective
 from giant.model.routers import Router
 from giant.model.trunks import build_trunk
 
@@ -16,7 +18,7 @@ from giant.model.trunks import build_trunk
 # ---------------------------------------------------------------------------
 
 
-def resolve_type_n_classes(particle_type_cfg: dict, particle_emb_dim: int) -> int:
+def resolve_type_n_classes(particle_type_cfg: ParticleTypeConfig, particle_emb_dim: int) -> int:
     """Effective width fed to `stage2_type_dim`/`stage2_trunk_sec_dim` in
     place of a bare `conditioning.particle.emb_dim` read. Under
     `target = "onehot"` this is `stage2_model.particle_type.n_classes` (0 =
@@ -27,50 +29,52 @@ def resolve_type_n_classes(particle_type_cfg: dict, particle_emb_dim: int) -> in
     apply — the width stays `conditioning.particle.emb_dim`, the embedding
     table's own dimensionality (`validate_config` requires
     `conditioning.particle.type = "embedding"` here)."""
-    if particle_type_cfg.get("target", "physical") == "onehot":
-        return particle_type_cfg.get("n_classes", 0) or particle_emb_dim
+    if particle_type_cfg.target == "onehot":
+        return particle_type_cfg.n_classes or particle_emb_dim
     return particle_emb_dim
 
 
-def stage2_type_dim(particle_type_cfg: dict, emb_dim: int) -> int:
+def stage2_type_dim(particle_type_cfg: ParticleTypeConfig, emb_dim: int) -> int:
     """Width of a single secondary slot's type slice —
     `PARTICLE_PHYS_DIM` (log_mass, charge) for `target = "physical"`, else
     `emb_dim` (both `"onehot"` class logits and `"embedding"` vectors are
     this many classes/dims wide — callers resolve `emb_dim` via
     `resolve_type_n_classes` first)."""
-    target = particle_type_cfg.get("target", "physical")
-    return PARTICLE_PHYS_DIM if target == "physical" else emb_dim
+    return PARTICLE_PHYS_DIM if particle_type_cfg.target == "physical" else emb_dim
 
 
-def stage2_trunk_sec_dim(particle_type_cfg: dict, generator: str, k_max: int, emb_dim: int) -> int:
+def stage2_trunk_sec_dim(particle_type_cfg: ParticleTypeConfig, generator: str, k_max: int, emb_dim: int) -> int:
     """`Stage2OneShot`'s trunk output width.
 
     `target = "physical"` is untouched from v0.2/today:
     `k_max * SEC_SLOT_DIM`, the type slice folded into the same
     flow-matched/WGAN vector as the continuous stick/dir slots.
 
-    `target` in `("onehot", "embedding")`: under `generator == "wgan"` the
-    type slice is still folded in (adversarial for onehot via ST-Gumbel,
-    already-continuous for embedding), just `emb_dim` wide instead of
-    `PARTICLE_PHYS_DIM` wide: `k_max * (CONT_SLOT_DIM + emb_dim)`. Under
-    `generator in ("flow", "ddpm")` the type slice isn't part of this vector
-    at all — it's `Stage2OneShot.type_head`'s job instead — so the trunk
-    only covers `k_max * CONT_SLOT_DIM`.
+    `target` in `("onehot", "embedding")`: under an objective with
+    `folds_type_slice` (currently just wgan) the type slice is still folded
+    in (adversarial for onehot via ST-Gumbel, already-continuous for
+    embedding), just `emb_dim` wide instead of `PARTICLE_PHYS_DIM` wide:
+    `k_max * (CONT_SLOT_DIM + emb_dim)`. Otherwise (flow/ddpm) the type slice
+    isn't part of this vector at all — it's `Stage2OneShot.type_head`'s job
+    instead — so the trunk only covers `k_max * CONT_SLOT_DIM`.
     """
-    target = particle_type_cfg.get("target", "physical")
-    if target == "physical":
+    if particle_type_cfg.target == "physical":
         return k_max * SEC_SLOT_DIM
-    if generator == "wgan":
+    if build_objective(generator).folds_type_slice:
         return k_max * (CONT_SLOT_DIM + emb_dim)
     return k_max * CONT_SLOT_DIM
 
 
-class Stage1Model(nn.Module):
-    """Predicts the 9D primary post-step vector. No `n_sec_head` — fresh runs
-    move it to stage 2, except for a migrated v0.2 checkpoint
-    (`n_sec_head_k_max` given), where it stays attached here
-    since that's where its weights live and what conditioning it was trained
-    against (see `_migrate_legacy_model_config`).
+class StageModel(nn.Module):
+    """Base owning the scaffolding common to `Stage1Model`, `Stage2OneShot`,
+    `Stage2Autoregressive` (gitea #39): build-or-share `cond_enc`,
+    `particle_type_cfg` normalisation, and — via `_build_trunk_and_heads`,
+    called by each subclass's `__init__` once its own conditioning-assembly
+    modules exist — the objective/time-embedding/trunk construction and the
+    `n_sec_head`/`type_head` classifier heads. A subclass supplies only its
+    own conditioning assembly (`Stage1Model` uses `cond_enc` directly;
+    `Stage2OneShot`/`Stage2Autoregressive` add a context-fusion path) and its
+    trunk's output width.
 
     `cond_enc`, if given, is used in place of building a fresh
     `ConditionEncoder` — `conditioning.share_stages = true`: `build_models`
@@ -81,8 +85,149 @@ class Stage1Model(nn.Module):
         self,
         pdg_vocab: int,
         mat_vocab: int,
-        particle_cfg: dict,
-        material_cfg: dict,
+        particle_cfg: ConditioningAxisConfig,
+        material_cfg: ConditioningAxisConfig,
+        cond_out_dim: int,
+        generator: str,
+        noise_dim: int,
+        k_max: int | None = None,
+        particle_type_cfg: ParticleTypeConfig | None = None,
+        cond_enc: ConditionEncoder | None = None,
+    ) -> None:
+        super().__init__()
+        self.generator_kind = generator
+        self.noise_dim = noise_dim
+        self.k_max = k_max
+        # `ParticleTypeConfig()`'s own dataclass default is target="onehot"
+        # (the config.toml default when [stage2_model.particle_type] is
+        # omitted) — a different question from "nobody passed anything to
+        # this constructor", which direct/test construction relies on
+        # defaulting to "physical" (build_models/build_critics always pass
+        # particle_type_cfg explicitly, so this sentinel is never hit there).
+        self.particle_type_cfg = (
+            particle_type_cfg if particle_type_cfg is not None else ParticleTypeConfig(target="physical")
+        )
+        self.type_dim = stage2_type_dim(
+            self.particle_type_cfg, resolve_type_n_classes(self.particle_type_cfg, particle_cfg.emb_dim)
+        )
+        self.cond_enc = (
+            cond_enc
+            if cond_enc is not None
+            else ConditionEncoder(pdg_vocab, mat_vocab, particle_cfg, material_cfg, out_dim=cond_out_dim)
+        )
+
+    def _build_trunk_and_heads(
+        self,
+        *,
+        trunk_out_dim: int,
+        hidden_dim: int,
+        n_res_blocks: int,
+        cond_out_dim: int,
+        time_dim: int,
+        router: Router | None,
+        trunk_type: str,
+        block_conditioning: str,
+        dropout: float,
+        n_sec_head_k_max: int | None,
+        n_sec_head_cfg: dict | None,
+        type_head_out_dim: int | None,
+        type_head_cfg: dict | None,
+        build_stop_head: bool = False,
+        stop_head_cfg: dict | None = None,
+    ) -> None:
+        """Builds `self.time_emb`, `self.trunk`, `self.n_sec_head`,
+        `self.type_head`, `self.stop_head`. Called by a subclass's `__init__`
+        after it has set up its own conditioning-assembly modules —
+        `merged_cond_dim` below must match the width that assembly
+        (`_cond_embed`/`_base_cond`/`_token_cond`, or plain `cond_enc` for
+        `Stage1Model`) actually produces.
+
+        `n_sec_head` is built iff `n_sec_head_k_max is not None` (output
+        width `n_sec_head_k_max + 1`) — `Stage1Model` passes this only for a
+        migrated v0.2 checkpoint, `Stage2OneShot`/`Stage2Autoregressive` pass
+        it whenever `build_n_sec_head=True`. `type_head` is built iff
+        `type_head_out_dim is not None` (the caller — only the two Stage2
+        classes — passes `None` exactly when `particle_type_cfg.target ==
+        "physical"`) *and* the objective doesn't fold the type slice into its
+        own trunk output (checked here, since `objective` is already needed
+        for the trunk itself). `stop_head` is built iff `build_stop_head` —
+        only `Stage2Autoregressive` ever passes `True` (`n_sec.mode ==
+        "stop_token"`, mutually exclusive with `n_sec_head`), a single
+        `cond_out_dim -> 1` logit per call, same `HeadConfig` shape rules as
+        the other two heads.
+        """
+        objective = build_objective(self.generator_kind)
+        has_time = objective.needs_time
+        self.time_emb = SinusoidalEmbedding(time_dim) if has_time else None
+        merged_cond_dim = (time_dim if has_time else 0) + cond_out_dim
+        in_dim = objective.trunk_in_dim(trunk_out_dim, self.noise_dim)
+        self.trunk = build_trunk(
+            router,
+            trunk_type,
+            in_dim,
+            trunk_out_dim,
+            hidden_dim,
+            n_res_blocks,
+            merged_cond_dim,
+            dropout,
+            block_conditioning,
+        )
+        self.n_sec_head = None
+        if n_sec_head_k_max is not None:
+            head_cfg = HeadConfig.from_dict(n_sec_head_cfg)
+            hidden = max(1, round(hidden_dim * head_cfg.hidden_ratio))
+            self.n_sec_head = build_mlp_head(cond_out_dim, n_sec_head_k_max + 1, hidden, head_cfg.depth)
+        self.type_head = None
+        if type_head_out_dim is not None and not objective.folds_type_slice:
+            head_cfg = HeadConfig.from_dict(type_head_cfg)
+            hidden = max(1, round(hidden_dim * head_cfg.hidden_ratio))
+            self.type_head = build_mlp_head(cond_out_dim, type_head_out_dim, hidden, head_cfg.depth)
+        self.stop_head = None
+        if build_stop_head:
+            head_cfg = HeadConfig.from_dict(stop_head_cfg)
+            hidden = max(1, round(hidden_dim * head_cfg.hidden_ratio))
+            self.stop_head = build_mlp_head(cond_out_dim, 1, hidden, head_cfg.depth)
+
+    def _require_n_sec_head(self) -> None:
+        if self.n_sec_head is None:
+            raise RuntimeError(
+                f"this {type(self).__name__} has no n_sec_head — it belongs to "
+                "a migrated v0.2 checkpoint (n_sec.owner='stage1'); call "
+                "stage1.predict_n_sec(cond_cont, cond_cat) instead"
+            )
+
+    def _require_type_head(self) -> None:
+        if self.type_head is None:
+            raise RuntimeError(
+                f"this {type(self).__name__} has no type_head — either "
+                "particle_type.target='physical' (the type slice is part of "
+                "forward()'s own output) or generator='wgan' (the WGAN "
+                "trainer reads the type slice out of forward()'s output "
+                "directly instead)"
+            )
+
+    def _require_stop_head(self) -> None:
+        if self.stop_head is None:
+            raise RuntimeError(
+                f"this {type(self).__name__} has no stop_head — only a "
+                "Stage2Autoregressive built with stage2_model.n_sec.mode = "
+                "'stop_token' owns one"
+            )
+
+
+class Stage1Model(StageModel):
+    """Predicts the 9D primary post-step vector. No `n_sec_head` — fresh runs
+    move it to stage 2, except for a migrated v0.2 checkpoint
+    (`n_sec_head_k_max` given), where it stays attached here
+    since that's where its weights live and what conditioning it was trained
+    against (see `_migrate_legacy_model_config`)."""
+
+    def __init__(
+        self,
+        pdg_vocab: int,
+        mat_vocab: int,
+        particle_cfg: ConditioningAxisConfig,
+        material_cfg: ConditioningAxisConfig,
         hidden_dim: int = 256,
         n_res_blocks: int = 6,
         cond_out_dim: int = 128,
@@ -92,29 +237,37 @@ class Stage1Model(nn.Module):
         time_dim: int = 64,
         noise_dim: int = 64,
         router: Router | None = None,
+        trunk_type: str = "resmlp",
+        block_conditioning: str = "add",
         n_sec_head_k_max: int | None = None,
         cond_enc: ConditionEncoder | None = None,
+        n_sec_head_cfg: dict | None = None,
     ) -> None:
-        super().__init__()
-        self.generator_kind = generator
-        self.noise_dim = noise_dim
-        self.cond_enc = (
-            cond_enc
-            if cond_enc is not None
-            else ConditionEncoder(pdg_vocab, mat_vocab, particle_cfg, material_cfg, out_dim=cond_out_dim)
+        super().__init__(
+            pdg_vocab,
+            mat_vocab,
+            particle_cfg,
+            material_cfg,
+            cond_out_dim=cond_out_dim,
+            generator=generator,
+            noise_dim=noise_dim,
+            cond_enc=cond_enc,
+        )
+        self._build_trunk_and_heads(
+            trunk_out_dim=x_dim,
+            hidden_dim=hidden_dim,
+            n_res_blocks=n_res_blocks,
+            cond_out_dim=cond_out_dim,
+            time_dim=time_dim,
+            router=router,
+            trunk_type=trunk_type,
+            block_conditioning=block_conditioning,
+            dropout=dropout,
+            n_sec_head_k_max=n_sec_head_k_max,
+            n_sec_head_cfg=n_sec_head_cfg,
+            type_head_out_dim=None,
+            type_head_cfg=None,
         )
-        has_time = generator in ("flow", "ddpm")
-        self.time_emb = SinusoidalEmbedding(time_dim) if has_time else None
-        merged_cond_dim = (time_dim if has_time else 0) + cond_out_dim
-        in_dim = noise_dim if generator == "wgan" else x_dim
-        self.trunk = build_trunk(router, in_dim, x_dim, hidden_dim, n_res_blocks, merged_cond_dim, dropout)
-        self.n_sec_head = None
-        if n_sec_head_k_max is not None:
-            self.n_sec_head = nn.Sequential(
-                nn.Linear(cond_out_dim, hidden_dim // 2),
-                nn.SiLU(),
-                nn.Linear(hidden_dim // 2, n_sec_head_k_max + 1),
-            )
 
     def forward(
         self,
@@ -127,21 +280,28 @@ class Stage1Model(nn.Module):
         cond = torch.cat([self.time_emb(t), c_emb], dim=-1) if self.time_emb is not None else c_emb
         return self.trunk(x_t, cond, cond_cont, cond_cat)
 
-    def predict_n_sec(self, cond_cont: torch.Tensor, cond_cat: torch.Tensor) -> torch.Tensor:
-        """Return n_sec logits (B, K_MAX+1) from conditioning alone. Only
-        valid on a migrated v0.2 checkpoint's Stage1Model — fresh v0.3.0
-        configs predict n_sec from Stage2OneShot instead."""
+    def _require_n_sec_head(self) -> None:
+        """Overrides `StageModel`'s guard — a `Stage1Model` with no
+        `n_sec_head` points the caller to stage 2 (n_sec's default owner),
+        not to `stage1` as the base's message would."""
         if self.n_sec_head is None:
             raise RuntimeError(
                 "this Stage1Model has no n_sec_head — n_sec now lives on "
                 "stage 2 by default; this method only exists "
                 "for a migrated v0.2 checkpoint (n_sec.owner='stage1')"
             )
+
+    def predict_n_sec(self, cond_cont: torch.Tensor, cond_cat: torch.Tensor) -> torch.Tensor:
+        """Return n_sec logits (B, K_MAX+1) from conditioning alone. Only
+        valid on a migrated v0.2 checkpoint's Stage1Model — fresh v0.3.0
+        configs predict n_sec from Stage2OneShot instead."""
+        self._require_n_sec_head()
+        assert self.n_sec_head is not None
         c_emb = self.cond_enc(cond_cont, cond_cat)
         return self.n_sec_head(c_emb)
 
 
-class Stage2OneShot(nn.Module):
+class Stage2OneShot(StageModel):
     """Predicts all `k_max` secondary slots simultaneously — v0.2 behaviour,
     reproduced exactly (`decoder = "autoregressive"` is `Stage2Autoregressive`,
     step 4/5, not implemented yet).
@@ -150,29 +310,27 @@ class Stage2OneShot(nn.Module):
     (a migrated v0.2 checkpoint, whose n_sec_head instead attaches to
     Stage1Model — see `_migrate_legacy_model_config`).
 
-    `particle_type_cfg["target"]` (default `"physical"`) selects the
+    `particle_type_cfg.target` (default `"physical"`) selects the
     secondary-type mechanism: `"physical"` keeps the type slice folded into
     the trunk's own
     flow-matched/WGAN output, unchanged from v0.2 (`sec_dim` — computed by
     the caller via `stage2_trunk_sec_dim` — already reflects this). Under
-    `"onehot"`/`"embedding"` with `generator in ("flow", "ddpm")`, the type
+    `"onehot"`/`"embedding"` with an objective (`giant.model.objectives`) that
+    doesn't fold the type slice (flow/ddpm), the type
     slice is predicted by a separate `type_head` instead (same shape pattern
     as `n_sec_head`) — `sec_dim` then covers only the continuous
     stick/dir slots, `type_head` covers `k_max * emb_dim` type logits/vectors.
-    Under `generator == "wgan"` the type slice stays folded into `sec_dim`
+    Under a folding objective (wgan) the type slice stays folded into `sec_dim`
     (just `emb_dim` instead of `PARTICLE_PHYS_DIM` wide) and `type_head` is
     unused (`None`) — the WGAN trainer handles the ST-Gumbel relaxation.
-
-    `cond_enc`, if given, is used in place of building a fresh
-    `ConditionEncoder` — see `Stage1Model`'s docstring (`conditioning.share_stages`).
     """
 
     def __init__(
         self,
         pdg_vocab: int,
         mat_vocab: int,
-        particle_cfg: dict,
-        material_cfg: dict,
+        particle_cfg: ConditioningAxisConfig,
+        material_cfg: ConditioningAxisConfig,
         hidden_dim: int = 256,
         n_res_blocks: int = 6,
         cond_out_dim: int = 128,
@@ -185,51 +343,48 @@ class Stage2OneShot(nn.Module):
         noise_dim: int = 64,
         k_max: int = K_MAX,
         router: Router | None = None,
+        trunk_type: str = "resmlp",
+        block_conditioning: str = "add",
         build_n_sec_head: bool = True,
-        particle_type_cfg: dict | None = None,
+        particle_type_cfg: ParticleTypeConfig | None = None,
         cond_enc: ConditionEncoder | None = None,
+        n_sec_head_cfg: dict | None = None,
+        type_head_cfg: dict | None = None,
     ) -> None:
-        super().__init__()
-        self.generator_kind = generator
-        self.noise_dim = noise_dim
-        self.k_max = k_max
-        self.particle_type_cfg = dict(particle_type_cfg or {"target": "physical"})
-        self.type_dim = stage2_type_dim(
-            self.particle_type_cfg, resolve_type_n_classes(self.particle_type_cfg, particle_cfg["emb_dim"])
-        )
-        self.cond_enc = (
-            cond_enc
-            if cond_enc is not None
-            else ConditionEncoder(pdg_vocab, mat_vocab, particle_cfg, material_cfg, out_dim=cond_out_dim)
+        super().__init__(
+            pdg_vocab,
+            mat_vocab,
+            particle_cfg,
+            material_cfg,
+            cond_out_dim=cond_out_dim,
+            generator=generator,
+            noise_dim=noise_dim,
+            k_max=k_max,
+            particle_type_cfg=particle_type_cfg,
+            cond_enc=cond_enc,
         )
         self.context_adapter = ContextAdapter(x_dim, context_dim)
         self.fuse = nn.Sequential(
             nn.Linear(cond_out_dim + context_dim, cond_out_dim),
             nn.SiLU(),
         )
-        has_time = generator in ("flow", "ddpm")
-        self.time_emb = SinusoidalEmbedding(time_dim) if has_time else None
-        merged_cond_dim = (time_dim if has_time else 0) + cond_out_dim
-        in_dim = noise_dim if generator == "wgan" else sec_dim
-        self.trunk = build_trunk(router, in_dim, sec_dim, hidden_dim, n_res_blocks, merged_cond_dim, dropout)
-        self.n_sec_head = None
-        if build_n_sec_head:
-            self.n_sec_head = nn.Sequential(
-                nn.Linear(cond_out_dim, hidden_dim // 2),
-                nn.SiLU(),
-                nn.Linear(hidden_dim // 2, k_max + 1),
-            )
-        self.type_head = None
-        target = self.particle_type_cfg.get("target", "physical")
-        if target != "physical" and generator in ("flow", "ddpm"):
-            emb_dim = resolve_type_n_classes(self.particle_type_cfg, particle_cfg["emb_dim"])
-            self.type_head = nn.Sequential(
-                nn.Linear(cond_out_dim, hidden_dim // 2),
-                nn.SiLU(),
-                nn.Linear(hidden_dim // 2, k_max * emb_dim),
-            )
-            self._type_k_max = k_max
-            self._type_emb_dim = emb_dim
+        target = self.particle_type_cfg.target
+        type_head_out_dim = None if target == "physical" else k_max * self.type_dim
+        self._build_trunk_and_heads(
+            trunk_out_dim=sec_dim,
+            hidden_dim=hidden_dim,
+            n_res_blocks=n_res_blocks,
+            cond_out_dim=cond_out_dim,
+            time_dim=time_dim,
+            router=router,
+            trunk_type=trunk_type,
+            block_conditioning=block_conditioning,
+            dropout=dropout,
+            n_sec_head_k_max=k_max if build_n_sec_head else None,
+            n_sec_head_cfg=n_sec_head_cfg,
+            type_head_out_dim=type_head_out_dim,
+            type_head_cfg=type_head_cfg,
+        )
 
     def _cond_embed(self, cond_cont: torch.Tensor, cond_cat: torch.Tensor, stage1_out: torch.Tensor) -> torch.Tensor:
         base = self.cond_enc(cond_cont, cond_cat)
@@ -254,12 +409,8 @@ class Stage2OneShot(nn.Module):
         cond_cat: torch.Tensor,
         stage1_out: torch.Tensor,
     ) -> torch.Tensor:
-        if self.n_sec_head is None:
-            raise RuntimeError(
-                "this Stage2OneShot has no n_sec_head — it belongs to a "
-                "migrated v0.2 checkpoint (n_sec.owner='stage1'); call "
-                "stage1.predict_n_sec(cond_cont, cond_cat) instead"
-            )
+        self._require_n_sec_head()
+        assert self.n_sec_head is not None
         c_emb = self._cond_embed(cond_cont, cond_cat, stage1_out)
         return self.n_sec_head(c_emb)
 
@@ -273,19 +424,13 @@ class Stage2OneShot(nn.Module):
         vectors (`target="embedding"`) — only under `generator in ("flow",
         "ddpm")`; `generator == "wgan"` folds the type slice into `forward`'s
         own output instead (see class docstring)."""
-        if self.type_head is None:
-            raise RuntimeError(
-                "this Stage2OneShot has no type_head — either "
-                "particle_type.target='physical' (the type slice is part of "
-                "forward()'s own output) or generator='wgan' (the WGAN "
-                "trainer reads the type slice out of forward()'s output "
-                "directly instead)"
-            )
+        self._require_type_head()
+        assert self.type_head is not None
         c_emb = self._cond_embed(cond_cont, cond_cat, stage1_out)
-        return self.type_head(c_emb).view(-1, self._type_k_max, self._type_emb_dim)
+        return self.type_head(c_emb).view(-1, self.k_max, self.type_dim)
 
 
-class Stage2Autoregressive(nn.Module):
+class Stage2Autoregressive(StageModel):
     """Emits secondaries one at a time in descending-energy order, instead
     of `Stage2OneShot`'s simultaneous
     k_max-slot prediction. `history` selects `MarkovHistory` or
@@ -305,18 +450,21 @@ class Stage2Autoregressive(nn.Module):
     `context_adapter` only) feeds `predict_n_sec`, since n_sec doesn't depend
     on token position; `_token_cond` additionally fuses in the history
     encoding and two running scalars (remaining energy-budget fraction,
-    normalized slot index), and feeds `forward`/`predict_type`/the trunk.
+    normalized slot index), and feeds `forward`/`predict_type`/`predict_stop`/
+    the trunk.
 
-    `cond_enc`, if given, is used in place of building a fresh
-    `ConditionEncoder` — see `Stage1Model`'s docstring (`conditioning.share_stages`).
+    `n_sec.mode = "stop_token"` (`build_stop_head=True`) replaces
+    `predict_n_sec`'s one-shot classifier with `predict_stop`'s per-token EOS
+    logit instead — the two heads are mutually exclusive (`build_n_sec_head`
+    is `False` whenever this is `True`, see `giant.model.builders`).
     """
 
     def __init__(
         self,
         pdg_vocab: int,
         mat_vocab: int,
-        particle_cfg: dict,
-        material_cfg: dict,
+        particle_cfg: ConditioningAxisConfig,
+        material_cfg: ConditioningAxisConfig,
         hidden_dim: int = 256,
         n_res_blocks: int = 6,
         cond_out_dim: int = 128,
@@ -328,29 +476,34 @@ class Stage2Autoregressive(nn.Module):
         noise_dim: int = 64,
         k_max: int = K_MAX,
         router: Router | None = None,
+        trunk_type: str = "resmlp",
+        block_conditioning: str = "add",
         build_n_sec_head: bool = True,
-        particle_type_cfg: dict | None = None,
+        particle_type_cfg: ParticleTypeConfig | None = None,
         history: str = "markov",
         attn_n_heads: int = 4,
         attn_n_layers: int = 2,
         cond_enc: ConditionEncoder | None = None,
+        n_sec_head_cfg: dict | None = None,
+        type_head_cfg: dict | None = None,
+        build_stop_head: bool = False,
+        stop_sampling: str = "greedy",
+        stop_head_cfg: dict | None = None,
     ) -> None:
-        super().__init__()
-        if history not in ("markov", "attention"):
-            raise ValueError(f"stage2_model.autoregressive.history={history!r} — must be 'markov' or 'attention'")
-        self.history_kind = history
-        self.generator_kind = generator
-        self.noise_dim = noise_dim
-        self.k_max = k_max
-        self.particle_type_cfg = dict(particle_type_cfg or {"target": "physical"})
-        emb_dim = resolve_type_n_classes(self.particle_type_cfg, particle_cfg["emb_dim"])
-        self.type_dim = stage2_type_dim(self.particle_type_cfg, emb_dim)
-
-        self.cond_enc = (
-            cond_enc
-            if cond_enc is not None
-            else ConditionEncoder(pdg_vocab, mat_vocab, particle_cfg, material_cfg, out_dim=cond_out_dim)
+        super().__init__(
+            pdg_vocab,
+            mat_vocab,
+            particle_cfg,
+            material_cfg,
+            cond_out_dim=cond_out_dim,
+            generator=generator,
+            noise_dim=noise_dim,
+            k_max=k_max,
+            particle_type_cfg=particle_type_cfg,
+            cond_enc=cond_enc,
         )
+        self.history_kind = history
+        self.stop_sampling = stop_sampling
         self.context_adapter = ContextAdapter(x_dim, context_dim)
         self.base_fuse = nn.Sequential(
             nn.Linear(cond_out_dim + context_dim, cond_out_dim),
@@ -362,10 +515,8 @@ class Stage2Autoregressive(nn.Module):
         # this, a reasonable default rather than a design-doc-specified value.
         history_dim = cond_out_dim
         hist_in_dim = CONT_SLOT_DIM + self.type_dim
-        self.history_encoder: HistoryEncoder = (
-            AttentionHistory(hist_in_dim, history_dim, n_heads=attn_n_heads, n_layers=attn_n_layers)
-            if history == "attention"
-            else MarkovHistory(hist_in_dim, history_dim)
+        self.history_encoder: HistoryEncoder = build_history(
+            history, hist_in_dim, history_dim, n_heads=attn_n_heads, n_layers=attn_n_layers
         )
         token_fuse_in = cond_out_dim + context_dim + history_dim + 2  # +2: remaining_frac, slot_idx
         self.token_fuse = nn.Sequential(
@@ -373,37 +524,31 @@ class Stage2Autoregressive(nn.Module):
             nn.SiLU(),
         )
 
-        has_time = generator in ("flow", "ddpm")
-        self.time_emb = SinusoidalEmbedding(time_dim) if has_time else None
-        merged_cond_dim = (time_dim if has_time else 0) + cond_out_dim
-        token_dim = stage2_trunk_sec_dim(self.particle_type_cfg, generator, 1, emb_dim)
-        in_dim = noise_dim if generator == "wgan" else token_dim
-        self.trunk = build_trunk(
-            router,
-            in_dim,
-            token_dim,
-            hidden_dim,
-            n_res_blocks,
-            merged_cond_dim,
-            dropout,
+        # `self.type_dim` (set by StageModel.__init__) doubles as the raw
+        # `emb_dim` `stage2_trunk_sec_dim` wants: for a non-"physical" target
+        # `stage2_type_dim` already resolved `type_dim` to exactly that value;
+        # for "physical" the emb_dim argument goes unused anyway.
+        token_dim = stage2_trunk_sec_dim(self.particle_type_cfg, generator, 1, self.type_dim)
+        target = self.particle_type_cfg.target
+        type_head_out_dim = None if target == "physical" else self.type_dim
+        self._build_trunk_and_heads(
+            trunk_out_dim=token_dim,
+            hidden_dim=hidden_dim,
+            n_res_blocks=n_res_blocks,
+            cond_out_dim=cond_out_dim,
+            time_dim=time_dim,
+            router=router,
+            trunk_type=trunk_type,
+            block_conditioning=block_conditioning,
+            dropout=dropout,
+            n_sec_head_k_max=k_max if build_n_sec_head else None,
+            n_sec_head_cfg=n_sec_head_cfg,
+            type_head_out_dim=type_head_out_dim,
+            type_head_cfg=type_head_cfg,
+            build_stop_head=build_stop_head,
+            stop_head_cfg=stop_head_cfg,
         )
 
-        self.n_sec_head = None
-        if build_n_sec_head:
-            self.n_sec_head = nn.Sequential(
-                nn.Linear(cond_out_dim, hidden_dim // 2),
-                nn.SiLU(),
-                nn.Linear(hidden_dim // 2, k_max + 1),
-            )
-        self.type_head = None
-        target = self.particle_type_cfg.get("target", "physical")
-        if target != "physical" and generator in ("flow", "ddpm"):
-            self.type_head = nn.Sequential(
-                nn.Linear(cond_out_dim, hidden_dim // 2),
-                nn.SiLU(),
-                nn.Linear(hidden_dim // 2, self.type_dim),
-            )
-
     def _base_cond(self, cond_cont: torch.Tensor, cond_cat: torch.Tensor, stage1_out: torch.Tensor) -> torch.Tensor:
         base = self.cond_enc(cond_cont, cond_cat)
         ctx = self.context_adapter(stage1_out)
@@ -437,12 +582,12 @@ class Stage2Autoregressive(nn.Module):
 
     def init_history_cache(self):
         """Inference-only incremental-decoding state for `self.history_encoder`
-        (`giant/sample.py`'s AR loop): `None` under `history="markov"` (its
-        per-step cost is already O(1) — see `HistoryEncoder`'s docstring), or
-        `AttentionHistory.init_cache()` under `history="attention"`."""
-        if isinstance(self.history_encoder, AttentionHistory):
-            return self.history_encoder.init_cache()
-        return None
+        (`giant/sample.py`'s AR loop) — whatever `self.history_encoder.init_cache()`
+        returns for the configured `history` type: `None` under `history="markov"`
+        (its per-step cost is already O(1) — see `HistoryEncoder`'s docstring),
+        or `AttentionHistory.init_cache()`'s real per-block KV cache under
+        `history="attention"`."""
+        return self.history_encoder.init_cache()
 
     def history_step(self, token_feat: torch.Tensor, has_prev: torch.Tensor, cache) -> tuple[torch.Tensor, object]:
         """One inference slot's worth of history encoding: advances `cache`
@@ -454,9 +599,7 @@ class Stage2Autoregressive(nn.Module):
         every model call made for this slot), `new_cache` is what to pass into
         the *next* slot's `history_step`. Must be called exactly once per
         slot — see `AttentionHistory.step`'s docstring."""
-        if isinstance(self.history_encoder, AttentionHistory):
-            return self.history_encoder.step(token_feat, has_prev, cache)
-        return self.history_encoder(token_feat, has_prev), cache
+        return self.history_encoder.step(token_feat, has_prev, cache)
 
     def forward(
         self,
@@ -496,12 +639,8 @@ class Stage2Autoregressive(nn.Module):
         return out.view(B, K, -1)
 
     def predict_n_sec(self, cond_cont: torch.Tensor, cond_cat: torch.Tensor, stage1_out: torch.Tensor) -> torch.Tensor:
-        if self.n_sec_head is None:
-            raise RuntimeError(
-                "this Stage2Autoregressive has no n_sec_head — it belongs to "
-                "a migrated v0.2 checkpoint (n_sec.owner='stage1'); call "
-                "stage1.predict_n_sec(cond_cont, cond_cat) instead"
-            )
+        self._require_n_sec_head()
+        assert self.n_sec_head is not None
         return self.n_sec_head(self._base_cond(cond_cont, cond_cat, stage1_out))
 
     def predict_type(
@@ -515,14 +654,8 @@ class Stage2Autoregressive(nn.Module):
         slot_idx: torch.Tensor,
         hist: torch.Tensor | None = None,
     ) -> torch.Tensor:
-        if self.type_head is None:
-            raise RuntimeError(
-                "this Stage2Autoregressive has no type_head — either "
-                "particle_type.target='physical' (the type slice is part of "
-                "forward()'s own output) or generator='wgan' (the WGAN "
-                "trainer reads the type slice out of forward()'s output "
-                "directly instead)"
-            )
+        self._require_type_head()
+        assert self.type_head is not None
         c_emb = self._token_cond(
             cond_cont,
             cond_cat,
@@ -536,6 +669,38 @@ class Stage2Autoregressive(nn.Module):
         B, K, _ = c_emb.shape
         return self.type_head(c_emb.reshape(B * K, -1)).view(B, K, self.type_dim)
 
+    def predict_stop(
+        self,
+        cond_cont: torch.Tensor,
+        cond_cat: torch.Tensor,
+        stage1_out: torch.Tensor,
+        history_feat: torch.Tensor,
+        has_prev: torch.Tensor,
+        remaining_frac: torch.Tensor,
+        slot_idx: torch.Tensor,
+        hist: torch.Tensor | None = None,
+    ) -> torch.Tensor:
+        """`(B, K)` raw stop logits — `n_sec.mode = "stop_token"` only.
+        Evaluated on slot `k`'s own conditioning (which carries slot `k-1`'s
+        history, same as `predict_type`), so this is `P(n_sec == k |
+        prefix)`: a high logit at slot `k` means "stop before generating a
+        token here" — the caller (`giant.sample.sample_secondaries_ar`)
+        checks it before spending a model call on that slot's token."""
+        self._require_stop_head()
+        assert self.stop_head is not None
+        c_emb = self._token_cond(
+            cond_cont,
+            cond_cat,
+            stage1_out,
+            history_feat,
+            has_prev,
+            remaining_frac,
+            slot_idx,
+            hist=hist,
+        )
+        B, K, _ = c_emb.shape
+        return self.stop_head(c_emb.reshape(B * K, -1)).view(B, K)
+
 
 class CriticModel(nn.Module):
     """Generator-agnostic WGAN-GP critic body: a scalar realism score, for
@@ -547,8 +712,8 @@ class CriticModel(nn.Module):
         self,
         pdg_vocab: int,
         mat_vocab: int,
-        particle_cfg: dict,
-        material_cfg: dict,
+        particle_cfg: ConditioningAxisConfig,
+        material_cfg: ConditioningAxisConfig,
         in_dim: int,
         hidden_dim: int = 256,
         n_res_blocks: int = 6,

giant/model/network.py

@@ -9,18 +9,47 @@ import X` call site keeps working unchanged.
 
 from giant.model._legacy import _migrate_legacy_model_config, migrate_legacy_state_dict
 from giant.model.builders import build_critics, build_models
-from giant.model.encoders import ConditionEncoder, cat_col_layout
-from giant.model.history import AttentionHistory, HistoryEncoder, MarkovHistory, _CausalAttnBlock
-from giant.model.layers import ContextAdapter, ResBlock, SinusoidalEmbedding, _make_axis_mlp
+from giant.model.encoders import ConditionEncoder
+from giant.model.history import (
+    HISTORY_REGISTRY,
+    AttentionHistory,
+    HistoryEncoder,
+    MarkovHistory,
+    _CausalAttnBlock,
+    build_history,
+    register_history,
+)
+from giant.model.layers import (
+    BLOCK_REGISTRY,
+    AdaLNResBlock,
+    ContextAdapter,
+    FilmResBlock,
+    ResBlock,
+    SinusoidalEmbedding,
+    _make_axis_mlp,
+    build_block,
+    build_mlp_head,
+    register_block,
+)
 from giant.model.models import (
     CriticModel,
     Stage1Model,
     Stage2Autoregressive,
     Stage2OneShot,
+    StageModel,
     resolve_type_n_classes,
     stage2_trunk_sec_dim,
     stage2_type_dim,
 )
+from giant.model.objectives import (
+    OBJECTIVE_REGISTRY,
+    DdpmObjective,
+    FlowObjective,
+    Objective,
+    WganObjective,
+    build_objective,
+    register_objective,
+)
 from giant.model.routers import (
     ROUTER_REGISTRY,
     ComposedRouter,
@@ -36,25 +65,34 @@ from giant.model.routers import (
     register_router,
 )
 from giant.model.trunks import (
+    TRUNK_REGISTRY,
     ExpertTrunk,
-    MonolithicTrunk,
     RoutedTrunk,
     Trunk,
     _route_forward,
+    build_expert_body,
     build_trunk,
+    register_trunk,
 )
 
 __all__ = [
+    "AdaLNResBlock",
     "AttentionHistory",
+    "BLOCK_REGISTRY",
     "ComposedRouter",
     "ConditionEncoder",
     "ContextAdapter",
     "CriticModel",
+    "DdpmObjective",
     "EnergyRouter",
     "ExpertTrunk",
+    "FilmResBlock",
+    "FlowObjective",
+    "HISTORY_REGISTRY",
     "HistoryEncoder",
     "MarkovHistory",
-    "MonolithicTrunk",
+    "OBJECTIVE_REGISTRY",
+    "Objective",
     "PdgRouter",
     "ProcessRouter",
     "ROUTER_REGISTRY",
@@ -65,7 +103,10 @@ __all__ = [
     "Stage1Model",
     "Stage2Autoregressive",
     "Stage2OneShot",
+    "StageModel",
+    "TRUNK_REGISTRY",
     "Trunk",
+    "WganObjective",
     "_CausalAttnBlock",
     "_build_router_from_cfg",
     "_check_router_conditioning_compat",
@@ -73,14 +114,22 @@ __all__ = [
     "_migrate_legacy_model_config",
     "_parse_composed_axes",
     "_route_forward",
+    "build_block",
     "build_composed_router",
     "build_critics",
+    "build_expert_body",
+    "build_history",
+    "build_mlp_head",
     "build_models",
+    "build_objective",
     "build_router",
     "build_trunk",
-    "cat_col_layout",
     "migrate_legacy_state_dict",
+    "register_block",
+    "register_history",
+    "register_objective",
     "register_router",
+    "register_trunk",
     "resolve_type_n_classes",
     "stage2_trunk_sec_dim",
     "stage2_type_dim",

giant/model/objectives.py

@@ -0,0 +1,202 @@
+"""Generative objectives (flow/ddpm/wgan): `Objective` base + registry,
+mirroring `giant.model.routers`'s `Router` pattern (gitea #32). Each objective
+answers, in one place, the handful of questions every stage model/sampler/
+trainer used to re-derive independently from a bare `generator` string: does
+this stage need a time embedding, is it adversarial, does it fold the
+secondary type slice into its own trunk output, what does the trunk take as
+input, which stage-1/stage-2 loss does it train against.
+
+Self-contained (no dependency on `giant.model.models`, unlike `Router` which
+`giant.model.trunks` depends on) — `Objective` never needs to construct a
+stage model or critic itself, only describe one. This also sidesteps a
+`models.py` <-> `objectives.py` import cycle, since `models.py` calls
+`build_objective`.
+"""
+
+import inspect
+
+import torch
+
+from giant.model.schedule import (
+    CosineSchedule,
+    flow_matching_loss,
+    flow_matching_loss_secondary,
+    flow_matching_loss_secondary_ar,
+)
+
+# ---------------------------------------------------------------------------
+# Objective contract
+# ---------------------------------------------------------------------------
+
+
+class Objective:
+    """Contract for a pluggable generative objective. Not an `nn.Module` —
+    unlike `Router`, no objective owns learnable parameters, so a plain
+    strategy object is the honest fit.
+
+    `needs_time`/`is_adversarial`/`folds_type_slice`/`supports_stage2_decoder`
+    are set by each concrete subclass (no defaults here — a new objective
+    should have to state all four, not silently inherit one that happens to
+    be wrong for it). See `FlowObjective`/`DdpmObjective`/`WganObjective`.
+    """
+
+    needs_time: bool
+    is_adversarial: bool
+    folds_type_slice: bool
+    supports_stage2_decoder: bool = True
+
+    def trunk_in_dim(self, out_dim: int, noise_dim: int) -> int:
+        """Width of the trunk's own input — `out_dim` (denoising/flow-matching
+        a same-shape vector) for every non-adversarial objective;
+        `WganObjective` overrides to `noise_dim` (a single-pass noise-to-output
+        generator)."""
+        return out_dim
+
+    def build_schedule(self, n_steps: int, device: torch.device) -> CosineSchedule | None:
+        """Objective-owned auxiliary state a stage trainer must build once
+        and hold onto (device-placed) across its training loop. `None` for
+        every objective except `DdpmObjective` (its noise schedule)."""
+        return None
+
+    def stage1_loss(
+        self,
+        model: torch.nn.Module,
+        x1: torch.Tensor,
+        cond_cont: torch.Tensor,
+        cond_cat: torch.Tensor,
+        *,
+        schedule: object | None = None,
+    ) -> torch.Tensor:
+        """Stage-1 training loss. Only implemented by non-adversarial
+        objectives — `WganObjective` is unused here, `WGANStageTrainer` has
+        its own G/D step instead."""
+        raise NotImplementedError(f"{type(self).__name__} has no stage1_loss")
+
+    def stage2_loss(
+        self,
+        model: torch.nn.Module,
+        x1_s2: torch.Tensor,
+        cond_cont: torch.Tensor,
+        cond_cat: torch.Tensor,
+        stage1_ctx: torch.Tensor,
+        sec_mask: torch.Tensor,
+        *,
+        type_dim: int | None,
+        ar_inputs: dict[str, torch.Tensor] | None = None,
+    ) -> torch.Tensor:
+        """Stage-2 secondary-decoder training loss, one-shot or
+        autoregressive depending on whether `ar_inputs` is given. Same
+        adversarial caveat as `stage1_loss`."""
+        raise NotImplementedError(f"{type(self).__name__} has no stage2_loss")
+
+
+OBJECTIVE_REGISTRY: dict[str, type[Objective]] = {}
+
+
+def register_objective(name: str):
+    def decorator(cls: type[Objective]) -> type[Objective]:
+        OBJECTIVE_REGISTRY[name] = cls
+        return cls
+
+    return decorator
+
+
+def build_objective(name: str, **kwargs) -> Objective:
+    """Factory: look up an `Objective` subclass by name (a `generator`
+    config value) from the registry.
+
+    Every registered objective is fed the same kwargs; kwargs not declared by
+    that type's constructor are silently dropped, so per-type hyperparameters
+    (e.g. `DdpmObjective`'s `n_steps`) can coexist in one call without
+    special-casing — same convention as `giant.model.routers.build_router`.
+    """
+    if name not in OBJECTIVE_REGISTRY:
+        raise ValueError(f"unknown generator/objective {name!r}; available: {sorted(OBJECTIVE_REGISTRY)}")
+    cls = OBJECTIVE_REGISTRY[name]
+    accepted = set(inspect.signature(cls.__init__).parameters) - {"self"}
+    filtered = {k: v for k, v in kwargs.items() if k in accepted}
+    return cls(**filtered)
+
+
+# ---------------------------------------------------------------------------
+# Concrete objectives
+# ---------------------------------------------------------------------------
+
+
+@register_objective("flow")
+class FlowObjective(Objective):
+    """Conditional flow matching (Lipman et al. 2022) — the primary
+    objective. ~10 ODE steps at inference (`giant.sample.sample_flow`)."""
+
+    needs_time = True
+    is_adversarial = False
+    folds_type_slice = False
+
+    def stage1_loss(self, model, x1, cond_cont, cond_cat, *, schedule=None) -> torch.Tensor:
+        return flow_matching_loss(model, x1, cond_cont, cond_cat)
+
+    def stage2_loss(
+        self,
+        model,
+        x1_s2,
+        cond_cont,
+        cond_cat,
+        stage1_ctx,
+        sec_mask,
+        *,
+        type_dim=None,
+        ar_inputs=None,
+    ) -> torch.Tensor:
+        if ar_inputs is not None:
+            return flow_matching_loss_secondary_ar(
+                model,
+                x1_s2,
+                cond_cont,
+                cond_cat,
+                stage1_ctx,
+                ar_inputs["history_feat"],
+                ar_inputs["has_prev"],
+                ar_inputs["remaining_frac"],
+                ar_inputs["slot_idx"],
+                sec_mask,
+                type_dim=type_dim,
+            )
+        return flow_matching_loss_secondary(model, x1_s2, cond_cont, cond_cat, stage1_ctx, sec_mask, type_dim=type_dim)
+
+
+@register_objective("ddpm")
+class DdpmObjective(Objective):
+    """Full DDPM ancestral sampling (Nichol & Dhariwal 2021 cosine schedule)
+    — the throwaway baseline. Stage-1 only: no `Stage2*` class has ever been
+    trained with `generator="ddpm"` in practice, so there's no stage-2 ddpm
+    loss to dispatch to (matches `FlowDDPMStageTrainer`'s pre-existing
+    stage-2 guard)."""
+
+    needs_time = True
+    is_adversarial = False
+    folds_type_slice = False
+    supports_stage2_decoder = False
+
+    def __init__(self, n_steps: int = 1000) -> None:
+        self.n_steps = n_steps
+
+    def build_schedule(self, n_steps: int, device: torch.device) -> CosineSchedule:
+        return CosineSchedule(T=n_steps).to(device)
+
+    def stage1_loss(self, model, x1, cond_cont, cond_cat, *, schedule=None) -> torch.Tensor:
+        assert schedule is not None, "DdpmObjective.stage1_loss needs a schedule (see build_schedule)"
+        return schedule.loss(model, x1, cond_cont, cond_cat)
+
+
+@register_objective("wgan")
+class WganObjective(Objective):
+    """WGAN-GP (Gulrajani et al. 2017) — single forward pass instead of an
+    ODE loop. `stage1_loss`/`stage2_loss` are unused: `WGANStageTrainer` owns
+    its own dual generator/critic step instead of a single scalar loss."""
+
+    needs_time = False
+    is_adversarial = True
+    folds_type_slice = True
+
+    def trunk_in_dim(self, out_dim: int, noise_dim: int) -> int:
+        return noise_dim

giant/model/routers.py

@@ -11,6 +11,7 @@ import torch
 import torch.nn as nn
 import torch.nn.functional as F
 
+from giant.cond_layout import CondLayout
 from giant.constants import COND_DIM
 
 # ---------------------------------------------------------------------------
@@ -44,21 +45,36 @@ class Router(nn.Module):
         straight-through Gumbel-softmax (`gumbel=True`, train mode only):
         hardens the forward pass to a one-hot sample (matching eval-time
         top-1 dispatch) while keeping the soft sample's gradient on backward.
+
+        Forced fp32 (`torch.autocast(..., enabled=False)`) regardless of the
+        caller's ambient `train.precision` autocast region: `clamp_min(1e-8)`
+        below sits under bf16's precision but *above* fp16's ~6e-8 subnormal
+        floor, so `log_probs` degrading here is exactly the kind of quiet
+        drift that cost a whole rollout benchmark before (see the MoE section
+        of CLAUDE.md's Roadmap) — cheap to rule out (gitea #47).
         """
-        probs = self.gate(cond_cont, cond_cat)
-        if not (self.gumbel and self.training):
-            return probs
-        log_probs = torch.log(probs.clamp_min(1e-8))
-        return F.gumbel_softmax(log_probs, tau=self.gumbel_tau, hard=True, dim=-1)
+        with torch.autocast(cond_cont.device.type, enabled=False):
+            probs = self.gate(cond_cont, cond_cat)
+            if not (self.gumbel and self.training):
+                return probs
+            log_probs = torch.log(probs.clamp_min(1e-8))
+            return F.gumbel_softmax(log_probs, tau=self.gumbel_tau, hard=True, dim=-1)
 
     def top1(self, cond_cont: torch.Tensor, cond_cat: torch.Tensor) -> torch.Tensor:
         """(B,) hard expert index, used for eval-time grouped dispatch."""
-        return self.gate(cond_cont, cond_cat).argmax(dim=-1)
+        with torch.autocast(cond_cont.device.type, enabled=False):
+            return self.gate(cond_cont, cond_cat).argmax(dim=-1)
 
     def balance_loss(self, cond_cont: torch.Tensor, cond_cat: torch.Tensor) -> torch.Tensor:
-        """Importance CV^2 load-balancing auxiliary loss (Shazeer et al. 2017)."""
-        importance = self.gate(cond_cont, cond_cat).sum(dim=0)  # (n_experts,)
-        return (importance.std() / (importance.mean() + 1e-8)) ** 2
+        """Importance CV^2 load-balancing auxiliary loss (Shazeer et al. 2017).
+
+        Forced fp32 — `importance` sums `gate()` over the whole batch (a
+        large-magnitude accumulation in reduced precision), then takes a
+        `std/mean` ratio: a classic catastrophic-cancellation shape (gitea
+        #47)."""
+        with torch.autocast(cond_cont.device.type, enabled=False):
+            importance = self.gate(cond_cont, cond_cat).sum(dim=0)  # (n_experts,)
+            return (importance.std() / (importance.mean() + 1e-8)) ** 2
 
     def classify_loss(self, cond_cont: torch.Tensor, cond_cat: torch.Tensor, labels: torch.Tensor) -> torch.Tensor:
         """Optional supervised auxiliary loss shaping the router's own belief.
@@ -75,12 +91,17 @@ class Router(nn.Module):
 
     def gate_stats(self, cond_cont: torch.Tensor, cond_cat: torch.Tensor) -> tuple[torch.Tensor, torch.Tensor]:
         """Diagnostics: `(norm_entropy, importance)` — see v0.2 docstring for
-        the full explanation, unchanged in v0.3.0."""
-        gate = self.gate(cond_cont, cond_cat)  # (B, n_experts)
-        row_entropy = -(gate * (gate + 1e-8).log()).sum(dim=-1)  # (B,)
-        norm_entropy = row_entropy.mean() / math.log(self.n_experts)
-        importance = gate.sum(dim=0)  # (n_experts,)
-        return norm_entropy, importance
+        the full explanation, unchanged in v0.3.0.
+
+        Forced fp32, same rationale as `balance_loss`/`combine_weights`: the
+        `+ 1e-8` epsilon here is `entropy_loss`'s training-loss path too, not
+        just a diagnostic (gitea #47)."""
+        with torch.autocast(cond_cont.device.type, enabled=False):
+            gate = self.gate(cond_cont, cond_cat)  # (B, n_experts)
+            row_entropy = -(gate * (gate + 1e-8).log()).sum(dim=-1)  # (B,)
+            norm_entropy = row_entropy.mean() / math.log(self.n_experts)
+            importance = gate.sum(dim=0)  # (n_experts,)
+            return norm_entropy, importance
 
 
 ROUTER_REGISTRY: dict[str, type[Router]] = {}
@@ -211,7 +232,7 @@ class PdgRouter(Router):
             self.register_buffer("centers", centers)
 
     def gate(self, cond_cont: torch.Tensor, cond_cat: torch.Tensor) -> torch.Tensor:
-        e = self.pdg_emb(cond_cat[:, 0])  # (B, emb_dim)
+        e = self.pdg_emb(cond_cat[:, CondLayout.PDG_COL])  # (B, emb_dim)
         d2 = ((e.unsqueeze(1) - self.centers.unsqueeze(0)) ** 2).sum(-1)  # (B, n_experts)
         return torch.softmax(-d2 / self.temperature, dim=-1)
 
@@ -243,8 +264,8 @@ class ProcessRouter(Router):
         )
 
     def logits(self, cond_cont: torch.Tensor, cond_cat: torch.Tensor) -> torch.Tensor:
-        pdg_e = self.pdg_emb(cond_cat[:, 0])
-        mat_e = self.mat_emb(cond_cat[:, 1])
+        pdg_e = self.pdg_emb(cond_cat[:, CondLayout.PDG_COL])
+        mat_e = self.mat_emb(cond_cat[:, CondLayout.MAT_COL])
         h = torch.cat([cond_cont, pdg_e, mat_e], dim=-1)
         return self.classifier(h)
 

giant/model/summary.py

@@ -0,0 +1,318 @@
+"""Build-only model introspection (gitea #46): construct the resolved
+Stage1/Stage2/critic graph from a config with no dataset attached, and report
+per-module parameter counts, trunk widths, which heads exist, and — via
+differential probing — which `conditioning`/`stage1_model`/`stage2_model`
+config keys actually shape the built model. This is the runtime counterpart
+to `tests/test_config_consumed_keys.py`'s static per-identifier audit: that
+test asks "does any code reference this key's name at all", this module asks
+"given *this* resolved config, does the key change what `build_models`/
+`build_critics` (`giant/model/builders.py`) actually produces".
+
+Differential probing, not identifier matching: build the model once from the
+resolved config and take a structural fingerprint (`_fingerprint` — which
+submodules exist, every parameter's/buffer's shape+dtype, every plain scalar
+attribute stored on any module). Then, for each in-scope leaf key, perturb
+just that one value (`_perturb`), rebuild, and re-fingerprint. A changed
+fingerprint — or a rebuild that raises — means the key was consumed; an
+identical fingerprint means construction never looked at it under this
+particular config. A key can be genuinely inert under one config and live
+under another (e.g. any `stage1_model.router.*` key when `router.enabled =
+false`) — that config-dependence is exactly the "silently degenerate
+combination" issue #46 is after, so it is reported per-run rather than
+baked into a static table.
+
+Keys legitimately owned by the trainer/sampler/rollout rather than by
+`build_models`/`build_critics` (loss weights, WGAN-GP training
+hyperparameters, teacher-forcing and stage1-context schedules, ...) are
+cataloged in `_NOT_BUILD_TIME` below so the report doesn't flag them as
+suspicious. One leaf is inert under every config today —
+`stage2_model.autoregressive.order` — matching
+`tests/test_config_consumed_keys.py`'s own `_KNOWN_UNUSED` entry; it is
+deliberately *not* in `_NOT_BUILD_TIME`, since "always inert" is itself the
+finding those two tests independently converge on.
+"""
+
+import copy
+from dataclasses import dataclass, field
+
+import torch.nn as nn
+
+from giant.config import _get_path, _set_path, leaf_paths
+from giant.model.builders import build_critics, build_models
+from giant.model.trunks import RoutedTrunk
+
+_IN_SCOPE_ROOTS = ("conditioning", "stage1_model", "stage2_model")
+
+_PROBE_STR = "__giant_model_summary_probe__"
+
+# A handful of string leaves branch on equality against one specific literal
+# (e.g. `builders.py`: `stop_token = s2_spec.n_sec.mode == "stop_token"`),
+# where every value other than that literal behaves identically. A single
+# generic sentinel probe would then falsely read as inert whenever the
+# config's *current* value is already one of those identically-behaving
+# "other" values (e.g. mode="head") — it never crosses the one boundary that
+# actually matters. Named here so probing tries the real alternative(s) too;
+# every other string leaf is registry-validated (raises on garbage, still
+# correctly detected as consumed) or genuinely value-independent, so doesn't
+# need an entry.
+_STRING_ALTERNATIVES: dict[str, tuple[str, ...]] = {
+    "stage2_model.n_sec.owner": ("stage1", "stage2"),
+    "stage2_model.n_sec.mode": ("stop_token", "head", "truth"),
+    "stage2_model.particle_type.target": ("physical", "onehot", "embedding"),
+}
+
+# Verified by reading giant/training/trainers.py, giant/training/stage2_inputs.py
+# and giant/rollout.py while implementing gitea #46 — not auto-derived, so a
+# future reader touching these fields should re-check this table still holds.
+_NOT_BUILD_TIME: dict[str, str] = {
+    "stage1_model.init_from": "training/checkpoint.py's init_stages_from_checkpoints, run before build_stage_trainers (gitea #42)",
+    "stage1_model.freeze": "trainers.py: StageSpec.freeze, gates StageTrainer._step_optimizer (gitea #42)",
+    "stage2_model.init_from": "training/checkpoint.py's init_stages_from_checkpoints, run before build_stage_trainers (gitea #42)",
+    "stage2_model.freeze": "trainers.py: StageSpec.freeze, gates StageTrainer._step_optimizer (gitea #42)",
+    "stage1_model.lambda": "trainers.py: StageSpec.lambda_weight, the total-loss mix weight",
+    "stage2_model.lambda": "trainers.py: StageSpec.lambda_weight, the total-loss mix weight",
+    "stage2_model.n_sec.lambda": "trainers.py: StageSpec.n_sec_lambda, the n_sec-head loss weight",
+    "stage2_model.particle_type.lambda": "trainers.py: Stage2Trainer.particle_type_lambda, the type-head loss weight",
+    "stage2_model.particle_type.other_policy": "giant/rollout.py: resolves an 'other'-bucket secondary's PDG code at inference",
+    "stage2_model.particle_type.class_weighting": "trainers.py: FlowDDPMStageTrainer.type_class_weights, shapes the type-head loss, not the built graph (gitea #44)",
+    "stage2_model.autoregressive.teacher_forcing": "giant/training/stage2_inputs.py's training-time input assembly",
+    "stage2_model.autoregressive.tf_p_start": "trainers.py's teacher-forcing schedule",
+    "stage2_model.autoregressive.tf_p_end": "trainers.py's teacher-forcing schedule",
+    "stage2_model.stage1_context": "trainers.py's stage1/stage2 boundary — StageTrainer._stage1_context",
+    "stage2_model.ctx_p_start": "trainers.py's stage1-context sampling schedule",
+    "stage2_model.ctx_p_end": "trainers.py's stage1-context sampling schedule",
+    "stage1_model.router.lambda_balance": "trainers.py's load-balancing auxiliary loss weight",
+    "stage1_model.router.lambda_entropy": "trainers.py's entropy-regularization auxiliary loss weight",
+    "stage1_model.router.lambda_proc": "trainers.py's supervised process-classification auxiliary loss weight",
+    "stage1_model.router.gumbel_tau_start": "trainers.py's expert-combination Gumbel-softmax temperature anneal",
+    "stage1_model.router.gumbel_tau_end": "trainers.py's expert-combination Gumbel-softmax temperature anneal",
+    "stage2_model.router.lambda_balance": "trainers.py's load-balancing auxiliary loss weight",
+    "stage2_model.router.lambda_entropy": "trainers.py's entropy-regularization auxiliary loss weight",
+    "stage2_model.router.lambda_proc": "trainers.py's supervised process-classification auxiliary loss weight",
+    "stage2_model.router.gumbel_tau_start": "trainers.py's expert-combination Gumbel-softmax temperature anneal",
+    "stage2_model.router.gumbel_tau_end": "trainers.py's expert-combination Gumbel-softmax temperature anneal",
+    "stage1_model.wgan.n_critic": "trainers.py's WGAN-GP critic-update cadence",
+    "stage1_model.wgan.gp_weight": "trainers.py's WGAN-GP gradient-penalty coefficient",
+    "stage1_model.wgan.critic_lr": "trainers.py's critic optimizer learning rate",
+    "stage2_model.wgan.n_critic": "trainers.py's WGAN-GP critic-update cadence",
+    "stage2_model.wgan.gp_weight": "trainers.py's WGAN-GP gradient-penalty coefficient",
+    "stage2_model.wgan.critic_lr": "trainers.py's critic optimizer learning rate",
+    "stage2_model.wgan.gumbel_tau_start": "trainers.py's type-slice Gumbel-softmax temperature anneal (type_gumbel_tau_start)",
+    "stage2_model.wgan.gumbel_tau_end": "trainers.py's type-slice Gumbel-softmax temperature anneal (type_gumbel_tau_end)",
+}
+
+
+@dataclass
+class ModelSummary:
+    modules: dict[str, nn.Module]
+    consumed: list[str]
+    inert: list[str]
+    elsewhere: list[str]
+    pdg_vocab: int
+    mat_vocab: int
+    vocab_caveats: list[str] = field(default_factory=list)
+
+
+def _build_model_config(cfg: dict, pdg_vocab: int, mat_vocab: int) -> dict:
+    return {
+        "pdg_vocab": pdg_vocab,
+        "mat_vocab": mat_vocab,
+        "conditioning": cfg["conditioning"],
+        "stage1_model": cfg["stage1_model"],
+        "stage2_model": cfg["stage2_model"],
+    }
+
+
+def _built_modules(cfg: dict, pdg_vocab: int, mat_vocab: int) -> dict[str, nn.Module]:
+    model_config = _build_model_config(cfg, pdg_vocab, mat_vocab)
+    modules: dict[str, nn.Module] = {}
+    for name, m in build_models(model_config).items():
+        if m is not None:
+            modules[name] = m
+    for name, m in build_critics(model_config).items():
+        if m is not None:
+            modules[f"{name}_critic"] = m
+    return modules
+
+
+def _fingerprint(modules: dict[str, nn.Module]) -> list:
+    """A config-shape fingerprint of the built graph: which submodules
+    exist, every parameter's/buffer's shape+dtype (never values — those are
+    randomly initialized and irrelevant to *structure*), and every plain
+    scalar attribute any module stores on itself (e.g. `Stage2Autoregressive
+    .stop_sampling`, `EnergyRouter.temperature`) — this is what makes a
+    non-parametric key's effect on construction observable."""
+    sig = []
+    for stage_name, module in modules.items():
+        for mod_name, m in module.named_modules():
+            full = f"{stage_name}.{mod_name}" if mod_name else stage_name
+            for k, v in vars(m).items():
+                if k.startswith("_"):
+                    continue
+                if v is None or isinstance(v, (bool, int, float, str)):
+                    sig.append((full, k, v))
+        for pname, p in module.named_parameters():
+            sig.append((stage_name, "param", pname, tuple(p.shape), str(p.dtype)))
+        for bname, b in module.named_buffers():
+            sig.append((stage_name, "buffer", bname, tuple(b.shape), str(b.dtype)))
+    return sorted(sig, key=repr)
+
+
+def _perturb_candidates(path: str, value) -> list:
+    """Values to try perturbing `path`'s current `value` to, in order —
+    probing stops at the first one that changes the fingerprint or raises.
+    Almost always a single candidate; see `_STRING_ALTERNATIVES`."""
+    if isinstance(value, bool):
+        return [not value]
+    if isinstance(value, int):
+        return [value + 1]
+    if isinstance(value, float):
+        return [value + 1.0]
+    if isinstance(value, str):
+        alternatives = [v for v in _STRING_ALTERNATIVES.get(path, ()) if v != value]
+        return [*alternatives, _PROBE_STR]
+    raise TypeError(f"gitea #46 probing: unsupported leaf value type {type(value)!r} ({value!r})")
+
+
+def _vocab_caveats(cfg: dict) -> list[str]:
+    caveats = []
+    if _get_path(cfg, "conditioning.particle.type") == "embedding":
+        caveats.append(
+            "conditioning.particle.type = 'embedding' -- pdg_vocab below is a "
+            "placeholder (no dataset attached to derive the real training vocab size)"
+        )
+    if _get_path(cfg, "conditioning.material.type") == "embedding":
+        caveats.append(
+            "conditioning.material.type = 'embedding' -- mat_vocab below is a "
+            "placeholder (no dataset attached to derive the real training vocab size)"
+        )
+    for stage in ("stage1_model", "stage2_model"):
+        router_type = _get_path(cfg, f"{stage}.router.type")
+        if _get_path(cfg, f"{stage}.router.enabled") and router_type in ("pdg", "process"):
+            caveats.append(
+                f"{stage}.router.type = {router_type!r} builds its own pdg_vocab-sized "
+                "embedding -- the count above is a placeholder"
+            )
+    return caveats
+
+
+def summarize_model(cfg: dict, pdg_vocab: int, mat_vocab: int) -> ModelSummary:
+    """Build `cfg`'s model with no dataset attached and report its resolved
+    graph, plus which `conditioning`/`stage1_model`/`stage2_model` config
+    keys actually shaped it (differential probing — see module docstring).
+    `cfg` must already be a fully-merged v0.3 config (`merge_cli_overrides`
+    output) — this does not migrate or validate it."""
+    modules = _built_modules(cfg, pdg_vocab, mat_vocab)
+    baseline_fp = _fingerprint(modules)
+
+    in_scope = [p for p in leaf_paths(cfg) if p.split(".", 1)[0] in _IN_SCOPE_ROOTS]
+    consumed: list[str] = []
+    inert: list[str] = []
+    elsewhere: list[str] = []
+    for path in in_scope:
+        original = _get_path(cfg, path)
+        changed = False
+        for candidate in _perturb_candidates(path, original):
+            probe_cfg = copy.deepcopy(
+                {
+                    "conditioning": cfg["conditioning"],
+                    "stage1_model": cfg["stage1_model"],
+                    "stage2_model": cfg["stage2_model"],
+                }
+            )
+            _set_path(probe_cfg, path, candidate)
+            try:
+                changed = _fingerprint(_built_modules(probe_cfg, pdg_vocab, mat_vocab)) != baseline_fp
+            except Exception:
+                changed = True
+            if changed:
+                break
+        if changed:
+            consumed.append(path)
+        elif path in _NOT_BUILD_TIME:
+            elsewhere.append(path)
+        else:
+            inert.append(path)
+
+    return ModelSummary(
+        modules=modules,
+        consumed=sorted(consumed),
+        inert=sorted(inert),
+        elsewhere=sorted(elsewhere),
+        pdg_vocab=pdg_vocab,
+        mat_vocab=mat_vocab,
+        vocab_caveats=_vocab_caveats(cfg),
+    )
+
+
+def _tree_lines(module: nn.Module, name: str, indent: int = 0) -> list[str]:
+    total = sum(p.numel() for p in module.parameters())
+    in_dim = getattr(module, "in_dim", None)
+    out_dim = getattr(module, "out_dim", None)
+    widths = f"  [in={in_dim}, out={out_dim}]" if in_dim is not None and out_dim is not None else ""
+    lines = [f"{'  ' * indent}{name} ({type(module).__name__}): {total:,}{widths}"]
+    for child_name, child in module.named_children():
+        lines.extend(_tree_lines(child, child_name, indent + 1))
+    return lines
+
+
+_HEAD_NAMES = ("n_sec_head", "type_head", "stop_head")
+
+
+def _stage_header(name: str, module: nn.Module) -> list[str]:
+    total = sum(p.numel() for p in module.parameters())
+    lines = [f"{name}: {type(module).__name__} -- {total:,} parameters"]
+    generator = getattr(module, "generator_kind", None)
+    if generator is not None:
+        lines.append(f"  generator: {generator}")
+    trunk = getattr(module, "trunk", None)
+    if trunk is not None:
+        in_dim = getattr(trunk, "in_dim", "?")
+        out_dim = getattr(trunk, "out_dim", "?")
+        if isinstance(trunk, RoutedTrunk):
+            detail = f"routed, n_experts={trunk.router.n_experts}, expert type={type(trunk.experts[0]).__name__}"
+        else:
+            detail = f"unrouted, {type(trunk).__name__}"
+        lines.append(f"  trunk: {detail}, in={in_dim}, out={out_dim}")
+    history_kind = getattr(module, "history_kind", None)
+    if history_kind is not None:
+        lines.append(f"  autoregressive history: {history_kind}")
+    present = [h for h in _HEAD_NAMES if getattr(module, h, None) is not None]
+    absent = [h for h in _HEAD_NAMES if hasattr(module, h) and getattr(module, h) is None]
+    if present or absent:
+        lines.append(f"  heads present: {', '.join(present) if present else 'none'}")
+        if absent:
+            lines.append(f"  heads absent: {', '.join(absent)}")
+    return lines
+
+
+def render_summary(summary: ModelSummary) -> str:
+    lines: list[str] = []
+    for name, module in summary.modules.items():
+        lines.extend(_stage_header(name, module))
+        lines.extend(_tree_lines(module, name, indent=1))
+        lines.append("")
+
+    lines.append(
+        f"config keys read during construction: {len(summary.consumed)} / "
+        f"read elsewhere (trainer/sampler/rollout): {len(summary.elsewhere)} / "
+        f"inert under this config: {len(summary.inert)}"
+    )
+    if summary.elsewhere:
+        lines.append("read elsewhere, not by construction:")
+        for path in summary.elsewhere:
+            lines.append(f"  {path}  ({_NOT_BUILD_TIME[path]})")
+    lines.append("inert under this config (declared, parsed, but doing nothing here):")
+    if summary.inert:
+        for path in summary.inert:
+            lines.append(f"  {path}")
+    else:
+        lines.append("  (none)")
+
+    if summary.vocab_caveats:
+        lines.append("")
+        lines.append("vocab placeholder caveats:")
+        for caveat in summary.vocab_caveats:
+            lines.append(f"  {caveat}")
+
+    return "\n".join(lines)

giant/model/trunks.py

@@ -1,15 +1,61 @@
-"""Trunks: everything downstream of the fused conditioning vector — monolithic
-or expert-routed (issues.md Issue 8)."""
+"""Trunks: everything downstream of the fused conditioning vector — a
+registrable expert *body* architecture (`TRUNK_REGISTRY`/`register_trunk`),
+used standalone or mixed by a `Router` (issues.md Issue 8; trunk-selectability
+gitea #33).
+
+Whether a body is mixed is orthogonal to which body it is: `RoutedTrunk`
+builds `router.n_experts` instances of whichever body `trunk_type` names, so
+a future body (e.g. a transformer) automatically gets a mixture variant for
+free — no separate "routed transformer trunk" class needed.
+"""
 
 import torch
 import torch.nn as nn
 
-from giant.model.layers import ResBlock
+from giant.model.layers import build_block
 from giant.model.routers import Router
 
+TRUNK_REGISTRY: dict[str, type[nn.Module]] = {}
 
+
+def register_trunk(name: str):
+    def decorator(cls: type[nn.Module]) -> type[nn.Module]:
+        TRUNK_REGISTRY[name] = cls
+        return cls
+
+    return decorator
+
+
+def build_expert_body(
+    name: str,
+    in_dim: int,
+    out_dim: int,
+    hidden_dim: int,
+    n_blocks: int,
+    cond_dim: int,
+    dropout: float = 0.0,
+    block_conditioning: str = "add",
+) -> nn.Module:
+    """Factory: look up a registered trunk body by name and construct one
+    instance of it — used both for a standalone (unrouted) trunk and for each
+    expert inside a `RoutedTrunk`. `block_conditioning` selects the
+    `BLOCK_REGISTRY` entry each body's internal `ResBlock`-family blocks use
+    (`trunk.block_conditioning`, gitea #34) — an optional trailing kwarg a
+    future non-`ResBlock`-based body can simply ignore, same idiom as
+    `Trunk.forward`'s accept-and-ignore `cond_cont`/`cond_cat`."""
+    if name not in TRUNK_REGISTRY:
+        raise ValueError(f"unknown trunk type {name!r}; available: {sorted(TRUNK_REGISTRY)}")
+    cls = TRUNK_REGISTRY[name]
+    return cls(in_dim, out_dim, hidden_dim, n_blocks, cond_dim, dropout, block_conditioning=block_conditioning)
+
+
+@register_trunk("resmlp")
 class ExpertTrunk(nn.Module):
-    """One small expert: `input_proj -> ResBlock stack -> out_proj`.
+    """`input_proj -> ResBlock stack -> out_proj` — the registered `"resmlp"`
+    trunk body. Used both standalone (no router: `forward`'s `cond_cont`/
+    `cond_cat` are accepted and ignored, satisfying the `Trunk` interface
+    directly with no wrapper class) and as one expert inside a `RoutedTrunk`
+    (`_route_forward` calls it with just `(x, cond)`).
 
     Unlike v0.2, `out_dim` is independent of `in_dim` — needed by stage-2 AR
     tokens later (`noise_dim` in, `4 + type_dim` out), even though every
@@ -24,13 +70,24 @@ class ExpertTrunk(nn.Module):
         n_blocks: int,
         cond_dim: int,
         dropout: float = 0.0,
+        block_conditioning: str = "add",
     ) -> None:
         super().__init__()
+        self.in_dim = in_dim
+        self.out_dim = out_dim
         self.input_proj = nn.Linear(in_dim, hidden_dim)
-        self.blocks = nn.ModuleList([ResBlock(hidden_dim, cond_dim, dropout=dropout) for _ in range(n_blocks)])
+        self.blocks = nn.ModuleList(
+            [build_block(block_conditioning, hidden_dim, cond_dim, dropout) for _ in range(n_blocks)]
+        )
         self.out_proj = nn.Linear(hidden_dim, out_dim)
 
-    def forward(self, x: torch.Tensor, cond: torch.Tensor) -> torch.Tensor:
+    def forward(
+        self,
+        x: torch.Tensor,
+        cond: torch.Tensor,
+        cond_cont: torch.Tensor | None = None,
+        cond_cat: torch.Tensor | None = None,
+    ) -> torch.Tensor:
         x = self.input_proj(x)
         for block in self.blocks:
             x = block(x, cond)
@@ -52,29 +109,61 @@ def _route_forward(
     N-expert dense compute, fully differentiable (`weight` is
     `router.combine_weights`). Eval mode: grouped top-1 dispatch — each row
     runs exactly one expert, the actual source of the per-call speedup.
+
+    The accumulator's dtype is deferred to the first expert call rather than
+    fixed at fp32: under autocast (`train.precision = "bf16"`, gitea #47) an
+    expert's `ResBlock` stack returns bf16, and an fp32-fixed accumulator
+    would silently upcast every mixture term (train mode) or downcast every
+    dispatched row via `index_put_` (eval mode) — making a `RoutedTrunk`
+    return a different dtype than the unrouted `ExpertTrunk` it's a drop-in
+    replacement for, purely because `router.enabled` was set.
+
+    `router.combine_weights` is deliberately fp32 internally (it forces its
+    own autocast-disabled region — see `Router.combine_weights`'s docstring),
+    so `weights` itself is always fp32 regardless of the ambient precision.
+    Left as-is, `weights[:, i:i+1] * expert(x, cond)` would type-promote the
+    whole mixture back to fp32 by ordinary PyTorch promotion rules — the same
+    dtype-mismatch bug this function exists to avoid, just moved one line
+    over. `weights` is cast down to each expert's own output dtype right
+    before combining: the softmax stays numerically stable at fp32, but its
+    *result* (values in [0, 1], not precision-sensitive to represent) loses
+    nothing meaningful by then being used at bf16.
     """
     if training:
-        weights = router.combine_weights(cond_cont, cond_cat)  # (B, n_experts)
-        out = torch.zeros(x.shape[0], experts[0].out_proj.out_features, device=x.device)
+        weights = router.combine_weights(cond_cont, cond_cat)  # (B, n_experts), fp32
+        out = None
         for i, expert in enumerate(experts):
-            out = out + weights[:, i : i + 1] * expert(x, cond)
+            expert_out = expert(x, cond)
+            term = weights[:, i : i + 1].to(expert_out.dtype) * expert_out
+            out = term if out is None else out + term
+        assert out is not None, "RoutedTrunk built with zero experts"
         return out
 
     idx = router.top1(cond_cont, cond_cat)  # (B,)
-    out_dim = experts[0].out_proj.out_features
-    out = torch.zeros(x.shape[0], out_dim, device=x.device)
+    out = None
     for i, expert in enumerate(experts):
         mask = idx == i
         if mask.any():
-            out[mask] = expert(x[mask], cond[mask])
+            expert_out = expert(x[mask], cond[mask])
+            if out is None:
+                out = torch.zeros(x.shape[0], expert_out.shape[-1], device=x.device, dtype=expert_out.dtype)
+            out[mask] = expert_out
+    if out is None:
+        # No row was ever dispatched (only reachable with an empty batch,
+        # x.shape[0] == 0) — nothing to infer a dtype from, so fall back to
+        # x's own, matching this function's pre-autocast behavior.
+        out = torch.zeros(x.shape[0], experts[0].out_dim, device=x.device, dtype=x.dtype)
     return out
 
 
 class Trunk(nn.Module):
-    """Interface implemented by `MonolithicTrunk`/`RoutedTrunk`: everything
-    downstream of the fused conditioning vector, i.e. the actual generative
-    trunk of a stage (`input_proj -> blocks -> out_proj`, monolithic or
-    expert-routed)."""
+    """Interface implemented by a standalone trunk body (any `TRUNK_REGISTRY`
+    entry, e.g. `ExpertTrunk`) and by `RoutedTrunk`: everything downstream of
+    the fused conditioning vector, i.e. the actual generative trunk of a
+    stage. Implementations are expected to expose `in_dim`/`out_dim`
+    attributes (as `ExpertTrunk`/`RoutedTrunk` do) — `giant.model.summary`
+    (gitea #46) reads them to report trunk widths without needing to know the
+    body architecture."""
 
     def forward(
         self,
@@ -86,49 +175,37 @@ class Trunk(nn.Module):
         raise NotImplementedError
 
 
-class MonolithicTrunk(Trunk):
-    def __init__(
-        self,
-        in_dim: int,
-        out_dim: int,
-        hidden_dim: int,
-        n_res_blocks: int,
-        cond_dim: int,
-        dropout: float = 0.0,
-    ) -> None:
-        super().__init__()
-        self.input_proj = nn.Linear(in_dim, hidden_dim)
-        self.blocks = nn.ModuleList([ResBlock(hidden_dim, cond_dim, dropout=dropout) for _ in range(n_res_blocks)])
-        self.out_proj = nn.Linear(hidden_dim, out_dim)
-
-    def forward(
-        self,
-        x: torch.Tensor,
-        cond: torch.Tensor,
-        cond_cont: torch.Tensor,
-        cond_cat: torch.Tensor,
-    ) -> torch.Tensor:
-        x = self.input_proj(x)
-        for block in self.blocks:
-            x = block(x, cond)
-        return self.out_proj(x)
-
-
 class RoutedTrunk(Trunk):
     def __init__(
         self,
         router: Router,
+        trunk_type: str,
         in_dim: int,
         out_dim: int,
         hidden_dim: int,
         n_res_blocks: int,
         cond_dim: int,
         dropout: float = 0.0,
+        block_conditioning: str = "add",
     ) -> None:
         super().__init__()
         self.router = router
+        self.in_dim = in_dim
+        self.out_dim = out_dim
         self.experts = nn.ModuleList(
-            [ExpertTrunk(in_dim, out_dim, hidden_dim, n_res_blocks, cond_dim, dropout) for _ in range(router.n_experts)]
+            [
+                build_expert_body(
+                    trunk_type,
+                    in_dim,
+                    out_dim,
+                    hidden_dim,
+                    n_res_blocks,
+                    cond_dim,
+                    dropout,
+                    block_conditioning=block_conditioning,
+                )
+                for _ in range(router.n_experts)
+            ]
         )
 
     def forward(
@@ -143,13 +220,30 @@ class RoutedTrunk(Trunk):
 
 def build_trunk(
     router: Router | None,
+    trunk_type: str,
     in_dim: int,
     out_dim: int,
     hidden_dim: int,
     n_res_blocks: int,
     cond_dim: int,
     dropout: float = 0.0,
-) -> Trunk:
+    block_conditioning: str = "add",
+) -> nn.Module:
+    """Build a stage's trunk: `trunk_type` (a `TRUNK_REGISTRY` key, e.g.
+    `"resmlp"`) selects the expert body architecture; `router`, if given,
+    wraps `router.n_experts` instances of that body in a `RoutedTrunk`
+    mixture — otherwise a single body is returned directly (no wrapper
+    class), which is what makes an unrouted trunk's state-dict keys land
+    directly under `trunk.*` instead of `trunk.experts.0.*` (see
+    `giant.model._legacy.migrate_legacy_state_dict`, which assumes exactly
+    this flat layout for a v0.2 monolithic checkpoint). `block_conditioning`
+    (a `BLOCK_REGISTRY` key, e.g. `"add"`/`"film"`/`"adaln"`) selects each
+    body's conditioning-injection mechanism (gitea #34).
+    """
     if router is not None:
-        return RoutedTrunk(router, in_dim, out_dim, hidden_dim, n_res_blocks, cond_dim, dropout)
-    return MonolithicTrunk(in_dim, out_dim, hidden_dim, n_res_blocks, cond_dim, dropout)
+        return RoutedTrunk(
+            router, trunk_type, in_dim, out_dim, hidden_dim, n_res_blocks, cond_dim, dropout, block_conditioning
+        )
+    return build_expert_body(
+        trunk_type, in_dim, out_dim, hidden_dim, n_res_blocks, cond_dim, dropout, block_conditioning
+    )

giant/model/wgan.py

@@ -22,21 +22,31 @@ def gradient_penalty(
     norm to 1 — `x_hat`/`grad` are forced to all-zero for such a row, which
     would otherwise contribute a constant `(||0|| - 1)^2 == 1` bias to the
     mean regardless of critic behavior — so they're excluded from the mean.
+
+    Deliberately kept fp32 (`torch.autocast(..., enabled=False)`) regardless
+    of the caller's ambient `train.precision` autocast region: this is a
+    `create_graph=True` double-backward, and `grad.norm(2, dim=1)` sums
+    squares over the critic's full input width (hundreds of dims for stage
+    2), which overflows bf16's range at gradient magnitudes well within
+    normal early-WGAN-GP territory. Disclosed cost: the critic forward
+    inside this function always runs fp32, even when the rest of the WGAN
+    stage's step is bf16 (gitea #47).
     """
-    eps = torch.rand(real.size(0), 1, device=real.device)
-    x_hat = eps * real + (1 - eps) * fake
-    if mask is not None:
-        x_hat = x_hat * mask
-    x_hat = x_hat.requires_grad_(True)
-    scores = critic_fn(x_hat)
-    grad = torch.autograd.grad(outputs=scores.sum(), inputs=x_hat, create_graph=True)[0]
-    if mask is not None:
-        grad = grad * mask
-    penalty = (grad.norm(2, dim=1) - 1) ** 2
-    if mask is not None:
-        valid = (mask.sum(dim=1) > 0).float()
-        return (penalty * valid).sum() / valid.sum().clamp_min(1.0)
-    return penalty.mean()
+    with torch.autocast(real.device.type, enabled=False):
+        eps = torch.rand(real.size(0), 1, device=real.device)
+        x_hat = eps * real.float() + (1 - eps) * fake.float()
+        if mask is not None:
+            x_hat = x_hat * mask
+        x_hat = x_hat.requires_grad_(True)
+        scores = critic_fn(x_hat)
+        grad = torch.autograd.grad(outputs=scores.sum(), inputs=x_hat, create_graph=True)[0]
+        if mask is not None:
+            grad = grad * mask
+        penalty = (grad.norm(2, dim=1) - 1) ** 2
+        if mask is not None:
+            valid = (mask.sum(dim=1) > 0).float()
+            return (penalty * valid).sum() / valid.sum().clamp_min(1.0)
+        return penalty.mean()
 
 
 def critic_loss(

giant/pipeline.py

@@ -188,8 +188,8 @@ def run_setup_stage(
     # independent of both.
     particle_cfg = cfg["conditioning"]["particle"]
     material_cfg = cfg["conditioning"]["material"]
-    particle_type_cfg_dict = cfg["stage2_model"].get("particle_type") or {}
-    particle_type_target = config.ParticleTypeConfig.from_dict(particle_type_cfg_dict).target
+    particle_type_cfg = config.ParticleTypeConfig.from_dict(cfg["stage2_model"].get("particle_type"))
+    particle_type_target = particle_type_cfg.target
 
     def _pdg_topn(n_classes: int) -> TopNMap:
         cache_key = setup_cache.topn_key("pdg", n_classes)
@@ -210,7 +210,7 @@ def run_setup_stage(
 
     sec_type_topn_map: TopNMap | None = None
     if particle_type_target == "onehot":
-        sec_type_n_classes = resolve_type_n_classes(particle_type_cfg_dict, particle_cfg["emb_dim"])
+        sec_type_n_classes = resolve_type_n_classes(particle_type_cfg, particle_cfg["emb_dim"])
         sec_type_topn_map = _pdg_topn(sec_type_n_classes)
 
     mat_topn_map: TopNMap | None = None
@@ -271,6 +271,13 @@ def run_setup_stage(
                     particle_conditioning=particle_conditioning,
                     material_conditioning=material_conditioning,
                     sec_phys_only=True,
+                    # This pass reads only cond_cont/sec_cont, never cond_cat —
+                    # but cond_cat's width is the conditioning modes' call
+                    # (giant.cond_layout.CondLayout), so an "onehot" axis still
+                    # has to be handed its map rather than silently yielding a
+                    # narrower array.
+                    pdg_topn_map=pdg_topn_map.class_map if pdg_topn_map is not None else None,
+                    mat_topn_map=mat_topn_map.class_map if mat_topn_map is not None else None,
                     k_max=k_max,
                 )
                 cond_cont = feats.cond_cont
@@ -352,7 +359,7 @@ def run_train_job(
             "section)"
         )
 
-    config.validate_config(cfg)
+    config.validate_config(cfg, resume=resume is not None)
     particle_conditioning = cfg["conditioning"]["particle"]["type"]
     material_conditioning = cfg["conditioning"]["material"]["type"]
     k_max = cfg["stage2_model"]["k_max"]

giant/rollout.py

@@ -141,7 +141,7 @@ def decode_secondary_identity(
     Returns (sec_E, sec_dir_world, sec_mass, sec_charge, sec_pdg,
     sec_type_l1_dist) — the last is `None` except under `"embedding"`.
     """
-    target = sec_decoder.particle_type_cfg.get("target", "physical")
+    target = sec_decoder.particle_type_cfg.target
 
     if target == "physical":
         sec_full = torch.cat([sec_cont, sec_type], dim=-1).cpu().numpy()
@@ -491,7 +491,7 @@ def rollout(
             "conditioning.particle.type='onehot' rollout needs pdg_topn_map "
             "(the checkpoint's saved top-N map) — see ckpt['pdg_topn_map']"
         )
-    if sec_decoder.particle_type_cfg.get("target") == "onehot" and sec_type_topn_map is None:
+    if sec_decoder.particle_type_cfg.target == "onehot" and sec_type_topn_map is None:
         raise RuntimeError(
             "stage2_model.particle_type.target='onehot' rollout needs sec_type_topn_map "
             "(the checkpoint's saved top-N map) — see ckpt['sec_type_topn_map']"
@@ -681,7 +681,6 @@ def _step_chunk(
     post_pos = reconstruct_post_pos(tr["pre_pos"], tr["pre_dir"], step_length, travel_dir_local)
 
     n_sec_pred = resolve_n_sec(stage1_model, sec_decoder, cc, ck, stage1_norm, n_sec_pred_stage1)
-    n_sec_np = n_sec_pred.cpu().numpy().astype(np.int64)
 
     # --- Secondaries ---
     # No snapping for "physical"/history-facing state elsewhere in the
@@ -691,7 +690,13 @@ def _step_chunk(
     # decode_secondary_identity's docstring for how each
     # particle_type.target differs on whether PDG resolution is a real
     # identity decision or just a reporting label.
-    sec_cont, sec_type, _valid = sample_stage2(sec_decoder, cc, ck, stage1_norm, n_sec_pred, steps)
+    sec_cont, sec_type, sec_valid = sample_stage2(sec_decoder, cc, ck, stage1_norm, n_sec_pred, steps)
+    # A stop-token decoder resolves n_sec_pred=None above — the real count
+    # only exists once sample_stage2 has actually generated (or stopped
+    # generating) tokens, so read it back off sec_valid here. Under every
+    # other n_sec.mode sec_valid was built FROM n_sec_pred, so this is a
+    # no-op round trip in those cases.
+    n_sec_np = sec_valid.sum(dim=-1).cpu().numpy().astype(np.int64)
     sec_E, sec_dir_world, sec_mass, sec_charge, sec_pdg_code, sec_type_l1_dist = decode_secondary_identity(
         sec_decoder,
         sec_cont,

giant/sample.py

@@ -2,7 +2,7 @@ import torch
 import torch.nn.functional as F
 
 from giant.constants import CONT_SLOT_DIM, X_DIM
-from giant.model.network import Stage2Autoregressive, stage2_trunk_sec_dim
+from giant.model.network import DdpmObjective, Stage2Autoregressive, build_objective, stage2_trunk_sec_dim
 from giant.model.schedule import CosineSchedule
 
 
@@ -131,8 +131,8 @@ def _stage2_flat_width(sec_decoder: torch.nn.Module) -> int:
 
 
 def _type_folded(sec_decoder: torch.nn.Module) -> bool:
-    target = sec_decoder.particle_type_cfg.get("target", "physical")
-    return target == "physical" or sec_decoder.generator_kind == "wgan"
+    target = sec_decoder.particle_type_cfg.target
+    return target == "physical" or build_objective(sec_decoder.generator_kind).folds_type_slice
 
 
 def _decode_stage2_flat(
@@ -229,14 +229,14 @@ def sample_secondaries_ar(
     cond_cont: torch.Tensor,
     cond_cat: torch.Tensor,
     stage1_out: torch.Tensor,
-    n_sec_pred: torch.Tensor,
+    n_sec_pred: torch.Tensor | None,
     steps: int = 10,
 ) -> tuple[torch.Tensor, torch.Tensor, torch.Tensor]:
     """`Stage2Autoregressive` inference loop: one token at a time, in
-    descending-energy slot order, `k_max` sequential calls. Unlike training
-    (teacher forcing — a single parallel pass over ground-truth tokens, see
-    `giant.training.stage2_inputs._assemble_stage2_ar_inputs`), there is no
-    ground truth at inference: each token's conditioning is built
+    descending-energy slot order, up to `k_max` sequential calls. Unlike
+    training (teacher forcing — a single parallel pass over ground-truth
+    tokens, see `giant.training.stage2_inputs._assemble_stage2_ar_inputs`),
+    there is no ground truth at inference: each token's conditioning is built
     free-running, from the PREVIOUS TOKEN'S OWN just-generated output — the
     train/inference gap that is the cost of markov history's
     expressiveness.
@@ -244,7 +244,30 @@ def sample_secondaries_ar(
     A `{flow,ddpm}` token costs `steps` ODE substeps; `wgan` costs one pass —
     the "K sequential forwards" cost applies per-token here, not
     once, so a flow/ddpm AR run costs ~`k_max * steps` model calls per
-    physics step.
+    physics step (or ~`n_sec * steps` under `n_sec_pred=None` below, once
+    every row in the batch has stopped).
+
+    `n_sec_pred`, if given, fixes each row's secondary count up front (as
+    resolved by `resolve_n_sec` — `n_sec.mode` in `("head", "truth")`, or a
+    stop-token decoder driven by `_assemble_stage2_ar_inputs_scheduled`'s
+    ground-truth `n_sec`, which must run the *full* `k_max`-length free-
+    running self-sample regardless of the decoder's own stop head — the
+    scheduled-sampling training contract does not truncate). This always
+    runs the full `k_max`-iteration loop, masking by the given count at the
+    end exactly as before.
+
+    `n_sec_pred=None` is only valid when `sec_decoder.stop_head` is set
+    (`n_sec.mode = "stop_token"`): before generating each slot's token, that
+    slot's own stop logit (`predict_stop`, evaluated on the same prefix
+    conditioning as the token itself — see `predict_type`'s docstring for
+    why this needs no extra state) decides whether generation should have
+    already stopped, per `sec_decoder.stop_sampling` ("greedy": threshold at
+    0; "sample": a Bernoulli draw at `sigmoid(logit)`). A row's own
+    `n_sec_pred` is the first slot index where this fires; once every row in
+    the batch has fired, the loop breaks before spending a model call on the
+    next slot's token — the average-case cost win the docstring above
+    describes. A row that never fires within `k_max` is capped there
+    (`K_MAX` stays a safety cap, not a modeling ceiling).
 
     Under `history="attention"` the history encoding is computed once per
     slot via `Stage2Autoregressive.history_step` (a KV-cache append)
@@ -281,8 +304,8 @@ def sample_secondaries_ar(
     device = cond_cont.device
     k_max = sec_decoder.k_max
     type_dim = sec_decoder.type_dim
-    generator = sec_decoder.generator_kind
-    target = sec_decoder.particle_type_cfg.get("target", "physical")
+    objective = build_objective(sec_decoder.generator_kind)
+    target = sec_decoder.particle_type_cfg.target
     type_folded = _type_folded(sec_decoder)
     token_dim = CONT_SLOT_DIM + type_dim if type_folded else CONT_SLOT_DIM
 
@@ -294,6 +317,16 @@ def sample_secondaries_ar(
     remaining = torch.ones(B, device=device)
     history_cache = sec_decoder.init_history_cache()
 
+    use_stop_token = n_sec_pred is None
+    if use_stop_token:
+        assert getattr(sec_decoder, "stop_head", None) is not None, (
+            "sample_secondaries_ar called with n_sec_pred=None on a decoder "
+            "with no stop_head — only valid under stage2_model.n_sec.mode = "
+            "'stop_token'"
+        )
+        finished = torch.zeros(B, dtype=torch.bool, device=device)
+        derived_n_sec = torch.full((B,), k_max, dtype=torch.long, device=device)
+
     for k in range(k_max):
         has_prev = torch.full((B, 1), k >= 1, dtype=torch.bool, device=device)
         history_feat = prev_repr.unsqueeze(1)  # (B, 1, CONT_SLOT_DIM + type_dim)
@@ -301,7 +334,27 @@ def sample_secondaries_ar(
         slot_idx = torch.full((B, 1), k / max(k_max - 1, 1), device=device, dtype=torch.float32)
         hist, history_cache = sec_decoder.history_step(history_feat, has_prev, history_cache)
 
-        if generator == "wgan":
+        if use_stop_token:
+            stop_logit = sec_decoder.predict_stop(
+                cond_cont,
+                cond_cat,
+                stage1_out,
+                history_feat,
+                has_prev,
+                remaining_frac,
+                slot_idx,
+                hist=hist,
+            ).squeeze(1)
+            if sec_decoder.stop_sampling == "sample":
+                stop_now = torch.rand(B, device=device) < torch.sigmoid(stop_logit)
+            else:
+                stop_now = stop_logit >= 0.0
+            derived_n_sec[stop_now & ~finished] = k
+            finished = finished | stop_now
+            if finished.all():
+                break
+
+        if objective.is_adversarial:
             z = torch.randn(B, 1, sec_decoder.noise_dim, device=device)
             token = sec_decoder(
                 z,
@@ -362,7 +415,8 @@ def sample_secondaries_ar(
         prev_repr = torch.cat([stick_fraction.unsqueeze(-1), cont_k[:, 1:4], type_for_history], dim=-1)
         remaining = torch.clamp(remaining * (1.0 - stick_fraction), min=0.0)
 
-    sec_valid = torch.arange(k_max, device=device).unsqueeze(0) < n_sec_pred.unsqueeze(1)
+    resolved_n_sec = derived_n_sec if use_stop_token else n_sec_pred
+    sec_valid = torch.arange(k_max, device=device).unsqueeze(0) < resolved_n_sec.unsqueeze(1)
     return sec_cont, sec_type, sec_valid
 
 
@@ -383,10 +437,10 @@ def sample_stage1(
     ddpm_steps: int = 1000,
 ) -> tuple[torch.Tensor, torch.Tensor | None]:
     """Dispatches on `stage1_model.generator_kind`."""
-    kind = stage1_model.generator_kind
-    if kind == "wgan":
+    objective = build_objective(stage1_model.generator_kind)
+    if objective.is_adversarial:
         return sample_wgan(stage1_model, cond_cont, cond_cat)
-    if kind == "ddpm":
+    if isinstance(objective, DdpmObjective):
         schedule = CosineSchedule(T=ddpm_steps).to(cond_cont.device)
         return sample_ddpm(stage1_model, cond_cont, cond_cat, schedule)
     return sample_flow(stage1_model, cond_cont, cond_cat, steps=steps)
@@ -397,7 +451,7 @@ def sample_stage2(
     cond_cont: torch.Tensor,
     cond_cat: torch.Tensor,
     stage1_out: torch.Tensor,
-    n_sec_pred: torch.Tensor,
+    n_sec_pred: torch.Tensor | None,
     steps: int,
 ) -> tuple[torch.Tensor, torch.Tensor, torch.Tensor]:
     """Dispatches on `decoder` (one-shot vs autoregressive — the class
@@ -406,10 +460,16 @@ def sample_stage2(
     built with `generator="ddpm"` in practice and `flow_matching_loss_secondary*`
     is the only stage-2 training path that exists for the non-adversarial
     case, so there's nothing to dispatch to here.
+
+    `n_sec_pred=None` (from `resolve_n_sec` on a stop-token decoder) is only
+    meaningful for the autoregressive path — see `sample_secondaries_ar`'s
+    docstring; the one-shot samplers have no per-token stop mechanism to
+    derive a count from, so `n_sec_pred` must already be resolved for them.
     """
     if isinstance(sec_decoder, Stage2Autoregressive):
         return sample_secondaries_ar(sec_decoder, cond_cont, cond_cat, stage1_out, n_sec_pred, steps=steps)
-    if sec_decoder.generator_kind == "wgan":
+    assert n_sec_pred is not None, "one-shot stage-2 decoders need a resolved n_sec_pred"
+    if build_objective(sec_decoder.generator_kind).is_adversarial:
         return sample_secondaries_wgan(sec_decoder, cond_cont, cond_cat, stage1_out, n_sec_pred)
     return sample_secondaries(sec_decoder, cond_cont, cond_cat, stage1_out, n_sec_pred, steps=steps)
 
@@ -421,20 +481,31 @@ def resolve_n_sec(
     cond_cat: torch.Tensor,
     stage1_out: torch.Tensor,
     n_sec_pred: torch.Tensor | None,
-) -> torch.Tensor:
+) -> torch.Tensor | None:
     """`n_sec_pred` is already populated when `stage1_model` owns a legacy
     `n_sec_head` (a migrated v0.2 checkpoint — see `Stage1Model`'s
-    docstring); otherwise ask stage 2, which owns it by default. Raises if
-    neither stage owns a head at all — the only way that happens is
-    `stage2_model.n_sec.mode` other than `"head"` (`"truth"`/`"stop_token"`),
-    neither of which is a valid rollout-/predict-capable checkpoint."""
+    docstring); otherwise ask stage 2, which owns it by default.
+
+    Returns `None` when `sec_decoder` owns a `stop_head` (`n_sec.mode =
+    "stop_token"`) instead of an `n_sec_head` — there is nothing to resolve
+    up front in that case, since the count only exists once
+    `sample_secondaries_ar` has actually generated (or stopped generating)
+    tokens; the caller passes this `None` straight through to `sample_stage2`
+    and reads the real count back off its returned `sec_valid`
+    (`sec_valid.sum(-1)`) afterwards.
+
+    Raises if neither stage owns any n_sec mechanism at all — the only way
+    that happens is `stage2_model.n_sec.mode = "truth"`, which is not a valid
+    rollout-/predict-capable checkpoint."""
     if n_sec_pred is not None:
         return n_sec_pred
+    if getattr(sec_decoder, "stop_head", None) is not None:
+        return None
     if getattr(sec_decoder, "n_sec_head", None) is None:
         raise RuntimeError(
-            "checkpoint has no n_sec_head on either stage — needs "
-            "stage2_model.n_sec.mode = 'head' (the default); 'truth' is "
-            "standalone-evaluation-only and 'stop_token' isn't implemented"
+            "checkpoint has no n_sec_head/stop_head on either stage — needs "
+            "stage2_model.n_sec.mode = 'head' (the default) or 'stop_token'; "
+            "'truth' is standalone-evaluation-only"
         )
     logits = sec_decoder.predict_n_sec(cond_cont, cond_cat, stage1_out)
     return logits.argmax(dim=-1)

giant/tools/dwarf.py

@@ -442,43 +442,65 @@ def warm_cache(
         Path,
         typer.Argument(help="Parquet file, directory, or .manifest — same as `giant train`'s"),
     ],
+    config: Annotated[
+        Optional[Path],
+        typer.Option(
+            "--config",
+            "-c",
+            help="TOML config file to warm for — same file the `giant train` run(s) will use. "
+            "Mutually exclusive with the flags below (put val-fraction/seed/conditioning/router "
+            "settings in the file itself, so warming and training can't disagree on them)",
+        ),
+    ] = None,
     val_fraction: Annotated[
-        float,
+        Optional[float],
         typer.Option(
             "--val-fraction",
             "-f",
-            help="Must match the `giant train` run(s) to warm for",
+            help="Must match the `giant train` run(s) to warm for. Not allowed together with --config",
         ),
-    ] = 0.1,
+    ] = None,
     seed: Annotated[
-        int,
-        typer.Option("--seed", "-s", help="Must match the `giant train` run(s) to warm for"),
-    ] = 0,
+        Optional[int],
+        typer.Option(
+            "--seed",
+            "-s",
+            help="Must match the `giant train` run(s) to warm for. Not allowed together with --config",
+        ),
+    ] = None,
     particle_conditioning: Annotated[
-        Conditioning,
+        Optional[Conditioning],
         typer.Option(
             "--particle-conditioning",
-            help="Must match the `giant train` run(s)' conditioning.particle.type to warm for",
+            help="Must match the `giant train` run(s)' conditioning.particle.type to warm for. "
+            "Not allowed together with --config",
         ),
-    ] = Conditioning.physical,
+    ] = None,
     material_conditioning: Annotated[
-        Conditioning,
+        Optional[Conditioning],
         typer.Option(
             "--material-conditioning",
             help="Must match the `giant train` run(s)' conditioning.material.type "
             "to warm for — independent of --particle-conditioning "
-            "(the two axes may differ)",
+            "(the two axes may differ). Not allowed together with --config",
         ),
-    ] = Conditioning.physical,
+    ] = None,
     router: Annotated[
-        bool,
+        Optional[bool],
         typer.Option(
             "--router/--no-router",
-            help="Warm the process vocabulary too (only takes effect with --router-type process)",
+            help="Warm the process vocabulary too (only takes effect with --router-type process). "
+            "Not allowed together with --config",
         ),
-    ] = False,
-    router_type: Annotated[str, typer.Option("--router-type", help="Router implementation name")] = "energy",
-    n_experts: Annotated[int, typer.Option("--n-experts", help="Number of routed experts")] = 4,
+    ] = None,
+    router_type: Annotated[
+        Optional[str],
+        typer.Option("--router-type", help="Router implementation name. Not allowed together with --config"),
+    ] = None,
+    n_experts: Annotated[
+        Optional[int],
+        typer.Option("--n-experts", help="Number of routed experts. Not allowed together with --config"),
+    ] = None,
     rebuild: Annotated[
         bool,
         typer.Option("--rebuild", help="Ignore any existing sidecar and recompute every section"),
@@ -487,17 +509,38 @@ def warm_cache(
     """Precompute `giant train`'s setup-stage sidecar for `data` ahead of time.
 
     Warms the vocab maps, event-id split index, and the normalizer entry for
-    the given --val-fraction/--seed/--particle-conditioning/
-    --material-conditioning, so a later `giant train` run (or a `dwarf
-    hparam-scan` sweep, which shares one such entry across every run) skips
-    straight to training. See giant/data/setup_cache.py.
+    either --config, or the given --val-fraction/--seed/
+    --particle-conditioning/--material-conditioning/--router* flags, so a
+    later `giant train` run (or a `dwarf hparam-scan` sweep, which shares one
+    such entry across every run) skips straight to training. See
+    giant/data/setup_cache.py.
     """
+    flag_overrides = {
+        "--val-fraction": val_fraction,
+        "--seed": seed,
+        "--particle-conditioning": particle_conditioning,
+        "--material-conditioning": material_conditioning,
+        "--router/--no-router": router,
+        "--router-type": router_type,
+        "--n-experts": n_experts,
+    }
+    if config is not None:
+        given = [name for name, value in flag_overrides.items() if value is not None]
+        if given:
+            typer.echo(
+                f"error: --config cannot be combined with {', '.join(given)} "
+                "— put these settings in the config file instead",
+                err=True,
+            )
+            raise typer.Exit(1)
+
     run_warm_setup_cache(
         data=str(data),
+        config_path=config,
         val_fraction=val_fraction,
         seed=seed,
-        particle_conditioning=particle_conditioning.value,
-        material_conditioning=material_conditioning.value,
+        particle_conditioning=particle_conditioning.value if particle_conditioning is not None else None,
+        material_conditioning=material_conditioning.value if material_conditioning is not None else None,
         router_enabled=router,
         router_type=router_type,
         n_experts=n_experts,

giant/tools/warm_setup_cache.py

@@ -10,63 +10,86 @@ for the sidecar itself.
 from pathlib import Path
 
 from giant import config as gconfig
-from giant.constants import K_MAX
 from giant.pipeline import run_setup_stage
 
 
 def run_warm_setup_cache(
     data: str,
-    val_fraction: float = 0.1,
-    seed: int = 0,
-    particle_conditioning: str = "physical",
-    material_conditioning: str = "physical",
-    router_enabled: bool = False,
-    router_type: str = "energy",
-    n_experts: int = 4,
+    config_path: Path | None = None,
+    val_fraction: float | None = None,
+    seed: int | None = None,
+    particle_conditioning: str | None = None,
+    material_conditioning: str | None = None,
+    router_enabled: bool | None = None,
+    router_type: str | None = None,
+    n_experts: int | None = None,
     rebuild: bool = False,
     echo=print,
 ) -> None:
     """Populate (or refresh) the setup cache sidecar for `data`.
 
-    `val_fraction`/`seed`/`particle_conditioning`/`material_conditioning`
-    select the normalizer cache entry
-    (`giant.data.setup_cache.normalizer_key`) — pass the same values a later
-    `giant train` invocation will use so it hits this warmed entry. The two
-    conditioning axes are independent and may differ.
-    `router_enabled`/`router_type`/`n_experts` only matter for
-    `router_type == "process"` (warms that `n_experts`'s process map); the
-    energy-router quantile summary is always collected regardless, so a
-    later `--router-type energy` run never needs to rescan just to seed
-    centers.
+    Two mutually exclusive ways to select what to warm for (enforced by the
+    caller, `giant.tools.dwarf.warm_cache` — this function just trusts
+    whichever combination it's given):
+
+    - `config_path`: the same TOML `giant train --config` takes. Every value
+      `run_setup_stage` needs (`train.val_fraction`/`seed`,
+      `conditioning.particle`/`material.type`, both stages' `router`,
+      `stage2_model.particle_type.n_classes`, ...) is read from the one
+      resulting merged `cfg`, so a later `giant train --config <same file>`
+      run resolves to exactly the same cache keys — see gitea #59.
+    - The individual flags below: `val_fraction`/`seed`/
+      `particle_conditioning`/`material_conditioning` select the normalizer
+      cache entry (`giant.data.setup_cache.normalizer_key`) — pass the same
+      values a later `giant train` invocation will use so it hits this
+      warmed entry. The two conditioning axes are independent and may
+      differ. `router_enabled`/`router_type`/`n_experts` only matter for
+      `router_type == "process"` (warms that `n_experts`'s process map); the
+      energy-router quantile summary is always collected regardless, so a
+      later `--router-type energy` run never needs to rescan just to seed
+      centers.
+
+    Any flag left `None` is omitted from the merge, so it falls back to
+    `DEFAULT_CONFIG`'s own value (or the config file's, if `config_path` is
+    given) instead of silently overriding it — see gitea #59.
     """
-    router_cfg = {
-        "enabled": router_enabled,
-        "type": router_type,
-        "n_experts": n_experts,
-    }
-    # Merged against DEFAULT_CONFIG (not a hand-rolled partial dict) so
-    # run_setup_stage always sees every key it might read (e.g.
-    # conditioning.particle.emb_dim, stage2_model.particle_type.target) at
-    # its real default, not silently missing/None — see issues.md Issue 1.
+    overrides: dict = {}
+
+    conditioning_overrides: dict = {}
+    if particle_conditioning is not None:
+        conditioning_overrides["particle"] = {"type": particle_conditioning}
+    if material_conditioning is not None:
+        conditioning_overrides["material"] = {"type": material_conditioning}
+    if conditioning_overrides:
+        overrides["conditioning"] = conditioning_overrides
+
     # This CLI only ever configures one router (matching today's single
-    # --router-type flag), so it's placed on stage1_model; stage2_model's
-    # stays disabled.
-    cfg = gconfig.merge_cli_overrides(
-        gconfig.DEFAULT_CONFIG,
-        None,
-        {
-            "conditioning": {
-                "particle": {"type": particle_conditioning},
-                "material": {"type": material_conditioning},
-            },
-            "stage1_model": {"router": router_cfg},
-            "stage2_model": {"router": {"enabled": False}, "k_max": K_MAX},
-        },
-    )
+    # --router-type flag), so it's placed on stage1_model; stage2_model's is
+    # left to DEFAULT_CONFIG/the config file rather than forced disabled.
+    router_overrides: dict = {}
+    if router_enabled is not None:
+        router_overrides["enabled"] = router_enabled
+    if router_type is not None:
+        router_overrides["type"] = router_type
+    if n_experts is not None:
+        router_overrides["n_experts"] = n_experts
+    if router_overrides:
+        overrides["stage1_model"] = {"router": router_overrides}
+
+    train_overrides: dict = {}
+    if val_fraction is not None:
+        train_overrides["val_fraction"] = val_fraction
+    if seed is not None:
+        train_overrides["seed"] = seed
+    if train_overrides:
+        overrides["train"] = train_overrides
+
+    cfg = gconfig.merge_cli_overrides(gconfig.DEFAULT_CONFIG, config_path, overrides)
+    gconfig.validate_config(cfg)
     run_setup_stage(
         Path(data),
-        val_fraction=val_fraction,
-        seed=seed,
+        val_fraction=cfg["train"]["val_fraction"],
+        seed=cfg["train"]["seed"],
         cfg=cfg,
         cache_setup=True,
         rebuild_setup_cache=rebuild,

giant/training/__init__.py

@@ -5,7 +5,7 @@ Split out of the former single-module `giant/train.py`. The public surface is
 that tests and tooling construct directly.
 """
 
-from giant.training.checkpoint import build_checkpoint, load_checkpoint
+from giant.training.checkpoint import build_checkpoint, init_stages_from_checkpoints, load_checkpoint
 from giant.training.metrics import MetricsCollector, MetricSpec
 from giant.training.loop import train
 from giant.training.trainers import (
@@ -25,6 +25,7 @@ __all__ = [
     "WGANStageTrainer",
     "build_checkpoint",
     "build_stage_trainers",
+    "init_stages_from_checkpoints",
     "load_checkpoint",
     "train",
 ]

giant/training/amp.py

@@ -0,0 +1,47 @@
+"""Mixed-precision training support (`train.precision`, gitea #47).
+
+Only `"fp32"` (no autocast) and `"bf16"` are supported — no `"fp16"`/
+`GradScaler`. bf16 needs no gradient scaler and covers every training GPU in
+the fleet (Ampere and newer: A100, L40S, H200, RTX 4070); fp16 would need a
+scaler *and* fixes to two fragile spots that stay correct under bf16 but break
+under fp16's narrower range — `giant.model.routers`' `1e-8` epsilons (below
+fp16's ~6e-8 subnormal floor) and `giant.model.wgan.gradient_penalty`'s
+sum-of-squares gradient norm (overflows fp16 above ~65504). Revisit if a
+pre-Ampere (V100) training target ever shows up.
+"""
+
+import torch
+
+_SUPPORTED_DEVICE_TYPES = ("cuda", "cpu")
+
+
+def resolve_autocast(precision: str, device: torch.device) -> tuple[str, torch.dtype, bool]:
+    """Resolves `train.precision` + a target device into the
+    `(device_type, dtype, enabled)` triple `torch.autocast` takes as kwargs —
+    computed once per `StageTrainer` rather than re-derived every step.
+
+    Raises `ValueError` rather than silently falling back to fp32: a training
+    run that's quietly not using the mixed precision it was configured for is
+    a wasted GPU-week, not a warning.
+    """
+    if precision == "fp32":
+        return device.type, torch.float32, False
+    if precision != "bf16":
+        raise ValueError(f"unknown precision {precision!r}; must be 'fp32' or 'bf16'")
+
+    if device.type == "cuda":
+        if not torch.cuda.is_bf16_supported():
+            cap = torch.cuda.get_device_capability(device)
+            raise ValueError(
+                f"train.precision = 'bf16' but {torch.cuda.get_device_name(device)} "
+                f"(compute capability {cap[0]}.{cap[1]}) has no native bf16 support "
+                "(needs Ampere/sm_80 or newer) — use train.precision = 'fp32' instead"
+            )
+        return "cuda", torch.bfloat16, True
+    if device.type == "cpu":
+        # torch 2.3's CPU autocast supports bf16 unconditionally — this is
+        # also what lets the bf16 training path be tested without a GPU.
+        return "cpu", torch.bfloat16, True
+    raise ValueError(
+        f"train.precision = 'bf16' is not supported on device type {device.type!r} (only {_SUPPORTED_DEVICE_TYPES} are)"
+    )

giant/training/checkpoint.py

@@ -8,6 +8,8 @@ and per-stage `optimizer_<stage>` / `optimizer_d_<stage>` / `lr_sched_<stage>`
 entries.
 """
 
+import torch
+
 from giant.training.trainers import StageTrainer
 
 #: Stage name -> the checkpoint key its weights live under. Historical: stage
@@ -46,6 +48,37 @@ def build_checkpoint(
     return ckpt
 
 
+def init_stages_from_checkpoints(trainers: dict[str, StageTrainer]) -> list[str]:
+    """Load each trainer's `spec.init_from` checkpoint (gitea #42) into its
+    model, before training starts — the partial-retrain counterpart to
+    `load_checkpoint`'s full-run `--resume`. Only weights move: unlike
+    `load_checkpoint`, this never touches optimizer/lr_sched/epoch state, so
+    it composes cleanly with `--resume` (call this first; a resume's own
+    `load_checkpoint` then overwrites whatever this loaded with the resumed
+    run's own weights).
+
+    A stage with no `init_from` set (`""`, the default) is left alone. The
+    EMA companion (`<key>_ema`) is loaded too when both the source checkpoint
+    and this trainer have one, so `--weights ema` at inference still sees the
+    source's EMA shadow rather than a copy of its raw weights. Returns one
+    description string per stage actually initialized, for the caller to
+    echo.
+    """
+    loaded = []
+    for name, trainer in trainers.items():
+        init_from = trainer.spec.init_from
+        if not init_from:
+            continue
+        key = _STAGE_KEY[name]
+        ckpt = torch.load(init_from, map_location="cpu", weights_only=False)
+        trainer.model.load_state_dict(ckpt[key])
+        ema_key = f"{key}_ema"
+        if trainer.ema_model is not None and ema_key in ckpt:
+            trainer.ema_model.load_state_dict(ckpt[ema_key])
+        loaded.append(f"{name}: loaded from {init_from}" + (" (frozen)" if trainer.frozen else ""))
+    return loaded
+
+
 def load_checkpoint(trainers: dict[str, StageTrainer], ckpt: dict, lr: float) -> None:
     """Restore every active stage, then hand `lr`'s authority back to the
     config — `load_state_dict` would otherwise leave the checkpoint's own

giant/training/loop.py

@@ -20,7 +20,7 @@ from tqdm import tqdm
 
 from giant.data.loader import TopNMap
 from giant.data.setup_cache import topnmap_to_json
-from giant.training.checkpoint import build_checkpoint, load_checkpoint
+from giant.training.checkpoint import build_checkpoint, init_stages_from_checkpoints, load_checkpoint
 from giant.training.metrics import MetricsCollector
 from giant.training.trainers import (
     FlowDDPMStageTrainer,
@@ -132,9 +132,12 @@ def train(
     validate_steps = t.get("validate_steps", 10)
     max_val_batches = t.get("max_val_batches", 0)
 
-    trainers = build_stage_trainers(cfg, models, critics, device, total_train_batches)
+    sec_type_class_counts = sec_type_topn_map.class_counts if sec_type_topn_map is not None else None
+    trainers = build_stage_trainers(cfg, models, critics, device, total_train_batches, sec_type_class_counts)
     if not trainers:
         raise ValueError("no active stage — stage1_model.active and stage2_model.active are both false")
+    for line in init_stages_from_checkpoints(trainers):
+        print(line)
     has_adversarial = any(not tr.supports_val_loss for tr in trainers.values())
 
     checkpoint_extras = {

giant/training/stage2_inputs.py

@@ -11,7 +11,9 @@ live in one place and stay unit-testable on their own.
 import torch
 import torch.nn.functional as F
 
+from giant.config import ParticleTypeConfig
 from giant.constants import CONT_SLOT_DIM, PARTICLE_PHYS_DIM
+from giant.model.objectives import build_objective
 from giant.sample import sample_secondaries_ar
 
 
@@ -30,7 +32,7 @@ def _gumbel_tau(step: int, total_steps: int, tau_start: float, tau_end: float) -
 def _type_repr(
     sec_type_idx: torch.Tensor,
     sec_cont: torch.Tensor,
-    particle_type_cfg: dict,
+    particle_type_cfg: ParticleTypeConfig,
     cond_enc: torch.nn.Module,
     emb_dim: int,
 ) -> torch.Tensor:
@@ -45,7 +47,7 @@ def _type_repr(
     latter must always reflect the true physical secondary that came before,
     regardless of what the *current* token's own training objective is.
     """
-    target = particle_type_cfg.get("target", "physical")
+    target = particle_type_cfg.target
     if target == "physical":
         return sec_cont[..., CONT_SLOT_DIM : CONT_SLOT_DIM + PARTICLE_PHYS_DIM]
     if target == "onehot":
@@ -56,7 +58,7 @@ def _type_repr(
 def _assemble_stage2_ar_target(
     sec_cont: torch.Tensor,
     sec_type_idx: torch.Tensor,
-    particle_type_cfg: dict,
+    particle_type_cfg: ParticleTypeConfig,
     generator: str,
     cond_enc: torch.nn.Module,
     emb_dim: int,
@@ -69,19 +71,20 @@ def _assemble_stage2_ar_target(
 
     - `target = "physical"`: unchanged from v0.2 — `sec_cont` (stick_logit,
       dir, log_mass, charge) as-is.
-    - `target` in `("onehot", "embedding")` + `generator in ("flow", "ddpm")`:
-      just the continuous stick/dir slots — the type slice isn't part of
-      this tensor at all (`type_head` handles it separately).
-    - `target` in `("onehot", "embedding")` + `generator == "wgan"`: stick/dir
-      slots concatenated with the per-slot type representation (a one-hot of
-      the true class, relaxed on the *generated* side only, by the caller;
-      or the conditioning's own detached embedding-table row).
+    - `target` in `("onehot", "embedding")` + an objective that doesn't fold
+      the type slice (flow/ddpm): just the continuous stick/dir slots — the
+      type slice isn't part of this tensor at all (`type_head` handles it
+      separately).
+    - `target` in `("onehot", "embedding")` + a folding objective (wgan):
+      stick/dir slots concatenated with the per-slot type representation (a
+      one-hot of the true class, relaxed on the *generated* side only, by the
+      caller; or the conditioning's own detached embedding-table row).
     """
-    target = particle_type_cfg.get("target", "physical")
+    target = particle_type_cfg.target
     if target == "physical":
         return sec_cont
     cont = sec_cont[..., :CONT_SLOT_DIM]
-    if generator != "wgan":
+    if not build_objective(generator).folds_type_slice:
         return cont
     type_repr = _type_repr(sec_type_idx, sec_cont, particle_type_cfg, cond_enc, emb_dim)
     return torch.cat([cont, type_repr], dim=-1)
@@ -90,7 +93,7 @@ def _assemble_stage2_ar_target(
 def _assemble_stage2_real(
     sec_cont: torch.Tensor,
     sec_type_idx: torch.Tensor,
-    particle_type_cfg: dict,
+    particle_type_cfg: ParticleTypeConfig,
     generator: str,
     cond_enc: torch.nn.Module,
     emb_dim: int,
@@ -117,9 +120,17 @@ def _remaining_energy_fraction(fraction: torch.Tensor) -> torch.Tensor:
     slot i: `1.0` at `i=0`, `prod_{j<i}(1-fraction_j)` for `i>=1`
     ("no re-derivation needed": the existing
     stick-breaking encoding is already scale-free, so this is derivable from
-    the batch's ground-truth stick logits alone, no `e_sec` required)."""
-    cumprod = torch.cumprod(1.0 - fraction, dim=1)
-    return torch.cat([torch.ones_like(cumprod[:, :1]), cumprod[:, :-1]], dim=1)
+    the batch's ground-truth stick logits alone, no `e_sec` required).
+
+    Forced fp32 regardless of the caller's ambient `train.precision` autocast
+    region: a `cumprod` over `K_MAX` slots in bf16 underflows to zero within a
+    handful of slots, killing `remaining_frac` as a conditioning signal — the
+    numpy encoder (`giant.data.transforms.encode_secondaries`'s stick-breaking
+    twin) already promotes to float64 for exactly this reason (gitea #47)."""
+    with torch.autocast(fraction.device.type, enabled=False):
+        fraction = fraction.float()
+        cumprod = torch.cumprod(1.0 - fraction, dim=1)
+        return torch.cat([torch.ones_like(cumprod[:, :1]), cumprod[:, :-1]], dim=1)
 
 
 def _shift_prev(x: torch.Tensor) -> torch.Tensor:
@@ -137,6 +148,27 @@ def _ar_has_prev(k_max: int, device: torch.device) -> torch.Tensor:
     return (torch.arange(k_max, device=device) >= 1).unsqueeze(0)
 
 
+def _stop_target_and_mask(n_sec: torch.Tensor, k_max: int, device: torch.device) -> tuple[torch.Tensor, torch.Tensor]:
+    """`(target, mask)`, both `(B, K_MAX)`, for `n_sec.mode = "stop_token"`'s
+    per-slot EOS head (`Stage2Autoregressive.predict_stop`).
+
+    `predict_stop` is evaluated on slot `k`'s own (pre-token) conditioning —
+    "should generation have already stopped by here" — so `target[k] = 1`
+    exactly at `k == n_sec` (the first invalid slot: `sample_secondaries_ar`
+    checks this before spending a model call generating that slot's token),
+    `0` elsewhere. `mask` is `k <= n_sec` — one slot *wider* than
+    `StageTrainer._sec_mask`'s `k < n_sec` token-content mask, since the stop
+    slot itself (`k == n_sec`) must be supervised even though there is no
+    real secondary there. A row with `n_sec == k_max` has no in-range stop
+    slot at all: `mask` covers the full `k_max` range (every generated token
+    is real) and `target` is all-zero — `sample_secondaries_ar` correctly
+    never breaks early for it, running into the `k_max` safety cap instead."""
+    idx = torch.arange(k_max, device=device).unsqueeze(0)
+    target = (idx == n_sec.unsqueeze(1)).float()
+    mask = idx <= n_sec.unsqueeze(1)
+    return target, mask
+
+
 def _ar_meta(k_max: int, batch: int, device: torch.device, fraction: torch.Tensor) -> dict[str, torch.Tensor]:
     """`has_prev`/`remaining_frac`/`slot_idx` — the three per-token AR
     conditioning tensors that don't depend on *which* history representation
@@ -155,7 +187,7 @@ def _ar_meta(k_max: int, batch: int, device: torch.device, fraction: torch.Tenso
 def _assemble_stage2_ar_inputs(
     sec_cont: torch.Tensor,
     sec_type_idx: torch.Tensor,
-    particle_type_cfg: dict,
+    particle_type_cfg: ParticleTypeConfig,
     cond_enc: torch.nn.Module,
     emb_dim: int,
 ) -> dict[str, torch.Tensor]:
@@ -178,27 +210,43 @@ def _assemble_stage2_ar_inputs(
     return {"history_feat": history_feat, **_ar_meta(K, B, device, fraction)}
 
 
-def _stage2_tf_prob(mode: str, p_start: float, p_end: float, epoch: int, total_epochs: int) -> float:
-    """P(condition slot k+1 on the TRUE token k rather than the model's own
-    prediction), for the current epoch
-    (`stage2_model.autoregressive.teacher_forcing`).
-    `"always"`/`"never"` are the two degenerate constants; `"scheduled"`
-    linearly interpolates
-    `p_start` (epoch 0) to `p_end` (the final epoch) — standard scheduled
-    sampling (Bengio et al. 2015)."""
-    if mode == "always":
-        return 1.0
-    if mode == "never":
-        return 0.0
+def _linear_schedule(p_start: float, p_end: float, epoch: int, total_epochs: int) -> float:
+    """Linear interpolation from `p_start` (epoch 0) to `p_end` (the final
+    epoch) — standard scheduled sampling (Bengio et al. 2015), shared by
+    every train-time schedule keyed on epoch."""
     frac = epoch / max(total_epochs - 1, 1)
     frac = min(max(frac, 0.0), 1.0)
     return p_start + (p_end - p_start) * frac
 
 
+def _stage2_tf_prob(mode: str, p_start: float, p_end: float, epoch: int, total_epochs: int) -> float:
+    """P(condition slot k+1 on the TRUE token k rather than the model's own
+    prediction), for the current epoch
+    (`stage2_model.autoregressive.teacher_forcing`).
+    `"always"`/`"never"` are the two degenerate constants; `"scheduled"`
+    linearly interpolates `p_start` to `p_end` via `_linear_schedule`."""
+    if mode == "always":
+        return 1.0
+    if mode == "never":
+        return 0.0
+    return _linear_schedule(p_start, p_end, epoch, total_epochs)
+
+
+def _ctx_truth_prob(mode: str, p_start: float, p_end: float, epoch: int, total_epochs: int) -> float:
+    """P(condition stage 2 on the TRUE stage-1 outcome rather than a fresh
+    stage-1 sample), for the current epoch (`stage2_model.stage1_context`).
+    `"truth"` is the degenerate constant 1.0; `"sampled"` linearly
+    interpolates `ctx_p_start` to `ctx_p_end` via `_linear_schedule` — the
+    stage-boundary counterpart of `_stage2_tf_prob`."""
+    if mode == "truth":
+        return 1.0
+    return _linear_schedule(p_start, p_end, epoch, total_epochs)
+
+
 def _history_repr_from_ar_sample(
     sec_cont_pred: torch.Tensor,
     sec_type_pred: torch.Tensor,
-    particle_type_cfg: dict,
+    particle_type_cfg: ParticleTypeConfig,
 ) -> tuple[torch.Tensor, torch.Tensor, torch.Tensor]:
     """`(fraction, direction, type_repr)` — the same triple `_type_repr` /
     `_stick_fraction` derive from ground truth, but from a free-running
@@ -211,7 +259,7 @@ def _history_repr_from_ar_sample(
     representation."""
     fraction = torch.sigmoid(sec_cont_pred[..., 0])
     direction = sec_cont_pred[..., 1:4]
-    if particle_type_cfg.get("target", "physical") == "onehot":
+    if particle_type_cfg.target == "onehot":
         type_dim = sec_type_pred.size(-1)
         type_repr = F.one_hot(sec_type_pred.argmax(-1), num_classes=type_dim).float()
     else:
@@ -227,7 +275,7 @@ def _assemble_stage2_ar_inputs_scheduled(
     sec_cont: torch.Tensor,
     sec_type_idx: torch.Tensor,
     n_sec: torch.Tensor,
-    particle_type_cfg: dict,
+    particle_type_cfg: ParticleTypeConfig,
     cond_enc: torch.nn.Module,
     emb_dim: int,
     p_tf: float,

giant/training/trainers.py

@@ -25,21 +25,19 @@ import torch.optim as optim
 from giant.config import ParticleTypeConfig, Stage1ModelConfig, Stage2ModelConfig, TrainConfig
 from giant.constants import CONT_SLOT_DIM
 from giant.data.dataset import StepBatch
-from giant.model.network import Router, resolve_type_n_classes, stage2_type_dim
-from giant.model.schedule import (
-    CosineSchedule,
-    flow_matching_loss,
-    flow_matching_loss_secondary,
-    flow_matching_loss_secondary_ar,
-)
+from giant.model.network import Router, build_objective, resolve_type_n_classes, stage2_type_dim
 from giant.model.wgan import generator_loss, gradient_penalty
+from giant.sample import sample_stage1
+from giant.training.amp import resolve_autocast
 from giant.training.metrics import MetricSpec, stage_metric, train_metric, val_metric
 from giant.training.stage2_inputs import (
     _assemble_stage2_ar_inputs_scheduled,
     _assemble_stage2_ar_target,
+    _ctx_truth_prob,
     _gumbel_tau,
     _relax_onehot_type_slice,
     _stage2_tf_prob,
+    _stop_target_and_mask,
 )
 
 
@@ -78,6 +76,41 @@ def _batch_to_device(batch: StepBatch, device: torch.device) -> StepBatch:
     return type(batch)(*(t.to(device) for t in batch))
 
 
+def _type_class_weight_vector(class_counts: dict[int, int], n_classes: int, scheme: str) -> list[float] | None:
+    """Per-class `F.cross_entropy(weight=...)` vector for the stage-2 type
+    head's `class_weighting` (gitea #44), or `None` under `"none"` (the
+    pre-#44 unweighted-CE behavior — the caller must pass that through as
+    `weight=None`, not a vector of ones, so old runs stay bit-identical).
+
+    `"inverse_freq"`: `1 / count` per class, normalized to mean 1 over
+    `n_classes` so switching this on doesn't rescale the type loss against
+    `particle_type.lambda` / the generator loss it's summed with. A class
+    with zero training examples (fewer distinct species than `n_classes - 1`
+    slots) clamps its count to 1 — its weight is otherwise undefined, and
+    since it never appears in a batch's labels the value is inert anyway.
+
+    Raises if `scheme != "none"` and `class_counts` is empty: that means the
+    `TopNMap` behind this run predates gitea #44 (a stale checkpoint's decode
+    map, or a not-yet-rebuilt setup-cache sidecar) and truly has no
+    frequency information to weight by — silently falling back to uniform
+    weights would look like the feature is active when it isn't.
+    """
+    if scheme == "none":
+        return None
+    if not class_counts:
+        raise ValueError(
+            f"stage2_model.particle_type.class_weighting = {scheme!r} requires "
+            "per-class counts, but this run's sec_type_topn_map has none "
+            "(class_counts={}) — it was built before gitea #44 or loaded "
+            "from a stale setup-cache sidecar/checkpoint; rebuild the setup "
+            "cache (giant train --rebuild-setup-cache) or retrain."
+        )
+    counts = [max(class_counts.get(i, 0), 1) for i in range(n_classes)]
+    inv = [1.0 / c for c in counts]
+    mean_inv = sum(inv) / len(inv)
+    return [w / mean_inv for w in inv]
+
+
 @dataclass(frozen=True)
 class StageSpec:
     """One stage's resolved training configuration.
@@ -92,13 +125,22 @@ class StageSpec:
     generator: str
     decoder: str = "one_shot"
 
+    # partial-retrain (gitea #42)
+    init_from: str = ""
+    freeze: bool = False
+
     # loss weights
     lambda_weight: float = 1.0
     n_sec_lambda: float = 0.1
+    n_sec_mode: str = "head"
 
     # particle-type target (stage 2 only)
     particle_type: ParticleTypeConfig = field(default_factory=ParticleTypeConfig)
     particle_type_n_classes: int = 16
+    # Resolved by from_config from sec_type_class_counts (dataset-derived,
+    # not itself a cfg value — see _type_class_weight_vector) crossed with
+    # particle_type.class_weighting (gitea #44). None under "none".
+    type_class_weights: list[float] | None = None
 
     # optimization
     lr: float = 3e-4
@@ -107,6 +149,7 @@ class StageSpec:
     warmup_epochs: int = 0
     epochs: int = 1
     steps_per_epoch: int = 1
+    precision: str = "fp32"
 
     # routing auxiliaries
     lambda_balance: float = 0.0
@@ -121,6 +164,11 @@ class StageSpec:
     tf_p_end: float = 1.0
     ar_sample_steps: int = 10
 
+    # stage-1/stage-2 boundary (stage 2 only)
+    stage1_context: str = "truth"
+    ctx_p_start: float = 1.0
+    ctx_p_end: float = 0.0
+
     # generator-specific
     ddpm_n_steps: int = 1000
     n_critic: int = 5
@@ -130,7 +178,18 @@ class StageSpec:
     type_gumbel_tau_end: float = 0.1
 
     @classmethod
-    def from_config(cls, cfg: dict, name: str, is_stage2: bool, steps_per_epoch: int) -> "StageSpec":
+    def from_config(
+        cls,
+        cfg: dict,
+        name: str,
+        is_stage2: bool,
+        steps_per_epoch: int,
+        sec_type_class_counts: dict[int, int] | None = None,
+    ) -> "StageSpec":
+        """`sec_type_class_counts` is dataset-derived (`sec_type_topn_map.class_counts`,
+        gitea #44), not a `cfg` value — it's the one input to `StageSpec` that
+        doesn't come from `cfg`, kept separate from the "only place that
+        reads `cfg`" invariant below on purpose."""
         t = TrainConfig.from_dict(cfg["train"])
         # n_sec/particle_type/decoder/autoregressive/wgan's gumbel_tau_* are
         # stage-2-only concepts, always read off s2_spec (guarded by
@@ -143,16 +202,23 @@ class StageSpec:
         # stage 1's).
         s2_spec = Stage2ModelConfig.from_dict(cfg["stage2_model"])
         stage_spec = s2_spec if is_stage2 else Stage1ModelConfig.from_dict(cfg["stage1_model"])
+        particle_type_n_classes = resolve_type_n_classes(
+            s2_spec.particle_type, cfg["conditioning"]["particle"]["emb_dim"]
+        )
         return cls(
             name=name,
             is_stage2=is_stage2,
             generator=stage_spec.generator,
             decoder=s2_spec.decoder if is_stage2 else "one_shot",
+            init_from=stage_spec.init_from,
+            freeze=stage_spec.freeze,
             lambda_weight=stage_spec.lambda_weight,
             n_sec_lambda=s2_spec.n_sec.lambda_weight,
+            n_sec_mode=s2_spec.n_sec.mode,
             particle_type=s2_spec.particle_type,
-            particle_type_n_classes=resolve_type_n_classes(
-                s2_spec.particle_type.to_dict(), cfg["conditioning"]["particle"]["emb_dim"]
+            particle_type_n_classes=particle_type_n_classes,
+            type_class_weights=_type_class_weight_vector(
+                sec_type_class_counts or {}, particle_type_n_classes, s2_spec.particle_type.class_weighting
             ),
             # train.* keys are all guaranteed by DEFAULT_CONFIG's deep-merge
             # (giant/config.py), so TrainConfig.from_dict never has to fall
@@ -164,6 +230,7 @@ class StageSpec:
             warmup_epochs=t.warmup_epochs,
             epochs=t.epochs,
             steps_per_epoch=max(steps_per_epoch, 1),
+            precision=t.precision,
             lambda_balance=stage_spec.router.lambda_balance,
             lambda_proc=stage_spec.router.lambda_proc,
             lambda_entropy=stage_spec.router.lambda_entropy,
@@ -172,6 +239,9 @@ class StageSpec:
             teacher_forcing=s2_spec.autoregressive.teacher_forcing if is_stage2 else cls.teacher_forcing,
             tf_p_start=s2_spec.autoregressive.tf_p_start if is_stage2 else cls.tf_p_start,
             tf_p_end=s2_spec.autoregressive.tf_p_end if is_stage2 else cls.tf_p_end,
+            stage1_context=s2_spec.stage1_context if is_stage2 else cls.stage1_context,
+            ctx_p_start=s2_spec.ctx_p_start if is_stage2 else cls.ctx_p_start,
+            ctx_p_end=s2_spec.ctx_p_end if is_stage2 else cls.ctx_p_end,
             # AR self-sampling under scheduled/never teacher forcing reuses
             # train.validate_steps as its flow-matching ODE step count — no
             # dedicated config key for this (the autoregressive config lists
@@ -189,13 +259,16 @@ class StageSpec:
 class StageTrainer:
     """One active stage's optimizer(s), EMA, and per-batch step.
 
-    Reads only the shared `StepBatch` (`giant.data.dataset`) — stage 2 always
-    conditions on the ground-truth `x1_s1` (`stage2_model.stage1_context =
-    "truth"`, stage-level teacher forcing; `"sampled"` is not implemented),
-    so stage trainers never need each other's output at train time. This means
-    "stage-2-only training is a cheap ablation, not new plumbing" falls out
-    for free: a trainer only exists for active stages, and inactive stages
-    are simply never constructed.
+    Reads only the shared `StepBatch` (`giant.data.dataset`) by default — stage
+    2 conditions on the ground-truth `x1_s1` (`stage2_model.stage1_context =
+    "truth"`, stage-level teacher forcing), so "stage-2-only training is a
+    cheap ablation, not new plumbing" falls out for free: a trainer only
+    exists for active stages, and inactive stages are simply never
+    constructed. `stage2_model.stage1_context = "sampled"` is the one
+    exception — `build_stage_trainers` wires the stage-2 trainer to the
+    stage-1 one via `attach_stage1` so it can draw a real stage-1 sample
+    (`giant.sample.sample_stage1`) instead, scheduled by `ctx_p_start`/
+    `ctx_p_end` (see `_stage1_context`).
 
     Grad-norm clipping is per-stage here — v0.2's single shared optimizer
     clipped both stages' gradients jointly; splitting per stage is a small,
@@ -234,12 +307,19 @@ class StageTrainer:
         self.is_stage2 = spec.is_stage2
         self.generator = spec.generator
         self.decoder = spec.decoder
+        self.frozen = spec.freeze
         self.device = device
         self.model = model.to(device)
         self.router = _stage_router(self.model)
         self._modules = (self.model, *extra_modules)
 
-        self.particle_type_cfg = spec.particle_type.to_dict()
+        # Resolved once (not re-derived every step) — see
+        # giant.training.amp.resolve_autocast (gitea #47).
+        self._autocast_device_type, self._autocast_dtype, self._autocast_enabled = resolve_autocast(
+            spec.precision, device
+        )
+
+        self.particle_type_cfg = spec.particle_type
         self.particle_type_n_classes = spec.particle_type_n_classes
         self.ema_decay = spec.ema_decay
 
@@ -249,6 +329,18 @@ class StageTrainer:
             for p in self.ema_model.parameters():
                 p.requires_grad_(False)
 
+        #: Set by `attach_stage1` when `stage2_model.stage1_context =
+        #: "sampled"` — the stage-1 `StageTrainer` this (stage-2) trainer
+        #: draws its context sample from. `None` for stage 1 itself, and for
+        #: stage 2 under "truth".
+        self.stage1_source: "StageTrainer | None" = None
+
+    def attach_stage1(self, stage1_trainer: "StageTrainer") -> None:
+        """Wires this (stage-2) trainer to the stage-1 trainer it should
+        sample from under `stage2_model.stage1_context = "sampled"` — see
+        `build_stage_trainers`."""
+        self.stage1_source = stage1_trainer
+
     # --- schedule -------------------------------------------------------
 
     def _init_lr_schedule(self, optimizer: optim.Optimizer, warmup_steps: int, total_steps: int) -> None:
@@ -292,6 +384,58 @@ class StageTrainer:
         for module in self._modules:
             module.eval()
 
+    # --- stage-1/stage-2 boundary (shared by both trainer subclasses) ---
+
+    def _stage1_context(
+        self,
+        x1_s1: torch.Tensor,
+        cond_cont: torch.Tensor,
+        cond_cat: torch.Tensor,
+        epoch: int | None,
+    ) -> torch.Tensor:
+        """The stage-1 outcome stage 2 conditions on this batch.
+
+        `epoch=None` means "always ground truth" regardless of
+        `spec.stage1_context` — the same val-loss convention `_ar_inputs`
+        uses, so validation stays a stable, non-stochastic comparison.
+        Otherwise, under `stage1_context = "sampled"`, each example
+        independently uses the ground truth with probability `p_truth`
+        (`_ctx_truth_prob`, ramped by `ctx_p_start`/`ctx_p_end`) and a fresh
+        `giant.sample.sample_stage1` draw from `stage1_source.sampling_model()`
+        otherwise — a real sampling pass, not a cheap proxy, matching
+        `_assemble_stage2_ar_inputs_scheduled`'s precedent for the equivalent
+        in-stage-2 self-sample. Mixed per example (not per-dimension): a row
+        is either the real ground-truth 9D vector or a real sample, never an
+        elementwise blend of the two.
+        """
+        x1_s1 = x1_s1.detach()
+        if self.stage1_source is None or epoch is None:
+            return x1_s1
+        p_truth = _ctx_truth_prob(
+            self.spec.stage1_context,
+            self.spec.ctx_p_start,
+            self.spec.ctx_p_end,
+            epoch,
+            self.spec.epochs,
+        )
+        if p_truth >= 1.0:
+            return x1_s1
+
+        stage1_model = self.stage1_source.sampling_model()
+        was_training = stage1_model.training
+        sampled, _ = sample_stage1(
+            stage1_model,
+            cond_cont,
+            cond_cat,
+            steps=self.spec.ar_sample_steps,
+            ddpm_steps=self.stage1_source.spec.ddpm_n_steps,
+        )
+        if was_training:
+            stage1_model.train()
+
+        use_truth = torch.rand(x1_s1.size(0), 1, device=x1_s1.device) < p_truth
+        return torch.where(use_truth, x1_s1, sampled).detach()
+
     # --- stage-2 secondary assembly (shared by both trainer subclasses) ---
 
     def _ar_inputs(
@@ -380,10 +524,9 @@ class StageTrainer:
         stage1-vs-stage2 `predict_n_sec` signature split, shared by the
         non-adversarial and WGAN trainers.
 
-        Gated on `n_sec_head is None`, not on `n_sec.mode`: a future
-        `mode="stop_token"` model (currently rejected in
-        `validate_config`) carries no head and would train its EOS signal in
-        the generator/AR loss path instead, so this correctly stays zero.
+        Gated on `n_sec_head is None`, not on `n_sec.mode`: a `mode =
+        "stop_token"` model carries no head at all (see `_stop_loss` for its
+        EOS signal instead), so this correctly stays zero for it.
         """
         if self.model.n_sec_head is None:
             zero = torch.zeros((), device=device)
@@ -397,14 +540,77 @@ class StageTrainer:
         nsec_acc = (logits.argmax(dim=-1) == n_sec).float().mean()
         return l_nsec, nsec_acc
 
-    @staticmethod
-    def _step_optimizer(optimizer: optim.Optimizer, loss: torch.Tensor, params: list) -> float:
+    def _stop_loss(
+        self,
+        cond_cont: torch.Tensor,
+        cond_cat: torch.Tensor,
+        stage1_ctx: torch.Tensor,
+        n_sec: torch.Tensor,
+        device: torch.device,
+        ar_inputs: dict[str, torch.Tensor] | None,
+    ) -> tuple[torch.Tensor, torch.Tensor]:
+        """`(l_stop, stop_acc)` for `n_sec.mode = "stop_token"`'s per-slot EOS
+        head (`Stage2Autoregressive.predict_stop`) — zeros when this stage
+        owns no `stop_head` (every other `n_sec.mode`), the same gating
+        convention `_n_sec_loss` uses for `n_sec_head`. The two heads are
+        mutually exclusive (`giant.model.builders`), so exactly one of
+        `_n_sec_loss`/`_stop_loss` is ever non-zero for a given stage.
+
+        Masked BCE against `_stop_target_and_mask`'s per-slot target — one
+        slot wider than `sec_mask` (the stop slot itself, `k == n_sec`, needs
+        supervision even though it holds no real secondary)."""
+        stop_head = getattr(self.model, "stop_head", None)
+        if stop_head is None:
+            zero = torch.zeros((), device=device)
+            return zero, zero
+        assert ar_inputs is not None
+        logits = self.model.predict_stop(
+            cond_cont,
+            cond_cat,
+            stage1_ctx,
+            ar_inputs["history_feat"],
+            ar_inputs["has_prev"],
+            ar_inputs["remaining_frac"],
+            ar_inputs["slot_idx"],
+        )
+        target, mask = _stop_target_and_mask(n_sec, logits.size(1), device)
+        mask_f = mask.float()
+        denom = mask_f.sum().clamp(min=1)
+        bce = F.binary_cross_entropy_with_logits(logits, target, reduction="none")
+        l_stop = (bce * mask_f).sum() / denom
+        stop_acc = (((logits >= 0).float() == target).float() * mask_f).sum() / denom
+        return l_stop, stop_acc
+
+    def _autocast(self) -> torch.autocast:
+        """The training-step autocast region (`train.precision`, gitea #47).
+
+        Only wraps forward/loss computation — `backward()`/`optimizer.step()`
+        stay outside, and `val_loss` never calls this at all, so validation
+        (and the best-checkpoint selection it drives) stays precision-
+        independent and comparable against every fp32-only run recorded so
+        far. `enabled=False` under `precision = "fp32"` (the default) makes
+        this a true no-op, so callers never need to branch on precision
+        themselves."""
+        return torch.autocast(
+            self._autocast_device_type,
+            dtype=self._autocast_dtype,
+            enabled=self._autocast_enabled,
+        )
+
+    def _step_optimizer(self, optimizer: optim.Optimizer, loss: torch.Tensor, params: list) -> float:
         """`zero_grad -> backward -> clip_grad_norm_(1.0) -> step`, returning
-        the pre-clip grad norm. The one place the grad-clip constant lives."""
+        the pre-clip grad norm. The one place the grad-clip constant lives.
+
+        `self.frozen` (`stage{1,2}_model.freeze`, gitea #42) skips only the
+        final `optimizer.step()` — backward/clip still run so loss/grad_norm
+        stay meaningful to watch, but the stage's weights (and, for a WGAN
+        stage, its critic's — this same method is both trainers' single
+        optimizer-step choke point) never move."""
         optimizer.zero_grad()
         loss.backward()
         grad_norm = torch.nn.utils.clip_grad_norm_(params, 1.0)
-        optimizer.step()
+        if not self.frozen:
+            optimizer.step()
         return grad_norm.item()
 
     def _extra_state(self) -> dict:
@@ -450,20 +656,29 @@ class FlowDDPMStageTrainer(StageTrainer):
     """flow or ddpm generator for a single stage."""
 
     def __init__(self, spec: StageSpec, model: torch.nn.Module, device: torch.device) -> None:
-        if spec.is_stage2 and spec.generator not in ("flow",):
+        objective = build_objective(spec.generator, n_steps=spec.ddpm_n_steps)
+        if spec.is_stage2 and not objective.supports_stage2_decoder:
             raise NotImplementedError(
                 f"stage2_model.generator={spec.generator!r} is accepted by the "
                 "schema but not implemented in v0.3.0 for stage 2 (only "
                 "'flow' and 'wgan' have a stage-2 secondary-decoder loss)"
             )
         super().__init__(spec, model, device)
-        self.particle_type_lambda = self.particle_type_cfg.get("lambda", 1.0)
+        self.objective = objective
+        self.particle_type_lambda = self.particle_type_cfg.lambda_weight
         # Width of the type slice actually folded into x1_s2 by _sec_target,
-        # under this trainer's generator (flow/ddpm only — see the
-        # NotImplementedError above): "physical" keeps it folded in
-        # (PARTICLE_PHYS_DIM wide, unchanged from v0.2); "onehot"/"embedding"
-        # pull it out into model.type_head instead (0 here).
-        self._flow_type_dim = None if self.particle_type_cfg.get("target", "physical") == "physical" else 0
+        # under this trainer's objective (flow/ddpm only — see the
+        # NotImplementedError above, neither folds the type slice): "physical"
+        # keeps it folded in (PARTICLE_PHYS_DIM wide, unchanged from v0.2);
+        # "onehot"/"embedding" pull it out into model.type_head instead (0
+        # here).
+        self._flow_type_dim = None if self.particle_type_cfg.target == "physical" else 0
+        # gitea #44: None under class_weighting = "none" (the default),
+        # matching F.cross_entropy's own unweighted default — a real tensor
+        # only materializes when the config asked for one.
+        self.type_class_weights = (
+            None if spec.type_class_weights is None else torch.tensor(spec.type_class_weights, device=device)
+        )
 
         self.params = list(self.model.parameters())
         self.optimizer = optim.AdamW(self.params, lr=spec.lr, weight_decay=spec.weight_decay)
@@ -472,7 +687,7 @@ class FlowDDPMStageTrainer(StageTrainer):
             warmup_steps=spec.warmup_epochs * spec.steps_per_epoch,
             total_steps=max(spec.epochs * spec.steps_per_epoch, 1),
         )
-        self.ddpm_schedule = CosineSchedule(T=spec.ddpm_n_steps).to(device) if spec.generator == "ddpm" else None
+        self.ddpm_schedule = self.objective.build_schedule(spec.ddpm_n_steps, device)
 
         self.train_metrics = [
             train_metric(key)
@@ -480,10 +695,12 @@ class FlowDDPMStageTrainer(StageTrainer):
                 "loss",
                 "loss_gen",
                 "loss_nsec",
+                "loss_stop",
                 "loss_balance",
                 "loss_proc",
                 "loss_entropy",
                 "nsec_acc",
+                "stop_acc",
                 "loss_type",
                 "type_acc",
                 "grad_norm",
@@ -496,6 +713,8 @@ class FlowDDPMStageTrainer(StageTrainer):
                 "loss_gen",
                 "loss_nsec",
                 "nsec_acc",
+                "loss_stop",
+                "stop_acc",
                 "loss_type",
                 "type_acc",
             )
@@ -504,26 +723,9 @@ class FlowDDPMStageTrainer(StageTrainer):
 
     def _generator_loss(self, cond_cont, cond_cat, x1_s1, x1_s2, sec_mask, stage1_ctx, ar_inputs=None):
         if not self.is_stage2:
-            if self.generator == "flow":
-                return flow_matching_loss(self.model, x1_s1, cond_cont, cond_cat)
-            assert self.ddpm_schedule is not None
-            return self.ddpm_schedule.loss(self.model, x1_s1, cond_cont, cond_cat)
-        if self.decoder == "autoregressive":
-            assert ar_inputs is not None
-            return flow_matching_loss_secondary_ar(
-                self.model,
-                x1_s2,
-                cond_cont,
-                cond_cat,
-                stage1_ctx,
-                ar_inputs["history_feat"],
-                ar_inputs["has_prev"],
-                ar_inputs["remaining_frac"],
-                ar_inputs["slot_idx"],
-                sec_mask,
-                type_dim=self._flow_type_dim,
-            )
-        return flow_matching_loss_secondary(
+            return self.objective.stage1_loss(self.model, x1_s1, cond_cont, cond_cat, schedule=self.ddpm_schedule)
+        assert self.decoder != "autoregressive" or ar_inputs is not None
+        return self.objective.stage2_loss(
             self.model,
             x1_s2,
             cond_cont,
@@ -531,6 +733,7 @@ class FlowDDPMStageTrainer(StageTrainer):
             stage1_ctx,
             sec_mask,
             type_dim=self._flow_type_dim,
+            ar_inputs=ar_inputs,
         )
 
     def _type_loss(
@@ -568,9 +771,13 @@ class FlowDDPMStageTrainer(StageTrainer):
             type_out = self.model.predict_type(cond_cont, cond_cat, stage1_ctx)
         mask = sec_mask.float()
         denom = mask.sum().clamp(min=1)
-        if self.particle_type_cfg.get("target") == "onehot":
-            ce = F.cross_entropy(type_out.transpose(1, 2), sec_type_idx, reduction="none")
+        if self.particle_type_cfg.target == "onehot":
+            ce = F.cross_entropy(
+                type_out.transpose(1, 2), sec_type_idx, weight=self.type_class_weights, reduction="none"
+            )
             l_type = (ce * mask).sum() / denom
+            # Unweighted, deliberately — type_acc is a diagnostic of raw
+            # per-slot correctness, not the (possibly class-weighted) loss.
             type_acc = ((type_out.argmax(-1) == sec_type_idx).float() * mask).sum() / denom
         else:  # "embedding"
             target_vec = self.model.cond_enc.pdg_emb(sec_type_idx).detach()
@@ -580,9 +787,10 @@ class FlowDDPMStageTrainer(StageTrainer):
 
     def _compute(self, batch: StepBatch, device: torch.device, epoch: int | None = None) -> dict:
         """`epoch=None` (the `val_loss` path) always uses full teacher
-        forcing (`p_tf=1.0`) regardless of `spec.teacher_forcing` — validation
-        should stay a stable, non-stochastic ground-truth comparison; only
-        the training `step` path schedules `p_tf` by epoch."""
+        forcing (`p_tf=1.0`) and the ground-truth stage-1 context, regardless
+        of `spec.teacher_forcing`/`spec.stage1_context` — validation should
+        stay a stable, non-stochastic ground-truth comparison; only the
+        training `step` path schedules `p_tf`/`p_truth` by epoch."""
         (
             cond_cont,
             cond_cat,
@@ -593,7 +801,7 @@ class FlowDDPMStageTrainer(StageTrainer):
             sec_type_idx,
         ) = _batch_to_device(batch, device)
         sec_mask = self._sec_mask(n_sec, sec_cont.size(1), device)
-        stage1_ctx = x1_s1.detach()
+        stage1_ctx = self._stage1_context(x1_s1, cond_cont, cond_cat, epoch)
 
         x1_s2 = None
         ar_inputs = None
@@ -605,6 +813,7 @@ class FlowDDPMStageTrainer(StageTrainer):
 
         l_gen = self._generator_loss(cond_cont, cond_cat, x1_s1, x1_s2, sec_mask, stage1_ctx, ar_inputs=ar_inputs)
         l_nsec, nsec_acc = self._n_sec_loss(cond_cont, cond_cat, stage1_ctx, n_sec, device)
+        l_stop, stop_acc = self._stop_loss(cond_cont, cond_cat, stage1_ctx, n_sec, device, ar_inputs)
 
         l_type, type_acc = self._type_loss(
             cond_cont,
@@ -625,7 +834,11 @@ class FlowDDPMStageTrainer(StageTrainer):
             if self.spec.lambda_entropy > 0:
                 l_entropy = self.router.entropy_loss(cond_cont, cond_cat)
 
-        total = self.spec.lambda_weight * l_gen + self.spec.n_sec_lambda * l_nsec + self.particle_type_lambda * l_type
+        total = (
+            self.spec.lambda_weight * l_gen
+            + self.spec.n_sec_lambda * (l_nsec + l_stop)
+            + self.particle_type_lambda * l_type
+        )
         if self.spec.lambda_balance > 0:
             total = total + self.spec.lambda_balance * l_balance
         if self.spec.lambda_proc > 0:
@@ -637,12 +850,14 @@ class FlowDDPMStageTrainer(StageTrainer):
             "loss": total,
             "loss_gen": l_gen,
             "loss_nsec": l_nsec,
+            "loss_stop": l_stop,
             "loss_type": l_type,
             "type_acc": type_acc,
             "loss_balance": l_balance,
             "loss_proc": l_proc,
             "loss_entropy": l_entropy,
             "nsec_acc": nsec_acc,
+            "stop_acc": stop_acc,
         }
 
     def step(self, batch: StepBatch, device: torch.device, global_step: int) -> dict:
@@ -654,10 +869,12 @@ class FlowDDPMStageTrainer(StageTrainer):
                 self.spec.gumbel_tau_end,
             )
         epoch = global_step // self.spec.steps_per_epoch
-        out = self._compute(batch, device, epoch=epoch)
+        with self._autocast():
+            out = self._compute(batch, device, epoch=epoch)
         grad_norm = self._step_optimizer(self.optimizer, out["loss"], self.params)
-        self.lr_sched.step()
-        if self.ema_model is not None:
+        if not self.frozen:
+            self.lr_sched.step()
+        if self.ema_model is not None and not self.frozen:
             _update_ema(self.ema_model, self.model, self.ema_decay)
         stats = {key: value.item() for key, value in out.items()}
         stats["grad_norm"] = grad_norm
@@ -742,10 +959,12 @@ class WGANStageTrainer(StageTrainer):
             "gp_loss",
             "loss_nsec",
             "nsec_acc",
+            "loss_stop",
+            "stop_acc",
             "grad_norm_d",
             "grad_norm_g",
         ]
-        if self.is_stage2 and self.particle_type_cfg.get("target") == "onehot":
+        if self.is_stage2 and self.particle_type_cfg.target == "onehot":
             # Differentiability instrumentation — only meaningful when the
             # type slice is a straight-through Gumbel relaxation.
             train_keys += ["grad_norm_type_slice", "grad_norm_cont_slice"]
@@ -754,11 +973,15 @@ class WGANStageTrainer(StageTrainer):
         self.stage_metrics = [stage_metric("lr"), stage_metric("critic_lr")]
 
     def _stage2_real_and_fake(self, batch_tensors: _Stage2RealFakeBatch, stage1_ctx, global_step, device):
-        """Build `(real, fake_raw, mask, critic_fn)` for stage 2, covering
-        both decoders and all three particle-type targets. `fake_raw` still
-        needs the caller's straight-through relaxation under
+        """Build `(real, fake_raw, mask, critic_fn, ar_inputs)` for stage 2,
+        covering both decoders and all three particle-type targets. `fake_raw`
+        still needs the caller's straight-through relaxation under
         `particle_type.target = "onehot"`, and neither tensor is masked-and-
-        multiplied on the fake side yet."""
+        multiplied on the fake side yet. `ar_inputs` is `None` under
+        `decoder = "one_shot"`; under `"autoregressive"` it's the same dict
+        `_ar_inputs` built to condition `self.model` above — returned so the
+        caller's `_stop_loss` reuses it instead of paying for a second
+        (possibly self-sampling) `_ar_inputs` call."""
         cond_cont, cond_cat, n_sec, sec_cont, sec_type_idx = batch_tensors
         B = cond_cont.size(0)
         type_dim = stage2_type_dim(self.particle_type_cfg, self.particle_type_n_classes)
@@ -771,27 +994,28 @@ class WGANStageTrainer(StageTrainer):
         def critic_fn(x):
             return self.critic(x, cond_cont, cond_cat, stage1_ctx)
 
+        ar_inputs = None
         if self.decoder == "autoregressive":
             epoch = global_step // self.spec.steps_per_epoch
-            ar = self._ar_inputs(cond_cont, cond_cat, stage1_ctx, sec_cont, sec_type_idx, n_sec, epoch)
-            real = self._sec_target(sec_cont, sec_type_idx, "wgan", flatten=False).reshape(B, -1) * mask
+            ar_inputs = self._ar_inputs(cond_cont, cond_cat, stage1_ctx, sec_cont, sec_type_idx, n_sec, epoch)
+            real = self._sec_target(sec_cont, sec_type_idx, self.generator, flatten=False).reshape(B, -1) * mask
             z = torch.randn(B, k_max, self.model.noise_dim, device=device)
             fake_raw = self.model(
                 z,
                 cond_cont,
                 cond_cat,
                 stage1_ctx,
-                ar["history_feat"],
-                ar["has_prev"],
-                ar["remaining_frac"],
-                ar["slot_idx"],
+                ar_inputs["history_feat"],
+                ar_inputs["has_prev"],
+                ar_inputs["remaining_frac"],
+                ar_inputs["slot_idx"],
             ).reshape(B, -1)
         else:
-            real = self._sec_target(sec_cont, sec_type_idx, "wgan", flatten=True) * mask
+            real = self._sec_target(sec_cont, sec_type_idx, self.generator, flatten=True) * mask
             z = torch.randn(B, self.model.noise_dim, device=device)
             fake_raw = self.model(z, cond_cont, cond_cat, stage1_ctx)
 
-        return real, fake_raw, mask, critic_fn
+        return real, fake_raw, mask, critic_fn, ar_inputs
 
     def step(self, batch: StepBatch, device: torch.device, global_step: int) -> dict:
         (
@@ -804,52 +1028,58 @@ class WGANStageTrainer(StageTrainer):
             sec_type_idx,
         ) = _batch_to_device(batch, device)
         B = cond_cont.size(0)
-        stage1_ctx = x1_s1.detach()
+        epoch = global_step // self.spec.steps_per_epoch
+        stage1_ctx = self._stage1_context(x1_s1, cond_cont, cond_cat, epoch)
         grad_probe: dict[str, float] = {}
 
-        if not self.is_stage2:
-            real = x1_s1
+        ar_inputs = None
+        with self._autocast():
+            if not self.is_stage2:
+                real = x1_s1
 
-            def critic_fn(x):
-                return self.critic(x, cond_cont, cond_cat)
+                def critic_fn(x):
+                    return self.critic(x, cond_cont, cond_cat)
 
-            z = torch.randn(B, self.model.noise_dim, device=device)
-            fake = self.model(z, cond_cont, cond_cat)
-            mask = None
-        else:
-            real, fake_raw, mask, critic_fn = self._stage2_real_and_fake(
-                _Stage2RealFakeBatch(cond_cont, cond_cat, n_sec, sec_cont, sec_type_idx),
-                stage1_ctx,
-                global_step,
-                device,
-            )
-            if self.particle_type_cfg.get("target", "physical") == "onehot":
-                # Straight-through Gumbel-softmax relaxation of the type
-                # slice only — the critic must see a hard one-hot forward
-                # (matching what "real" data looks like) while gradient
-                # still flows smoothly to the generator. grad_probe captures
-                # the gradient-magnitude instrumentation — see
-                # _relax_onehot_type_slice's docstring.
-                tau = _gumbel_tau(
+                z = torch.randn(B, self.model.noise_dim, device=device)
+                fake = self.model(z, cond_cont, cond_cat)
+                mask = None
+            else:
+                real, fake_raw, mask, critic_fn, ar_inputs = self._stage2_real_and_fake(
+                    _Stage2RealFakeBatch(cond_cont, cond_cat, n_sec, sec_cont, sec_type_idx),
+                    stage1_ctx,
                     global_step,
-                    self.total_steps,
-                    self.spec.type_gumbel_tau_start,
-                    self.spec.type_gumbel_tau_end,
+                    device,
                 )
-                fake_raw = _relax_onehot_type_slice(
-                    fake_raw,
-                    sec_cont.size(1),
-                    CONT_SLOT_DIM,
-                    stage2_type_dim(self.particle_type_cfg, self.particle_type_n_classes),
-                    tau,
-                    grad_probe=grad_probe,
-                )
-            fake = fake_raw * mask
+                if self.particle_type_cfg.target == "onehot":
+                    # Straight-through Gumbel-softmax relaxation of the type
+                    # slice only — the critic must see a hard one-hot forward
+                    # (matching what "real" data looks like) while gradient
+                    # still flows smoothly to the generator. grad_probe captures
+                    # the gradient-magnitude instrumentation — see
+                    # _relax_onehot_type_slice's docstring.
+                    tau = _gumbel_tau(
+                        global_step,
+                        self.total_steps,
+                        self.spec.type_gumbel_tau_start,
+                        self.spec.type_gumbel_tau_end,
+                    )
+                    fake_raw = _relax_onehot_type_slice(
+                        fake_raw,
+                        sec_cont.size(1),
+                        CONT_SLOT_DIM,
+                        stage2_type_dim(self.particle_type_cfg, self.particle_type_n_classes),
+                        tau,
+                        grad_probe=grad_probe,
+                    )
+                fake = fake_raw * mask
 
-        # --- critic step (every batch) ---
-        fake_detached = fake.detach()
-        real_score = critic_fn(real)
-        fake_score = critic_fn(fake_detached)
+            # --- critic step (every batch) ---
+            fake_detached = fake.detach()
+            real_score = critic_fn(real)
+            fake_score = critic_fn(fake_detached)
+
+        # gradient_penalty forces its own fp32 region internally (see its
+        # docstring) regardless of the ambient autocast above.
         gp = gradient_penalty(critic_fn, real, fake_detached, mask=mask)
         d_loss = fake_score.mean() - real_score.mean() + self.gp_weight * gp
         wasserstein = (real_score.mean() - fake_score.mean()).detach()
@@ -858,27 +1088,31 @@ class WGANStageTrainer(StageTrainer):
 
         # --- generator (+ n_sec) step ---
         did_g_step = global_step % self.n_critic == 0
-        l_nsec, nsec_acc = self._n_sec_loss(cond_cont, cond_cat, stage1_ctx, n_sec, device)
+        with self._autocast():
+            l_nsec, nsec_acc = self._n_sec_loss(cond_cont, cond_cat, stage1_ctx, n_sec, device)
+            l_stop, stop_acc = self._stop_loss(cond_cont, cond_cat, stage1_ctx, n_sec, device, ar_inputs)
 
-        # On a non-generator-step batch with no n_sec_head on this stage
-        # (n_sec now defaults to stage 2), there's nothing for
+        # On a non-generator-step batch with no n_sec_head/stop_head on this
+        # stage (n_sec now defaults to stage 2), there's nothing for
         # the generator optimizer to do this batch — g_loss would otherwise
         # be a graph-less zero tensor, which .backward() rejects outright.
-        skip_g_step = not did_g_step and self.model.n_sec_head is None
+        skip_g_step = not did_g_step and self.model.n_sec_head is None and self.model.stop_head is None
         if did_g_step:
-            g_loss_adv = generator_loss(critic_fn, fake)
-            g_loss = self.spec.lambda_weight * g_loss_adv + self.spec.n_sec_lambda * l_nsec
+            with self._autocast():
+                g_loss_adv = generator_loss(critic_fn, fake)
+            g_loss = self.spec.lambda_weight * g_loss_adv + self.spec.n_sec_lambda * (l_nsec + l_stop)
         else:
             g_loss_adv = torch.zeros((), device=device)
-            g_loss = self.spec.n_sec_lambda * l_nsec
+            g_loss = self.spec.n_sec_lambda * (l_nsec + l_stop)
         if skip_g_step:
             grad_norm_g = 0.0
         else:
             grad_norm_g = self._step_optimizer(self.optimizer, g_loss, self.g_params)
 
         if did_g_step:
-            self.lr_sched.step()
-            if self.ema_model is not None:
+            if not self.frozen:
+                self.lr_sched.step()
+            if self.ema_model is not None and not self.frozen:
                 _update_ema(self.ema_model, self.model, self.ema_decay)
 
         return {
@@ -888,6 +1122,8 @@ class WGANStageTrainer(StageTrainer):
             "gp_loss": gp.item(),
             "loss_nsec": l_nsec.item(),
             "nsec_acc": nsec_acc.item(),
+            "loss_stop": l_stop.item(),
+            "stop_acc": stop_acc.item(),
             "did_g_step": did_g_step,
             "grad_norm": grad_norm_d + grad_norm_g,
             "grad_norm_d": grad_norm_d,
@@ -948,16 +1184,28 @@ def build_stage_trainers(
     critics: dict[str, torch.nn.Module | None],
     device: torch.device,
     total_train_batches: int,
+    sec_type_class_counts: dict[int, int] | None = None,
 ) -> dict[str, StageTrainer]:
     """One trainer per active stage — `models[name] is None` means that stage
-    is `active = false` and is simply never constructed."""
+    is `active = false` and is simply never constructed.
+
+    `stage2_model.stage1_context = "sampled"` additionally wires the
+    stage-2 trainer to the stage-1 one (`StageTrainer.attach_stage1`) so it
+    can draw a real stage-1 sample instead of only ever seeing the
+    ground-truth stage-1 outcome — `validate_config` already guarantees both
+    stages are active whenever that config value is set.
+
+    `sec_type_class_counts` (`sec_type_topn_map.class_counts`, gitea #44) is
+    the one dataset-derived input `StageSpec.from_config` needs beyond `cfg`
+    — `None`/absent whenever `stage2_model.particle_type.class_weighting =
+    "none"` (the default), which never reads it."""
     trainers: dict[str, StageTrainer] = {}
     for name, is_stage2 in (("stage1", False), ("stage2", True)):
         model = models.get(name)
         if model is None:
             continue
-        spec = StageSpec.from_config(cfg, name, is_stage2, max(total_train_batches, 1))
-        if spec.generator == "wgan":
+        spec = StageSpec.from_config(cfg, name, is_stage2, max(total_train_batches, 1), sec_type_class_counts)
+        if build_objective(spec.generator).is_adversarial:
             critic = critics.get(name)
             assert critic is not None, (
                 f"{name}_model.generator='wgan' requires a critic (see giant.model.network.build_critics)"
@@ -965,4 +1213,9 @@ def build_stage_trainers(
             trainers[name] = WGANStageTrainer(spec, model, critic, device)
         else:
             trainers[name] = FlowDDPMStageTrainer(spec, model, device)
+
+    stage2 = trainers.get("stage2")
+    stage1 = trainers.get("stage1")
+    if stage2 is not None and stage1 is not None and stage2.spec.stage1_context == "sampled":
+        stage2.attach_stage1(stage1)
     return trainers

giant/validate.py

@@ -82,7 +82,7 @@ def validate_marginals(
     one-shot-vs-autoregressive-agnostic): n_sec
     distribution (+ classification accuracy), per-slot energy-fraction
     marginals, and a particle-type marginal whose shape depends on
-    `sec_decoder.particle_type_cfg["target"]` — restricted to each side's own
+    `sec_decoder.particle_type_cfg.target` — restricted to each side's own
     valid slots (real: `n_sec`; generated: the resolved `n_sec_pred`), since
     the two need not agree on how many slots are valid. Adds {"n_sec_real",
     "n_sec_pred", "n_sec_accuracy", "energy_fraction_kl"} plus, under
@@ -103,7 +103,7 @@ def validate_marginals(
         sec_decoder.eval()
 
     k_max = sec_decoder.k_max if sec_decoder is not None else 0
-    target = sec_decoder.particle_type_cfg.get("target", "physical") if sec_decoder is not None else "physical"
+    target = sec_decoder.particle_type_cfg.target if sec_decoder is not None else "physical"
 
     all_real, all_gen = [], []
     all_n_sec_real, all_n_sec_pred = [], []
@@ -129,10 +129,7 @@ def validate_marginals(
             continue
 
         n_sec_pred = resolve_n_sec(stage1_model, sec_decoder, cond_cont, cond_cat, gen, n_sec_pred)
-        n_sec_pred_np = n_sec_pred.cpu().numpy()
         n_sec_np = n_sec.numpy()
-        all_n_sec_real.append(n_sec_np)
-        all_n_sec_pred.append(n_sec_pred_np)
 
         real_valid = np.arange(k_max)[None, :] < n_sec_np[:, None]  # (B, k_max)
         real_frac = 1.0 / (1.0 + np.exp(-sec_cont[:, :, 0].numpy().astype(np.float64)))
@@ -140,6 +137,13 @@ def validate_marginals(
         sec_cont_pred, sec_type_pred, sec_valid_pred = sample_stage2(
             sec_decoder, cond_cont, cond_cat, gen, n_sec_pred, steps=steps
         )
+        # A stop-token decoder resolves n_sec_pred=None above — read the real
+        # count back off sec_valid_pred instead (a no-op round trip under
+        # every other n_sec.mode, where sec_valid_pred was built FROM
+        # n_sec_pred in the first place).
+        n_sec_pred_np = sec_valid_pred.sum(dim=-1).cpu().numpy()
+        all_n_sec_real.append(n_sec_np)
+        all_n_sec_pred.append(n_sec_pred_np)
         gen_frac = 1.0 / (1.0 + np.exp(-sec_cont_pred[:, :, 0].cpu().numpy().astype(np.float64)))
         gen_valid = sec_valid_pred.cpu().numpy()
 

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "giant"
-version = "0.3.0"
+version = "0.3.4"
 description = "Geant4 step-function surrogate via conditional flow matching"
 readme = "README.md"
 requires-python = ">=3.12"
@@ -26,6 +26,8 @@ dev = [
     "pytest-cov>=5,<8",
     "ruff>=0.15,<1",
     "ty>=0.0.50,<0.1",
+    "bump-my-version>=1.2,<2",
+    "git-cliff>=2,<3",
     "giant[convert,analysis,geometry,wandb]",
 ]
 geometry = [

tests/test_amp.py

@@ -0,0 +1,136 @@
+"""Tests for giant/training/amp.py (gitea #47)."""
+
+import tempfile
+from pathlib import Path
+
+import pytest
+import torch
+
+from giant.model.routers import EnergyRouter
+from giant.model.wgan import gradient_penalty
+from giant.training.amp import resolve_autocast
+from giant.training.stage2_inputs import _remaining_energy_fraction
+from test_train import _base_cfg, _run_train
+
+# ---------------------------------------------------------------------------
+# resolve_autocast
+# ---------------------------------------------------------------------------
+
+
+def test_resolve_autocast_fp32_is_disabled():
+    device_type, dtype, enabled = resolve_autocast("fp32", torch.device("cpu"))
+    assert device_type == "cpu"
+    assert dtype is torch.float32
+    assert enabled is False
+
+
+def test_resolve_autocast_bf16_on_cpu_is_enabled():
+    """CPU bf16 autocast is what lets the mixed-precision path be tested
+    without a GPU (torch 2.3 supports it)."""
+    device_type, dtype, enabled = resolve_autocast("bf16", torch.device("cpu"))
+    assert device_type == "cpu"
+    assert dtype is torch.bfloat16
+    assert enabled is True
+
+
+def test_resolve_autocast_bf16_on_unsupported_cuda_raises(monkeypatch):
+    monkeypatch.setattr(torch.cuda, "is_bf16_supported", lambda: False)
+    monkeypatch.setattr(torch.cuda, "get_device_capability", lambda device=None: (7, 0))
+    monkeypatch.setattr(torch.cuda, "get_device_name", lambda device=None: "Tesla V100")
+    with pytest.raises(ValueError, match="bf16"):
+        resolve_autocast("bf16", torch.device("cuda"))
+
+
+def test_resolve_autocast_bf16_on_mps_raises():
+    with pytest.raises(ValueError, match="bf16"):
+        resolve_autocast("bf16", torch.device("mps"))
+
+
+def test_resolve_autocast_unknown_precision_raises():
+    with pytest.raises(ValueError, match="fp32.*bf16"):
+        resolve_autocast("fp16", torch.device("cpu"))
+
+
+# ---------------------------------------------------------------------------
+# End-to-end: train() under bf16 on CPU
+# ---------------------------------------------------------------------------
+
+
+def test_train_end_to_end_bf16_cpu_completes_and_stores_fp32_params():
+    """Reuses tests/test_train.py's synthetic-batch harness — train() itself
+    is device-agnostic, and CPU bf16 autocast is real (not mocked) in torch
+    2.3, so this is a genuine exercise of the autocast region added to
+    FlowDDPMStageTrainer.step/WGANStageTrainer.step, not just a config
+    passthrough check.
+
+    Also asserts the checkpoint's stored parameters are fp32: autocast only
+    changes the dtype of intermediate activations, never the model's own
+    stored weights — a regression here would mean something accidentally
+    cast the model itself (e.g. `model.to(dtype=torch.bfloat16)`) rather than
+    using autocast."""
+    cfg = _base_cfg()
+    cfg["train"]["precision"] = "bf16"
+    with tempfile.TemporaryDirectory() as tmp:
+        out_dir = Path(tmp) / "run"
+        _run_train(cfg, out_dir)
+        assert (out_dir / "last.pt").exists()
+        assert (out_dir / "metrics.csv").exists()
+        ckpt = torch.load(out_dir / "last.pt", weights_only=False)
+        for stage_key in ("model", "sec_decoder"):
+            if stage_key not in ckpt:
+                continue
+            for name, tensor in ckpt[stage_key].items():
+                if tensor.is_floating_point():
+                    assert tensor.dtype == torch.float32, f"{stage_key}.{name} is {tensor.dtype}, expected fp32"
+
+
+@pytest.mark.parametrize("generator", ["wgan", "flow"])
+def test_train_end_to_end_bf16_cpu_stage2_generators(generator):
+    """bf16 covers both trainer subclasses (FlowDDPMStageTrainer and
+    WGANStageTrainer) — the wgan default in _base_cfg exercises the
+    generator-forward/critic-scoring autocast region added to
+    WGANStageTrainer.step, and flow exercises the plain _compute wrap."""
+    cfg = _base_cfg()
+    cfg["train"]["precision"] = "bf16"
+    cfg["stage2_model"]["generator"] = generator
+    with tempfile.TemporaryDirectory() as tmp:
+        _run_train(cfg, Path(tmp) / "run")
+
+
+# ---------------------------------------------------------------------------
+# fp32 guards: correct in fp32, quietly degrade in bf16 — stay fp32 even
+# under an active bf16 autocast region.
+# ---------------------------------------------------------------------------
+
+
+def test_remaining_energy_fraction_stays_fp32_under_bf16_autocast():
+    fraction = torch.rand(4, 5).to(torch.bfloat16)
+    with torch.autocast("cpu", dtype=torch.bfloat16, enabled=True):
+        out = _remaining_energy_fraction(fraction)
+    assert out.dtype == torch.float32
+
+
+def test_gradient_penalty_stays_fp32_under_bf16_autocast():
+    critic = torch.nn.Linear(6, 1)
+
+    def critic_fn(x):
+        return critic(x)
+
+    real = torch.randn(4, 6)
+    fake = torch.randn(4, 6)
+    with torch.autocast("cpu", dtype=torch.bfloat16, enabled=True):
+        gp = gradient_penalty(critic_fn, real, fake)
+    assert gp.dtype == torch.float32
+
+
+def test_router_balance_and_entropy_loss_stay_fp32_under_bf16_autocast():
+    router = EnergyRouter(n_experts=3)
+    cond_cont = torch.randn(8, 15)
+    cond_cat = torch.zeros(8, 2, dtype=torch.long)
+    with torch.autocast("cpu", dtype=torch.bfloat16, enabled=True):
+        balance = router.balance_loss(cond_cont, cond_cat)
+        entropy = router.entropy_loss(cond_cont, cond_cat)
+        weights = router.combine_weights(cond_cont, cond_cat)
+    assert balance.dtype == torch.float32
+    assert entropy.dtype == torch.float32
+    assert weights.dtype == torch.float32

tests/test_analysis_reduce.py

@@ -10,9 +10,11 @@ from giant.analysis import reduce as R
 from giant.analysis.sources import (
     SYNTHETIC_TERMINATION_REASONS,
     Side,
+    open_side,
     physical_steps,
     secondaries,
 )
+from giant.data.loader import EVENT_ID_FILE_STRIDE
 
 
 def _rollout_frame() -> pl.LazyFrame:
@@ -102,6 +104,31 @@ def test_hist1d_overall_and_grouped():
     assert hg[11].sum() == 4
 
 
+def test_hist1d_clamps_extreme_values_and_drops_nan():
+    # A rollout can emit a wildly out-of-range step_length (or an inf/NaN); the
+    # fixed-edge binning must clamp rather than overflow the i32 bin cast.
+    lf = pl.DataFrame({"x": [5.0, 1.0725e10, float("inf"), -float("inf"), float("nan"), None]}).lazy()
+    edges = np.linspace(0.0, 50.0, 6)  # width 10
+    h = R.hist1d(lf, pl.col("x"), edges)
+    # 5 -> bin 0; 1e10 and +inf -> top bin; -inf -> bin 0; NaN/null dropped
+    assert h[0].tolist() == [2, 0, 0, 0, 2]
+
+
+def test_profile_partial_clamps_extreme_values_and_drops_nan():
+    lf = pl.DataFrame(
+        {
+            "event_id": [1, 1, 1, 1],
+            "z": [5.0, 1.0725e10, float("nan"), 45.0],
+            "w": [1.0, 2.0, 4.0, 8.0],
+        }
+    ).lazy()
+    edges = np.linspace(0.0, 50.0, 6)
+    ev, mat = R.profile_partial(lf, pl.col("z"), edges, pl.col("w"))
+    assert ev.tolist() == [1]
+    # 1e10 clamps into the top bin alongside 45; the NaN row's weight is dropped
+    assert mat[0].tolist() == [1.0, 0.0, 0.0, 0.0, 10.0]
+
+
 def test_physical_steps_drops_synthetic_rollout_rows_only():
     lf = _rollout_frame()
     phys = physical_steps(lf, Side.rollout).collect()
@@ -169,3 +196,35 @@ def test_pdg_and_material_labels():
     assert G.pdg_label(22) == "gamma"
     assert G.pdg_label(999999) == "999999"
     assert G.material_label("G4_PbWO4") == "PbWO4"
+
+
+def _write_shard(path, event_ids, edeps):
+    pl.DataFrame({"event_id": event_ids, "pdg": [11] * len(event_ids), "edep": edeps}).write_parquet(path)
+
+
+def test_open_side_reference_offsets_event_ids_across_shards(tmp_path):
+    # Each shard is a separate Geant4 job whose own event_id numbering restarts
+    # from 0 — a naive multi-shard scan collides on event_id across shards.
+    _write_shard(tmp_path / "a.parquet", [0, 1], [1.0, 2.0])
+    _write_shard(tmp_path / "b.parquet", [0, 1], [3.0, 4.0])
+    df = open_side(tmp_path, Side.reference).sort("event_id").collect()
+    assert df["event_id"].to_list() == [0, 1, EVENT_ID_FILE_STRIDE, EVENT_ID_FILE_STRIDE + 1]
+    assert df["edep"].to_list() == [1.0, 2.0, 3.0, 4.0]
+    assert "__source_path" not in df.columns
+
+
+def test_open_side_reference_single_file_unchanged(tmp_path):
+    _write_shard(tmp_path / "only.parquet", [0, 1], [1.0, 2.0])
+    df = open_side(tmp_path / "only.parquet", Side.reference).sort("event_id").collect()
+    assert df["event_id"].to_list() == [0, 1]
+    assert "__source_path" not in df.columns
+
+
+def test_open_side_reference_manifest(tmp_path):
+    _write_shard(tmp_path / "a.parquet", [0, 1], [1.0, 2.0])
+    _write_shard(tmp_path / "b.parquet", [0, 1], [3.0, 4.0])
+    manifest = tmp_path / "shards.manifest"
+    manifest.write_text("a.parquet\nb.parquet\n")
+    df = open_side(manifest, Side.reference).sort("event_id").collect()
+    assert df["event_id"].to_list() == [0, 1, EVENT_ID_FILE_STRIDE, EVENT_ID_FILE_STRIDE + 1]
+    assert df["edep"].to_list() == [1.0, 2.0, 3.0, 4.0]

tests/test_cli_new_run.py

@@ -91,6 +91,31 @@ def test_dry_run_writes_nothing(tmp_path: Path):
     assert not out_dir.exists()
 
 
+def test_stage1_init_from_and_freeze_flags_scaffold_a_partial_retrain_config(tmp_path: Path):
+    """gitea #42."""
+    out_dir = tmp_path / "run5"
+    result = runner.invoke(
+        app,
+        [
+            "new-run",
+            "--out",
+            str(out_dir),
+            "--stage1-init-from",
+            "ckpt/stage1_good/best.pt",
+            "--stage1-freeze",
+        ],
+    )
+    assert result.exit_code == 0, result.output
+
+    with open(out_dir / "config.toml", "rb") as f:
+        cfg = tomllib.load(f)
+
+    assert cfg["stage1_model"]["init_from"] == "ckpt/stage1_good/best.pt"
+    assert cfg["stage1_model"]["freeze"] is True
+    assert cfg["stage2_model"]["init_from"] == ""
+    assert cfg["stage2_model"]["freeze"] is False
+
+
 def test_force_guard_refuses_to_clobber_existing_checkpoints(tmp_path: Path):
     out_dir = tmp_path / "run5"
     out_dir.mkdir()

tests/test_cli_train_overrides.py

@@ -97,6 +97,33 @@ def test_wgan_knobs_split_per_stage(monkeypatch, tmp_path):
     assert cfg["stage2_model"]["wgan"]["gp_weight"] == 2.5
 
 
+def test_stage1_init_from_and_freeze_flags_land_in_cfg_and_dont_touch_stage2(monkeypatch, tmp_path):
+    """gitea #42: --stage{1,2}-init-from/--stage{1,2}-freeze are stage-scoped
+    only. --stage1-freeze alone would fail validate_config (freeze requires
+    init_from or --resume), so both flags are passed together here."""
+    cfg = _invoke_and_capture_cfg(
+        monkeypatch,
+        tmp_path,
+        ["--stage1-init-from", "ckpt/stage1_good/best.pt", "--stage1-freeze"],
+    )
+    assert cfg["stage1_model"]["init_from"] == "ckpt/stage1_good/best.pt"
+    assert cfg["stage1_model"]["freeze"] is True
+    assert cfg["stage2_model"]["init_from"] == ""
+    assert cfg["stage2_model"]["freeze"] is False
+
+
+def test_stage2_init_from_and_freeze_flags_land_in_cfg_and_dont_touch_stage1(monkeypatch, tmp_path):
+    cfg = _invoke_and_capture_cfg(
+        monkeypatch,
+        tmp_path,
+        ["--stage2-init-from", "ckpt/stage2_good/best.pt", "--stage2-freeze"],
+    )
+    assert cfg["stage2_model"]["init_from"] == "ckpt/stage2_good/best.pt"
+    assert cfg["stage2_model"]["freeze"] is True
+    assert cfg["stage1_model"]["init_from"] == ""
+    assert cfg["stage1_model"]["freeze"] is False
+
+
 def test_batch_size_invalid_string_errors(monkeypatch, tmp_path):
     monkeypatch.setattr(cli, "run_train_job", lambda *a, **kw: None)
     result = runner.invoke(

tests/test_cond_layout.py

@@ -0,0 +1,87 @@
+import pytest
+from giant.cond_layout import AXIS_TYPES, CondLayout
+from giant.constants import COND_DIM, COND_DIM_BASE, MATERIAL_PHYS_DIM, PARTICLE_PHYS_DIM
+
+# ── cond_cat column layout ───────────────────────────────────────────────────
+
+
+def test_topn_cols_neither_onehot():
+    layout = CondLayout.from_types("physical", "embedding")
+    assert (layout.particle_topn_col, layout.material_topn_col) == (None, None)
+    assert layout.cat_dim == 2
+
+
+def test_topn_cols_particle_only():
+    layout = CondLayout.from_types("onehot", "physical")
+    assert (layout.particle_topn_col, layout.material_topn_col) == (2, None)
+    assert layout.cat_dim == 3
+
+
+def test_topn_cols_material_only():
+    layout = CondLayout.from_types("physical", "onehot")
+    assert (layout.particle_topn_col, layout.material_topn_col) == (None, 2)
+    assert layout.cat_dim == 3
+
+
+def test_topn_cols_both_onehot_particle_then_material():
+    layout = CondLayout.from_types("onehot", "onehot")
+    assert (layout.particle_topn_col, layout.material_topn_col) == (2, 3)
+    assert layout.cat_dim == 4
+
+
+def test_dense_vocab_cols_are_mode_independent():
+    """Columns 0/1 are always the dense pdg/material index — giant.model.routers
+    reads them without knowing the conditioning mode."""
+    assert (CondLayout.PDG_COL, CondLayout.MAT_COL) == (0, 1)
+    for particle in AXIS_TYPES:
+        for material in AXIS_TYPES:
+            layout = CondLayout.from_types(particle, material)
+            assert layout.particle_topn_col not in (layout.PDG_COL, layout.MAT_COL)
+            assert layout.material_topn_col not in (layout.PDG_COL, layout.MAT_COL)
+
+
+# ── cond_cont slice layout ───────────────────────────────────────────────────
+
+
+def test_cont_slices_tile_cond_cont_exactly():
+    """base / particle_phys / material_phys must partition cond_cont with no
+    gap and no overlap — a gap or overlap is exactly the silent
+    mis-indexing this object exists to prevent."""
+    layout = CondLayout.from_types("physical", "physical")
+    covered = list(range(*layout.base.indices(COND_DIM)))
+    covered += list(range(*layout.particle_phys.indices(COND_DIM)))
+    covered += list(range(*layout.material_phys.indices(COND_DIM)))
+    assert covered == list(range(COND_DIM))
+
+
+def test_cont_slice_widths_match_constants():
+    layout = CondLayout.from_types("embedding", "embedding")
+    assert layout.base == slice(0, COND_DIM_BASE)
+    assert layout.particle_phys.stop - layout.particle_phys.start == PARTICLE_PHYS_DIM
+    assert layout.material_phys.stop - layout.material_phys.start == MATERIAL_PHYS_DIM
+    assert layout.cont_dim == COND_DIM
+
+
+def test_cont_slices_are_mode_independent():
+    """cond_cont is COND_DIM wide in every mode — a non-"physical" axis gets
+    its block zero-filled rather than dropped, so the slices never move."""
+    physical = CondLayout.from_types("physical", "physical")
+    for particle in AXIS_TYPES:
+        for material in AXIS_TYPES:
+            layout = CondLayout.from_types(particle, material)
+            assert layout.base == physical.base
+            assert layout.particle_phys == physical.particle_phys
+            assert layout.material_phys == physical.material_phys
+
+
+# ── validation ───────────────────────────────────────────────────────────────
+
+
+def test_unknown_particle_type_raises():
+    with pytest.raises(ValueError, match="unknown conditioning.particle.type 'bogus'"):
+        CondLayout.from_types("bogus", "physical")
+
+
+def test_unknown_material_type_raises():
+    with pytest.raises(ValueError, match="unknown conditioning.material.type 'bogus'"):
+        CondLayout.from_types("physical", "bogus")

tests/test_config.py

@@ -51,9 +51,13 @@ def test_giant_config_to_dict_matches_default_config():
         gconfig.Stage2WganConfig,
         gconfig.RouterConfig,
         gconfig.Stage2RouterConfig,
+        gconfig.TrunkConfig,
         gconfig.NSecConfig,
         gconfig.ParticleTypeConfig,
         gconfig.AutoregressiveConfig,
+        gconfig.HeadConfig,
+        gconfig.Stage1HeadsConfig,
+        gconfig.Stage2HeadsConfig,
         gconfig.Stage1ModelConfig,
         gconfig.Stage2ModelConfig,
         gconfig.TrainConfig,
@@ -75,6 +79,52 @@ def test_stage2_model_config_defaults_match_documented_v030_intent():
     assert spec.particle_type.target == "onehot"
 
 
+def test_trunk_config_defaults_to_resmlp_for_both_stages():
+    """gitea #33: a v0.2-migrated / pre-existing config with no `trunk` key
+    at all must reproduce today's behaviour exactly."""
+    assert gconfig.Stage1ModelConfig().trunk.type == "resmlp"
+    assert gconfig.Stage2ModelConfig().trunk.type == "resmlp"
+    assert gconfig.DEFAULT_CONFIG["stage1_model"]["trunk"]["type"] == "resmlp"
+    assert gconfig.DEFAULT_CONFIG["stage2_model"]["trunk"]["type"] == "resmlp"
+
+
+def test_trunk_config_defaults_block_conditioning_to_add_for_both_stages():
+    """gitea #34: a pre-existing config with no `block_conditioning` key
+    must reproduce today's additive-bias behaviour exactly."""
+    assert gconfig.Stage1ModelConfig().trunk.block_conditioning == "add"
+    assert gconfig.Stage2ModelConfig().trunk.block_conditioning == "add"
+    assert gconfig.DEFAULT_CONFIG["stage1_model"]["trunk"]["block_conditioning"] == "add"
+    assert gconfig.DEFAULT_CONFIG["stage2_model"]["trunk"]["block_conditioning"] == "add"
+
+
+def test_init_from_freeze_default_to_unset_for_both_stages():
+    """gitea #42: a pre-existing config with no init_from/freeze key must
+    reproduce today's from-scratch, always-training behaviour exactly."""
+    assert gconfig.Stage1ModelConfig().init_from == ""
+    assert gconfig.Stage1ModelConfig().freeze is False
+    assert gconfig.Stage2ModelConfig().init_from == ""
+    assert gconfig.Stage2ModelConfig().freeze is False
+    assert gconfig.DEFAULT_CONFIG["stage1_model"]["init_from"] == ""
+    assert gconfig.DEFAULT_CONFIG["stage1_model"]["freeze"] is False
+    assert gconfig.DEFAULT_CONFIG["stage2_model"]["init_from"] == ""
+    assert gconfig.DEFAULT_CONFIG["stage2_model"]["freeze"] is False
+
+
+def test_heads_config_defaults_reproduce_pre_gitea_36_hardcoded_shape():
+    """gitea #36: a pre-existing config with no `heads` key must reproduce
+    today's hardcoded `hidden_dim // 2`, one-hidden-layer architecture
+    exactly."""
+    assert gconfig.Stage1ModelConfig().heads.n_sec.hidden_ratio == 0.5
+    assert gconfig.Stage1ModelConfig().heads.n_sec.depth == 2
+    assert gconfig.Stage2ModelConfig().heads.n_sec.hidden_ratio == 0.5
+    assert gconfig.Stage2ModelConfig().heads.n_sec.depth == 2
+    assert gconfig.Stage2ModelConfig().heads.type.hidden_ratio == 0.5
+    assert gconfig.Stage2ModelConfig().heads.type.depth == 2
+    assert gconfig.DEFAULT_CONFIG["stage1_model"]["heads"]["n_sec"] == {"hidden_ratio": 0.5, "depth": 2}
+    assert gconfig.DEFAULT_CONFIG["stage2_model"]["heads"]["n_sec"] == {"hidden_ratio": 0.5, "depth": 2}
+    assert gconfig.DEFAULT_CONFIG["stage2_model"]["heads"]["type"] == {"hidden_ratio": 0.5, "depth": 2}
+
+
 def test_particle_type_config_n_classes_defaults_to_zero_and_round_trips():
     """gitea #29: n_classes=0 means "inherit conditioning.particle.emb_dim"
     — the default must stay 0 so an existing config.toml with no
@@ -82,7 +132,15 @@ def test_particle_type_config_n_classes_defaults_to_zero_and_round_trips():
     assert gconfig.ParticleTypeConfig().n_classes == 0
     spec = gconfig.ParticleTypeConfig.from_dict({"n_classes": 32})
     assert spec.n_classes == 32
-    assert spec.to_dict()["n_classes"] == 32
+
+
+def test_particle_type_config_class_weighting_defaults_to_none_and_round_trips():
+    """gitea #44: an existing config.toml with no
+    stage2_model.particle_type.class_weighting key must reproduce the
+    pre-#44 unweighted-CE behavior exactly."""
+    assert gconfig.ParticleTypeConfig().class_weighting == "none"
+    spec = gconfig.ParticleTypeConfig.from_dict({"class_weighting": "inverse_freq"})
+    assert spec.class_weighting == "inverse_freq"
 
 
 def test_router_config_extra_round_trips_composed_axis_keys():
@@ -113,7 +171,17 @@ def test_n_sec_config_owner_defaults_to_stage2():
 def test_n_sec_config_owner_round_trips():
     n_sec = gconfig.NSecConfig.from_dict({"mode": "head", "owner": "stage1"})
     assert n_sec.owner == "stage1"
-    assert n_sec.to_dict() == {"mode": "head", "lambda": 0.1, "owner": "stage1"}
+    assert n_sec.to_dict() == {"mode": "head", "lambda": 0.1, "owner": "stage1", "stop_sampling": "greedy"}
+
+
+def test_n_sec_config_stop_sampling_defaults_to_greedy():
+    assert gconfig.NSecConfig().stop_sampling == "greedy"
+
+
+def test_n_sec_config_stop_sampling_round_trips():
+    n_sec = gconfig.NSecConfig.from_dict({"mode": "stop_token", "stop_sampling": "sample"})
+    assert n_sec.stop_sampling == "sample"
+    assert n_sec.to_dict()["stop_sampling"] == "sample"
 
 
 # ---------------------------------------------------------------------------
@@ -644,6 +712,42 @@ def test_validate_config_embedding_target_passes_with_embedding_conditioning():
     gconfig.validate_config(cfg)  # must not raise
 
 
+def test_validate_config_bad_class_weighting_rejected():
+    cfg = _cfg_with(**{"stage2_model.particle_type.class_weighting": "effective_num"})
+    with pytest.raises(ValueError, match="class_weighting"):
+        gconfig.validate_config(cfg)
+
+
+def test_validate_config_class_weighting_requires_onehot_target():
+    cfg = _cfg_with(
+        **{
+            "stage2_model.particle_type.class_weighting": "inverse_freq",
+            "stage2_model.particle_type.target": "physical",
+        }
+    )
+    with pytest.raises(ValueError, match="onehot"):
+        gconfig.validate_config(cfg)
+
+
+def test_validate_config_class_weighting_incompatible_with_wgan_generator():
+    # stage2_model.generator defaults to "wgan" and particle_type.target
+    # defaults to "onehot", so only class_weighting needs overriding here.
+    cfg = _cfg_with(**{"stage2_model.particle_type.class_weighting": "inverse_freq"})
+    with pytest.raises(ValueError, match="wgan"):
+        gconfig.validate_config(cfg)
+
+
+def test_validate_config_class_weighting_passes_with_onehot_and_flow():
+    cfg = _cfg_with(
+        **{
+            "stage2_model.particle_type.class_weighting": "inverse_freq",
+            "stage2_model.particle_type.target": "onehot",
+            "stage2_model.generator": "flow",
+        }
+    )
+    gconfig.validate_config(cfg)  # must not raise
+
+
 def test_validate_config_mixed_particle_material_conditioning_is_valid():
     """The particle and material conditioning axes are configured
     independently and may mix freely — e.g. material
@@ -688,22 +792,166 @@ def test_validate_config_tie_to_stage1_requires_stage1_active():
         assert "tie_to_stage1" in str(e)
 
 
-def test_validate_config_stop_token_not_implemented():
+@pytest.mark.parametrize("stage_name", ["stage1_model", "stage2_model"])
+def test_validate_config_freeze_without_init_from_or_resume_rejected(stage_name):
+    cfg = _cfg_with(**{f"{stage_name}.freeze": True})
+    try:
+        gconfig.validate_config(cfg)
+        assert False, "expected ValueError"
+    except ValueError as e:
+        assert "init_from" in str(e)
+        assert "--resume" in str(e)
+
+
+@pytest.mark.parametrize("stage_name", ["stage1_model", "stage2_model"])
+def test_validate_config_freeze_with_init_from_passes(stage_name):
+    cfg = _cfg_with(**{f"{stage_name}.freeze": True, f"{stage_name}.init_from": "ckpt/best.pt"})
+    gconfig.validate_config(cfg)  # must not raise
+
+
+@pytest.mark.parametrize("stage_name", ["stage1_model", "stage2_model"])
+def test_validate_config_freeze_without_init_from_passes_under_resume(stage_name):
+    cfg = _cfg_with(**{f"{stage_name}.freeze": True})
+    gconfig.validate_config(cfg, resume=True)  # must not raise
+
+
+def test_validate_config_stop_token_accepted_under_autoregressive():
+    """DEFAULT_CONFIG's stage2_model.decoder is already "autoregressive"
+    (see test_stage2_model_config_defaults_match_documented_v030_intent), so
+    mode="stop_token" alone must not raise."""
     cfg = _cfg_with(**{"stage2_model.n_sec.mode": "stop_token"})
+    gconfig.validate_config(cfg)  # must not raise
+
+
+def test_validate_config_stop_token_rejected_under_one_shot():
+    cfg = _cfg_with(
+        **{
+            "stage2_model.n_sec.mode": "stop_token",
+            "stage2_model.decoder": "one_shot",
+        }
+    )
     try:
         gconfig.validate_config(cfg)
         assert False, "expected ValueError"
     except ValueError as e:
-        assert "stop_token" in str(e)
+        assert "stop_token" in str(e) and "autoregressive" in str(e)
 
 
-def test_validate_config_stage1_context_sampled_not_implemented():
+def test_validate_config_stop_token_rejected_for_stage1_owner():
+    cfg = _cfg_with(
+        **{
+            "stage2_model.n_sec.mode": "stop_token",
+            "stage2_model.n_sec.owner": "stage1",
+        }
+    )
+    try:
+        gconfig.validate_config(cfg)
+        assert False, "expected ValueError"
+    except ValueError as e:
+        assert "stop_token" in str(e) and "owner" in str(e)
+
+
+def test_validate_config_bad_stop_sampling_rejected():
+    cfg = _cfg_with(**{"stage2_model.n_sec.stop_sampling": "bogus"})
+    try:
+        gconfig.validate_config(cfg)
+        assert False, "expected ValueError"
+    except ValueError as e:
+        assert "stop_sampling" in str(e)
+
+
+def test_validate_config_default_precision_is_fp32():
+    assert gconfig.DEFAULT_CONFIG["train"]["precision"] == "fp32"
+
+
+def test_validate_config_bf16_precision_accepted():
+    cfg = _cfg_with(**{"train.precision": "bf16"})
+    gconfig.validate_config(cfg)  # no raise
+
+
+@pytest.mark.parametrize("bad", ["fp16", "bogus", ""])
+def test_validate_config_bad_precision_rejected(bad):
+    cfg = _cfg_with(**{"train.precision": bad})
+    try:
+        gconfig.validate_config(cfg)
+        assert False, "expected ValueError"
+    except ValueError as e:
+        assert "precision" in str(e)
+
+
+def test_validate_config_stage1_context_sampled_accepted_with_both_stages_active():
+    """gitea #41: 'sampled' is now implemented, so DEFAULT_CONFIG's
+    stage1_model/stage2_model.active = true (both) must let it through."""
     cfg = _cfg_with(**{"stage2_model.stage1_context": "sampled"})
+    gconfig.validate_config(cfg)  # must not raise
+
+
+def test_validate_config_bad_stage1_context_rejected():
+    cfg = _cfg_with(**{"stage2_model.stage1_context": "bogus"})
     try:
         gconfig.validate_config(cfg)
         assert False, "expected ValueError"
     except ValueError as e:
-        assert "sampled" in str(e)
+        assert "stage1_context" in str(e)
+
+
+def test_validate_config_stage1_context_sampled_requires_stage1_active():
+    cfg = _cfg_with(
+        **{
+            "stage2_model.stage1_context": "sampled",
+            "stage1_model.active": False,
+        }
+    )
+    try:
+        gconfig.validate_config(cfg)
+        assert False, "expected ValueError"
+    except ValueError as e:
+        assert "sampled" in str(e) and "stage1_model.active" in str(e)
+
+
+def test_validate_config_stage1_context_sampled_requires_stage2_active():
+    cfg = _cfg_with(
+        **{
+            "stage2_model.stage1_context": "sampled",
+            "stage2_model.active": False,
+        }
+    )
+    try:
+        gconfig.validate_config(cfg)
+        assert False, "expected ValueError"
+    except ValueError as e:
+        assert "sampled" in str(e) and "stage2_model.active" in str(e)
+
+
+@pytest.mark.parametrize("key", ["ctx_p_start", "ctx_p_end"])
+@pytest.mark.parametrize("value", [-0.1, 1.1])
+def test_validate_config_ctx_p_out_of_range_rejected(key, value):
+    cfg = _cfg_with(
+        **{
+            "stage2_model.stage1_context": "sampled",
+            f"stage2_model.{key}": value,
+        }
+    )
+    try:
+        gconfig.validate_config(cfg)
+        assert False, "expected ValueError"
+    except ValueError as e:
+        assert key in str(e)
+
+
+def test_validate_config_stage1_context_sampled_always_truth_rejected_as_noop():
+    cfg = _cfg_with(
+        **{
+            "stage2_model.stage1_context": "sampled",
+            "stage2_model.ctx_p_start": 1.0,
+            "stage2_model.ctx_p_end": 1.0,
+        }
+    )
+    try:
+        gconfig.validate_config(cfg)
+        assert False, "expected ValueError"
+    except ValueError as e:
+        assert "ctx_p_start" in str(e) and "ctx_p_end" in str(e)
 
 
 def test_validate_config_n_sec_truth_rejected_for_rollout_capable_checkpoint():
@@ -911,6 +1159,41 @@ def test_validate_config_keys_skips_meta_section():
     gconfig.validate_config_keys(cfg)  # must not raise
 
 
+def test_validate_config_keys_allows_trunk_type():
+    cfg = _cfg_with(**{"stage1_model.trunk.type": "resmlp", "stage2_model.trunk.type": "resmlp"})
+    gconfig.validate_config_keys(cfg)  # must not raise
+
+
+def test_validate_config_keys_rejects_unknown_trunk_key():
+    cfg = _cfg_with(**{"stage1_model.trunk.type_o": "resmlp"})  # typo for type
+    try:
+        gconfig.validate_config_keys(cfg)
+        assert False, "expected ValueError"
+    except ValueError as e:
+        assert "stage1_model.trunk.type_o" in str(e)
+        assert "type" in str(e)
+
+
+def test_validate_config_keys_allows_block_conditioning():
+    cfg = _cfg_with(
+        **{
+            "stage1_model.trunk.block_conditioning": "film",
+            "stage2_model.trunk.block_conditioning": "adaln",
+        }
+    )
+    gconfig.validate_config_keys(cfg)  # must not raise
+
+
+def test_validate_config_keys_rejects_unknown_block_conditioning_key():
+    cfg = _cfg_with(**{"stage1_model.trunk.block_conditioning_o": "film"})  # typo
+    try:
+        gconfig.validate_config_keys(cfg)
+        assert False, "expected ValueError"
+    except ValueError as e:
+        assert "stage1_model.trunk.block_conditioning_o" in str(e)
+        assert "block_conditioning" in str(e)
+
+
 def test_merge_cli_overrides_rejects_typo_in_toml_file(tmp_path):
     path = tmp_path / "config.toml"
     path.write_text("[meta]\nconfig_version = 3\n\n[stage1_model]\nn_res_block = 12\n")
@@ -957,6 +1240,11 @@ def test_overrides_from_flags_train_block_passthrough():
     assert overrides == {"train": {"epochs": 5, "lr": 1e-3}}
 
 
+def test_overrides_from_flags_precision_passthrough():
+    overrides = gconfig.overrides_from_flags({"precision": "bf16"})
+    assert overrides == {"train": {"precision": "bf16"}}
+
+
 @pytest.mark.parametrize(
     ("shorthand", "explicit", "path_key"),
     [
@@ -1075,6 +1363,21 @@ def test_overrides_from_flags_critic_sizing_is_stage_scoped_only(stage_flag, sta
     assert overrides == {stage_model: {"wgan": {path_key: 32}}}
 
 
+@pytest.mark.parametrize(
+    ("init_from_flag", "freeze_flag", "stage_model"),
+    [
+        ("stage1_init_from", "stage1_freeze", "stage1_model"),
+        ("stage2_init_from", "stage2_freeze", "stage2_model"),
+    ],
+)
+def test_overrides_from_flags_init_from_freeze_is_stage_scoped_only(init_from_flag, freeze_flag, stage_model):
+    """gitea #42: no shared alias — a checkpoint has one set of weights per
+    stage, so "freeze both stages from the same file" has no sensible
+    meaning."""
+    overrides = gconfig.overrides_from_flags({init_from_flag: "ckpt/best.pt", freeze_flag: True})
+    assert overrides == {stage_model: {"init_from": "ckpt/best.pt", "freeze": True}}
+
+
 # ---------------------------------------------------------------------------
 # checkpoint config-mismatch warnings (unchanged surface, still exercised)
 # ---------------------------------------------------------------------------

tests/test_config_consumed_keys.py

@@ -28,6 +28,7 @@ import ast
 from pathlib import Path
 
 from giant.config import DEFAULT_CONFIG
+from giant.config import leaf_paths as _leaf_paths
 
 _REPO_ROOT = Path(__file__).resolve().parents[1]
 
@@ -53,13 +54,6 @@ _EXCLUDED_FILES = ("giant/model/_legacy.py",)
 # it. If a key here starts showing up as consumed, the fix landed and this
 # entry is stale — see test_known_unused_allow_list_has_no_stale_entries.
 _KNOWN_UNUSED = {
-    "stage2_model.stage1_context": (
-        "issues.md Issue 1 — trainers.py hardcodes stage1_ctx to the "
-        "ground-truth stage-1 output; 'sampled' is now rejected loudly by "
-        "validate_config (not silently accepted), but the key still isn't "
-        "read by any build/train consumer file since only 'truth' can pass "
-        "validation — see Issue 16 for the real implementation"
-    ),
     "stage2_model.autoregressive.order": (
         "gitea #30 — validate_config now checks order is 'energy_desc', but "
         "nothing in the build/train/rollout consumer whitelist reads the "
@@ -72,19 +66,6 @@ _KNOWN_UNUSED = {
 _FIELD_NAME_OVERRIDES = {"lambda": "lambda_weight"}
 
 
-def _leaf_paths(node: dict, prefix: str = "") -> list[str]:
-    paths = []
-    for key, value in node.items():
-        if prefix == "" and key == "meta":
-            continue
-        path = f"{prefix}.{key}" if prefix else key
-        if isinstance(value, dict):
-            paths.extend(_leaf_paths(value, path))
-        else:
-            paths.append(path)
-    return paths
-
-
 def _field_name(leaf_path: str) -> str:
     name = leaf_path.rsplit(".", 1)[-1]
     return _FIELD_NAME_OVERRIDES.get(name, name)

tests/test_dwarf.py

@@ -124,6 +124,11 @@ def test_warm_cache_router_process_warms_proc_map(tmp_path):
         [
             "warm-cache",
             str(data),
+            # router.type="process" is incompatible with the default
+            # conditioning.particle.type="physical" (validate_config, now
+            # enforced by warm-cache too — see gitea #59).
+            "--particle-conditioning",
+            "embedding",
             "--router",
             "--router-type",
             "process",
@@ -167,3 +172,63 @@ def test_warm_cache_different_val_fraction_is_separate_entry(tmp_path):
     assert loaded is not None
     assert "valfrac=0.1_seed=0_pcond=physical_mcond=physical" in loaded.normalizers
     assert "valfrac=0.3_seed=0_pcond=physical_mcond=physical" in loaded.normalizers
+
+
+def test_warm_cache_config_warms_particle_type_n_classes(tmp_path):
+    """gitea #59: a config setting stage2_model.particle_type.n_classes away
+    from its 0 (= inherit conditioning.particle.emb_dim) default must warm
+    the pdg top-N map under that n_classes, not the emb_dim default, so a
+    later `giant train --config <same file>` run hits it instead of quietly
+    re-scanning every parquet file."""
+    data = _make_synthetic_steps(tmp_path / "data.parquet", n_events=20)
+    config_path = tmp_path / "config.toml"
+    config_path.write_text("[meta]\nconfig_version = 3\n\n[stage2_model.particle_type]\nn_classes = 32\n")
+
+    runner.invoke(app, ["warm-cache", str(data), "--config", str(config_path)])
+    result = runner.invoke(app, ["warm-cache", str(data), "--config", str(config_path)])
+
+    assert result.exit_code == 0, result.output
+    assert "pdg top-N map: cache hit" in result.output
+    assert "32 classes" in result.output
+
+
+def test_warm_cache_config_rejects_val_fraction_flag(tmp_path):
+    data = _make_synthetic_steps(tmp_path / "data.parquet", n_events=20)
+    config_path = tmp_path / "config.toml"
+    config_path.write_text("[meta]\nconfig_version = 3\n")
+
+    result = runner.invoke(
+        app,
+        ["warm-cache", str(data), "--config", str(config_path), "--val-fraction", "0.2"],
+    )
+
+    assert result.exit_code != 0
+    assert "--config" in result.output
+    assert "--val-fraction" in result.output
+
+
+def test_warm_cache_config_rejects_router_flags(tmp_path):
+    data = _make_synthetic_steps(tmp_path / "data.parquet", n_events=20)
+    config_path = tmp_path / "config.toml"
+    config_path.write_text("[meta]\nconfig_version = 3\n")
+
+    result = runner.invoke(
+        app,
+        [
+            "warm-cache",
+            str(data),
+            "--config",
+            str(config_path),
+            "--router",
+            "--router-type",
+            "process",
+            "--n-experts",
+            "3",
+        ],
+    )
+
+    assert result.exit_code != 0
+    assert "--config" in result.output
+    assert "--router/--no-router" in result.output
+    assert "--router-type" in result.output
+    assert "--n-experts" in result.output

tests/test_flow.py

@@ -1,11 +1,12 @@
 import torch
+from giant.config import ConditioningAxisConfig
 from giant.constants import COND_DIM
 from giant.model.network import Stage1Model
 from giant.model.schedule import CosineSchedule, flow_matching_loss
 from giant.sample import sample_flow, sample_ddim
 
-PARTICLE_CFG = {"type": "physical", "emb_dim": 8, "n_layers": 1}
-MATERIAL_CFG = {"type": "physical", "emb_dim": 8, "n_layers": 1}
+PARTICLE_CFG = ConditioningAxisConfig(type="physical", emb_dim=8, n_layers=1)
+MATERIAL_CFG = ConditioningAxisConfig(type="physical", emb_dim=8, n_layers=1)
 
 
 def _small_model():

tests/test_layers.py

@@ -0,0 +1,42 @@
+import pytest
+import torch
+
+from giant.model.layers import build_mlp_head
+
+
+def test_build_mlp_head_depth_1_is_bare_linear():
+    head = build_mlp_head(8, 4, hidden=16, depth=1)
+    assert len(head) == 1
+    assert isinstance(head[0], torch.nn.Linear)
+    assert head[0].in_features == 8
+    assert head[0].out_features == 4
+    out = head(torch.randn(3, 8))
+    assert out.shape == (3, 4)
+
+
+def test_build_mlp_head_depth_2_matches_pre_gitea_36_shape():
+    head = build_mlp_head(8, 4, hidden=16, depth=2)
+    assert len(head) == 3
+    assert isinstance(head[0], torch.nn.Linear)
+    assert head[0].in_features == 8
+    assert head[0].out_features == 16
+    assert isinstance(head[1], torch.nn.SiLU)
+    assert isinstance(head[2], torch.nn.Linear)
+    assert head[2].in_features == 16
+    assert head[2].out_features == 4
+    out = head(torch.randn(5, 8))
+    assert out.shape == (5, 4)
+
+
+def test_build_mlp_head_depth_3_has_extra_hidden_layer():
+    head = build_mlp_head(8, 4, hidden=16, depth=3)
+    assert len(head) == 5
+    widths = [(m.in_features, m.out_features) for m in head if isinstance(m, torch.nn.Linear)]
+    assert widths == [(8, 16), (16, 16), (16, 4)]
+    out = head(torch.randn(2, 8))
+    assert out.shape == (2, 4)
+
+
+def test_build_mlp_head_depth_0_raises():
+    with pytest.raises(ValueError, match="depth"):
+        build_mlp_head(8, 4, hidden=16, depth=0)

tests/test_loader.py

@@ -195,6 +195,10 @@ def test_build_topn_map_from_files_keeps_most_frequent(tmp_path):
     assert m.class_map["G4_Fe"] == 2  # "other" (n_classes - 1)
     assert m.class_map["G4_Pb"] == 2
     assert m.other_members == {"G4_Fe": 2, "G4_Pb": 1}
+    # class_counts (gitea #44): per resulting index, "other" is the sum of
+    # everything folded into it (2 + 1 = 3), and the total equals row count.
+    assert m.class_counts == {0: 5, 1: 3, 2: 3}
+    assert sum(m.class_counts.values()) == len(materials)
 
 
 def test_build_topn_map_from_files_fewer_values_than_n_classes(tmp_path):
@@ -205,6 +209,8 @@ def test_build_topn_map_from_files_fewer_values_than_n_classes(tmp_path):
 
     assert m.class_map == {"G4_AIR": 0, "PbWO4": 1}
     assert m.other_members == {}
+    # No "other" bucket ever populated -> no entry for its index either.
+    assert m.class_counts == {0: 1, 1: 1}
 
 
 def test_build_pdg_topn_map_from_files_pools_primary_and_secondary_pdg(tmp_path):
@@ -224,6 +230,7 @@ def test_build_pdg_topn_map_from_files_pools_primary_and_secondary_pdg(tmp_path)
     # pooled: 11 -> 5, 22 -> 1 (primary) + 10 (secondary) = 11
     assert m.class_map[22] == 0
     assert m.class_map[11] == 1
+    assert m.class_counts == {0: 11, 1: 5}
 
 
 def test_build_pdg_topn_map_from_files_missing_sec_pdg_list_column(tmp_path):

tests/test_model_summary.py

@@ -0,0 +1,137 @@
+"""Tests for `giant model summary` (gitea #46)."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+from typer.testing import CliRunner
+
+from giant import config as gconfig
+from giant.cli import app
+from giant.materials import MATERIAL_PROPERTIES
+from giant.model.summary import _NOT_BUILD_TIME, _built_modules, _vocab_caveats, summarize_model
+
+runner = CliRunner()
+
+_PDG_VOCAB = 300
+_MAT_VOCAB = len(MATERIAL_PROPERTIES)
+
+
+def _cfg(overrides: dict | None = None) -> dict:
+    return gconfig.merge_cli_overrides(gconfig.DEFAULT_CONFIG, None, overrides or {})
+
+
+@pytest.fixture(scope="module")
+def default_summary():
+    return summarize_model(_cfg(), pdg_vocab=_PDG_VOCAB, mat_vocab=_MAT_VOCAB)
+
+
+def test_default_config_builds_both_stages_with_a_real_tree(default_summary):
+    assert set(default_summary.modules) >= {"stage1", "stage2"}
+    for module in default_summary.modules.values():
+        assert sum(p.numel() for p in module.parameters()) > 0
+    stage1 = default_summary.modules["stage1"]
+    assert hasattr(stage1, "cond_enc")
+    assert hasattr(stage1, "trunk")
+    assert {"input_proj", "blocks", "out_proj"} <= {n for n, _ in stage1.trunk.named_children()}
+
+
+def test_every_in_scope_leaf_is_classified(default_summary):
+    in_scope = {
+        p
+        for p in gconfig.leaf_paths(gconfig.DEFAULT_CONFIG)
+        if p.split(".", 1)[0] in ("conditioning", "stage1_model", "stage2_model")
+    }
+    classified = set(default_summary.consumed) | set(default_summary.inert) | set(default_summary.elsewhere)
+    assert classified == in_scope
+
+
+def test_not_build_time_allow_list_has_no_stale_entries():
+    in_scope = set(gconfig.leaf_paths(gconfig.DEFAULT_CONFIG))
+    stale = set(_NOT_BUILD_TIME) - in_scope
+    assert not stale, f"_NOT_BUILD_TIME entries no longer in DEFAULT_CONFIG: {sorted(stale)}"
+
+
+def test_router_disabled_by_default_so_its_fields_are_inert(default_summary):
+    assert "stage1_model.router.n_experts" in default_summary.inert
+    assert "stage1_model.router.temperature" in default_summary.inert
+
+
+def test_markov_history_leaves_attention_dims_inert_but_history_itself_consumed(default_summary):
+    assert "stage2_model.autoregressive.attn_n_heads" in default_summary.inert
+    assert "stage2_model.autoregressive.attn_n_layers" in default_summary.inert
+    assert "stage2_model.autoregressive.history" in default_summary.consumed
+
+
+def test_single_literal_branch_fields_are_correctly_seen_as_consumed(default_summary):
+    """Regression guard: n_sec.owner ("stage2"), n_sec.mode ("head") and
+    particle_type.target ("onehot") each branch as `== "one specific other
+    literal"` in giant/model/builders.py|models.py. A naive single generic
+    sentinel probe lands in the same "not that literal" bucket as the
+    current value and never crosses the boundary that actually matters --
+    this is exactly what _STRING_ALTERNATIVES exists to fix."""
+    assert "stage2_model.n_sec.owner" in default_summary.consumed
+    assert "stage2_model.n_sec.mode" in default_summary.consumed
+    assert "stage2_model.particle_type.target" in default_summary.consumed
+
+
+def test_stage1_wgan_generator_swaps_flow_time_dim_for_critic_dims():
+    summary = summarize_model(_cfg({"stage1_model": {"generator": "wgan"}}), pdg_vocab=_PDG_VOCAB, mat_vocab=_MAT_VOCAB)
+    assert "stage1_model.flow.time_dim" in summary.inert
+    assert "stage1_model.wgan.noise_dim" in summary.consumed
+    assert "stage1_model.wgan.critic_hidden_dim" in summary.consumed
+
+
+def test_stage2_one_shot_decoder_makes_autoregressive_block_inert():
+    summary = summarize_model(
+        _cfg({"stage2_model": {"decoder": "one_shot"}}), pdg_vocab=_PDG_VOCAB, mat_vocab=_MAT_VOCAB
+    )
+    assert "stage2_model.autoregressive.history" in summary.inert
+    assert "history_encoder" not in {n for n, _ in summary.modules["stage2"].named_children()}
+
+
+def test_energy_router_enabled_consumes_core_fields_but_not_process_only_fields():
+    summary = summarize_model(
+        _cfg({"stage1_model": {"router": {"enabled": True, "type": "energy", "n_experts": 4}}}),
+        pdg_vocab=_PDG_VOCAB,
+        mat_vocab=_MAT_VOCAB,
+    )
+    assert "stage1_model.router.n_experts" in summary.consumed
+    assert "stage1_model.router.temperature" in summary.consumed
+    # emb_dim/hidden_dim are pdg/process-router-only kwargs -- build_router's
+    # signature filter drops them for an energy router.
+    assert "stage1_model.router.hidden_dim" in summary.inert
+    assert "stage1_model.router.emb_dim" in summary.inert
+
+
+def test_vocab_caveat_text_for_embedding_particle_conditioning():
+    cfg = _cfg({"conditioning": {"particle": {"type": "embedding"}}})
+    caveats = _vocab_caveats(cfg)
+    assert any("pdg_vocab" in c and "embedding" in c for c in caveats)
+    assert not any("mat_vocab" in c for c in caveats)
+
+
+def test_pdg_vocab_flag_changes_embedding_table_size():
+    cfg = _cfg({"conditioning": {"particle": {"type": "embedding"}}})
+    small = _built_modules(cfg, pdg_vocab=10, mat_vocab=_MAT_VOCAB)
+    big = _built_modules(cfg, pdg_vocab=1000, mat_vocab=_MAT_VOCAB)
+    assert big["stage1"].cond_enc.pdg_emb.weight.numel() > small["stage1"].cond_enc.pdg_emb.weight.numel()
+
+
+def test_invalid_combo_exits_nonzero_with_validate_config_message(tmp_path: Path):
+    config_path = tmp_path / "bad.toml"
+    config_path.write_text('[meta]\nconfig_version = 3\n\n[stage2_model.particle_type]\ntarget = "embedding"\n')
+    result = runner.invoke(app, ["model", "summary", "--config", str(config_path)])
+    assert result.exit_code == 1
+    assert "requires conditioning.particle.type = 'embedding'" in result.output
+
+
+def test_cli_default_smoke():
+    result = runner.invoke(app, ["model", "summary"])
+    assert result.exit_code == 0, result.output
+    assert "stage1" in result.output
+    assert "stage2" in result.output
+    assert "parameters" in result.output
+    assert "trunk" in result.output
+    assert "inert under this config" in result.output

tests/test_network.py

@@ -5,24 +5,28 @@ import torch
 from giant import config as gconfig
 from giant.constants import CONT_SLOT_DIM, COND_DIM, PARTICLE_PHYS_DIM, SEC_SLOT_DIM
 from giant.model.network import (
+    HISTORY_REGISTRY,
     AttentionHistory,
     ConditionEncoder,
+    HistoryEncoder,
     MarkovHistory,
     SinusoidalEmbedding,
     Stage1Model,
     Stage2Autoregressive,
     Stage2OneShot,
+    StageModel,
     build_critics,
+    build_history,
     build_models,
-    cat_col_layout,
+    build_objective,
     stage2_trunk_sec_dim,
     stage2_type_dim,
 )
 
-PARTICLE_CFG = {"type": "physical", "emb_dim": 8, "n_layers": 1}
-MATERIAL_CFG = {"type": "physical", "emb_dim": 8, "n_layers": 1}
-ONEHOT_PARTICLE_CFG = {"type": "onehot", "emb_dim": 6, "n_layers": 1}
-ONEHOT_MATERIAL_CFG = {"type": "onehot", "emb_dim": 4, "n_layers": 1}
+PARTICLE_CFG = gconfig.ConditioningAxisConfig(type="physical", emb_dim=8, n_layers=1)
+MATERIAL_CFG = gconfig.ConditioningAxisConfig(type="physical", emb_dim=8, n_layers=1)
+ONEHOT_PARTICLE_CFG = gconfig.ConditioningAxisConfig(type="onehot", emb_dim=6, n_layers=1)
+ONEHOT_MATERIAL_CFG = gconfig.ConditioningAxisConfig(type="onehot", emb_dim=4, n_layers=1)
 
 
 def test_sinusoidal_embedding_shape():
@@ -90,48 +94,72 @@ def test_stage1_model_no_n_sec_head_by_default():
     assert model.n_sec_head is None
 
 
-# --- cat_col_layout / stage2_type_dim / stage2_trunk_sec_dim ---------------
+def test_stage1_model_n_sec_head_default_cfg_matches_pre_gitea_36_shape():
+    """No n_sec_head_cfg given must reproduce the old hardcoded
+    hidden_dim // 2, one-hidden-layer architecture exactly (gitea #36)."""
+    model = Stage1Model(
+        pdg_vocab=3,
+        mat_vocab=2,
+        particle_cfg=PARTICLE_CFG,
+        material_cfg=MATERIAL_CFG,
+        hidden_dim=40,
+        cond_out_dim=12,
+        n_sec_head_k_max=15,
+    )
+    assert model.n_sec_head is not None
+    assert len(model.n_sec_head) == 3
+    assert model.n_sec_head[0].in_features == 12
+    assert model.n_sec_head[0].out_features == 20  # hidden_dim // 2
+    assert model.n_sec_head[2].out_features == 16  # k_max + 1
 
 
-def test_cat_col_layout_neither_onehot():
-    assert cat_col_layout("physical", "embedding") == (None, None)
+def test_stage1_model_n_sec_head_cfg_controls_hidden_width_and_depth():
+    model = Stage1Model(
+        pdg_vocab=3,
+        mat_vocab=2,
+        particle_cfg=PARTICLE_CFG,
+        material_cfg=MATERIAL_CFG,
+        hidden_dim=32,
+        cond_out_dim=16,
+        n_sec_head_k_max=15,
+        n_sec_head_cfg={"hidden_ratio": 0.25, "depth": 1},
+    )
+    assert model.n_sec_head is not None
+    assert len(model.n_sec_head) == 1
+    assert model.n_sec_head[0].in_features == 16
+    assert model.n_sec_head[0].out_features == 16
 
 
-def test_cat_col_layout_particle_only():
-    assert cat_col_layout("onehot", "physical") == (2, None)
-
-
-def test_cat_col_layout_material_only():
-    assert cat_col_layout("physical", "onehot") == (None, 2)
-
-
-def test_cat_col_layout_both_onehot_particle_then_material():
-    assert cat_col_layout("onehot", "onehot") == (2, 3)
+# --- stage2_type_dim / stage2_trunk_sec_dim --------------------------------
+# (the cond_cat column-layout tests live in tests/test_cond_layout.py)
 
 
 def test_stage2_type_dim_physical_is_particle_phys_dim():
-    assert stage2_type_dim({"target": "physical"}, emb_dim=16) == PARTICLE_PHYS_DIM
+    assert stage2_type_dim(gconfig.ParticleTypeConfig(target="physical"), emb_dim=16) == PARTICLE_PHYS_DIM
 
 
 def test_stage2_type_dim_onehot_and_embedding_are_emb_dim():
-    assert stage2_type_dim({"target": "onehot"}, emb_dim=16) == 16
-    assert stage2_type_dim({"target": "embedding"}, emb_dim=16) == 16
+    assert stage2_type_dim(gconfig.ParticleTypeConfig(target="onehot"), emb_dim=16) == 16
+    assert stage2_type_dim(gconfig.ParticleTypeConfig(target="embedding"), emb_dim=16) == 16
 
 
 def test_stage2_trunk_sec_dim_physical_matches_v02_sec_dim():
     k_max = 15
-    assert stage2_trunk_sec_dim({"target": "physical"}, "flow", k_max, emb_dim=16) == k_max * SEC_SLOT_DIM
-    assert stage2_trunk_sec_dim({"target": "physical"}, "wgan", k_max, emb_dim=16) == k_max * SEC_SLOT_DIM
+    physical = gconfig.ParticleTypeConfig(target="physical")
+    assert stage2_trunk_sec_dim(physical, "flow", k_max, emb_dim=16) == k_max * SEC_SLOT_DIM
+    assert stage2_trunk_sec_dim(physical, "wgan", k_max, emb_dim=16) == k_max * SEC_SLOT_DIM
 
 
 def test_stage2_trunk_sec_dim_onehot_wgan_folds_type_in():
     k_max = 15
-    assert stage2_trunk_sec_dim({"target": "onehot"}, "wgan", k_max, emb_dim=16) == k_max * (CONT_SLOT_DIM + 16)
+    onehot = gconfig.ParticleTypeConfig(target="onehot")
+    assert stage2_trunk_sec_dim(onehot, "wgan", k_max, emb_dim=16) == k_max * (CONT_SLOT_DIM + 16)
 
 
 def test_stage2_trunk_sec_dim_onehot_flow_excludes_type():
     k_max = 15
-    assert stage2_trunk_sec_dim({"target": "onehot"}, "flow", k_max, emb_dim=16) == k_max * CONT_SLOT_DIM
+    onehot = gconfig.ParticleTypeConfig(target="onehot")
+    assert stage2_trunk_sec_dim(onehot, "flow", k_max, emb_dim=16) == k_max * CONT_SLOT_DIM
 
 
 # --- ConditionEncoder onehot mode -------------------------------------------
@@ -139,8 +167,8 @@ def test_stage2_trunk_sec_dim_onehot_flow_excludes_type():
 
 def test_condition_encoder_onehot_forward_shape_and_gradients():
     B = 8
-    particle_emb_dim = int(ONEHOT_PARTICLE_CFG["emb_dim"])
-    material_emb_dim = int(ONEHOT_MATERIAL_CFG["emb_dim"])
+    particle_emb_dim = ONEHOT_PARTICLE_CFG.emb_dim
+    material_emb_dim = ONEHOT_MATERIAL_CFG.emb_dim
     enc = ConditionEncoder(
         pdg_vocab=5,
         mat_vocab=3,
@@ -171,12 +199,12 @@ def test_condition_encoder_onehot_is_a_true_one_hot_vector():
     verify the concatenated input segment really is one-hot, not e.g. an
     accidentally-learned embedding."""
     B = 4
-    particle_emb_dim = int(ONEHOT_PARTICLE_CFG["emb_dim"])
+    particle_emb_dim = ONEHOT_PARTICLE_CFG.emb_dim
     enc = ConditionEncoder(
         pdg_vocab=5,
         mat_vocab=3,
         particle_cfg=ONEHOT_PARTICLE_CFG,
-        material_cfg={"type": "physical", "emb_dim": 4, "n_layers": 1},
+        material_cfg=gconfig.ConditioningAxisConfig(type="physical", emb_dim=4, n_layers=1),
         out_dim=16,
     )
     cond_cont = torch.zeros(B, COND_DIM)
@@ -198,13 +226,11 @@ def test_condition_encoder_onehot_is_a_true_one_hot_vector():
 
 
 def _build_stage2(target: str, generator: str, emb_dim: int = 6) -> Stage2OneShot:
-    particle_cfg = {"type": "physical", "emb_dim": emb_dim, "n_layers": 1}
-    if target != "physical":
-        particle_cfg = dict(particle_cfg)
-        if target == "embedding":
-            particle_cfg["type"] = "embedding"
+    particle_cfg = gconfig.ConditioningAxisConfig(type="physical", emb_dim=emb_dim, n_layers=1)
+    if target == "embedding":
+        particle_cfg = gconfig.ConditioningAxisConfig(type="embedding", emb_dim=emb_dim, n_layers=1)
     k_max = 5
-    sec_dim = stage2_trunk_sec_dim({"target": target}, generator, k_max, emb_dim)
+    sec_dim = stage2_trunk_sec_dim(gconfig.ParticleTypeConfig(target=target), generator, k_max, emb_dim)
     return Stage2OneShot(
         pdg_vocab=5,
         mat_vocab=3,
@@ -217,7 +243,7 @@ def _build_stage2(target: str, generator: str, emb_dim: int = 6) -> Stage2OneSho
         sec_dim=sec_dim,
         generator=generator,
         k_max=k_max,
-        particle_type_cfg={"target": target, "lambda": 1.0},
+        particle_type_cfg=gconfig.ParticleTypeConfig(target=target),
     )
 
 
@@ -265,6 +291,38 @@ def test_stage2_oneshot_predict_type_raises_when_no_type_head():
         pass
 
 
+def test_stage2_oneshot_n_sec_head_and_type_head_cfg_control_hidden_width_and_depth():
+    """gitea #36: n_sec_head_cfg/type_head_cfg are independently tunable."""
+    k_max, emb_dim = 5, 6
+    particle_cfg = gconfig.ConditioningAxisConfig(type="onehot", emb_dim=emb_dim, n_layers=1)
+    sec_dim = stage2_trunk_sec_dim(gconfig.ParticleTypeConfig(target="onehot"), "flow", k_max, emb_dim)
+    model = Stage2OneShot(
+        pdg_vocab=5,
+        mat_vocab=3,
+        particle_cfg=particle_cfg,
+        material_cfg=MATERIAL_CFG,
+        hidden_dim=40,
+        n_res_blocks=1,
+        cond_out_dim=12,
+        context_dim=8,
+        sec_dim=sec_dim,
+        generator="flow",
+        k_max=k_max,
+        particle_type_cfg=gconfig.ParticleTypeConfig(target="onehot"),
+        n_sec_head_cfg={"hidden_ratio": 0.25, "depth": 1},
+        type_head_cfg={"hidden_ratio": 0.75, "depth": 2},
+    )
+    assert model.n_sec_head is not None
+    assert len(model.n_sec_head) == 1
+    assert model.n_sec_head[0].in_features == 12
+    assert model.n_sec_head[0].out_features == k_max + 1
+
+    assert model.type_head is not None
+    assert len(model.type_head) == 3
+    assert model.type_head[0].out_features == 30  # round(40 * 0.75)
+    assert model.type_head[2].out_features == k_max * emb_dim
+
+
 def test_stage2_oneshot_forward_shape_onehot_wgan():
     B, k_max, emb_dim = 4, 5, 6
     model = _build_stage2("onehot", "wgan", emb_dim=emb_dim)
@@ -293,8 +351,8 @@ def test_stage2_oneshot_particle_type_n_classes_overrides_conditioning_emb_dim()
     conditioning.particle.emb_dim, sizes the onehot type_head/type_dim when
     explicitly set — the two used to be silently the same number."""
     k_max = 5
-    particle_cfg = {"type": "physical", "emb_dim": 6, "n_layers": 1}
-    particle_type_cfg = {"target": "onehot", "lambda": 1.0, "n_classes": 20}
+    particle_cfg = gconfig.ConditioningAxisConfig(type="physical", emb_dim=6, n_layers=1)
+    particle_type_cfg = gconfig.ParticleTypeConfig(target="onehot", n_classes=20)
     sec_dim = stage2_trunk_sec_dim(particle_type_cfg, "flow", k_max, 20)
     model = Stage2OneShot(
         pdg_vocab=5,
@@ -310,7 +368,7 @@ def test_stage2_oneshot_particle_type_n_classes_overrides_conditioning_emb_dim()
         k_max=k_max,
         particle_type_cfg=particle_type_cfg,
     )
-    assert model.type_dim == 20  # not particle_cfg["emb_dim"] == 6
+    assert model.type_dim == 20  # not particle_cfg.emb_dim == 6
     assert model.type_head is not None
     assert model.type_head[-1].out_features == k_max * 20
 
@@ -407,6 +465,48 @@ def test_attention_history_step_matches_forward():
     assert torch.allclose(stepped, expected, atol=1e-5)
 
 
+# --- HISTORY_REGISTRY / build_history (gitea #35) ----------------------------
+
+
+def test_history_registry_has_exactly_the_two_known_histories():
+    assert set(HISTORY_REGISTRY) == {"markov", "attention"}
+
+
+def test_build_history_returns_correct_concrete_type():
+    assert isinstance(build_history("markov", 4, 6), MarkovHistory)
+    assert isinstance(build_history("attention", 4, 8), AttentionHistory)
+
+
+def test_build_history_unknown_name_raises():
+    with pytest.raises(ValueError):
+        build_history("bogus", 4, 6)
+
+
+def test_build_history_filters_kwargs_by_signature():
+    """Attention-only kwargs (n_heads/n_layers) must be silently dropped when
+    building a MarkovHistory, matching build_router's documented behavior for
+    per-type hyperparameters coexisting in one config."""
+    hist = build_history("markov", 4, 6, n_heads=2, n_layers=1)
+    assert isinstance(hist, MarkovHistory)
+
+
+def test_history_encoder_base_default_init_cache_and_step():
+    """A HistoryEncoder subclass implementing only forward() must still get
+    working O(1) init_cache/step defaults from the base class."""
+
+    class _StubHistory(HistoryEncoder):
+        def forward(self, feat, has_prev):
+            return feat * 2
+
+    hist = _StubHistory()
+    assert hist.init_cache() is None
+    feat = torch.randn(2, 1, 4)
+    has_prev = torch.ones(2, 1, dtype=torch.bool)
+    out, cache = hist.step(feat, has_prev, "unused-cache")
+    assert torch.equal(out, hist.forward(feat, has_prev))
+    assert cache == "unused-cache"
+
+
 # --- Stage2Autoregressive (v0.3.0 step 5) -----------------------------------
 
 
@@ -417,10 +517,9 @@ def _build_stage2_ar(
     k_max: int = 5,
     history: str = "markov",
 ) -> Stage2Autoregressive:
-    particle_cfg = {"type": "physical", "emb_dim": emb_dim, "n_layers": 1}
+    particle_cfg = gconfig.ConditioningAxisConfig(type="physical", emb_dim=emb_dim, n_layers=1)
     if target == "embedding":
-        particle_cfg = dict(particle_cfg)
-        particle_cfg["type"] = "embedding"
+        particle_cfg = gconfig.ConditioningAxisConfig(type="embedding", emb_dim=emb_dim, n_layers=1)
     return Stage2Autoregressive(
         pdg_vocab=5,
         mat_vocab=3,
@@ -432,7 +531,7 @@ def _build_stage2_ar(
         context_dim=8,
         generator=generator,
         k_max=k_max,
-        particle_type_cfg={"target": target, "lambda": 1.0},
+        particle_type_cfg=gconfig.ParticleTypeConfig(target=target),
         history=history,
     )
 
@@ -453,8 +552,8 @@ def test_stage2_autoregressive_history_invalid_raises():
 def test_stage2_autoregressive_particle_type_n_classes_overrides_conditioning_emb_dim():
     """gitea #29, Stage2Autoregressive side — see the Stage2OneShot version
     of this test for the full rationale."""
-    particle_cfg = {"type": "physical", "emb_dim": 6, "n_layers": 1}
-    particle_type_cfg = {"target": "onehot", "lambda": 1.0, "n_classes": 20}
+    particle_cfg = gconfig.ConditioningAxisConfig(type="physical", emb_dim=6, n_layers=1)
+    particle_type_cfg = gconfig.ParticleTypeConfig(target="onehot", n_classes=20)
     model = Stage2Autoregressive(
         pdg_vocab=5,
         mat_vocab=3,
@@ -468,11 +567,42 @@ def test_stage2_autoregressive_particle_type_n_classes_overrides_conditioning_em
         k_max=5,
         particle_type_cfg=particle_type_cfg,
     )
-    assert model.type_dim == 20  # not particle_cfg["emb_dim"] == 6
+    assert model.type_dim == 20  # not particle_cfg.emb_dim == 6
     assert model.type_head is not None
     assert model.type_head[-1].out_features == 20
 
 
+def test_stage2_autoregressive_n_sec_head_and_type_head_cfg_control_hidden_width_and_depth():
+    """gitea #36, Stage2Autoregressive side — see the Stage2OneShot version
+    of this test for the full rationale."""
+    particle_cfg = gconfig.ConditioningAxisConfig(type="physical", emb_dim=6, n_layers=1)
+    particle_type_cfg = gconfig.ParticleTypeConfig(target="onehot")
+    model = Stage2Autoregressive(
+        pdg_vocab=5,
+        mat_vocab=3,
+        particle_cfg=particle_cfg,
+        material_cfg=MATERIAL_CFG,
+        hidden_dim=40,
+        n_res_blocks=1,
+        cond_out_dim=12,
+        context_dim=8,
+        generator="flow",
+        k_max=5,
+        particle_type_cfg=particle_type_cfg,
+        n_sec_head_cfg={"hidden_ratio": 0.25, "depth": 1},
+        type_head_cfg={"hidden_ratio": 0.75, "depth": 2},
+    )
+    assert model.n_sec_head is not None
+    assert len(model.n_sec_head) == 1
+    assert model.n_sec_head[0].in_features == 12
+    assert model.n_sec_head[0].out_features == 6  # k_max + 1
+
+    assert model.type_head is not None
+    assert len(model.type_head) == 3
+    assert model.type_head[0].out_features == 30  # round(40 * 0.75)
+    assert model.type_head[2].out_features == model.type_dim
+
+
 @pytest.mark.parametrize("target", ["physical", "onehot", "embedding"])
 @pytest.mark.parametrize("generator", ["wgan", "flow"])
 @pytest.mark.parametrize("history", ["markov", "attention"])
@@ -482,9 +612,9 @@ def test_stage2_autoregressive_forward_shape(target, generator, history):
     cond_cont = torch.randn(B, COND_DIM)
     cond_cat = torch.zeros(B, 2, dtype=torch.long)
     stage1_out = torch.randn(B, 9)
-    type_dim = stage2_type_dim({"target": target}, emb_dim)
+    type_dim = stage2_type_dim(gconfig.ParticleTypeConfig(target=target), emb_dim)
     history_feat, has_prev, remaining_frac, slot_idx = _ar_inputs(B, K, CONT_SLOT_DIM + type_dim)
-    token_dim = stage2_trunk_sec_dim({"target": target}, generator, 1, emb_dim)
+    token_dim = stage2_trunk_sec_dim(gconfig.ParticleTypeConfig(target=target), generator, 1, emb_dim)
     if generator == "wgan":
         x_t = torch.randn(B, K, model.noise_dim)
         t = None
@@ -521,7 +651,7 @@ def test_stage2_autoregressive_predict_type_shape():
     cond_cont = torch.randn(B, COND_DIM)
     cond_cat = torch.zeros(B, 2, dtype=torch.long)
     stage1_out = torch.randn(B, 9)
-    type_dim = stage2_type_dim({"target": "onehot"}, emb_dim)
+    type_dim = stage2_type_dim(gconfig.ParticleTypeConfig(target="onehot"), emb_dim)
     history_feat, has_prev, remaining_frac, slot_idx = _ar_inputs(B, K, CONT_SLOT_DIM + type_dim)
     out = model.predict_type(
         cond_cont,
@@ -542,7 +672,7 @@ def test_stage2_autoregressive_predict_type_raises_when_no_type_head(target, gen
     cond_cont = torch.randn(B, COND_DIM)
     cond_cat = torch.zeros(B, 2, dtype=torch.long)
     stage1_out = torch.randn(B, 9)
-    type_dim = stage2_type_dim({"target": target}, emb_dim)
+    type_dim = stage2_type_dim(gconfig.ParticleTypeConfig(target=target), emb_dim)
     history_feat, has_prev, remaining_frac, slot_idx = _ar_inputs(B, K, CONT_SLOT_DIM + type_dim)
     with pytest.raises(RuntimeError):
         model.predict_type(
@@ -562,7 +692,7 @@ def test_stage2_autoregressive_gradients_flow_wgan_onehot():
     cond_cont = torch.randn(B, COND_DIM)
     cond_cat = torch.zeros(B, 2, dtype=torch.long)
     stage1_out = torch.randn(B, 9)
-    type_dim = stage2_type_dim({"target": "onehot"}, emb_dim)
+    type_dim = stage2_type_dim(gconfig.ParticleTypeConfig(target="onehot"), emb_dim)
     history_feat, has_prev, remaining_frac, slot_idx = _ar_inputs(B, K, CONT_SLOT_DIM + type_dim)
     z = torch.randn(B, K, model.noise_dim)
     gen_out = model(
@@ -587,9 +717,9 @@ def test_stage2_autoregressive_gradients_flow_onehot():
     cond_cont = torch.randn(B, COND_DIM)
     cond_cat = torch.zeros(B, 2, dtype=torch.long)
     stage1_out = torch.randn(B, 9)
-    type_dim = stage2_type_dim({"target": "onehot"}, emb_dim)
+    type_dim = stage2_type_dim(gconfig.ParticleTypeConfig(target="onehot"), emb_dim)
     history_feat, has_prev, remaining_frac, slot_idx = _ar_inputs(B, K, CONT_SLOT_DIM + type_dim)
-    token_dim = stage2_trunk_sec_dim({"target": "onehot"}, "flow", 1, emb_dim)
+    token_dim = stage2_trunk_sec_dim(gconfig.ParticleTypeConfig(target="onehot"), "flow", 1, emb_dim)
     x_t = torch.randn(B, K, token_dim)
     t = torch.rand(B, K)
     flow_out = model(
@@ -629,7 +759,7 @@ def test_stage2_autoregressive_history_step_matches_parallel_history_encoder():
     B, K, emb_dim = 3, 6, 6
     model = _build_stage2_ar("physical", "wgan", emb_dim=emb_dim, k_max=K, history="attention")
     model.eval()
-    type_dim = stage2_type_dim({"target": "physical"}, emb_dim)
+    type_dim = stage2_type_dim(gconfig.ParticleTypeConfig(target="physical"), emb_dim)
     hist_in_dim = CONT_SLOT_DIM + type_dim
     own_feat = torch.randn(B, K, hist_in_dim)  # token i's own raw feature
     has_prev_full = (torch.arange(K) >= 1).unsqueeze(0).expand(B, -1)
@@ -705,6 +835,54 @@ def test_build_models_share_stages_true_shared_params_are_in_both_stage_paramete
     assert shared_ids <= {id(p) for p in stage2.parameters()}
 
 
+def test_condition_encoder_stores_the_exact_particle_and_material_cfg_instances_passed_in():
+    """gitea #38: ConditionEncoder must not round-trip particle_cfg/
+    material_cfg through a dict — the exact ConditioningAxisConfig instance
+    passed in is what `.particle_cfg`/`.material_cfg` hold afterward."""
+    particle_cfg = gconfig.ConditioningAxisConfig(type="physical", emb_dim=8, n_layers=1)
+    material_cfg = gconfig.ConditioningAxisConfig(type="physical", emb_dim=8, n_layers=1)
+    enc = ConditionEncoder(pdg_vocab=3, mat_vocab=2, particle_cfg=particle_cfg, material_cfg=material_cfg)
+    assert enc.particle_cfg is particle_cfg
+    assert enc.material_cfg is material_cfg
+
+
+def test_stagemodel_stores_the_exact_particle_type_cfg_instance_passed_in():
+    """gitea #38: a StageModel subclass must not round-trip particle_type_cfg
+    through a dict — the exact ParticleTypeConfig instance passed in is what
+    `.particle_type_cfg` holds afterward."""
+    particle_type_cfg = gconfig.ParticleTypeConfig(target="onehot", n_classes=11)
+    sec_dim = stage2_trunk_sec_dim(particle_type_cfg, "flow", 5, 11)
+    model = Stage2OneShot(
+        pdg_vocab=3,
+        mat_vocab=2,
+        particle_cfg=PARTICLE_CFG,
+        material_cfg=MATERIAL_CFG,
+        hidden_dim=16,
+        n_res_blocks=1,
+        k_max=5,
+        sec_dim=sec_dim,
+        particle_type_cfg=particle_type_cfg,
+    )
+    assert model.particle_type_cfg is particle_type_cfg
+
+
+def test_build_models_particle_type_cfg_and_conditioning_axes_are_dataclasses_not_dicts():
+    """gitea #38: build_models must pass the parsed ConditioningAxisConfig/
+    ParticleTypeConfig dataclasses themselves down to the model constructors,
+    not re-serialize them to a dict first (the inversion the issue names) —
+    before the fix, .particle_type_cfg was a plain dict (s2_spec.particle_type
+    .to_dict()) and .cond_enc.particle_cfg came from the raw, unparsed
+    conditioning["particle"] dict."""
+    cfg = _minimal_model_config(share_stages=False)
+    cfg["stage2_model"]["particle_type"] = {"target": "onehot", "lambda": 1.0, "n_classes": 11}
+    built = build_models(cfg)
+    stage1, stage2 = built["stage1"], built["stage2"]
+    assert stage1 is not None and stage2 is not None
+    assert isinstance(stage2.particle_type_cfg, gconfig.ParticleTypeConfig)
+    assert isinstance(stage1.cond_enc.particle_cfg, gconfig.ConditioningAxisConfig)
+    assert isinstance(stage1.cond_enc.material_cfg, gconfig.ConditioningAxisConfig)
+
+
 def test_build_models_particle_type_n_classes_overrides_conditioning_emb_dim():
     """gitea #29 end-to-end through build_models: setting
     stage2_model.particle_type.n_classes independently of
@@ -765,7 +943,40 @@ def _partial_model_config() -> dict:
 def test_build_models_omitted_decoder_and_particle_type_match_default_config():
     built = build_models(_partial_model_config())
     assert isinstance(built["stage2"], Stage2Autoregressive)
-    assert built["stage2"].particle_type_cfg["target"] == "onehot"
+    assert built["stage2"].particle_type_cfg.target == "onehot"
+
+
+def test_build_models_custom_heads_block_controls_head_shapes():
+    """gitea #36: stage{1,2}_model.heads flows all the way from config dict
+    through build_models to the actual constructed head shapes."""
+    cfg = _partial_model_config()
+    cfg["stage1_model"] = {
+        "active": True,
+        "hidden_dim": 40,
+        "n_res_blocks": 1,
+        "heads": {"n_sec": {"hidden_ratio": 0.25, "depth": 1}},
+    }
+    cfg["stage2_model"]["decoder"] = "one_shot"
+    cfg["stage2_model"]["generator"] = "flow"  # wgan folds the type slice; no separate type_head
+    cfg["stage2_model"]["n_sec"] = {"owner": "stage1"}
+    cfg["stage2_model"]["heads"] = {
+        "n_sec": {"hidden_ratio": 0.25, "depth": 1},
+        "type": {"hidden_ratio": 0.75, "depth": 2},
+    }
+
+    built = build_models(cfg)
+    stage1, stage2 = built["stage1"], built["stage2"]
+    assert stage1 is not None
+    assert stage2 is not None
+
+    assert stage1.n_sec_head is not None
+    assert len(stage1.n_sec_head) == 1  # owner=stage1, so stage1 builds it
+    assert stage2.n_sec_head is None  # owner=stage1, so stage2 doesn't
+
+    assert isinstance(stage2, Stage2OneShot)
+    assert stage2.type_head is not None
+    assert len(stage2.type_head) == 3
+    assert stage2.type_head[0].out_features == 6  # round(8 * 0.75)
 
 
 def test_build_critics_omitted_particle_type_matches_default_config():
@@ -826,3 +1037,163 @@ def test_build_critics_stage2_critic_hidden_dim_and_n_res_blocks_override_genera
     assert overridden is not None
     assert overridden.input_proj.out_features == 16
     assert len(overridden.blocks) == 3
+
+
+# ── StageModel base (gitea #39): Stage1Model/Stage2OneShot/Stage2Autoregressive
+# scaffolding — construction order, and therefore fresh-init RNG draw order and
+# state_dict key set, must stay byte-for-byte what it was before the base class
+# existed. ------------------------------------------------------------------
+
+_STAGE_HIDDEN_DIM = 32
+_STAGE_N_BLOCKS = 2
+_STAGE_COND_OUT_DIM = 16
+
+
+def _resblock_keys(prefix: str) -> set[str]:
+    return {
+        f"{prefix}.norm.weight",
+        f"{prefix}.norm.bias",
+        f"{prefix}.linear1.weight",
+        f"{prefix}.linear1.bias",
+        f"{prefix}.cond_proj.weight",
+        f"{prefix}.linear2.weight",
+        f"{prefix}.linear2.bias",
+    }
+
+
+def _trunk_keys(prefix: str = "trunk") -> set[str]:
+    keys = {
+        f"{prefix}.input_proj.weight",
+        f"{prefix}.input_proj.bias",
+        f"{prefix}.out_proj.weight",
+        f"{prefix}.out_proj.bias",
+    }
+    for i in range(_STAGE_N_BLOCKS):
+        keys |= _resblock_keys(f"{prefix}.blocks.{i}")
+    return keys
+
+
+def _cond_enc_keys() -> set[str]:
+    return {
+        "cond_enc.mlp.0.weight",
+        "cond_enc.mlp.0.bias",
+        "cond_enc.mlp.2.weight",
+        "cond_enc.mlp.2.bias",
+        "cond_enc.particle_mlp.0.weight",
+        "cond_enc.particle_mlp.0.bias",
+        "cond_enc.material_mlp.0.weight",
+        "cond_enc.material_mlp.0.bias",
+    }
+
+
+def _fuse_keys(name: str) -> set[str]:
+    return {f"{name}.0.weight", f"{name}.0.bias"}
+
+
+def _head_keys(name: str) -> set[str]:
+    return {f"{name}.0.weight", f"{name}.0.bias", f"{name}.2.weight", f"{name}.2.bias"}
+
+
+def _expected_stage_keys(*, has_time: bool, extra: set[str]) -> set[str]:
+    keys = _cond_enc_keys() | _trunk_keys() | extra
+    if has_time:
+        keys.add("time_emb.freqs")
+    return keys
+
+
+@pytest.mark.parametrize("generator", ["flow", "wgan"])
+def test_stage1_model_state_dict_keys_unchanged_by_stagemodel_refactor(generator):
+    model = Stage1Model(
+        pdg_vocab=5,
+        mat_vocab=3,
+        particle_cfg=PARTICLE_CFG,
+        material_cfg=MATERIAL_CFG,
+        hidden_dim=_STAGE_HIDDEN_DIM,
+        n_res_blocks=_STAGE_N_BLOCKS,
+        cond_out_dim=_STAGE_COND_OUT_DIM,
+        generator=generator,
+        time_dim=8,
+        noise_dim=8,
+        n_sec_head_k_max=15,
+    )
+    expected = _expected_stage_keys(
+        has_time=build_objective(generator).needs_time,
+        extra=_head_keys("n_sec_head"),
+    )
+    assert set(model.state_dict().keys()) == expected
+
+
+@pytest.mark.parametrize("generator", ["flow", "wgan"])
+def test_stage2_oneshot_state_dict_keys_unchanged_by_stagemodel_refactor(generator):
+    model = Stage2OneShot(
+        pdg_vocab=5,
+        mat_vocab=3,
+        particle_cfg=PARTICLE_CFG,
+        material_cfg=MATERIAL_CFG,
+        hidden_dim=_STAGE_HIDDEN_DIM,
+        n_res_blocks=_STAGE_N_BLOCKS,
+        cond_out_dim=_STAGE_COND_OUT_DIM,
+        generator=generator,
+        time_dim=8,
+        noise_dim=8,
+        k_max=15,
+    )
+    extra = _head_keys("n_sec_head") | {"context_adapter.proj.weight", "context_adapter.proj.bias"} | _fuse_keys("fuse")
+    expected = _expected_stage_keys(has_time=build_objective(generator).needs_time, extra=extra)
+    assert set(model.state_dict().keys()) == expected
+
+
+@pytest.mark.parametrize("generator", ["flow", "wgan"])
+def test_stage2_autoregressive_state_dict_keys_unchanged_by_stagemodel_refactor(generator):
+    model = Stage2Autoregressive(
+        pdg_vocab=5,
+        mat_vocab=3,
+        particle_cfg=PARTICLE_CFG,
+        material_cfg=MATERIAL_CFG,
+        hidden_dim=_STAGE_HIDDEN_DIM,
+        n_res_blocks=_STAGE_N_BLOCKS,
+        cond_out_dim=_STAGE_COND_OUT_DIM,
+        generator=generator,
+        time_dim=8,
+        noise_dim=8,
+        k_max=15,
+    )
+    extra = (
+        _head_keys("n_sec_head")
+        | {"context_adapter.proj.weight", "context_adapter.proj.bias"}
+        | _fuse_keys("base_fuse")
+        | _fuse_keys("token_fuse")
+        | {"history_encoder.start", "history_encoder.mlp.0.weight", "history_encoder.mlp.0.bias"}
+    )
+    expected = _expected_stage_keys(has_time=build_objective(generator).needs_time, extra=extra)
+    assert set(model.state_dict().keys()) == expected
+
+
+@pytest.mark.parametrize("cls", [Stage1Model, Stage2OneShot, Stage2Autoregressive])
+def test_stage_classes_are_stagemodel_subclasses(cls):
+    assert issubclass(cls, StageModel)
+
+
+@pytest.mark.parametrize("cls", [Stage1Model, Stage2OneShot, Stage2Autoregressive])
+@pytest.mark.parametrize("generator", ["flow", "ddpm", "wgan"])
+def test_stagemodel_time_emb_matches_objective_needs_time(cls, generator):
+    kwargs = dict(
+        pdg_vocab=5,
+        mat_vocab=3,
+        particle_cfg=PARTICLE_CFG,
+        material_cfg=MATERIAL_CFG,
+        hidden_dim=_STAGE_HIDDEN_DIM,
+        n_res_blocks=_STAGE_N_BLOCKS,
+        cond_out_dim=_STAGE_COND_OUT_DIM,
+        generator=generator,
+        time_dim=8,
+        noise_dim=8,
+    )
+    if cls is Stage1Model:
+        kwargs["n_sec_head_k_max"] = 15
+    else:
+        kwargs["k_max"] = 15
+    model = cls(**kwargs)
+    assert model.generator_kind == generator
+    assert model.noise_dim == 8
+    assert (model.time_emb is not None) == build_objective(generator).needs_time

tests/test_objectives.py

@@ -0,0 +1,251 @@
+"""Tests for `giant/model/objectives.py` — the generator/objective registry
+(gitea #32) that replaced bare `generator in ("flow", "ddpm", "wgan")`
+string checks scattered across models.py/sample.py/builders.py/
+stage2_inputs.py/trainers.py."""
+
+import pytest
+import torch
+
+from giant.config import ConditioningAxisConfig
+from giant.constants import COND_DIM, CONT_SLOT_DIM, PARTICLE_PHYS_DIM, SEC_SLOT_DIM, X_DIM
+from giant.model.network import (
+    OBJECTIVE_REGISTRY,
+    DdpmObjective,
+    FlowObjective,
+    Stage1Model,
+    Stage2Autoregressive,
+    Stage2OneShot,
+    WganObjective,
+    build_objective,
+)
+from giant.model.schedule import CosineSchedule, flow_matching_loss, flow_matching_loss_secondary
+
+_PHYS_CFG = ConditioningAxisConfig(type="physical", emb_dim=8, n_layers=1)
+
+
+def _cond(B: int, pdg: int = 3, mat: int = 2) -> tuple[torch.Tensor, torch.Tensor]:
+    cond_cont = torch.randn(B, COND_DIM)
+    cond_cat = torch.stack([torch.randint(0, pdg, (B,)), torch.randint(0, mat, (B,))], dim=1)
+    return cond_cont, cond_cat
+
+
+# ── registry ─────────────────────────────────────────────────────────────
+
+
+def test_registry_has_exactly_the_three_known_objectives():
+    assert set(OBJECTIVE_REGISTRY) == {"flow", "ddpm", "wgan"}
+
+
+def test_build_objective_returns_correct_concrete_type():
+    assert isinstance(build_objective("flow"), FlowObjective)
+    assert isinstance(build_objective("ddpm"), DdpmObjective)
+    assert isinstance(build_objective("wgan"), WganObjective)
+
+
+def test_build_objective_unknown_name_raises():
+    with pytest.raises(ValueError, match="unknown generator/objective"):
+        build_objective("bogus")
+
+
+def test_build_objective_filters_kwargs_by_signature():
+    # FlowObjective takes no constructor args — n_steps (a DdpmObjective-only
+    # kwarg) must be silently dropped, not raise a TypeError.
+    build_objective("flow", n_steps=500)
+    ddpm = build_objective("ddpm", n_steps=250)
+    assert isinstance(ddpm, DdpmObjective)
+    assert ddpm.n_steps == 250
+
+
+# ── flags ────────────────────────────────────────────────────────────────
+
+
+def test_flow_objective_flags():
+    obj = build_objective("flow")
+    assert obj.needs_time is True
+    assert obj.is_adversarial is False
+    assert obj.folds_type_slice is False
+    assert obj.supports_stage2_decoder is True
+
+
+def test_ddpm_objective_flags():
+    obj = build_objective("ddpm")
+    assert obj.needs_time is True
+    assert obj.is_adversarial is False
+    assert obj.folds_type_slice is False
+    assert obj.supports_stage2_decoder is False
+
+
+def test_wgan_objective_flags():
+    obj = build_objective("wgan")
+    assert obj.needs_time is False
+    assert obj.is_adversarial is True
+    assert obj.folds_type_slice is True
+    assert obj.supports_stage2_decoder is True
+
+
+# ── trunk_in_dim ─────────────────────────────────────────────────────────
+
+
+def test_trunk_in_dim_flow_and_ddpm_pass_through_out_dim():
+    assert build_objective("flow").trunk_in_dim(out_dim=9, noise_dim=8) == 9
+    assert build_objective("ddpm").trunk_in_dim(out_dim=9, noise_dim=8) == 9
+
+
+def test_trunk_in_dim_wgan_uses_noise_dim():
+    assert build_objective("wgan").trunk_in_dim(out_dim=9, noise_dim=8) == 8
+
+
+# ── ddpm schedule ────────────────────────────────────────────────────────
+
+
+def test_ddpm_build_schedule_has_requested_length():
+    schedule = build_objective("ddpm").build_schedule(n_steps=17, device=torch.device("cpu"))
+    assert isinstance(schedule, CosineSchedule)
+    assert schedule.T == 17
+
+
+def test_flow_and_wgan_build_schedule_is_none():
+    assert build_objective("flow").build_schedule(100, torch.device("cpu")) is None
+    assert build_objective("wgan").build_schedule(100, torch.device("cpu")) is None
+
+
+# ── stage1_loss parity ──────────────────────────────────────────────────
+
+
+def test_flow_objective_stage1_loss_matches_direct_call():
+    torch.manual_seed(0)
+    model = Stage1Model(
+        pdg_vocab=3, mat_vocab=2, particle_cfg=_PHYS_CFG, material_cfg=_PHYS_CFG, hidden_dim=16, n_res_blocks=1
+    )
+    cond_cont, cond_cat = _cond(4)
+    x1 = torch.randn(4, X_DIM)
+
+    torch.manual_seed(1)
+    expected = flow_matching_loss(model, x1, cond_cont, cond_cat)
+    torch.manual_seed(1)
+    actual = build_objective("flow").stage1_loss(model, x1, cond_cont, cond_cat)
+    assert torch.allclose(actual, expected)
+
+
+def test_ddpm_objective_stage1_loss_matches_direct_call():
+    torch.manual_seed(0)
+    model = Stage1Model(
+        pdg_vocab=3,
+        mat_vocab=2,
+        particle_cfg=_PHYS_CFG,
+        material_cfg=_PHYS_CFG,
+        hidden_dim=16,
+        n_res_blocks=1,
+        generator="ddpm",
+    )
+    cond_cont, cond_cat = _cond(4)
+    x1 = torch.randn(4, X_DIM)
+    objective = build_objective("ddpm", n_steps=50)
+    schedule = objective.build_schedule(50, torch.device("cpu"))
+    assert isinstance(schedule, CosineSchedule)
+
+    torch.manual_seed(1)
+    expected = schedule.loss(model, x1, cond_cont, cond_cat)
+    torch.manual_seed(1)
+    actual = objective.stage1_loss(model, x1, cond_cont, cond_cat, schedule=schedule)
+    assert torch.allclose(actual, expected)
+
+
+def test_ddpm_objective_stage1_loss_requires_a_schedule():
+    model = Stage1Model(
+        pdg_vocab=3,
+        mat_vocab=2,
+        particle_cfg=_PHYS_CFG,
+        material_cfg=_PHYS_CFG,
+        hidden_dim=16,
+        n_res_blocks=1,
+        generator="ddpm",
+    )
+    cond_cont, cond_cat = _cond(4)
+    with pytest.raises(AssertionError):
+        build_objective("ddpm").stage1_loss(model, torch.randn(4, X_DIM), cond_cont, cond_cat, schedule=None)
+
+
+# ── stage2_loss dispatch ─────────────────────────────────────────────────
+
+
+def test_flow_objective_stage2_loss_one_shot_matches_direct_call():
+    torch.manual_seed(0)
+    B, k_max = 4, 5
+    sec_dim = k_max * SEC_SLOT_DIM
+    model = Stage2OneShot(
+        pdg_vocab=3,
+        mat_vocab=2,
+        particle_cfg=_PHYS_CFG,
+        material_cfg=_PHYS_CFG,
+        hidden_dim=16,
+        n_res_blocks=1,
+        generator="flow",
+        sec_dim=sec_dim,
+        k_max=k_max,
+    )
+    cond_cont, cond_cat = _cond(B)
+    stage1_ctx = torch.randn(B, X_DIM)
+    x1_s2 = torch.randn(B, sec_dim)
+    sec_mask = torch.ones(B, k_max, dtype=torch.bool)
+
+    torch.manual_seed(1)
+    expected = flow_matching_loss_secondary(model, x1_s2, cond_cont, cond_cat, stage1_ctx, sec_mask, type_dim=None)
+    torch.manual_seed(1)
+    actual = build_objective("flow").stage2_loss(
+        model, x1_s2, cond_cont, cond_cat, stage1_ctx, sec_mask, type_dim=None, ar_inputs=None
+    )
+    assert torch.allclose(actual, expected)
+
+
+def test_flow_objective_stage2_loss_dispatches_to_ar_when_ar_inputs_given():
+    torch.manual_seed(0)
+    B, k_max = 4, 5
+    model = Stage2Autoregressive(
+        pdg_vocab=3,
+        mat_vocab=2,
+        particle_cfg=_PHYS_CFG,
+        material_cfg=_PHYS_CFG,
+        hidden_dim=16,
+        n_res_blocks=1,
+        generator="flow",
+        k_max=k_max,
+    )
+    cond_cont, cond_cat = _cond(B)
+    stage1_ctx = torch.randn(B, X_DIM)
+    token_dim = CONT_SLOT_DIM + PARTICLE_PHYS_DIM
+    x1_s2 = torch.randn(B, k_max, token_dim)
+    sec_mask = torch.ones(B, k_max, dtype=torch.bool)
+    ar_inputs = {
+        "history_feat": torch.randn(B, k_max, token_dim),
+        "has_prev": torch.ones(B, k_max, dtype=torch.bool),
+        "remaining_frac": torch.rand(B, k_max),
+        "slot_idx": torch.linspace(0, 1, k_max).unsqueeze(0).expand(B, -1),
+    }
+
+    loss = build_objective("flow").stage2_loss(
+        model, x1_s2, cond_cont, cond_cat, stage1_ctx, sec_mask, type_dim=None, ar_inputs=ar_inputs
+    )
+    assert loss.dim() == 0
+    assert torch.isfinite(loss)
+
+
+def test_ddpm_objective_stage2_loss_not_implemented():
+    dummy_model = torch.nn.Module()
+    dummy = torch.zeros(1)
+    with pytest.raises(NotImplementedError):
+        build_objective("ddpm").stage2_loss(
+            dummy_model, dummy, dummy, dummy, dummy, torch.ones(1, 1, dtype=torch.bool), type_dim=None
+        )
+
+
+def test_wgan_objective_has_no_loss_methods():
+    dummy_model = torch.nn.Module()
+    dummy = torch.zeros(1)
+    objective = build_objective("wgan")
+    with pytest.raises(NotImplementedError):
+        objective.stage1_loss(dummy_model, dummy, dummy, dummy)
+    with pytest.raises(NotImplementedError):
+        objective.stage2_loss(
+            dummy_model, dummy, dummy, dummy, dummy, torch.ones(1, 1, dtype=torch.bool), type_dim=None
+        )

tests/test_phase2.py

@@ -4,6 +4,7 @@ import numpy as np
 import pytest
 import torch
 
+from giant.config import ConditioningAxisConfig
 from giant.constants import (
     COND_DIM,
     CONT_SLOT_DIM,
@@ -23,9 +24,9 @@ from giant.sample import sample_secondaries
 # ── helpers ──────────────────────────────────────────────────────────────────
 
 
-def _particle_material_cfg(conditioning: str) -> tuple[dict, dict]:
-    cfg = {"type": conditioning, "emb_dim": 16, "n_layers": 1}
-    return dict(cfg), dict(cfg)
+def _particle_material_cfg(conditioning: str) -> tuple[ConditioningAxisConfig, ConditioningAxisConfig]:
+    cfg = ConditioningAxisConfig(type=conditioning, emb_dim=16, n_layers=1)
+    return cfg, cfg
 
 
 def _stage1(pdg=3, mat=2, conditioning="embedding"):
@@ -626,3 +627,53 @@ def test_decode_secondaries_mass_charge_round_trip_with_normalizer():
     _, _, sec_mass, sec_charge, _ = decode_secondaries(sec_cont_normed, n_sec, e_sec, pre_dir, sec_phys_normalizer=norm)
     assert sec_mass[0, 0] == pytest.approx(938.27208943, abs=1e-2)
     assert sec_charge[0, 0] == pytest.approx(1.0, abs=1e-4)
+
+
+def test_decode_secondaries_extreme_negative_log_mass_stays_nonnegative():
+    from giant.data.transforms import decode_secondaries, log_transform
+
+    N = 1
+    e_sec = np.array([5.0], dtype=np.float32)
+    n_sec = np.array([1])
+    pre_dir = np.array([[0.0, 0.0, 1.0]], dtype=np.float32)
+
+    sec_cont = np.zeros((N, K_MAX, 6), dtype=np.float32)
+    sec_cont[0, 0, 0] = 10.0  # stick logit -> ~all of e_sec
+    sec_cont[0, 0, 1:4] = [0, 0, 1]
+    sec_cont[0, 0, 4] = -50.0  # raw model prediction: extremely negative log_mass
+    sec_cont[0, 0, 5] = 1.0
+
+    _, _, sec_mass, _, _ = decode_secondaries(sec_cont, n_sec, e_sec, pre_dir)
+
+    # A raw model prediction isn't itself the output of log_transform, so
+    # naively applying inv_log_transform can undershoot zero (see
+    # decode_secondaries) — which then crashes the next log_transform call
+    # once this mass is fed back in as conditioning during rollout. The
+    # float32 residual from clipping can land a hair below zero, but must
+    # stay well above -eps so log_transform(mass) stays finite.
+    assert sec_mass[0, 0] > -1e-8
+    log_transform(sec_mass[0, 0])
+
+
+def test_decode_secondaries_extreme_positive_log_mass_stays_finite():
+    from giant.data.transforms import decode_secondaries, log_transform
+
+    N = 1
+    e_sec = np.array([5.0], dtype=np.float32)
+    n_sec = np.array([1])
+    pre_dir = np.array([[0.0, 0.0, 1.0]], dtype=np.float32)
+
+    sec_cont = np.zeros((N, K_MAX, 6), dtype=np.float32)
+    sec_cont[0, 0, 0] = 10.0  # stick logit -> ~all of e_sec
+    sec_cont[0, 0, 1:4] = [0, 0, 1]
+    sec_cont[0, 0, 4] = 200.0  # raw model prediction: extremely positive log_mass
+    sec_cont[0, 0, 5] = 1.0
+
+    _, _, sec_mass, _, _ = decode_secondaries(sec_cont, n_sec, e_sec, pre_dir)
+
+    # Mirror image of the extreme-negative case above: exp(log_mass)
+    # overflows float32 to inf for an unclipped raw prediction this large,
+    # which then crashes the next log_transform call the same way a
+    # negative mass would.
+    assert np.isfinite(sec_mass[0, 0])
+    log_transform(sec_mass[0, 0])

tests/test_pipeline.py

@@ -231,7 +231,7 @@ def test_run_train_job_builds_caches_and_persists_material_topn_map(tmp_path, da
 
 def test_run_train_job_no_topn_map_for_physical_target(tmp_path, data):
     cfg = _tiny_cfg()
-    cfg["stage2_model"]["particle_type"] = {"target": "physical", "lambda": 1.0}
+    cfg["stage2_model"]["particle_type"].update({"target": "physical", "lambda": 1.0})
     echo = _run(data, tmp_path / "out", cfg=cfg)
     assert not any("top-N map" in m for m in echo)
 

tests/test_release_tooling.py

@@ -0,0 +1,77 @@
+"""Config-correctness tests for the CI version-bump/tag/changelog automation
+(gitea #50). The workflow YAML itself can only be exercised by a real push to
+master, so these check the two config files it drives (.bumpversion.toml,
+cliff.toml) against real repo content instead.
+"""
+
+import re
+import shutil
+import subprocess
+import tomllib
+from pathlib import Path
+
+import pytest
+
+_ROOT = Path(__file__).resolve().parents[1]
+
+
+def test_bumpversion_search_pattern_matches_pyproject():
+    bump_config = tomllib.loads((_ROOT / ".bumpversion.toml").read_text())["tool"]["bumpversion"]
+    current_version = bump_config["current_version"]
+    search = bump_config["files"][0]["search"].format(current_version=current_version)
+
+    pyproject = (_ROOT / "pyproject.toml").read_text()
+    assert search in pyproject, (
+        f"bumpversion search pattern {search!r} (rendered from .bumpversion.toml's "
+        f"current_version={current_version!r}) not found in pyproject.toml — "
+        "the bump would silently edit nothing"
+    )
+
+
+@pytest.mark.skipif(shutil.which("git-cliff") is None, reason="git-cliff binary not on PATH")
+def test_cliff_config_groups_and_links_commits(tmp_path):
+    repo = tmp_path / "repo"
+    repo.mkdir()
+    subprocess.run(["git", "init", "-q"], cwd=repo, check=True)
+    subprocess.run(["git", "config", "user.name", "test"], cwd=repo, check=True)
+    subprocess.run(["git", "config", "user.email", "test@example.com"], cwd=repo, check=True)
+
+    _commit(repo, "Add class-balanced secondary particle-type loss (gitea #44)")
+    _commit(repo, "Fix leaking secondary energy budget")
+    _commit(repo, "Merge pull request 'Add X' (#1) from fix/issue-1 into master")
+    _commit(repo, "chore: bump version 0.3.3 -> 0.3.4 [skip ci]")
+
+    result = subprocess.run(
+        [
+            "git-cliff",
+            "--config",
+            str(_ROOT / "cliff.toml"),
+            "--repository",
+            str(repo),
+            "--tag",
+            "v0.3.4",
+            "--unreleased",
+        ],
+        capture_output=True,
+        text=True,
+        check=True,
+    )
+    changelog = result.stdout
+
+    assert "## [0.3.4]" in changelog
+    assert "### Added" in changelog
+    assert "### Fixed" in changelog
+    assert re.search(
+        r"\[gitea #44\]\(https://git\.larsbogner\.de/lars/giant/issues/44\)",
+        changelog,
+    )
+    assert "Add class-balanced secondary particle-type loss" in changelog
+    assert "Fix leaking secondary energy budget" in changelog
+    assert "Merge pull request" not in changelog
+    assert "skip ci" not in changelog
+
+
+def _commit(repo: Path, message: str) -> None:
+    (repo / "f.txt").write_text(message)
+    subprocess.run(["git", "add", "f.txt"], cwd=repo, check=True)
+    subprocess.run(["git", "commit", "-q", "-m", message], cwd=repo, check=True)

tests/test_rollout.py

@@ -8,6 +8,7 @@ import numpy as np
 import pytest
 import torch
 
+from giant.config import ConditioningAxisConfig, ParticleTypeConfig
 from giant.constants import TERM_ESCAPED, TERM_MAX_STEPS, TERM_UNKNOWN_PDG, K_MAX
 from giant.data.loader import TopNMap
 from giant.data.transforms import Normalizer
@@ -27,8 +28,8 @@ MAT_MAP = {"G4_AIR": 0, "G4_PbWO4": 1}
 
 
 def _models(conditioning="embedding"):
-    particle_cfg = {"type": conditioning, "emb_dim": 16, "n_layers": 1}
-    material_cfg = {"type": conditioning, "emb_dim": 16, "n_layers": 1}
+    particle_cfg = ConditioningAxisConfig(type=conditioning, emb_dim=16, n_layers=1)
+    material_cfg = ConditioningAxisConfig(type=conditioning, emb_dim=16, n_layers=1)
     s1 = Stage1Model(
         pdg_vocab=3,
         mat_vocab=2,
@@ -365,9 +366,10 @@ def _models_v3(
     k_max=6,
     emb_dim=4,
     stage2_has_n_sec_head=True,
+    stop_token=False,
 ):
-    particle_cfg = {"type": conditioning, "emb_dim": emb_dim, "n_layers": 1}
-    material_cfg = {"type": conditioning, "emb_dim": emb_dim, "n_layers": 1}
+    particle_cfg = ConditioningAxisConfig(type=conditioning, emb_dim=emb_dim, n_layers=1)
+    material_cfg = ConditioningAxisConfig(type=conditioning, emb_dim=emb_dim, n_layers=1)
     # A fresh v0.3.0 Stage1Model — no n_sec_head_k_max, unlike _models() above
     # (n_sec ownership moves to stage 2 by default).
     s1 = Stage1Model(
@@ -380,7 +382,7 @@ def _models_v3(
         generator=generator1,
         noise_dim=8,
     )
-    particle_type_cfg = {"target": target}
+    particle_type_cfg = ParticleTypeConfig(target=target)
     # Explicit kwargs rather than a shared **common dict: a dict() call whose
     # values have heterogeneous types (str/int/dict/bool) widens under static
     # analysis to dict[str, <big union>], which then makes every constructor
@@ -416,7 +418,8 @@ def _models_v3(
             noise_dim=8,
             k_max=k_max,
             particle_type_cfg=particle_type_cfg,
-            build_n_sec_head=stage2_has_n_sec_head,
+            build_n_sec_head=stage2_has_n_sec_head and not stop_token,
+            build_stop_head=stop_token,
         )
     return s1.eval(), s2.eval()
 
@@ -480,6 +483,23 @@ def test_rollout_stage2_owns_n_sec_when_stage1_has_no_head(fake_material_props):
         assert dep + leak == pytest.approx(seeds["pre_E"][i], rel=1e-4)
 
 
+@pytest.mark.parametrize("generator2", ["flow", "wgan"])
+def test_rollout_stop_token_end_to_end(fake_material_props, generator2):
+    """gitea #40: n_sec.mode='stop_token' (no n_sec_head on either stage —
+    resolve_n_sec must return None and let sample_stage2's AR loop derive
+    the count from its own stop head) must still run to completion, produce
+    secondaries, and conserve energy exactly like the 'head' mode."""
+    s1, s2 = _models_v3(decoder="autoregressive", generator2=generator2, stop_token=True)
+    rec = _run_v3(s1, s2)
+    assert len(rec["event_id"]) > 0
+    seeds = _seeds()
+    for i, ev in enumerate(seeds["event_id"]):
+        m = rec["event_id"] == ev
+        dep = rec["edep"][m].sum()
+        leak = rec["pre_E"][m & (rec["termination_reason"] == TERM_ESCAPED)].sum()
+        assert dep + leak == pytest.approx(seeds["pre_E"][i], rel=1e-4)
+
+
 def test_resolve_n_sec_raises_when_neither_stage_owns_head(fake_material_props):
     """Neither stage owning n_sec_head only happens for a
     stage2_model.n_sec.mode other than "head" — not a valid rollout-capable
@@ -557,8 +577,8 @@ COND_MAT_TOPN_MAP = TopNMap(class_map={"G4_AIR": 0, "G4_PbWO4": 1}, other_member
 
 
 def _onehot_conditioning_models():
-    particle_cfg = {"type": "onehot", "emb_dim": len(PDG_MAP), "n_layers": 1}
-    material_cfg = {"type": "onehot", "emb_dim": len(MAT_MAP), "n_layers": 1}
+    particle_cfg = ConditioningAxisConfig(type="onehot", emb_dim=len(PDG_MAP), n_layers=1)
+    material_cfg = ConditioningAxisConfig(type="onehot", emb_dim=len(MAT_MAP), n_layers=1)
     s1 = Stage1Model(
         pdg_vocab=3,
         mat_vocab=2,
@@ -574,7 +594,7 @@ def _onehot_conditioning_models():
         material_cfg=material_cfg,
         hidden_dim=32,
         n_res_blocks=2,
-        sec_dim=stage2_trunk_sec_dim({"target": "physical"}, "flow", K_MAX, 3),
+        sec_dim=stage2_trunk_sec_dim(ParticleTypeConfig(target="physical"), "flow", K_MAX, 3),
         generator="flow",
         time_dim=16,
     )
@@ -637,9 +657,9 @@ def _run_conditioning_and_type_onehot_different_n_classes():
     conditioning.particle.emb_dim (gitea #29)."""
     cond_emb_dim = len(PDG_MAP)  # 3
     type_n_classes = 5  # deliberately different from cond_emb_dim
-    particle_cfg = {"type": "onehot", "emb_dim": cond_emb_dim, "n_layers": 1}
-    material_cfg = {"type": "onehot", "emb_dim": len(MAT_MAP), "n_layers": 1}
-    particle_type_cfg = {"target": "onehot", "n_classes": type_n_classes}
+    particle_cfg = ConditioningAxisConfig(type="onehot", emb_dim=cond_emb_dim, n_layers=1)
+    material_cfg = ConditioningAxisConfig(type="onehot", emb_dim=len(MAT_MAP), n_layers=1)
+    particle_type_cfg = ParticleTypeConfig(target="onehot", n_classes=type_n_classes)
 
     s1 = Stage1Model(
         pdg_vocab=3,

tests/test_router.py

@@ -3,24 +3,32 @@
 import pytest
 import torch
 
+from giant.config import ConditioningAxisConfig
 from giant.constants import COND_DIM, K_MAX, SEC_DIM, X_DIM
 from giant.model.network import (
+    BLOCK_REGISTRY,
+    TRUNK_REGISTRY,
+    AdaLNResBlock,
     ComposedRouter,
     EnergyRouter,
-    MonolithicTrunk,
+    ExpertTrunk,
+    FilmResBlock,
     PdgRouter,
     ProcessRouter,
     ROUTER_REGISTRY,
+    ResBlock,
     RoutedTrunk,
     Stage1Model,
     Stage2OneShot,
+    build_block,
     build_composed_router,
+    build_expert_body,
     build_models,
     build_router,
 )
 
-PARTICLE_CFG = {"type": "physical", "emb_dim": 8, "n_layers": 1}
-MATERIAL_CFG = {"type": "physical", "emb_dim": 8, "n_layers": 1}
+PARTICLE_CFG = ConditioningAxisConfig(type="physical", emb_dim=8, n_layers=1)
+MATERIAL_CFG = ConditioningAxisConfig(type="physical", emb_dim=8, n_layers=1)
 
 
 def _cond(B=8, pdg=3, mat=2):
@@ -144,6 +152,68 @@ def test_build_router_unknown_type_raises():
     raise AssertionError("expected ValueError for unknown router type")
 
 
+# ── TRUNK_REGISTRY / build_expert_body ──────────────────────────────────────
+
+
+def test_trunk_registry_has_resmlp():
+    assert "resmlp" in TRUNK_REGISTRY
+    assert TRUNK_REGISTRY["resmlp"] is ExpertTrunk
+
+
+def test_build_expert_body_unknown_type_raises():
+    try:
+        build_expert_body("nonexistent", in_dim=4, out_dim=4, hidden_dim=8, n_blocks=1, cond_dim=4)
+    except ValueError:
+        return
+    raise AssertionError("expected ValueError for unknown trunk type")
+
+
+# ── BLOCK_REGISTRY / build_block (gitea #34) ────────────────────────────────
+
+
+def test_block_registry_has_add_film_adaln():
+    assert BLOCK_REGISTRY["add"] is ResBlock
+    assert BLOCK_REGISTRY["film"] is FilmResBlock
+    assert BLOCK_REGISTRY["adaln"] is AdaLNResBlock
+
+
+def test_build_block_unknown_type_raises():
+    try:
+        build_block("nonexistent", dim=8, cond_dim=4)
+    except ValueError:
+        return
+    raise AssertionError("expected ValueError for unknown block conditioning type")
+
+
+@pytest.mark.parametrize("block_type", ["add", "film", "adaln"])
+def test_block_forward_shape(block_type):
+    block = build_block(block_type, dim=8, cond_dim=4)
+    x = torch.randn(5, 8)
+    cond = torch.randn(5, 4)
+    out = block(x, cond)
+    assert out.shape == (5, 8)
+
+
+def test_film_res_block_output_invariant_to_cond_at_init():
+    """Zero-initialized film_proj means gamma=beta=0 at construction, so the
+    output must not depend on which cond is passed in."""
+    block = FilmResBlock(dim=8, cond_dim=4)
+    x = torch.randn(5, 8)
+    cond_a = torch.randn(5, 4)
+    cond_b = torch.randn(5, 4)
+    torch.testing.assert_close(block(x, cond_a), block(x, cond_b))
+
+
+def test_adaln_res_block_is_identity_at_init():
+    """Zero-initialized adaln_proj means scale=shift=gate=0 at construction,
+    so the block must be the exact identity function (the 'Zero' in
+    AdaLN-Zero)."""
+    block = AdaLNResBlock(dim=8, cond_dim=4)
+    x = torch.randn(5, 8)
+    cond = torch.randn(5, 4)
+    torch.testing.assert_close(block(x, cond), x)
+
+
 # ── EnergyRouter learn_width / learn_temperature ────────────────────────────
 
 
@@ -993,8 +1063,10 @@ def test_build_models_monolith_when_router_absent():
     stage1, stage2 = models["stage1"], models["stage2"]
     assert isinstance(stage1, Stage1Model)
     assert isinstance(stage2, Stage2OneShot)
-    assert isinstance(stage1.trunk, MonolithicTrunk)
-    assert isinstance(stage2.trunk, MonolithicTrunk)
+    assert not isinstance(stage1.trunk, RoutedTrunk)
+    assert not isinstance(stage2.trunk, RoutedTrunk)
+    assert isinstance(stage1.trunk, ExpertTrunk)
+    assert isinstance(stage2.trunk, ExpertTrunk)
 
 
 def test_build_models_monolith_when_router_disabled():
@@ -1006,8 +1078,10 @@ def test_build_models_monolith_when_router_disabled():
     models = build_models(cfg)
     stage1, stage2 = models["stage1"], models["stage2"]
     assert stage1 is not None and stage2 is not None
-    assert isinstance(stage1.trunk, MonolithicTrunk)
-    assert isinstance(stage2.trunk, MonolithicTrunk)
+    assert not isinstance(stage1.trunk, RoutedTrunk)
+    assert not isinstance(stage2.trunk, RoutedTrunk)
+    assert isinstance(stage1.trunk, ExpertTrunk)
+    assert isinstance(stage2.trunk, ExpertTrunk)
 
 
 def test_build_models_routed_when_enabled():
@@ -1040,6 +1114,59 @@ def test_build_models_routed_when_enabled():
     assert len(stage2.trunk.experts) == 4
 
 
+def test_build_models_explicit_resmlp_trunk_type_matches_default():
+    """stage1_model.trunk.type = 'resmlp' is the default's spelled-out
+    equivalent, not a behaviour change — gitea #33."""
+    default_cfg = _nested_cfg(pdg_vocab=4, mat_vocab=2)
+    explicit_cfg = _nested_cfg(pdg_vocab=4, mat_vocab=2, trunk={"type": "resmlp"})
+    default_stage1 = build_models(default_cfg)["stage1"]
+    explicit_stage1 = build_models(explicit_cfg)["stage1"]
+    assert default_stage1 is not None and explicit_stage1 is not None
+    assert type(default_stage1.trunk) is type(explicit_stage1.trunk) is ExpertTrunk
+    assert default_stage1.trunk.input_proj.weight.shape == explicit_stage1.trunk.input_proj.weight.shape
+    default_params = sum(p.numel() for p in default_stage1.parameters())
+    explicit_params = sum(p.numel() for p in explicit_stage1.parameters())
+    assert default_params == explicit_params
+
+
+def test_build_models_explicit_add_block_conditioning_matches_default():
+    """stage1_model.trunk.block_conditioning = 'add' is the default's
+    spelled-out equivalent, not a behaviour change — gitea #34."""
+    default_cfg = _nested_cfg(pdg_vocab=4, mat_vocab=2)
+    explicit_cfg = _nested_cfg(pdg_vocab=4, mat_vocab=2, trunk={"type": "resmlp", "block_conditioning": "add"})
+    default_stage1 = build_models(default_cfg)["stage1"]
+    explicit_stage1 = build_models(explicit_cfg)["stage1"]
+    assert default_stage1 is not None and explicit_stage1 is not None
+    assert type(default_stage1.trunk.blocks[0]) is type(explicit_stage1.trunk.blocks[0]) is ResBlock
+    default_params = sum(p.numel() for p in default_stage1.parameters())
+    explicit_params = sum(p.numel() for p in explicit_stage1.parameters())
+    assert default_params == explicit_params
+
+
+@pytest.mark.parametrize("block_type,cls", [("film", FilmResBlock), ("adaln", AdaLNResBlock)])
+def test_build_models_selects_block_conditioning(block_type, cls):
+    cfg = _nested_cfg(pdg_vocab=4, mat_vocab=2, trunk={"type": "resmlp", "block_conditioning": block_type})
+    stage1 = build_models(cfg)["stage1"]
+    assert stage1 is not None
+    assert isinstance(stage1.trunk, ExpertTrunk)
+    assert all(isinstance(b, cls) for b in stage1.trunk.blocks)
+
+
+def test_build_models_routed_trunk_uses_block_conditioning_for_every_expert():
+    cfg = _nested_cfg(
+        pdg_vocab=4,
+        mat_vocab=2,
+        trunk={"type": "resmlp", "block_conditioning": "film"},
+        stage1_router={"enabled": True, "type": "energy", "n_experts": 3},
+    )
+    stage1 = build_models(cfg)["stage1"]
+    assert stage1 is not None
+    assert isinstance(stage1.trunk, RoutedTrunk)
+    assert len(stage1.trunk.experts) == 3
+    for expert in stage1.trunk.experts:
+        assert all(isinstance(b, FilmResBlock) for b in expert.blocks)
+
+
 def test_build_models_routed_pair_is_drop_in_for_sample_flow():
     """Exercise the exact calling convention giant/sample.py uses."""
     from giant.sample import sample_flow, sample_secondaries
@@ -1068,3 +1195,37 @@ def test_build_models_routed_pair_is_drop_in_for_sample_flow():
     )
     assert sec_cont.shape == (B, K_MAX, 4)
     assert sec_valid.shape == (B, K_MAX)
+
+
+def test_routed_and_unrouted_trunk_agree_on_dtype_under_bf16_autocast():
+    """gitea #47 regression: `_route_forward`'s accumulator (giant/model/
+    trunks.py) used to be a hard-fp32 `torch.zeros`, so under autocast a
+    `RoutedTrunk` returned fp32 while an unrouted `ExpertTrunk` returned
+    bf16 — `router.enabled` alone silently changed the model's output dtype.
+    Checked in both train mode (the differentiable mixture sum) and eval
+    mode (the masked `out[mask] = expert(...)` dispatch) — the two branches
+    of `_route_forward` had independent copies of the bug."""
+    torch.manual_seed(0)
+    cond_cont, cond_cat = _cond(B=6)
+    x = torch.randn(6, X_DIM)
+    t = torch.rand(6)
+
+    unrouted = Stage1Model(
+        pdg_vocab=3,
+        mat_vocab=2,
+        particle_cfg=PARTICLE_CFG,
+        material_cfg=MATERIAL_CFG,
+        hidden_dim=16,
+        n_res_blocks=2,
+    )
+    routed = _routed_stage1(n_experts=3)
+
+    for train_mode in (True, False):
+        unrouted.train(train_mode)
+        routed.train(train_mode)
+        with torch.autocast("cpu", dtype=torch.bfloat16, enabled=True):
+            out_unrouted = unrouted(x, cond_cont, cond_cat, t=t)
+            out_routed = routed(x, cond_cont, cond_cat, t=t)
+        assert out_unrouted.dtype == out_routed.dtype, (
+            f"train={train_mode}: unrouted returned {out_unrouted.dtype}, routed returned {out_routed.dtype}"
+        )

tests/test_sample.py

@@ -5,6 +5,7 @@ for the one-shot samplers."""
 import pytest
 import torch
 
+from giant.config import ConditioningAxisConfig, ParticleTypeConfig
 from giant.constants import COND_DIM, CONT_SLOT_DIM, K_MAX, PARTICLE_PHYS_DIM, X_DIM
 from giant.model.network import (
     Stage1Model,
@@ -20,12 +21,12 @@ from giant.sample import (
     sample_wgan,
 )
 
-_PHYS_CFG = {"type": "physical", "emb_dim": 8, "n_layers": 1}
+_PHYS_CFG = ConditioningAxisConfig(type="physical", emb_dim=8, n_layers=1)
 
 
-def _particle_material_cfg(conditioning: str, emb_dim: int) -> tuple[dict, dict]:
-    cfg = {"type": conditioning, "emb_dim": emb_dim, "n_layers": 1}
-    return dict(cfg), dict(cfg)
+def _particle_material_cfg(conditioning: str, emb_dim: int) -> tuple[ConditioningAxisConfig, ConditioningAxisConfig]:
+    cfg = ConditioningAxisConfig(type=conditioning, emb_dim=emb_dim, n_layers=1)
+    return cfg, cfg
 
 
 def _cond(B: int, pdg: int = 3, mat: int = 2) -> tuple[torch.Tensor, torch.Tensor]:
@@ -43,7 +44,7 @@ def _conditioning_for(target: str) -> str:
 
 def _stage2_oneshot(target: str, generator: str, emb_dim: int = 6, pdg: int = 3, mat: int = 2) -> Stage2OneShot:
     particle_cfg, material_cfg = _particle_material_cfg(_conditioning_for(target), emb_dim)
-    particle_type_cfg = {"target": target}
+    particle_type_cfg = ParticleTypeConfig(target=target)
     # build_models (giant/model/network.py) computes sec_dim this same way
     # before constructing Stage2OneShot — its own default (SEC_DIM, the
     # "physical" width) is only correct for target="physical".
@@ -84,7 +85,7 @@ def _stage2_ar(
         time_dim=16,
         noise_dim=8,
         k_max=k_max,
-        particle_type_cfg={"target": target},
+        particle_type_cfg=ParticleTypeConfig(target=target),
         history=history,
         attn_n_heads=2,
         attn_n_layers=1,
@@ -95,6 +96,45 @@ def _expected_type_dim(target: str, emb_dim: int) -> int:
     return PARTICLE_PHYS_DIM if target == "physical" else emb_dim
 
 
+def _stage2_ar_stop_token(
+    target: str,
+    generator: str,
+    stop_sampling: str = "greedy",
+    emb_dim: int = 6,
+    pdg: int = 3,
+    mat: int = 2,
+    k_max: int = 5,
+) -> Stage2Autoregressive:
+    particle_cfg, material_cfg = _particle_material_cfg(_conditioning_for(target), emb_dim)
+    return Stage2Autoregressive(
+        pdg_vocab=pdg,
+        mat_vocab=mat,
+        particle_cfg=particle_cfg,
+        material_cfg=material_cfg,
+        hidden_dim=32,
+        n_res_blocks=2,
+        generator=generator,
+        time_dim=16,
+        noise_dim=8,
+        k_max=k_max,
+        particle_type_cfg=ParticleTypeConfig(target=target),
+        build_n_sec_head=False,
+        build_stop_head=True,
+        stop_sampling=stop_sampling,
+    ).eval()
+
+
+def _force_stop_head_logit(decoder: Stage2Autoregressive, logit: float) -> None:
+    """Zeroes stop_head's weights and pins its bias, so predict_stop returns
+    `logit` for every row/slot regardless of conditioning — makes the AR
+    loop's stop decision deterministic for testing."""
+    assert decoder.stop_head is not None
+    last_linear = decoder.stop_head[-1]
+    with torch.no_grad():
+        last_linear.weight.zero_()
+        last_linear.bias.fill_(logit)
+
+
 # ── Stage-1 n_sec ownership ──────────────────────────────────────────────────
 
 
@@ -222,3 +262,77 @@ def test_sample_secondaries_ar_first_slot_has_no_history():
     sec_cont, sec_type, sec_valid = sample_secondaries_ar(decoder, cond_cont, cond_cat, stage1_out, n_sec_pred, steps=2)
     assert sec_cont.shape == (B, 1, CONT_SLOT_DIM)
     assert sec_valid.tolist() == [[False], [True], [True]]
+
+
+# ── Stage2Autoregressive: n_sec.mode = "stop_token" ─────────────────────────
+
+
+@pytest.mark.parametrize("stop_sampling", ["greedy", "sample"])
+def test_sample_secondaries_ar_stop_token_forced_stop_gives_zero_secondaries(stop_sampling):
+    """A stop_head pinned to a large positive logit fires at slot 0 for
+    every row under both policies (greedy: sigmoid(logit) >= 0.5; sample:
+    a Bernoulli draw at sigmoid(logit) ~= 1) — the loop should break before
+    generating any token."""
+    B, k_max = 4, 5
+    decoder = _stage2_ar_stop_token("physical", "flow", stop_sampling=stop_sampling, k_max=k_max)
+    _force_stop_head_logit(decoder, 50.0)
+    cond_cont, cond_cat = _cond(B)
+    stage1_out = torch.randn(B, X_DIM)
+    sec_cont, sec_type, sec_valid = sample_secondaries_ar(decoder, cond_cont, cond_cat, stage1_out, None, steps=2)
+    assert sec_valid.shape == (B, k_max)
+    assert not sec_valid.any()
+
+
+@pytest.mark.parametrize("stop_sampling", ["greedy", "sample"])
+def test_sample_secondaries_ar_stop_token_forced_never_stop_runs_to_k_max(stop_sampling):
+    """A stop_head pinned to a large negative logit never fires under either
+    policy, so every row is capped at k_max (the safety cap, not a modeling
+    ceiling)."""
+    B, k_max = 4, 5
+    decoder = _stage2_ar_stop_token("physical", "flow", stop_sampling=stop_sampling, k_max=k_max)
+    _force_stop_head_logit(decoder, -50.0)
+    cond_cont, cond_cat = _cond(B)
+    stage1_out = torch.randn(B, X_DIM)
+    sec_cont, sec_type, sec_valid = sample_secondaries_ar(decoder, cond_cont, cond_cat, stage1_out, None, steps=2)
+    assert sec_valid.all()
+
+
+@pytest.mark.parametrize("generator", ["flow", "wgan"])
+def test_sample_secondaries_ar_stop_token_valid_mask_is_always_a_prefix(generator):
+    """Without forcing the stop head, per-row stop timing varies — but
+    sec_valid must always be a contiguous prefix (slot k valid implies every
+    slot < k is also valid), matching the "head"/"truth" contract."""
+    B, k_max = 6, 5
+    decoder = _stage2_ar_stop_token("physical", generator, k_max=k_max)
+    cond_cont, cond_cat = _cond(B)
+    stage1_out = torch.randn(B, X_DIM)
+    _, _, sec_valid = sample_secondaries_ar(decoder, cond_cont, cond_cat, stage1_out, None, steps=2)
+    n = sec_valid.sum(dim=-1)
+    expected = torch.arange(k_max).unsqueeze(0) < n.unsqueeze(1)
+    assert torch.equal(sec_valid, expected)
+
+
+def test_sample_secondaries_ar_stop_token_explicit_n_sec_pred_ignores_stop_head():
+    """The scheduled-sampling training contract: passing n_sec_pred
+    explicitly (as _assemble_stage2_ar_inputs_scheduled's self-sample call
+    does, with ground-truth n_sec) must run the full k_max loop and mask by
+    the given count, even though the decoder owns a stop_head that would
+    otherwise stop early."""
+    B, k_max = 3, 5
+    decoder = _stage2_ar_stop_token("physical", "flow", k_max=k_max)
+    _force_stop_head_logit(decoder, 50.0)  # would stop immediately if consulted
+    cond_cont, cond_cat = _cond(B)
+    stage1_out = torch.randn(B, X_DIM)
+    n_sec_pred = torch.tensor([0, 2, k_max])
+    _, _, sec_valid = sample_secondaries_ar(decoder, cond_cont, cond_cat, stage1_out, n_sec_pred, steps=2)
+    for i, n in enumerate(n_sec_pred.tolist()):
+        assert sec_valid[i, :n].all()
+        assert not sec_valid[i, n:].any()
+
+
+def test_sample_secondaries_ar_none_n_sec_pred_without_stop_head_raises():
+    decoder = _stage2_ar("physical", "flow", k_max=5)  # head mode: no stop_head
+    cond_cont, cond_cat = _cond(3)
+    stage1_out = torch.randn(3, X_DIM)
+    with pytest.raises(AssertionError):
+        sample_secondaries_ar(decoder, cond_cont, cond_cat, stage1_out, None, steps=2)

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():

tests/test_train.py

@@ -5,11 +5,14 @@ import csv
 import math
 import tempfile
 from pathlib import Path
-from unittest.mock import MagicMock
+from unittest.mock import MagicMock, patch
 
+import numpy as np
 import pytest
 import torch
+import torch.nn.functional as F
 
+from giant.config import ParticleTypeConfig
 from giant.constants import (
     COND_DIM,
     CONT_SLOT_DIM,
@@ -18,16 +21,22 @@ from giant.constants import (
     SEC_SLOT_DIM,
     X_DIM,
 )
+from giant.checkpoint_io import load_for_inference
 from giant.data.dataset import StepBatch
-from giant.model.network import build_critics, build_models
+from giant.data.transforms import Normalizer
+from giant.model.network import Stage2Autoregressive, build_critics, build_models
+from giant.sample import sample_stage1 as trainers_sample_stage1
 from giant.training import (
     FlowDDPMStageTrainer,
     StageSpec,
     WGANStageTrainer,
+    build_checkpoint,
     build_stage_trainers,
+    init_stages_from_checkpoints,
     train,
 )
 from giant.training.metrics import _wandb_run_config
+from giant.training.trainers import _type_class_weight_vector
 from giant.training.stage2_inputs import (
     _ar_has_prev,
     _assemble_stage2_ar_inputs,
@@ -39,6 +48,7 @@ from giant.training.stage2_inputs import (
     _shift_prev,
     _stage2_tf_prob,
     _stick_fraction,
+    _stop_target_and_mask,
     _type_repr,
 )
 
@@ -119,6 +129,23 @@ def test_ar_has_prev_false_only_at_slot_zero():
     assert has_prev.tolist() == [[False, True, True, True, True]]
 
 
+def test_stop_target_and_mask_hand_computed():
+    # k_max=5; n_sec=0 (no real secondaries, stop slot is 0), n_sec=2
+    # (stop slot is 2), n_sec=5 (== k_max: no in-range stop slot at all).
+    n_sec = torch.tensor([0, 2, 5])
+    target, mask = _stop_target_and_mask(n_sec, 5, torch.device("cpu"))
+    assert target.tolist() == [
+        [1, 0, 0, 0, 0],
+        [0, 0, 1, 0, 0],
+        [0, 0, 0, 0, 0],
+    ]
+    assert mask.tolist() == [
+        [True, False, False, False, False],
+        [True, True, True, False, False],
+        [True, True, True, True, True],
+    ]
+
+
 # --- _stage2_tf_prob (v0.3.0 step 7) -----------
 
 
@@ -158,7 +185,7 @@ def test_type_repr_shapes_and_values(target):
     cond_enc = torch.nn.Module()
     if target == "embedding":
         cond_enc.pdg_emb = torch.nn.Embedding(emb_dim, emb_dim)
-    repr_ = _type_repr(sec_type_idx, sec_cont, {"target": target}, cond_enc, emb_dim)
+    repr_ = _type_repr(sec_type_idx, sec_cont, ParticleTypeConfig(target=target), cond_enc, emb_dim)
     expected_width = PARTICLE_PHYS_DIM if target == "physical" else emb_dim
     assert repr_.shape == (B, K, expected_width)
     if target == "physical":
@@ -187,7 +214,7 @@ def test_assemble_stage2_ar_target_matches_assemble_stage2_real_flattened(target
     cond_enc = torch.nn.Module()
     if target == "embedding":
         cond_enc.pdg_emb = torch.nn.Embedding(emb_dim, emb_dim)
-    particle_type_cfg = {"target": target}
+    particle_type_cfg = ParticleTypeConfig(target=target)
     flat = _assemble_stage2_real(sec_cont, sec_type_idx, particle_type_cfg, generator, cond_enc, emb_dim)
     unflat = _assemble_stage2_ar_target(sec_cont, sec_type_idx, particle_type_cfg, generator, cond_enc, emb_dim)
     assert torch.equal(unflat.flatten(1), flat)
@@ -198,7 +225,7 @@ def test_assemble_stage2_ar_inputs_shapes_and_history_feat_width():
     sec_cont = torch.randn(B, K_MAX, SEC_SLOT_DIM)
     sec_type_idx = torch.randint(0, emb_dim, (B, K_MAX))
     cond_enc = torch.nn.Module()
-    out = _assemble_stage2_ar_inputs(sec_cont, sec_type_idx, {"target": "physical"}, cond_enc, emb_dim)
+    out = _assemble_stage2_ar_inputs(sec_cont, sec_type_idx, ParticleTypeConfig(target="physical"), cond_enc, emb_dim)
     assert out["history_feat"].shape == (B, K_MAX, CONT_SLOT_DIM + PARTICLE_PHYS_DIM)
     assert out["has_prev"].shape == (B, K_MAX)
     assert out["remaining_frac"].shape == (B, K_MAX)
@@ -332,7 +359,7 @@ def _model_config(cfg):
     }
 
 
-def _run_train(cfg, out_dir, resume_path=None):
+def _run_train(cfg, out_dir, resume_path=None, normalizer_dict=None):
     model_config = _model_config(cfg)
     models = build_models(model_config)
     critics = build_critics(model_config)
@@ -346,7 +373,7 @@ def _run_train(cfg, out_dir, resume_path=None):
         val_loader=val_loader,
         device=torch.device("cpu"),
         out_dir=out_dir,
-        normalizer_dict={"cond": {}, "target": {}, "sec_phys": {}},
+        normalizer_dict=normalizer_dict or {"cond": {}, "target": {}, "sec_phys": {}},
         pdg_map={"22": 0},
         mat_map={"G4_AIR": 0},
         proc_map=None,
@@ -574,6 +601,313 @@ def test_flow_stage_trainer_ddpm_not_implemented_for_stage2():
         FlowDDPMStageTrainer(spec, torch.nn.Linear(1, 1), torch.device("cpu"))
 
 
+# --- gitea #44: class-balanced secondary particle-type loss -----------------
+
+
+def test_type_class_weight_vector_none_scheme_returns_none():
+    assert _type_class_weight_vector({0: 100, 1: 5}, n_classes=2, scheme="none") is None
+
+
+def test_type_class_weight_vector_raises_without_counts():
+    with pytest.raises(ValueError, match="class_counts"):
+        _type_class_weight_vector({}, n_classes=4, scheme="inverse_freq")
+
+
+def test_type_class_weight_vector_inverse_freq_favors_rare_class_and_has_mean_one():
+    weights = _type_class_weight_vector({0: 1000, 1: 10, 2: 1, 3: 1}, n_classes=4, scheme="inverse_freq")
+    assert weights is not None
+    assert len(weights) == 4
+    assert weights[1] > weights[0]  # rarer class -> larger weight
+    assert math.isclose(sum(weights) / len(weights), 1.0, rel_tol=1e-9)
+
+
+def test_type_class_weight_vector_missing_index_clamps_to_count_one():
+    # n_classes=3 but only index 0 was ever observed (e.g. a tiny dataset) —
+    # indices 1/2 must not divide by zero.
+    weights = _type_class_weight_vector({0: 10}, n_classes=3, scheme="inverse_freq")
+    assert weights is not None
+    assert all(math.isfinite(w) for w in weights)
+
+
+def _onehot_flow_stage2_setup():
+    """A built stage-2 model + a batch, under target='onehot' + generator='flow'
+    (mirrors the 'stage2_onehot_target_flow' case in test_train_end_to_end)."""
+    cfg = _base_cfg()
+    cfg["stage2_model"]["generator"] = "flow"
+    cfg["stage2_model"]["particle_type"] = {"target": "onehot", "lambda": 1.0}
+    model_config = _model_config(cfg)
+    model = build_models(model_config)["stage2"]
+    assert model is not None
+    batch = _fake_batches(1, 8)[0]
+    device = torch.device("cpu")
+    cond_cont, cond_cat, x1_s1 = batch.cond_cont, batch.cond_cat, batch.target_s1
+    # Mostly class 0 (common), a few slot 1's set to class 1 (rare) —
+    # PARTICLE_CFG's emb_dim=8, n_classes=0 (inherit) -> 8 type classes.
+    sec_type_idx = torch.zeros(8, K_MAX, dtype=torch.long)
+    sec_type_idx[:, :2] = 1
+    sec_mask = torch.ones(8, K_MAX, dtype=torch.bool)
+    return model, cond_cont, cond_cat, x1_s1, sec_type_idx, sec_mask, device
+
+
+def test_flow_ddpm_trainer_type_loss_none_leaves_weight_unset():
+    model, *_ = _onehot_flow_stage2_setup()
+    spec = StageSpec(
+        name="stage2",
+        is_stage2=True,
+        generator="flow",
+        particle_type=ParticleTypeConfig(target="onehot", class_weighting="none"),
+        particle_type_n_classes=8,
+        ema_decay=0.0,
+    )
+    trainer = FlowDDPMStageTrainer(spec, model, torch.device("cpu"))
+    assert trainer.type_class_weights is None
+
+
+def test_flow_ddpm_trainer_type_loss_matches_manual_weighted_cross_entropy():
+    model, cond_cont, cond_cat, x1_s1, sec_type_idx, sec_mask, device = _onehot_flow_stage2_setup()
+    class_counts = {0: 1000, 1: 10, 2: 1, 3: 1, 4: 1, 5: 1, 6: 1, 7: 1}
+    weights = _type_class_weight_vector(class_counts, n_classes=8, scheme="inverse_freq")
+    spec = StageSpec(
+        name="stage2",
+        is_stage2=True,
+        generator="flow",
+        particle_type=ParticleTypeConfig(target="onehot", class_weighting="inverse_freq"),
+        particle_type_n_classes=8,
+        type_class_weights=weights,
+        ema_decay=0.0,
+    )
+    trainer = FlowDDPMStageTrainer(spec, model, device)
+    assert trainer.type_class_weights is not None
+    stage1_ctx = trainer._stage1_context(x1_s1, cond_cont, cond_cat, epoch=None)
+
+    with torch.no_grad():
+        type_out = model.predict_type(cond_cont, cond_cat, stage1_ctx)
+        weight_t = torch.tensor(weights)
+        ce = F.cross_entropy(type_out.transpose(1, 2), sec_type_idx, weight=weight_t, reduction="none")
+        expected = (ce * sec_mask.float()).sum() / sec_mask.float().sum().clamp(min=1)
+
+        l_type, _ = trainer._type_loss(cond_cont, cond_cat, stage1_ctx, sec_type_idx, sec_mask, device)
+
+    assert torch.allclose(l_type, expected, atol=1e-6)
+
+    # Unweighted trainer, same model/batch — the two losses must differ
+    # (the batch mixes the common and rare classes, so weighting changes the
+    # per-slot contributions), confirming the weight is actually plumbed in.
+    spec_none = StageSpec(
+        name="stage2",
+        is_stage2=True,
+        generator="flow",
+        particle_type=ParticleTypeConfig(target="onehot", class_weighting="none"),
+        particle_type_n_classes=8,
+        ema_decay=0.0,
+    )
+    trainer_none = FlowDDPMStageTrainer(spec_none, model, device)
+    with torch.no_grad():
+        l_type_none, _ = trainer_none._type_loss(cond_cont, cond_cat, stage1_ctx, sec_type_idx, sec_mask, device)
+    assert not torch.allclose(l_type, l_type_none)
+
+
+def test_build_stage_trainers_threads_sec_type_class_counts_into_weights():
+    cfg = _base_cfg()
+    cfg["stage2_model"]["generator"] = "flow"
+    cfg["stage2_model"]["particle_type"] = {
+        "target": "onehot",
+        "lambda": 1.0,
+        "class_weighting": "inverse_freq",
+    }
+    model_config = _model_config(cfg)
+    models = build_models(model_config)
+    critics = build_critics(model_config)
+    class_counts = {i: 100 for i in range(8)}
+    class_counts[1] = 1  # one rare class
+    trainers = build_stage_trainers(
+        cfg, models, critics, torch.device("cpu"), total_train_batches=4, sec_type_class_counts=class_counts
+    )
+    stage2_trainer = trainers["stage2"]
+    assert isinstance(stage2_trainer, FlowDDPMStageTrainer)
+    weights = stage2_trainer.type_class_weights
+    assert weights is not None
+    assert weights[1] > weights[0]
+
+
+def test_build_stage_trainers_no_class_counts_with_none_weighting_is_fine():
+    """The overwhelmingly common case (class_weighting = 'none', the
+    default): build_stage_trainers must not require sec_type_class_counts at
+    all."""
+    cfg = _base_cfg()
+    cfg["stage2_model"]["generator"] = "flow"
+    cfg["stage2_model"].__setitem__("particle_type", {"target": "onehot", "lambda": 1.0})
+    model_config = _model_config(cfg)
+    models = build_models(model_config)
+    critics = build_critics(model_config)
+    trainers = build_stage_trainers(cfg, models, critics, torch.device("cpu"), total_train_batches=4)
+    stage2_trainer = trainers["stage2"]
+    assert isinstance(stage2_trainer, FlowDDPMStageTrainer)
+    assert stage2_trainer.type_class_weights is None
+
+
+# --- gitea #42: freeze / init_from -------------------------------------------
+
+
+def _state_dict_clone(module):
+    return {k: v.clone() for k, v in module.state_dict().items()}
+
+
+def _assert_state_dicts_equal(before, after, label):
+    for key, value in before.items():
+        assert torch.equal(value, after[key]), f"{label}: {key} changed while frozen"
+
+
+def test_frozen_flow_stage_trainer_step_does_not_update_model_or_ema():
+    cfg = _base_cfg()
+    model_config = _model_config(cfg)
+    model = build_models(model_config)["stage1"]
+    assert model is not None
+    spec = StageSpec(name="stage1", is_stage2=False, generator="flow", freeze=True, ema_decay=0.999, steps_per_epoch=4)
+    trainer = FlowDDPMStageTrainer(spec, model, torch.device("cpu"))
+    assert trainer.ema_model is not None
+    model_before = _state_dict_clone(trainer.model)
+    ema_before = _state_dict_clone(trainer.ema_model)
+    for batch in _fake_batches(4, 8):
+        trainer.step(batch, torch.device("cpu"), global_step=1)
+    _assert_state_dicts_equal(model_before, trainer.model.state_dict(), "frozen flow model")
+    _assert_state_dicts_equal(ema_before, trainer.ema_model.state_dict(), "frozen flow ema")
+
+
+def test_frozen_wgan_stage_trainer_step_does_not_update_generator_or_critic():
+    cfg = _base_cfg()
+    cfg["stage1_model"]["generator"] = "wgan"
+    model_config = _model_config(cfg)
+    models = build_models(model_config)
+    critics = build_critics(model_config)
+    assert models["stage1"] is not None and critics["stage1"] is not None
+    spec = StageSpec(
+        name="stage1",
+        is_stage2=False,
+        generator="wgan",
+        freeze=True,
+        n_critic=1,  # a generator step every batch, so a bug would surface immediately
+        ema_decay=0.999,
+        steps_per_epoch=4,
+    )
+    trainer = WGANStageTrainer(spec, models["stage1"], critics["stage1"], torch.device("cpu"))
+    assert trainer.ema_model is not None
+    model_before = _state_dict_clone(trainer.model)
+    critic_before = _state_dict_clone(trainer.critic)
+    ema_before = _state_dict_clone(trainer.ema_model)
+    for global_step, batch in enumerate(_fake_batches(4, 8)):
+        trainer.step(batch, torch.device("cpu"), global_step=global_step)
+    _assert_state_dicts_equal(model_before, trainer.model.state_dict(), "frozen wgan generator")
+    _assert_state_dicts_equal(critic_before, trainer.critic.state_dict(), "frozen wgan critic")
+    _assert_state_dicts_equal(ema_before, trainer.ema_model.state_dict(), "frozen wgan ema")
+
+
+@pytest.mark.parametrize("stage1_generator", ["flow", "wgan"])
+def test_train_end_to_end_frozen_stage1_unchanged_while_stage2_trains(stage1_generator):
+    cfg = _base_cfg()
+    cfg["stage1_model"]["generator"] = stage1_generator
+    cfg["stage1_model"]["freeze"] = True
+    model_config = _model_config(cfg)
+    models = build_models(model_config)
+    critics = build_critics(model_config)
+    assert models["stage1"] is not None and models["stage2"] is not None
+    stage1_before = _state_dict_clone(models["stage1"])
+    stage2_before = _state_dict_clone(models["stage2"])
+    with tempfile.TemporaryDirectory() as tmp:
+        train(
+            cfg=cfg,
+            models=models,
+            critics=critics,
+            train_loader=_fake_batches(4, cfg["train"]["batch_size"]),
+            val_loader=_fake_batches(2, cfg["train"]["batch_size"], seed=1),
+            device=torch.device("cpu"),
+            out_dir=Path(tmp) / "run",
+            normalizer_dict={"cond": {}, "target": {}, "sec_phys": {}},
+            pdg_map={"22": 0},
+            mat_map={"G4_AIR": 0},
+            proc_map=None,
+            model_config=model_config,
+            total_train_batches=4,
+        )
+    _assert_state_dicts_equal(stage1_before, models["stage1"].state_dict(), "frozen stage1")
+    stage2_after = models["stage2"].state_dict()
+    assert any(not torch.equal(v, stage2_after[k]) for k, v in stage2_before.items()), (
+        "unfrozen stage2 should have trained"
+    )
+
+
+def test_init_stages_from_checkpoints_loads_matching_stage_and_ema_weights(tmp_path):
+    cfg = _base_cfg()
+    model_config = _model_config(cfg)
+    source_models = build_models(model_config)
+    source_critics = build_critics(model_config)
+    source_trainers = build_stage_trainers(cfg, source_models, source_critics, torch.device("cpu"), 4)
+    source_stage1_ema = source_trainers["stage1"].ema_model
+    assert source_stage1_ema is not None
+    # Diverge the source's EMA from its raw weights so a same-vs-different
+    # check below actually distinguishes the two copy paths.
+    for p in source_stage1_ema.parameters():
+        p.data.add_(1.0)
+    ckpt_path = tmp_path / "source.pt"
+    ckpt = build_checkpoint(source_trainers, epoch=1, global_step=1, best_val_loss=0.0, extras={})
+    torch.save(ckpt, ckpt_path)
+
+    cfg2 = copy.deepcopy(cfg)
+    cfg2["stage1_model"]["init_from"] = str(ckpt_path)
+    dest_models = build_models(_model_config(cfg2))
+    dest_critics = build_critics(_model_config(cfg2))
+    dest_trainers = build_stage_trainers(cfg2, dest_models, dest_critics, torch.device("cpu"), 4)
+
+    loaded = init_stages_from_checkpoints(dest_trainers)
+    assert len(loaded) == 1 and "stage1" in loaded[0]
+    dest_stage1_ema = dest_trainers["stage1"].ema_model
+    assert dest_stage1_ema is not None
+
+    _assert_state_dicts_equal(
+        source_trainers["stage1"].model.state_dict(), dest_trainers["stage1"].model.state_dict(), "init_from raw"
+    )
+    _assert_state_dicts_equal(
+        source_stage1_ema.state_dict(),
+        dest_stage1_ema.state_dict(),
+        "init_from ema",
+    )
+    # stage2 has no init_from set -- untouched fresh init, not the source's.
+    stage2_matches_source = all(
+        torch.equal(v, dest_trainers["stage2"].model.state_dict()[k])
+        for k, v in source_trainers["stage2"].model.state_dict().items()
+    )
+    assert not stage2_matches_source
+
+
+def test_run_train_job_stage1_init_from_freeze_produces_rollout_capable_checkpoint(tmp_path):
+    """The exact scenario gitea #42 exists for: retrain stage 2 alone against
+    a fixed, known-good stage 1, and still get a checkpoint giant rollout can
+    load (checkpoint_io.load_for_inference with require_stage2=True)."""
+    normalizer_dict = {
+        "cond": Normalizer().fit(np.zeros((1, COND_DIM), dtype=np.float32)).to_dict(),
+        "target": Normalizer().fit(np.zeros((1, X_DIM), dtype=np.float32)).to_dict(),
+        "sec_phys": Normalizer().fit(np.zeros((1, 2), dtype=np.float32)).to_dict(),
+    }
+
+    cfg = _base_cfg()
+    source_out = tmp_path / "source"
+    _run_train(cfg, source_out, normalizer_dict=normalizer_dict)
+    source_ckpt = torch.load(source_out / "best.pt", weights_only=False)
+
+    cfg2 = copy.deepcopy(cfg)
+    cfg2["stage1_model"]["init_from"] = str(source_out / "best.pt")
+    cfg2["stage1_model"]["freeze"] = True
+    retrain_out = tmp_path / "retrain"
+    _run_train(cfg2, retrain_out, normalizer_dict=normalizer_dict)
+
+    ctx = load_for_inference(retrain_out / "best.pt", torch.device("cpu"), "rollout", require_stage2=True)
+    assert ctx.stage1 is not None and ctx.stage2 is not None
+
+    retrain_ckpt = torch.load(retrain_out / "best.pt", weights_only=False)
+    for key, value in source_ckpt["model"].items():
+        assert torch.equal(value, retrain_ckpt["model"][key]), f"frozen stage1 {key} drifted across the retrain"
+
+
 def test_stage_spec_from_config_omitted_decoder_and_particle_type_match_default_config():
     """Regression for issues.md Issue 1: StageSpec.from_config's own fallback
     defaults for stage2_model.decoder/particle_type must equal
@@ -739,6 +1073,71 @@ def test_wgan_onehot_one_shot_also_gets_grad_norm_instrumentation():
         assert any(float(r["stage2/train/grad_norm_cont_slice"]) > 0 for r in rows)
 
 
+# --- n_sec.mode = "stop_token" (gitea #40) ----------------------------------
+
+
+def _stop_token_cfg():
+    cfg = _base_cfg()
+    cfg["stage2_model"]["decoder"] = "autoregressive"
+    cfg["stage2_model"]["n_sec"] = {"mode": "stop_token", "lambda": 0.1}
+    return cfg
+
+
+@pytest.mark.parametrize("stage2_generator", ["wgan", "flow"])
+def test_build_stage_trainers_stop_token_step_runs(stage2_generator):
+    """A stop_token AR stage-2 trainer.step() must run and emit a finite
+    loss_stop for both non-adversarial (flow) and WGAN generators — the two
+    trainer subclasses wire the stop head's BCE term in independently."""
+    cfg = _stop_token_cfg()
+    cfg["stage2_model"]["generator"] = stage2_generator
+    model_config = _model_config(cfg)
+    models = build_models(model_config)
+    critics = build_critics(model_config)
+    trainers = build_stage_trainers(cfg, models, critics, torch.device("cpu"), total_train_batches=4)
+    trainer = trainers["stage2"]
+    batch = _fake_batches(1, 4)[0]
+    stats = trainer.step(batch, torch.device("cpu"), global_step=1)
+    assert math.isfinite(stats["loss_stop"])
+    assert math.isfinite(stats["stop_acc"])
+
+
+def test_stop_token_model_has_stop_head_not_n_sec_head():
+    cfg = _stop_token_cfg()
+    model_config = _model_config(cfg)
+    models = build_models(model_config)
+    stage2 = models["stage2"]
+    assert isinstance(stage2, Stage2Autoregressive)
+    assert stage2.n_sec_head is None
+    assert stage2.stop_head is not None
+
+
+def test_head_mode_model_has_n_sec_head_not_stop_head():
+    """Sanity check on the other side of the gate — the default 'head' mode
+    must be unaffected by the stop_head plumbing."""
+    cfg = _base_cfg()
+    cfg["stage2_model"]["decoder"] = "autoregressive"
+    model_config = _model_config(cfg)
+    models = build_models(model_config)
+    stage2 = models["stage2"]
+    assert isinstance(stage2, Stage2Autoregressive)
+    assert stage2.n_sec_head is not None
+    assert stage2.stop_head is None
+
+
+def test_train_end_to_end_stop_token():
+    """Full train() run with n_sec.mode='stop_token' must complete and write
+    a checkpoint + metrics.csv with finite losses throughout."""
+    cfg = _stop_token_cfg()
+    with tempfile.TemporaryDirectory() as tmp:
+        out_dir = Path(tmp) / "run"
+        _run_train(cfg, out_dir)
+        assert (out_dir / "last.pt").exists()
+        with open(out_dir / "metrics.csv", newline="") as f:
+            rows = list(csv.DictReader(f))
+        assert len(rows) == cfg["train"]["epochs"]
+        assert all(math.isfinite(float(r["stage2/train/loss_stop"])) for r in rows)
+
+
 def test_wgan_physical_omits_grad_norm_slice_columns():
     cfg = _base_cfg()  # _base_cfg's stage2_model.particle_type.target is "physical"
     with tempfile.TemporaryDirectory() as tmp:
@@ -747,3 +1146,127 @@ def test_wgan_physical_omits_grad_norm_slice_columns():
         header = (out_dir / "metrics.csv").read_text().splitlines()[0].split(",")
         assert "stage2/train/grad_norm_type_slice" not in header
         assert "stage2/train/grad_norm_cont_slice" not in header
+
+
+# --- stage2_model.stage1_context = "sampled" (gitea #41) --------------------
+
+
+def _sampled_ctx_cfg(ema_decay=0.999):
+    cfg = _base_cfg()
+    cfg["stage1_model"]["generator"] = "flow"
+    cfg["stage2_model"]["generator"] = "flow"
+    cfg["stage2_model"]["stage1_context"] = "sampled"
+    cfg["stage2_model"]["ctx_p_start"] = 0.0
+    cfg["stage2_model"]["ctx_p_end"] = 0.0
+    cfg["train"]["ema_decay"] = ema_decay
+    return cfg
+
+
+def _build_sampled_trainers(cfg):
+    model_config = _model_config(cfg)
+    models = build_models(model_config)
+    critics = build_critics(model_config)
+    return build_stage_trainers(cfg, models, critics, torch.device("cpu"), total_train_batches=4)
+
+
+def test_build_stage_trainers_attaches_stage1_only_under_sampled():
+    trainers = _build_sampled_trainers(_sampled_ctx_cfg())
+    assert trainers["stage2"].stage1_source is trainers["stage1"]
+    assert trainers["stage1"].stage1_source is None
+
+
+def test_build_stage_trainers_leaves_stage1_source_none_under_truth():
+    """Regression guard for the old silent no-op: 'truth' (the default) must
+    never attach a stage1_source, so _stage1_context short-circuits without
+    ever calling sample_stage1."""
+    cfg = _base_cfg()
+    trainers = _build_sampled_trainers(cfg)
+    assert trainers["stage2"].stage1_source is None
+
+
+def test_stage1_context_sampled_calls_sample_stage1_and_differs_from_truth():
+    cfg = _sampled_ctx_cfg()
+    trainers = _build_sampled_trainers(cfg)
+    stage1, stage2 = trainers["stage1"], trainers["stage2"]
+    batch = _fake_batches(1, 4)[0]
+    cond_cont, cond_cat, x1_s1 = batch.cond_cont, batch.cond_cat, batch.target_s1
+
+    with patch("giant.training.trainers.sample_stage1", wraps=trainers_sample_stage1) as spy:
+        ctx = stage2._stage1_context(x1_s1, cond_cont, cond_cat, epoch=0)
+    assert spy.call_count == 1
+    assert spy.call_args.args[0] is stage1.sampling_model()
+    assert not torch.equal(ctx, x1_s1)
+
+
+def test_stage1_context_truth_default_never_calls_sample_stage1():
+    cfg = _base_cfg()
+    trainers = _build_sampled_trainers(cfg)
+    stage2 = trainers["stage2"]
+    batch = _fake_batches(1, 4)[0]
+    cond_cont, cond_cat, x1_s1 = batch.cond_cont, batch.cond_cat, batch.target_s1
+
+    with patch("giant.training.trainers.sample_stage1", wraps=trainers_sample_stage1) as spy:
+        ctx = stage2._stage1_context(x1_s1, cond_cont, cond_cat, epoch=0)
+    assert spy.call_count == 0
+    assert torch.equal(ctx, x1_s1)
+
+
+def test_stage1_context_val_epoch_none_uses_ground_truth_even_under_sampled():
+    cfg = _sampled_ctx_cfg()
+    trainers = _build_sampled_trainers(cfg)
+    stage2 = trainers["stage2"]
+    batch = _fake_batches(1, 4)[0]
+    cond_cont, cond_cat, x1_s1 = batch.cond_cont, batch.cond_cat, batch.target_s1
+
+    with patch("giant.training.trainers.sample_stage1", wraps=trainers_sample_stage1) as spy:
+        ctx = stage2._stage1_context(x1_s1, cond_cont, cond_cat, epoch=None)
+    assert spy.call_count == 0
+    assert torch.equal(ctx, x1_s1)
+
+
+def test_stage1_context_sampled_preserves_stage1_training_mode():
+    """Every sampler in giant/sample.py flips its model to .eval() as a side
+    effect with no restore of its own (see sample_flow). Sampling from the
+    RAW stage-1 model (ema_decay=0, so sampling_model() returns self.model,
+    the same weights the stage-1 trainer is actively training on) must not
+    silently leave it in eval mode for the rest of the epoch's stage-1
+    updates."""
+    cfg = _sampled_ctx_cfg(ema_decay=0.0)
+    trainers = _build_sampled_trainers(cfg)
+    stage1, stage2 = trainers["stage1"], trainers["stage2"]
+    stage1.train_mode()
+    assert stage1.model.training
+    batch = _fake_batches(1, 4)[0]
+    cond_cont, cond_cat, x1_s1 = batch.cond_cont, batch.cond_cat, batch.target_s1
+
+    stage2._stage1_context(x1_s1, cond_cont, cond_cat, epoch=0)
+    assert stage1.model.training
+
+
+@pytest.mark.parametrize("stage2_generator", ["wgan", "flow"])
+def test_build_stage_trainers_sampled_step_runs(stage2_generator):
+    """Both trainer subclasses' call sites (FlowDDPMStageTrainer._compute,
+    WGANStageTrainer.step) must run end to end under 'sampled' and produce a
+    finite loss."""
+    cfg = _sampled_ctx_cfg()
+    cfg["stage2_model"]["generator"] = stage2_generator
+    trainers = _build_sampled_trainers(cfg)
+    trainer = trainers["stage2"]
+    batch = _fake_batches(1, 4)[0]
+    stats = trainer.step(batch, torch.device("cpu"), global_step=1)
+    loss_key = "g_loss" if stage2_generator == "wgan" else "loss"
+    assert math.isfinite(stats[loss_key])
+
+
+def test_train_end_to_end_stage1_context_sampled():
+    """Full train() run with stage1_context='sampled' must complete and
+    write a checkpoint + metrics.csv with finite losses throughout."""
+    cfg = _sampled_ctx_cfg()
+    with tempfile.TemporaryDirectory() as tmp:
+        out_dir = Path(tmp) / "run"
+        _run_train(cfg, out_dir)
+        assert (out_dir / "last.pt").exists()
+        with open(out_dir / "metrics.csv", newline="") as f:
+            rows = list(csv.DictReader(f))
+        assert len(rows) == cfg["train"]["epochs"]
+        assert all(math.isfinite(float(r["stage2/train/loss"])) for r in rows)

tests/test_transforms.py

@@ -2,6 +2,7 @@ import warnings
 
 import numpy as np
 import pytest
+from giant.cond_layout import AXIS_TYPES, CondLayout
 from giant.constants import COND_DIM, COND_DIM_BASE, K_MAX
 from giant.data.transforms import (
     build_cond_features,
@@ -531,6 +532,129 @@ def test_build_cond_features_rejects_legacy_normalizer_in_physical_mode(
         )
 
 
+# ── build_cond_features / build_features share one column layout (gitea #37) ──
+
+
+@pytest.mark.parametrize("particle_type", AXIS_TYPES)
+@pytest.mark.parametrize("material_type", AXIS_TYPES)
+def test_both_builders_agree_column_for_column(particle_type, material_type, fake_material_props):
+    """The two builders used to lay out cond_cont/cond_cat independently and
+    drift apart silently. They now share `_build_cond_arrays`, so for every
+    mode pair they must produce identical arrays."""
+    data = _minimal_step_data(3)
+    pdg_map, mat_map = {11: 0}, {"PbWO4": 0}
+    pdg_topn = {11: 0} if particle_type == "onehot" else None
+    mat_topn = {"PbWO4": 0} if material_type == "onehot" else None
+
+    cond_cont, cond_cat = build_cond_features(
+        data,
+        pdg_map,
+        mat_map,
+        particle_conditioning=particle_type,
+        material_conditioning=material_type,
+        pdg_topn_map=pdg_topn,
+        mat_topn_map=mat_topn,
+    )
+    feats = build_features(
+        data,
+        pdg_map,
+        mat_map,
+        particle_conditioning=particle_type,
+        material_conditioning=material_type,
+        pdg_topn_map=pdg_topn,
+        mat_topn_map=mat_topn,
+    )
+
+    layout = CondLayout.from_types(particle_type, material_type)
+    assert cond_cat.shape[1] == layout.cat_dim
+    np.testing.assert_array_equal(feats.cond_cont, cond_cont)
+    np.testing.assert_array_equal(feats.cond_cat, cond_cat)
+
+
+def test_build_features_physical_mode_tolerates_out_of_vocab_pdg_and_material():
+    """The permissive vocab lookup added for "physical"/"onehot" mode (see
+    build_cond_features) applies to build_features too — `giant predict` on a
+    file whose pdg/material aren't in the checkpoint's dense vocab must not
+    KeyError when nothing reads those indices."""
+    pdg_map = {11: 0, 22: 1}
+    mat_map = {"G4_AIR": 0}
+    data = _minimal_step_data(2)
+    data["pdg"] = np.full(2, 13, dtype=np.int64)  # not in pdg_map
+    data["material"] = np.full(2, "G4_Pb", dtype=object)  # not in mat_map
+
+    _, cond_cat, *_ = build_features(
+        data,
+        pdg_map,
+        mat_map,
+        particle_conditioning="physical",
+        material_conditioning="physical",
+    )
+    np.testing.assert_array_equal(cond_cat, [[0, 0], [0, 0]])  # dummy indices, no raise
+
+    with pytest.raises(KeyError):
+        build_features(
+            data,
+            pdg_map,
+            mat_map,
+            particle_conditioning="embedding",
+            material_conditioning="embedding",
+        )
+
+
+def test_build_features_pads_legacy_normalizer_in_embedding_mode():
+    """The legacy-normalizer padding (a pre-physical-conditioning checkpoint's
+    cond normalizer is COND_DIM_BASE wide) applies to build_features too —
+    `giant predict` reaches build_features, not build_cond_features."""
+    data = _minimal_step_data(3)
+    pdg_map, mat_map = {11: 0}, {"PbWO4": 0}
+    legacy_norm = Normalizer()
+    legacy_norm.mean = np.zeros(COND_DIM_BASE, dtype=np.float32)
+    legacy_norm.std = np.ones(COND_DIM_BASE, dtype=np.float32)
+
+    cond_cont, *_ = build_features(
+        data,
+        pdg_map,
+        mat_map,
+        cond_normalizer=legacy_norm,
+        particle_conditioning="embedding",
+        material_conditioning="embedding",
+    )
+
+    assert cond_cont.shape[-1] == COND_DIM
+    np.testing.assert_allclose(cond_cont[:, COND_DIM_BASE:], 0.0)
+
+
+def test_build_features_rejects_legacy_normalizer_in_physical_mode(fake_material_props):
+    data = _minimal_step_data(3)
+    pdg_map, mat_map = {11: 0}, {"PbWO4": 0}
+    legacy_norm = Normalizer()
+    legacy_norm.mean = np.zeros(COND_DIM_BASE, dtype=np.float32)
+    legacy_norm.std = np.ones(COND_DIM_BASE, dtype=np.float32)
+
+    with pytest.raises(ValueError, match="predates physical-property conditioning"):
+        build_features(
+            data,
+            pdg_map,
+            mat_map,
+            cond_normalizer=legacy_norm,
+            particle_conditioning="physical",
+            material_conditioning="physical",
+        )
+
+
+def test_onehot_axis_without_its_topn_map_raises():
+    """`cond_cat`'s width is the layout's call, so a "onehot" axis with no
+    top-N map is a hard error rather than a silently-narrower array that
+    ConditionEncoder would then index out of bounds."""
+    data = _minimal_step_data(2)
+    pdg_map, mat_map = {11: 0}, {"PbWO4": 0}
+
+    with pytest.raises(ValueError, match="needs pdg_topn_map"):
+        build_cond_features(data, pdg_map, mat_map, particle_conditioning="onehot")
+    with pytest.raises(ValueError, match="needs mat_topn_map"):
+        build_cond_features(data, pdg_map, mat_map, material_conditioning="onehot")
+
+
 # ── sorted_membership / _vectorized_map_lookup ──────────────────────────────
 
 

tests/test_validate.py

@@ -1,17 +1,18 @@
 import numpy as np
 import torch
 
+from giant.config import ConditioningAxisConfig, ParticleTypeConfig
 from giant.constants import COND_DIM, SEC_SLOT_DIM, X_DIM
 from giant.data.dataset import StepBatch
 from giant.model.network import Stage1Model, Stage2OneShot, stage2_trunk_sec_dim
 from giant.validate import validate_marginals
 
-_PARTICLE_CFG = {"type": "physical", "emb_dim": 8, "n_layers": 1}
-_MATERIAL_CFG = {"type": "physical", "emb_dim": 8, "n_layers": 1}
+_PARTICLE_CFG = ConditioningAxisConfig(type="physical", emb_dim=8, n_layers=1)
+_MATERIAL_CFG = ConditioningAxisConfig(type="physical", emb_dim=8, n_layers=1)
 _K_MAX = 5
 
 
-def _tiny_models(particle_type_cfg: dict | None = None):
+def _tiny_models(particle_type_cfg: ParticleTypeConfig | None = None):
     """A fresh v0.3.0 pair: Stage1Model owns no n_sec_head, so n_sec always
     comes from Stage2OneShot."""
     s1 = Stage1Model(
@@ -22,12 +23,13 @@ def _tiny_models(particle_type_cfg: dict | None = None):
         hidden_dim=16,
         n_res_blocks=1,
     )
-    target = (particle_type_cfg or {}).get("target", "physical")
+    resolved_type_cfg = particle_type_cfg or ParticleTypeConfig(target="physical")
+    target = resolved_type_cfg.target
     sec_dim = stage2_trunk_sec_dim(
-        particle_type_cfg or {"target": "physical"},
+        resolved_type_cfg,
         "flow",
         _K_MAX,
-        int(_PARTICLE_CFG["emb_dim"]),
+        _PARTICLE_CFG.emb_dim,
     )
     s2 = Stage2OneShot(
         pdg_vocab=3,
@@ -42,7 +44,7 @@ def _tiny_models(particle_type_cfg: dict | None = None):
         sec_dim=sec_dim,
         particle_type_cfg=particle_type_cfg,
     )
-    assert s2.particle_type_cfg.get("target", "physical") == target
+    assert s2.particle_type_cfg.target == target
     return s1.eval(), s2.eval()
 
 
@@ -95,7 +97,7 @@ def test_validate_marginals_physical_target_shapes():
 
 
 def test_validate_marginals_onehot_type_class_marginal():
-    particle_type_cfg = {"target": "onehot"}
+    particle_type_cfg = ParticleTypeConfig(target="onehot")
     s1, s2 = _tiny_models(particle_type_cfg)
     loader = _loader(n_sec_value=2, n_classes=s2.type_dim)
 

tests/test_wgan.py

@@ -1,12 +1,13 @@
 import torch
 
+from giant.config import ConditioningAxisConfig
 from giant.constants import COND_DIM, K_MAX, SEC_DIM, SEC_SLOT_DIM, X_DIM
 from giant.model.network import CriticModel, Stage1Model, Stage2OneShot
 from giant.model.wgan import critic_loss, generator_loss, gradient_penalty
 from giant.sample import sample_secondaries_wgan, sample_wgan
 
-PARTICLE_CFG = {"type": "physical", "emb_dim": 8, "n_layers": 1}
-MATERIAL_CFG = {"type": "physical", "emb_dim": 8, "n_layers": 1}
+PARTICLE_CFG = ConditioningAxisConfig(type="physical", emb_dim=8, n_layers=1)
+MATERIAL_CFG = ConditioningAxisConfig(type="physical", emb_dim=8, n_layers=1)
 
 
 def _cond(B=8):

uv.lock

@@ -5,19 +5,19 @@ resolution-markers = [
     "python_full_version >= '3.14' and sys_platform == 'win32' and extra != 'extra-5-giant-cpu' and extra == 'extra-5-giant-cuda'",
     "python_full_version >= '3.14' and sys_platform == 'emscripten' and extra != 'extra-5-giant-cpu' and extra == 'extra-5-giant-cuda'",
     "python_full_version >= '3.14' and sys_platform != 'emscripten' and sys_platform != 'win32' and extra != 'extra-5-giant-cpu' and extra == 'extra-5-giant-cuda'",
-    "python_full_version < '3.14' and sys_platform == 'win32' and extra != 'extra-5-giant-cpu' and extra == 'extra-5-giant-cuda'",
-    "python_full_version < '3.14' and sys_platform == 'emscripten' and extra != 'extra-5-giant-cpu' and extra == 'extra-5-giant-cuda'",
-    "python_full_version < '3.14' and sys_platform != 'emscripten' and sys_platform != 'win32' and extra != 'extra-5-giant-cpu' and extra == 'extra-5-giant-cuda'",
     "python_full_version >= '3.14' and sys_platform == 'win32' and extra == 'extra-5-giant-cpu' and extra != 'extra-5-giant-cuda'",
     "python_full_version >= '3.14' and sys_platform == 'emscripten' and extra == 'extra-5-giant-cpu' and extra != 'extra-5-giant-cuda'",
     "python_full_version >= '3.14' and sys_platform != 'emscripten' and sys_platform != 'win32' and extra == 'extra-5-giant-cpu' and extra != 'extra-5-giant-cuda'",
+    "python_full_version >= '3.14' and sys_platform == 'win32' and extra != 'extra-5-giant-cpu' and extra != 'extra-5-giant-cuda'",
+    "python_full_version >= '3.14' and sys_platform == 'emscripten' and extra != 'extra-5-giant-cpu' and extra != 'extra-5-giant-cuda'",
+    "python_full_version >= '3.14' and sys_platform != 'emscripten' and sys_platform != 'win32' and extra != 'extra-5-giant-cpu' and extra != 'extra-5-giant-cuda'",
+    "python_full_version < '3.14' and sys_platform == 'win32' and extra != 'extra-5-giant-cpu' and extra == 'extra-5-giant-cuda'",
+    "python_full_version < '3.14' and sys_platform == 'emscripten' and extra != 'extra-5-giant-cpu' and extra == 'extra-5-giant-cuda'",
+    "python_full_version < '3.14' and sys_platform != 'emscripten' and sys_platform != 'win32' and extra != 'extra-5-giant-cpu' and extra == 'extra-5-giant-cuda'",
     "python_full_version < '3.14' and sys_platform == 'win32' and extra == 'extra-5-giant-cpu' and extra != 'extra-5-giant-cuda'",
     "python_full_version < '3.14' and sys_platform == 'emscripten' and extra == 'extra-5-giant-cpu' and extra != 'extra-5-giant-cuda'",
     "(python_full_version == '3.13.*' and platform_machine == 'aarch64' and platform_python_implementation == 'CPython' and sys_platform == 'linux' and extra == 'extra-5-giant-cpu' and extra != 'extra-5-giant-cuda') or (python_full_version < '3.14' and platform_machine != 'aarch64' and sys_platform == 'linux' and extra == 'extra-5-giant-cpu' and extra != 'extra-5-giant-cuda') or (python_full_version < '3.14' and platform_python_implementation != 'CPython' and sys_platform == 'linux' and extra == 'extra-5-giant-cpu' and extra != 'extra-5-giant-cuda') or (python_full_version < '3.14' and sys_platform != 'darwin' and sys_platform != 'emscripten' and sys_platform != 'linux' and sys_platform != 'win32' and extra == 'extra-5-giant-cpu' and extra != 'extra-5-giant-cuda')",
     "(python_full_version < '3.13' and platform_machine == 'aarch64' and platform_python_implementation == 'CPython' and sys_platform == 'linux' and extra == 'extra-5-giant-cpu' and extra != 'extra-5-giant-cuda') or (python_full_version < '3.14' and sys_platform == 'darwin' and extra == 'extra-5-giant-cpu' and extra != 'extra-5-giant-cuda')",
-    "python_full_version >= '3.14' and sys_platform == 'win32' and extra != 'extra-5-giant-cpu' and extra != 'extra-5-giant-cuda'",
-    "python_full_version >= '3.14' and sys_platform == 'emscripten' and extra != 'extra-5-giant-cpu' and extra != 'extra-5-giant-cuda'",
-    "python_full_version >= '3.14' and sys_platform != 'emscripten' and sys_platform != 'win32' and extra != 'extra-5-giant-cpu' and extra != 'extra-5-giant-cuda'",
     "python_full_version < '3.14' and sys_platform == 'win32' and extra != 'extra-5-giant-cpu' and extra != 'extra-5-giant-cuda'",
     "python_full_version < '3.14' and sys_platform == 'emscripten' and extra != 'extra-5-giant-cpu' and extra != 'extra-5-giant-cuda'",
     "python_full_version < '3.14' and sys_platform != 'emscripten' and sys_platform != 'win32' and extra != 'extra-5-giant-cpu' and extra != 'extra-5-giant-cuda'",
@@ -45,6 +45,19 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/99/91/8acff4f5e50511b911bbccb72b8628a49c68ce14148cd9f6431094859a90/annotated_types-0.8.0-py3-none-any.whl", hash = "sha256:f072f4d804ea359e4eaf198b1af7a8b0943881a87f31bb764f8bf219bb9419e0", size = 13427, upload-time = "2026-07-23T20:16:12.938Z" },
 ]
 
+[[package]]
+name = "anyio"
+version = "4.14.2"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "idna", marker = "sys_platform != 'emscripten' or (extra == 'extra-5-giant-cpu' and extra == 'extra-5-giant-cuda')" },
+    { name = "typing-extensions", marker = "(python_full_version < '3.13' and sys_platform != 'emscripten') or (python_full_version >= '3.13' and extra == 'extra-5-giant-cpu' and extra == 'extra-5-giant-cuda') or (sys_platform == 'emscripten' and extra == 'extra-5-giant-cpu' and extra == 'extra-5-giant-cuda')" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/61/cc/a381afa6efea9f496eff839d4a6a1aed3bfafc7b3ab4b0d1b243a12573dd/anyio-4.14.2.tar.gz", hash = "sha256:cfa139f3ed1a23ee8f88a145ddb5ac7605b8bbfd8592baacd7ce3d8bb4313c7f", size = 260176, upload-time = "2026-07-12T20:29:07.082Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/da/35/f2287558c17e29fafc8ef3daf819bb9834061cfa43bff8014f7df7f63bdc/anyio-4.14.2-py3-none-any.whl", hash = "sha256:9f505dda5ac9f0c8309b5e8bd445a8c2bf7246f3ce950121e45ea15bc41d1494", size = 125813, upload-time = "2026-07-12T20:29:05.763Z" },
+]
+
 [[package]]
 name = "appnope"
 version = "0.1.4"
@@ -134,6 +147,35 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/44/a1/70ebfffd6c6edc6034a547838ee46287c65ed89f710592ddc39c76b4a5a8/awkward_cpp-53-cp314-cp314t-win_arm64.whl", hash = "sha256:1be0c1d87d9f4fdf94b767a061df849f1bb21579d302b2996fb101527fc80a97", size = 551257, upload-time = "2026-06-08T12:31:56.319Z" },
 ]
 
+[[package]]
+name = "bracex"
+version = "3.0.1"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/ac/01/5f394b8bcd6e5b92f73130990960423bbb19711f906bd9fe9ea5557c667c/bracex-3.0.1.tar.gz", hash = "sha256:4e38e32392e4a4780fe15d644bfc7c8514057cfc3861e060b11814ce829c25e4", size = 44019, upload-time = "2026-07-20T13:43:00.335Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/b8/8f/6f7273a7adb8d73fc8d21ede4376a3e475e52f98435c6007f69100dec8ca/bracex-3.0.1-py3-none-any.whl", hash = "sha256:6523ad83aeb5098a4ee597cff0f964442ff74e460bd3fafaffab6a013ff2288c", size = 11940, upload-time = "2026-07-20T13:42:59.268Z" },
+]
+
+[[package]]
+name = "bump-my-version"
+version = "1.5.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "click" },
+    { name = "httpx2" },
+    { name = "pydantic" },
+    { name = "pydantic-settings" },
+    { name = "questionary" },
+    { name = "rich" },
+    { name = "rich-click" },
+    { name = "tomlkit" },
+    { name = "wcmatch" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/23/09/5b09ac74962eca809cbf7010a08ea6ad405852bdd53489209a9f473d775c/bump_my_version-1.5.1.tar.gz", hash = "sha256:5079e443ab8c9a9903f140b427ff9f6fe8dd54013a55a4cf48b89326f3a71c07", size = 1132060, upload-time = "2026-08-06T14:26:38.9Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/b3/0b/5885530f79d4400368b9d4dcb9b39274c0d52e633f7871e7fc6feceea1e3/bump_my_version-1.5.1-py3-none-any.whl", hash = "sha256:df3e2989d0d7fe704718feb24a5880f089b6b6369e427a4445b89c3adebfcff1", size = 65090, upload-time = "2026-08-06T14:26:37.083Z" },
+]
+
 [[package]]
 name = "certifi"
 version = "2026.7.22"
@@ -633,7 +675,7 @@ wheels = [
 
 [[package]]
 name = "giant"
-version = "0.3.0"
+version = "0.3.4"
 source = { editable = "." }
 dependencies = [
     { name = "numpy" },
@@ -666,6 +708,8 @@ cuda = [
 ]
 dev = [
     { name = "awkward" },
+    { name = "bump-my-version" },
+    { name = "git-cliff" },
     { name = "ipykernel" },
     { name = "matplotlib" },
     { name = "plotstyle" },
@@ -688,7 +732,9 @@ wandb = [
 [package.metadata]
 requires-dist = [
     { name = "awkward", marker = "extra == 'convert'", specifier = ">=2.6,<3" },
+    { name = "bump-my-version", marker = "extra == 'dev'", specifier = ">=1.2,<2" },
     { name = "giant", extras = ["convert", "analysis", "geometry", "wandb"], marker = "extra == 'dev'" },
+    { name = "git-cliff", marker = "extra == 'dev'", specifier = ">=2,<3" },
     { name = "ipykernel", marker = "extra == 'analysis'", specifier = ">=7.3.0" },
     { name = "matplotlib", marker = "extra == 'analysis'", specifier = ">=3.8,<4" },
     { name = "numpy", specifier = ">=1.26,<3" },
@@ -713,6 +759,35 @@ requires-dist = [
 ]
 provides-extras = ["cpu", "cuda", "dev", "geometry", "wandb", "convert", "analysis"]
 
+[[package]]
+name = "git-cliff"
+version = "2.13.1"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/62/57/b12494e2cbc3c9154c942e64659b5aec2b1ce9f12d07f6dc6167e2c63ae5/git_cliff-2.13.1.tar.gz", hash = "sha256:e949ea9c3951ba6037b99eec465162be2584f27f0836ace45f44d6f45650f8c6", size = 113119, upload-time = "2026-04-26T10:33:42.331Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/8f/dd/24768c3c0030710d36706c17b997d06aee27cb76b27ab2abb058ae254175/git_cliff-2.13.1-py3-none-macosx_10_12_x86_64.whl", hash = "sha256:08a9cb0ec760e165210ed22fefa295b6549a3520b420db995ccbb3620cbb1fbe", size = 7260035, upload-time = "2026-04-26T10:33:16.269Z" },
+    { url = "https://files.pythonhosted.org/packages/22/df/842973ead79d27a58cd1eccd167191c0a71513e5c1e9dc30337dafdb7d36/git_cliff-2.13.1-py3-none-macosx_11_0_arm64.whl", hash = "sha256:e92cf470ecbe73f7d2963dfa80e8961a6b76888d0c19949b0f028a28a0a0470c", size = 6854384, upload-time = "2026-04-26T10:33:18.808Z" },
+    { url = "https://files.pythonhosted.org/packages/7c/4d/6d6efa7d61be8632563990ccd402e401695e4a85a0bb1002f28730d03268/git_cliff-2.13.1-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:2e8d8e420adf6a36b97e0fbdbf2b07e47712199a9baf3675c9a759430243ea26", size = 7308164, upload-time = "2026-04-26T10:33:20.869Z" },
+    { url = "https://files.pythonhosted.org/packages/f0/4a/98b8d2f53a2d0b7d313e98ab363ad7e0d6a514e878a8d678f22402cb0ec7/git_cliff-2.13.1-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:1ab059d671565189faa4f3858b2fb42535aa39fe265ad95d84d5c116a2724fc7", size = 7687163, upload-time = "2026-04-26T10:33:23.096Z" },
+    { url = "https://files.pythonhosted.org/packages/c7/07/cdd149b3909644aa3f0be7960406d9bbb38598f8618e039ac48cbb43ded6/git_cliff-2.13.1-py3-none-manylinux_2_28_aarch64.whl", hash = "sha256:a93db30da45967c42df607fbbc2092111fcd576b0ca9e2fbddd3f653d8c71be7", size = 7317670, upload-time = "2026-04-26T10:33:25.323Z" },
+    { url = "https://files.pythonhosted.org/packages/2e/11/6d377a7f3113f6e26d87a28a32013eb05bd62bce176d6f8ee808e4868c1f/git_cliff-2.13.1-py3-none-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:df9f5a2bd16e5225030c9c2362e6ac70b34a906c0fbb83f8cbf5ae46932ba0d2", size = 7502294, upload-time = "2026-04-26T10:33:27.315Z" },
+    { url = "https://files.pythonhosted.org/packages/80/6b/e1da9acf3aec99e6600be02b6ce0c9e8bd42d072e3120384514c905231e2/git_cliff-2.13.1-py3-none-manylinux_2_5_x86_64.manylinux1_x86_64.whl", hash = "sha256:c12276784d280aa6a7148d3e52ff139e891f4c97720cd9be581b19892ea39fe0", size = 7927258, upload-time = "2026-04-26T10:33:29.554Z" },
+    { url = "https://files.pythonhosted.org/packages/ed/ea/9f2188a5e474e5f02193d9c1cdf7028773d483a3f508a1df4f1d93c9cc80/git_cliff-2.13.1-py3-none-musllinux_1_2_aarch64.whl", hash = "sha256:17da93dc605cbc48c762770402067fa726437cedbd62514f9caef6e0ccb58a43", size = 7308153, upload-time = "2026-04-26T10:33:31.589Z" },
+    { url = "https://files.pythonhosted.org/packages/b3/70/5e2b2a0e42c07956f911e1eccd6dc6d79b96fc6c8a604a526c1ee0474c84/git_cliff-2.13.1-py3-none-musllinux_1_2_i686.whl", hash = "sha256:cd4a08cf3f638ec71d2ed451aa8673bef99e1107a36366153db97ca18d981655", size = 7502287, upload-time = "2026-04-26T10:33:33.894Z" },
+    { url = "https://files.pythonhosted.org/packages/05/50/cc4c1d3d360621c0235d66d2c74472d9993d8aadf23ffa311eaf29d7a3aa/git_cliff-2.13.1-py3-none-musllinux_1_2_x86_64.whl", hash = "sha256:c5bb87f6e1db18be09e50c9d59234dc949713e20c2700e94eca378d22ad79719", size = 7927253, upload-time = "2026-04-26T10:33:36.205Z" },
+    { url = "https://files.pythonhosted.org/packages/86/5d/717d30f37dad65a6cc5220b04a3ef1bc44c31fb56d0ce2895114e159df4f/git_cliff-2.13.1-py3-none-win32.whl", hash = "sha256:c8878972e0a6c26d9137fc406a611116239333578d95ac05064d2807920bd83c", size = 6718261, upload-time = "2026-04-26T10:33:38.1Z" },
+    { url = "https://files.pythonhosted.org/packages/99/b2/99fac50978b9a90bfec0f1b89354a667ec83f4990301f6c708abce05484e/git_cliff-2.13.1-py3-none-win_amd64.whl", hash = "sha256:856d831a0bede9c258229dbd4d4c2b1c0810d8fce3d3882729669e8dc09c72bf", size = 7714969, upload-time = "2026-04-26T10:33:40.163Z" },
+]
+
+[[package]]
+name = "h11"
+version = "0.16.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/01/ee/02a2c011bdab74c6fb3c75474d40b3052059d95df7e73351460c8588d963/h11-0.16.0.tar.gz", hash = "sha256:4e35b956cf45792e4caa5885e69fba00bdbc6ffafbfa020300e549b208ee5ff1", size = 101250, upload-time = "2025-04-24T03:35:25.427Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/04/4b/29cac41a4d98d144bf5f6d33995617b185d14b22401f75ca86f384e87ff1/h11-0.16.0-py3-none-any.whl", hash = "sha256:63cf8bbe7522de3bf65932fda1d9c2772064ffb3dae62d55932da54b31cb6c86", size = 37515, upload-time = "2025-04-24T03:35:24.344Z" },
+]
+
 [[package]]
 name = "hepunits"
 version = "2.4.6"
@@ -722,6 +797,45 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/85/10/7f9c58d1ec6a0b7f7783fe552f3593f39cda30c2e1d7a9d148ae711e748d/hepunits-2.4.6-py3-none-any.whl", hash = "sha256:089c52c3b84ef67a159b5e9ee9bdd50e1a442e3fd0c101303cc409c1e9011c4d", size = 17090, upload-time = "2026-06-16T09:23:35.35Z" },
 ]
 
+[[package]]
+name = "httpcore2"
+version = "2.11.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "h11", marker = "sys_platform != 'emscripten' or (extra == 'extra-5-giant-cpu' and extra == 'extra-5-giant-cuda')" },
+    { name = "truststore", marker = "sys_platform != 'emscripten' or (extra == 'extra-5-giant-cpu' and extra == 'extra-5-giant-cuda')" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/30/7d/ee6787efd5fe675d7cfd5eb149e40ccb5bdfc7e7c9252edcf7825c38986f/httpcore2-2.11.0.tar.gz", hash = "sha256:82e6fc95d784e6ee22ebd4b2cb57df53a2efb13ad6a11260a236ecebbc5f50c7", size = 67532, upload-time = "2026-08-18T08:03:53.008Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/f3/54/e84a5c82ac0959d5e55b3970d326fd95306446b2bf0702302888745f7e5c/httpcore2-2.11.0-py3-none-any.whl", hash = "sha256:c7c899fbc6b8abb6e747dda427aa6f52934c45e191eabb986965164ebb02a908", size = 83061, upload-time = "2026-08-18T08:03:50.894Z" },
+]
+
+[[package]]
+name = "httpx2"
+version = "2.11.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "anyio", marker = "sys_platform != 'emscripten' or (extra == 'extra-5-giant-cpu' and extra == 'extra-5-giant-cuda')" },
+    { name = "httpcore2", marker = "sys_platform != 'emscripten' or (extra == 'extra-5-giant-cpu' and extra == 'extra-5-giant-cuda')" },
+    { name = "httpx2-jsfetch", marker = "sys_platform == 'emscripten' or (extra == 'extra-5-giant-cpu' and extra == 'extra-5-giant-cuda')" },
+    { name = "idna" },
+    { name = "truststore", marker = "sys_platform != 'emscripten' or (extra == 'extra-5-giant-cpu' and extra == 'extra-5-giant-cuda')" },
+    { name = "typing-extensions", marker = "python_full_version < '3.13' or (extra == 'extra-5-giant-cpu' and extra == 'extra-5-giant-cuda')" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/d5/4d/b3fcae38f29bfb0f300517d085c488f41f65e5b0a73023976b2122f568cc/httpx2-2.11.0.tar.gz", hash = "sha256:ea01b2e8febfb026e2601814c77ecb1e64fff114a87bc789cb520e67f27e7809", size = 99617, upload-time = "2026-08-18T08:03:53.691Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/39/29/f60bcf54028601920c0ce3da81537bcd0af4ee19dd9672af85dc9dfd60e0/httpx2-2.11.0-py3-none-any.whl", hash = "sha256:c9790f62a327110f52a099f1e2030cbe32f78b28781ad68fe58bfd6f23e73ab0", size = 95043, upload-time = "2026-08-18T08:03:52.004Z" },
+]
+
+[[package]]
+name = "httpx2-jsfetch"
+version = "1.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/cd/c4/0e5636363151a2a1795e0a77617168b9ca438e1748ec05fc9b5687f93d64/httpx2_jsfetch-1.0.tar.gz", hash = "sha256:70a0e3eabfef7cce5ad9c629f7d01ca05e418f586646f4ddf14782e4c1454c60", size = 6872, upload-time = "2026-08-07T00:13:07.492Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/9b/43/832f631d32e4f1211caa2ba368317739fe71f0b8530e4c9d15dc454bac2a/httpx2_jsfetch-1.0-py3-none-any.whl", hash = "sha256:cb916b707601e69a07721aabc8f3f6659be3a6893bc1ff5c6f9e02241df2da32", size = 6382, upload-time = "2026-08-07T00:13:06.567Z" },
+]
+
 [[package]]
 name = "idna"
 version = "3.18"
@@ -1780,6 +1894,20 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/fa/c3/7c8b240552251faf6b3a957db200fcfbbcec36763c050428b601e0c9b83b/pydantic_core-2.46.4-graalpy312-graalpy250_312_native-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:00c603d540afdd6b80eb39f078f33ebd46211f02f33e34a32d9f053bba711de0", size = 2147590, upload-time = "2026-05-06T13:39:29.883Z" },
 ]
 
+[[package]]
+name = "pydantic-settings"
+version = "2.15.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "pydantic" },
+    { name = "python-dotenv" },
+    { name = "typing-inspection" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/68/ca/31c57507b13119d7d3cfa1576dad2911a4861e3be07b579395f4e9d393f9/pydantic_settings-2.15.0.tar.gz", hash = "sha256:694b793e84f766ba76a90ebdefc01d0a9a045dab0382bee70393da93712ad117", size = 261253, upload-time = "2026-08-07T09:24:57.419Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/30/a4/2bffa9f8e804325a09867f0e9d30795c80ea9f8d62560bd1b6ad6220eb2f/pydantic_settings-2.15.0-py3-none-any.whl", hash = "sha256:0ba092c291c94baceb5eff768aa0d56400a457585bc0175925a5a5510303da42", size = 69413, upload-time = "2026-08-07T09:24:55.839Z" },
+]
+
 [[package]]
 name = "pygments"
 version = "2.20.0"
@@ -1840,6 +1968,15 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/ec/57/56b9bcc3c9c6a792fcbaf139543cee77261f3651ca9da0c93f5c1221264b/python_dateutil-2.9.0.post0-py2.py3-none-any.whl", hash = "sha256:a8b2bc7bffae282281c8140a97d3aa9c14da0b136dfe83f850eea9a5f7470427", size = 229892, upload-time = "2024-03-01T18:36:18.57Z" },
 ]
 
+[[package]]
+name = "python-dotenv"
+version = "1.2.3"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/6a/53/ed9d74092561d4b01a2ef1349d52cdbc135e526c245f366b089cfca6de49/python_dotenv-1.2.3.tar.gz", hash = "sha256:a20a594dabeaa385725aa239d5244871c143ecb356add8a20fcf23773a6c3a35", size = 58945, upload-time = "2026-08-16T16:54:54.067Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/0d/17/c5c6b53ddc18f297992099b3d9ec16c855c0ccc83263a21fe4d1c625ec6c/python_dotenv-1.2.3-py3-none-any.whl", hash = "sha256:904552145e8bfed22162c09dab1c2b9b54fefa7b23ba780f4f26ca0316b0f0d9", size = 22780, upload-time = "2026-08-16T16:54:52.473Z" },
+]
+
 [[package]]
 name = "pyyaml"
 version = "6.0.3"
@@ -1929,6 +2066,18 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/81/d6/4bfbb40c9a0b42fc53c7cf442f6385db70b40f74a783130c5d0a5aa62228/pyzmq-27.1.0-cp314-cp314t-win_arm64.whl", hash = "sha256:dc5dbf68a7857b59473f7df42650c621d7e8923fb03fa74a526890f4d33cc4d7", size = 575170, upload-time = "2025-09-08T23:09:01.418Z" },
 ]
 
+[[package]]
+name = "questionary"
+version = "2.1.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "prompt-toolkit" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/f6/45/eafb0bba0f9988f6a2520f9ca2df2c82ddfa8d67c95d6625452e97b204a5/questionary-2.1.1.tar.gz", hash = "sha256:3d7e980292bb0107abaa79c68dd3eee3c561b83a0f89ae482860b181c8bd412d", size = 25845, upload-time = "2025-08-28T19:00:20.851Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/3c/26/1062c7ec1b053db9e499b4d2d5bc231743201b74051c973dadeac80a8f43/questionary-2.1.1-py3-none-any.whl", hash = "sha256:a51af13f345f1cdea62347589fbb6df3b290306ab8930713bfae4d475a7d4a59", size = 36753, upload-time = "2025-08-28T19:00:19.56Z" },
+]
+
 [[package]]
 name = "requests"
 version = "2.34.2"
@@ -1957,6 +2106,20 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/82/3b/64d4899d73f91ba49a8c18a8ff3f0ea8f1c1d75481760df8c68ef5235bf5/rich-15.0.0-py3-none-any.whl", hash = "sha256:33bd4ef74232fb73fe9279a257718407f169c09b78a87ad3d296f548e27de0bb", size = 310654, upload-time = "2026-04-12T08:24:02.83Z" },
 ]
 
+[[package]]
+name = "rich-click"
+version = "1.9.8"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "click" },
+    { name = "colorama", marker = "sys_platform == 'win32' or (extra == 'extra-5-giant-cpu' and extra == 'extra-5-giant-cuda')" },
+    { name = "rich" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/f7/ea/21e4867ea0ef881ffd4c0550fc21a061435e50d6324bcd034396633cbc18/rich_click-1.9.8.tar.gz", hash = "sha256:4008f921da88b5d91646c134ec881c1500e5a6b3f093e90e8f29400e09608371", size = 75363, upload-time = "2026-05-28T19:54:59.144Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/6d/97/a87901aef6b7e7e4a34c6dd6cc17dca8594a592ef9d9dd765fca2b7facf7/rich_click-1.9.8-py3-none-any.whl", hash = "sha256:12873865396e6927835d4eabb1cc3996edcd65b7ac9b2391a29eca4f335a2f93", size = 72189, upload-time = "2026-05-28T19:54:57.867Z" },
+]
+
 [[package]]
 name = "ruff"
 version = "0.15.17"
@@ -2149,6 +2312,15 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/32/d5/f9a850d79b0851d1d4ef6456097579a9005b31fea68726a4ae5f2d82ddd9/threadpoolctl-3.6.0-py3-none-any.whl", hash = "sha256:43a0b8fd5a2928500110039e43a5eed8480b918967083ea48dc3ab9f13c4a7fb", size = 18638, upload-time = "2025-03-13T13:49:21.846Z" },
 ]
 
+[[package]]
+name = "tomlkit"
+version = "0.15.1"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/94/96/e07752635b98536177fa1f37671c8f3cdde2e724c6bcf6034b2cfb571565/tomlkit-0.15.1.tar.gz", hash = "sha256:e25bbf38843005246210a12982776f27f99cb9be67160e14434d0c0d21ee1e97", size = 180129, upload-time = "2026-07-17T01:48:04.562Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/13/bc/8c13eb66537dce1d2bd3a57132902f38d0e7f5bb46fa9f4daed9fe9d76ee/tomlkit-0.15.1-py3-none-any.whl", hash = "sha256:177a05aece5a8ca5266fd3c448abb47b8d352f09d477d3ca8332db4d89b24304", size = 49449, upload-time = "2026-07-17T01:48:05.728Z" },
+]
+
 [[package]]
 name = "torch"
 version = "2.3.1"
@@ -2270,6 +2442,15 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/96/8d/1080ee4c231f361b6ce4470d556c8c435b67c7e0753aaa641497ee92f88b/traitlets-5.15.1-py3-none-any.whl", hash = "sha256:770a53705f84b81ac107e83a1b3328ff2dae16094d8fc3cfc004e4b22dfd8e92", size = 85858, upload-time = "2026-06-03T12:26:04.395Z" },
 ]
 
+[[package]]
+name = "truststore"
+version = "0.10.4"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/53/a3/1585216310e344e8102c22482f6060c7a6ea0322b63e026372e6dcefcfd6/truststore-0.10.4.tar.gz", hash = "sha256:9d91bd436463ad5e4ee4aba766628dd6cd7010cf3e2461756b3303710eebc301", size = 26169, upload-time = "2025-08-12T18:49:02.73Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/19/97/56608b2249fe206a67cd573bc93cd9896e1efb9e98bce9c163bcdc704b88/truststore-0.10.4-py3-none-any.whl", hash = "sha256:adaeaecf1cbb5f4de3b1959b42d41f6fab57b2b1666adb59e89cb0b53361d981", size = 18660, upload-time = "2025-08-12T18:49:01.46Z" },
+]
+
 [[package]]
 name = "ty"
 version = "0.0.50"
@@ -2394,6 +2575,18 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/07/78/75b6827a6665337a715c5347c5edbd84eca660f7a0f48d8d6d24d1f66bee/wandb-0.28.1-py3-none-win_arm64.whl", hash = "sha256:4aa07f13dd3bcac2c0524c8d0f49f76e83ab5c1054fd09f3b1a436cfcde146a6", size = 22299006, upload-time = "2026-07-16T18:47:02.71Z" },
 ]
 
+[[package]]
+name = "wcmatch"
+version = "11.0.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "bracex" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/57/43/30e407989e313677dbb9d5f045f966549a7254834571e342eaa4b55cc67b/wcmatch-11.0.1.tar.gz", hash = "sha256:1ea2b4fa678b8ca268253798d5963935df39132d47c3e241c0a0732224005e7d", size = 144662, upload-time = "2026-08-14T15:20:40.477Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/ce/77/7a02b0f05b3ffcdbef9719ce3ee0b508d6a29b58e95299f1580055671db3/wcmatch-11.0.1-py3-none-any.whl", hash = "sha256:fd149ecddb9f0a88ea780017d6dde17c994e494e7f7303d4e3c9d6251f978f4b", size = 43449, upload-time = "2026-08-14T15:20:39.379Z" },
+]
+
 [[package]]
 name = "wcwidth"
 version = "0.8.1"