fix(builder): enforce bug-family contracts and decouple payload wiring

src/open_range/builder/builder.py

@@ -40,6 +40,7 @@ from open_range.protocols import (
 )
 
 from open_range.builder.prompts import BUILDER_SYSTEM_PROMPT
+from open_range.builder.manifest_graph import compile_manifest_topology
 
 logger = logging.getLogger(__name__)
 
@@ -928,14 +929,26 @@ class TemplateOnlyBuilder:
         manifest: dict,
         context: BuildContext,
     ) -> SnapshotSpec:
-        """Build a snapshot deterministically from the vuln pool."""
+        """Build a canonicalized snapshot deterministically from templates."""
         rng = random.Random(context.seed if context.seed is not None else 42)
 
         # Filter pool to allowed bug_families
-        allowed = set(manifest.get("bug_families", []))
-        candidates = [v for v in self.vuln_pool if v["type"] in allowed]
-        if not candidates:
+        allowed = {
+            str(v).strip()
+            for v in manifest.get("bug_families", [])
+            if str(v).strip()
+        }
+        if allowed:
+            candidates = [v for v in self.vuln_pool if v["type"] in allowed]
+        else:
             candidates = list(self.vuln_pool)
+        if allowed and not candidates:
+            available = sorted({str(v.get("type", "")).strip() for v in self.vuln_pool if v.get("type")})
+            requested = sorted(allowed)
+            raise ValueError(
+                "No template vulnerabilities match manifest bug_families. "
+                f"requested={requested}, available={available}"
+            )
 
         if "prefer_live_admission_compatible_vulns" in context.narrative_hints:
             live_supported = {"sqli", "idor", "path_traversal", "weak_creds"}
@@ -1092,6 +1105,7 @@ class TemplateOnlyBuilder:
             npc_traffic=npc_traffic,
             task=task,
         )
+        snapshot.topology = compile_manifest_topology(manifest, snapshot.topology)
         snapshot.files = render_template_payloads(snapshot, manifest=manifest)
         logger.info(
             "TemplateOnlyBuilder: built snapshot with %d vulns (seed=%s)",
@@ -1197,11 +1211,16 @@ def render_template_payloads(
             _flag_value_for_type(snapshot, "sqli")
         )
 
-    if vuln_types.intersection({"path_traversal", "credential_reuse"}):
+    if "path_traversal" in vuln_types:
         files["web:/var/www/portal/download.php"] = _download_php(
             path_flag=_flag_value_for_type(snapshot, "path_traversal"),
             flag_names=_flag_names_for_type(snapshot, "path_traversal"),
         )
+    elif "credential_reuse" in vuln_types:
+        files["web:/var/www/portal/download.php"] = _download_php(
+            path_flag="",
+            flag_names=[],
+        )
 
     if "idor" in vuln_types:
         files["web:/var/www/portal/api/index.php"] = _idor_api_php(
@@ -1357,7 +1376,7 @@ if (stripos($q, "union") !== false || stripos($q, "flag") !== false) {{
 
 def _download_php(path_flag: str, flag_names: list[str] | None = None) -> str:
     flag = path_flag or "FLAG{placeholder}"
-    raw_names = flag_names or ["flag1.txt"]
+    raw_names = ["flag1.txt"] if flag_names is None else flag_names
     cases = "\n".join(
         f"""elseif (strpos($file, "{name}") !== false) {{
     echo "{flag}";

tests/test_builder.py

@@ -82,6 +82,33 @@ async def test_template_builder_clamps_min_vulns_to_candidate_pool(tier1_manifes
     assert all(v.type == "sqli" for v in spec.truth_graph.vulns)
 
 
+@pytest.mark.asyncio
+async def test_template_builder_fails_when_bug_family_has_no_template_match(tier1_manifest):
+    from open_range.builder.builder import TemplateOnlyBuilder
+
+    builder = TemplateOnlyBuilder()
+    manifest = {
+        **tier1_manifest,
+        "bug_families": ["totally_fake_bug_family"],
+    }
+    with pytest.raises(ValueError, match="No template vulnerabilities match manifest bug_families"):
+        await builder.build(manifest, BuildContext(seed=7, tier=1))
+
+
+@pytest.mark.asyncio
+async def test_template_builder_empty_bug_families_uses_default_pool(tier1_manifest):
+    from open_range.builder.builder import TemplateOnlyBuilder
+
+    builder = TemplateOnlyBuilder()
+    manifest = {
+        **tier1_manifest,
+        "bug_families": [],
+        "difficulty": {**tier1_manifest.get("difficulty", {}), "min_vulns": 1, "max_vulns": 1},
+    }
+    spec = await builder.build(manifest, BuildContext(seed=7, tier=1))
+    assert len(spec.truth_graph.vulns) == 1
+
+
 @pytest.mark.asyncio
 async def test_template_builder_avoids_previous_vulns(tier1_manifest):
     from open_range.builder.builder import TemplateOnlyBuilder
@@ -168,6 +195,55 @@ async def test_template_builder_uses_manifest_company_context(tier1_manifest):
     assert company["name"] in spec.files["web:/var/www/portal/index.php"]
 
 
+@pytest.mark.asyncio
+async def test_template_builder_output_is_manifest_canonicalized(tier1_manifest):
+    from open_range.builder.builder import TemplateOnlyBuilder
+
+    builder = TemplateOnlyBuilder()
+    spec = await builder.build(tier1_manifest, BuildContext(seed=1, tier=1))
+    assert "host_catalog" in spec.topology
+    assert "host_details" in spec.topology
+    assert "dependency_edges" in spec.topology
+    assert "principal_catalog" in spec.topology
+
+
+def test_render_payloads_credential_reuse_not_coupled_to_path_traversal_flag():
+    from open_range.builder.builder import render_template_payloads
+    from open_range.protocols import TruthGraph, Vulnerability
+
+    snapshot = SnapshotSpec(
+        topology={"tier": 1, "hosts": ["web"], "org_name": "OpenRange", "domain": "corp.local"},
+        truth_graph=TruthGraph(
+            vulns=[Vulnerability(id="v1", type="credential_reuse", host="ldap")]
+        ),
+        flags=[FlagSpec(id="f1", value="FLAG{cred_only}", path="/var/flags/flag1.txt", host="db")],
+        golden_path=[],
+    )
+    files = render_template_payloads(snapshot)
+    download = files["web:/var/www/portal/download.php"]
+    assert "config.php" in download
+    assert "FLAG{cred_only}" not in download
+    assert "flag1.txt" not in download
+
+
+def test_render_payloads_path_traversal_keeps_flag_wiring():
+    from open_range.builder.builder import render_template_payloads
+    from open_range.protocols import TruthGraph, Vulnerability
+
+    snapshot = SnapshotSpec(
+        topology={"tier": 1, "hosts": ["web"], "org_name": "OpenRange", "domain": "corp.local"},
+        truth_graph=TruthGraph(
+            vulns=[Vulnerability(id="v1", type="path_traversal", host="web")]
+        ),
+        flags=[FlagSpec(id="f1", value="FLAG{path}", path="/var/flags/path_flag.txt", host="web")],
+        golden_path=[],
+    )
+    files = render_template_payloads(snapshot)
+    download = files["web:/var/www/portal/download.php"]
+    assert "FLAG{path}" in download
+    assert "path_flag.txt" in download
+
+
 @pytest.mark.asyncio
 async def test_mutator_builds_child_snapshot_with_lineage(tier1_manifest):
     from open_range.builder.builder import TemplateOnlyBuilder