refactor(models): add get_population_ref() to ScenarioMeta, fix engine population resolution

Move duplicated _parse_base_population_ref() logic from 4 CLI commands
into a single get_population_ref() method on ScenarioMeta. Fix engine.py
to use the new method and add scenario-name-first fallback for agent and
network loading (new CLI flow vs legacy IDs).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: RandomOscillations

extropy/cli/commands/estimate.py

@@ -1,22 +1,12 @@
 """Estimate command for predicting simulation costs before running."""
 
-import re
-
 import typer
 
 from ..app import app, console, get_study_path
 from ..study import StudyContext, detect_study_folder, parse_version_ref
 from ..utils import Output, ExitCode
 
 
-def _parse_base_population_ref(ref: str) -> tuple[str, int | None]:
-    """Parse base_population reference like 'population.v2'."""
-    match = re.match(r"^(.+)\.v(\d+)$", ref)
-    if match:
-        return match.group(1), int(match.group(2))
-    return ref, None
-
-
 @app.command("estimate")
 def estimate_command(
     scenario: str = typer.Option(
@@ -96,12 +86,12 @@ def estimate_command(
         raise typer.Exit(1)
 
     # Load population spec (resolve from base_population or population_spec)
-    base_pop_ref = scenario_spec.meta.base_population or scenario_spec.meta.population_spec
-    if not base_pop_ref:
-        out.error("Scenario has no base_population or population_spec reference")
+    try:
+        pop_name, pop_version = scenario_spec.meta.get_population_ref()
+    except ValueError as e:
+        out.error(str(e))
         raise typer.Exit(1)
 
-    pop_name, pop_version = _parse_base_population_ref(base_pop_ref)
     pop_path = study_ctx.get_population_path(pop_name, pop_version)
     if not pop_path.exists():
         out.error(f"Population spec not found: {pop_path}")

extropy/cli/commands/network.py

@@ -260,9 +260,12 @@ def network_command(
 
     # Load base population spec (needed for config generation)
     merged_spec = None
-    base_pop_ref = scenario_spec.meta.base_population
-    if base_pop_ref:
-        pop_name, pop_version = _parse_base_population_ref(base_pop_ref)
+    try:
+        pop_name, pop_version = scenario_spec.meta.get_population_ref()
+    except ValueError:
+        pop_name, pop_version = None, None
+
+    if pop_name is not None:
         pop_path = study_ctx.get_population_path(pop_name, pop_version)
         try:
             pop_spec = PopulationSpec.from_yaml(pop_path)
@@ -755,14 +758,6 @@ def _resolve_scenario(
     return name, version
 
 
-def _parse_base_population_ref(ref: str) -> tuple[str, int | None]:
-    """Parse base_population reference like 'population.v2'."""
-    import re
-
-    match = re.match(r"^(.+)\.v(\d+)$", ref)
-    if match:
-        return match.group(1), int(match.group(2))
-    return ref, None
 
 
 def _save_network(

extropy/cli/commands/persona.py

@@ -112,20 +112,19 @@ def persona_command(
         raise typer.Exit(1)
 
     # Load base population spec
-    base_pop_ref = scenario_spec.meta.base_population
-    if not base_pop_ref:
-        # Legacy scenario - try population_spec path
-        if scenario_spec.meta.population_spec:
-            pop_path = Path(scenario_spec.meta.population_spec)
-            if not pop_path.is_absolute():
-                pop_path = study_ctx.root / pop_path
-        else:
-            out.error("Scenario has no base_population reference")
-            raise typer.Exit(1)
-    else:
-        # Parse base_population reference (e.g., "population.v2")
-        pop_name, pop_version = _parse_base_population_ref(base_pop_ref)
+    try:
+        pop_name, pop_version = scenario_spec.meta.get_population_ref()
+    except ValueError as e:
+        out.error(str(e))
+        raise typer.Exit(1)
+
+    if pop_version is not None:
         pop_path = study_ctx.get_population_path(pop_name, pop_version)
+    else:
+        # Legacy scenario — population_spec is a file path
+        pop_path = Path(pop_name)
+        if not pop_path.is_absolute():
+            pop_path = study_ctx.root / pop_path
 
     try:
         pop_spec = PopulationSpec.from_yaml(pop_path)
@@ -301,21 +300,6 @@ def _resolve_scenario(
     return name, version
 
 
-def _parse_base_population_ref(ref: str) -> tuple[str, int]:
-    """Parse base_population reference like 'population.v2'.
-
-    Returns:
-        Tuple of (name, version)
-    """
-    import re
-
-    match = re.match(r"^(.+)\.v(\d+)$", ref)
-    if match:
-        return match.group(1), int(match.group(2))
-    # Fallback: treat as name, get latest
-    return ref, None
-
-
 def _handle_show_mode(
     study_ctx: StudyContext,
     scenario_name: str,

extropy/cli/commands/sample.py

@@ -110,12 +110,12 @@ def sample_command(
         raise typer.Exit(1)
 
     # Load base population spec
-    base_pop_ref = scenario_spec.meta.base_population
-    if not base_pop_ref:
-        out.error("Scenario has no base_population reference")
+    try:
+        pop_name, pop_version = scenario_spec.meta.get_population_ref()
+    except ValueError as e:
+        out.error(str(e))
         raise typer.Exit(1)
 
-    pop_name, pop_version = _parse_base_population_ref(base_pop_ref)
     pop_path = study_ctx.get_population_path(pop_name, pop_version)
 
     try:
@@ -334,14 +334,6 @@ def _resolve_scenario(
     return name, version
 
 
-def _parse_base_population_ref(ref: str) -> tuple[str, int | None]:
-    """Parse base_population reference like 'population.v2'."""
-    import re
-
-    match = re.match(r"^(.+)\.v(\d+)$", ref)
-    if match:
-        return match.group(1), int(match.group(2))
-    return ref, None
 
 
 def _save_to_db(

extropy/core/models/scenario.py

@@ -14,6 +14,7 @@
 - Validation: ValidationError, ValidationWarning, ValidationResult
 """
 
+import re
 from datetime import datetime
 from enum import Enum
 from pathlib import Path
@@ -332,6 +333,28 @@ class ScenarioMeta(BaseModel):
     network_id: str = Field(default="default", description="Network ID in study DB")
     created_at: datetime = Field(default_factory=datetime.now)
 
+    def get_population_ref(self) -> tuple[str, int | None]:
+        """Parse the population reference from base_population or population_spec.
+
+        Handles versioned references like 'population.v2' → ('population', 2)
+        and plain names like 'population' → ('population', None).
+
+        Returns:
+            Tuple of (name, version) where version is None for unversioned refs.
+
+        Raises:
+            ValueError: If neither base_population nor population_spec is set.
+        """
+        ref = self.base_population or self.population_spec
+        if ref is None:
+            raise ValueError(
+                "Scenario has no base_population or population_spec reference"
+            )
+        match = re.match(r"^(.+)\.v(\d+)$", ref)
+        if match:
+            return match.group(1), int(match.group(2))
+        return ref, None
+
 
 class ScenarioSpec(BaseModel):
     """Complete specification for a scenario simulation."""

extropy/simulation/engine.py

@@ -2136,10 +2136,18 @@ def _reset_runtime_tables(path: Path, run_key: str) -> None:
     # Load scenario
     scenario = ScenarioSpec.from_yaml(scenario_path)
 
-    # Load population spec
-    pop_path = Path(scenario.meta.population_spec)
-    if not pop_path.is_absolute():
-        pop_path = scenario_path.parent / pop_path
+    # Load population spec (resolve from base_population or legacy population_spec)
+    pop_name, pop_version = scenario.meta.get_population_ref()
+
+    if pop_version is not None:
+        # Versioned ref (e.g. "population.v1") — resolve relative to study root
+        # Study structure: study_root/scenario/<name>/scenario.v1.yaml
+        study_root = scenario_path.parent.parent.parent
+        pop_path = study_root / f"{pop_name}.v{pop_version}.yaml"
+    else:
+        pop_path = Path(pop_name)
+        if not pop_path.is_absolute():
+            pop_path = scenario_path.parent / pop_path
     population_spec = PopulationSpec.from_yaml(pop_path)
 
     # Resolve canonical study DB
@@ -2163,15 +2171,20 @@ def _reset_runtime_tables(path: Path, run_key: str) -> None:
     )
 
     with open_study_db(study_db_resolved) as db:
-        agents = db.get_agents(scenario.meta.population_id)
+        # Try scenario-based lookup first (new CLI flow), fall back to legacy IDs
+        agents = db.get_agents_by_scenario(scenario.meta.name)
+        if not agents:
+            agents = db.get_agents(scenario.meta.population_id)
         if not agents:
             raise ValueError(
-                f"No agents for population_id '{scenario.meta.population_id}' in {study_db_resolved}"
+                f"No agents for scenario '{scenario.meta.name}' in {study_db_resolved}"
             )
-        network = db.get_network(scenario.meta.network_id)
+        network = db.get_network(scenario.meta.name)
+        if not network.get("edges"):
+            network = db.get_network(scenario.meta.network_id)
         if not network.get("edges"):
             raise ValueError(
-                f"No network edges for network_id '{scenario.meta.network_id}' in {study_db_resolved}"
+                f"No network edges for scenario '{scenario.meta.name}' in {study_db_resolved}"
             )
         db.create_simulation_run(
             run_id=resolved_run_id,