Add dwarf warm-cache to precompute the setup-stage sidecar

Lets the vocab maps, event-id split index, and normalizer stats be
warmed once for a dataset (right after `dwarf convert`, or before a
`dwarf hparam-scan` sweep) without needing to also start training.

Extracts the setup-stage logic out of giant/pipeline.py:run_train_job
into a standalone run_setup_stage() (returning a SetupStageResult),
reused by both run_train_job and the new dwarf command's
scripts/warm_setup_cache.py — a behavior-preserving refactor, covered
by the existing test_pipeline.py suite.

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

scripts/dwarf.py

@@ -25,6 +25,7 @@ from scripts.hparam_scan import DATA_DEFAULT, SCAN_DIR_DEFAULT, run_hparam_scan
 from scripts.migrate_geant_steps import run_migration
 from scripts.steps_to_parquet import convert_steps_to_parquet
 from scripts.steps_to_parquet_parallel import run_parallel_job
+from scripts.warm_setup_cache import run_warm_setup_cache
 
 app = typer.Typer(no_args_is_help=True)
 
@@ -471,6 +472,80 @@ def build_geometry_oracle(
     )
 
 
+class Conditioning(str, Enum):
+    physical = "physical"
+    embedding = "embedding"
+
+
+@app.command("warm-cache")
+def warm_cache(
+    data: Annotated[
+        Path,
+        typer.Argument(
+            help="Parquet file, directory, or .manifest — same as `giant train`'s"
+        ),
+    ],
+    val_fraction: Annotated[
+        float,
+        typer.Option(
+            "--val-fraction",
+            "-f",
+            help="Must match the `giant train` run(s) to warm for",
+        ),
+    ] = 0.1,
+    seed: Annotated[
+        int,
+        typer.Option(
+            "--seed", "-s", help="Must match the `giant train` run(s) to warm for"
+        ),
+    ] = 0,
+    conditioning: Annotated[
+        Conditioning,
+        typer.Option(
+            "--conditioning", help="Must match the `giant train` run(s) to warm for"
+        ),
+    ] = Conditioning.physical,
+    router: Annotated[
+        bool,
+        typer.Option(
+            "--router/--no-router",
+            help="Warm the process vocabulary too (only takes effect with "
+            "--router-type process)",
+        ),
+    ] = 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,
+    rebuild: Annotated[
+        bool,
+        typer.Option(
+            "--rebuild", help="Ignore any existing sidecar and recompute every section"
+        ),
+    ] = False,
+) -> None:
+    """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/--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.
+    """
+    run_warm_setup_cache(
+        data=str(data),
+        val_fraction=val_fraction,
+        seed=seed,
+        conditioning=conditioning.value,
+        router_enabled=router,
+        router_type=router_type,
+        n_experts=n_experts,
+        rebuild=rebuild,
+        echo=typer.echo,
+    )
+
+
 @app.command("hparam-scan")
 def hparam_scan(
     data: Annotated[str, typer.Option("--data")] = DATA_DEFAULT,

scripts/warm_setup_cache.py

@@ -0,0 +1,52 @@
+"""dwarf warm-cache — precompute `giant train`'s setup-stage sidecar ahead of time.
+
+Thin wrapper around `giant.pipeline.run_setup_stage` so a dataset's vocab
+maps, event-id split index, and normalizer stats can be warmed once — e.g.
+right after `dwarf convert`, or before kicking off a `dwarf hparam-scan`
+sweep — without needing to also start training. See giant/data/setup_cache.py
+for the sidecar itself.
+"""
+
+from pathlib import Path
+
+from giant.pipeline import run_setup_stage
+
+
+def run_warm_setup_cache(
+    data: str,
+    val_fraction: float = 0.1,
+    seed: int = 0,
+    conditioning: str = "physical",
+    router_enabled: bool = False,
+    router_type: str = "energy",
+    n_experts: int = 4,
+    rebuild: bool = False,
+    echo=print,
+) -> None:
+    """Populate (or refresh) the setup cache sidecar for `data`.
+
+    `val_fraction`/`seed`/`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.
+    `router_enabled`/`router_type`/`n_experts` only matter for
+    `router_type == "process"` (warms that `n_experts`'s process map); the
+    energy-router reservoir sample is always collected regardless, so a
+    later `--router-type energy` run never needs to rescan just to seed
+    centers.
+    """
+    router_cfg = {
+        "enabled": router_enabled,
+        "type": router_type,
+        "n_experts": n_experts,
+    }
+    run_setup_stage(
+        Path(data),
+        val_fraction=val_fraction,
+        seed=seed,
+        conditioning=conditioning,
+        router_cfg=router_cfg,
+        cache_setup=True,
+        rebuild_setup_cache=rebuild,
+        echo=echo,
+    )
+    echo("setup cache warmed.")