proxlb-solver 0.1.0__py3-none-any.whl

proxlb_solver/__init__.py

@@ -0,0 +1,53 @@
+"""ProxLB CP-SAT VM Scheduler.
+
+Public API
+----------
+Core types:
+    Cluster, Node, VM, Constraints, Balancing,
+    Solution, Migration, MigrationPlan, SolverStats
+
+Solver functions:
+    solve(cluster, time_limit_s)        — single-shot solve
+    solve_reachable(cluster, ...)       — solve with planner feedback loop
+
+ProxLB integration:
+    from_proxlb_data(proxlb_data, ...)  — convert live ProxLB data to Cluster
+    run_shadow(proxlb_data, cfg)        — shadow-mode observer (read-only)
+"""
+
+__version__ = "0.1.0"
+
+from .models import (
+    Cluster,
+    Node,
+    VM,
+    Constraints,
+    Balancing,
+    Solution,
+    Migration,
+    MigrationPlan,
+    SolverStats,
+)
+from .solver import solve, solve_reachable
+from .adapter import from_proxlb_data
+from .shadow import run_shadow
+
+__all__ = [
+    "__version__",
+    # Data models
+    "Cluster",
+    "Node",
+    "VM",
+    "Constraints",
+    "Balancing",
+    "Solution",
+    "Migration",
+    "MigrationPlan",
+    "SolverStats",
+    # Solver
+    "solve",
+    "solve_reachable",
+    # ProxLB integration
+    "from_proxlb_data",
+    "run_shadow",
+]

proxlb_solver/adapter.py

@@ -0,0 +1,332 @@
+"""
+Adapter to convert ProxLB data into Solver models.
+
+Accepts either:
+  - a plain dict  (standalone CLI use, unit tests, ProxLB ≤ 1.x)
+  - a ProxLbData Pydantic model  (ProxLB 2.0 integration)
+
+When a Pydantic model is received it is first normalised to the same flat-dict
+layout that the rest of this module expects, so there is a single code path
+after normalisation.
+
+Memory / reservation handling
+------------------------------
+ProxLB stores the *already-reduced* value in node memory_total after applying
+reservations.  The raw hardware total is reconstructed as:
+
+    raw_memory = memory_used + memory_free   (both come straight from the PVE API)
+
+By default (use_reservations=True) this adapter reconstructs the raw total and
+re-applies the reservation explicitly in Node.memory_reserve so the solver's
+constraints are transparent.  With use_reservations=False the reservation is
+zero, letting the solver use the full hardware capacity.
+
+Fallback: if memory_used + memory_free == 0 (e.g. synthetic test data),
+memory_total is used as-is with memory_reserve=0.
+"""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from typing import TYPE_CHECKING, Any, Dict
+
+from .models import Balancing, Cluster, Constraints, Expect, Node, VM
+
+if TYPE_CHECKING:
+    from proxlb.utils.proxlb_data import ProxLbData
+
+
+# ---------------------------------------------------------------------------
+# Normalisation: Pydantic → flat dict
+# ---------------------------------------------------------------------------
+
+def _reserve_to_dict(raw: Any) -> dict[str, Any]:
+    """Convert node_resource_reserve (may have StrEnum keys) to plain str keys."""
+    if not raw:
+        return {}
+    result = {}
+    for node_name, res_dict in raw.items():
+        result[str(node_name)] = {str(k): v for k, v in res_dict.items()}
+    return result
+
+
+def _pydantic_to_dict(proxlb_data: "ProxLbData") -> Dict[str, Any]:
+    """
+    Flatten a ProxLbData Pydantic model into the dict layout expected by
+    from_proxlb_data().  Only the fields the adapter actually reads are mapped.
+    """
+    bc = proxlb_data.meta.balancing
+
+    balancing_dict: Dict[str, Any] = {
+        "method":                  str(bc.method),
+        "mode":                    str(bc.mode),
+        "balanciness":             bc.balanciness,
+        "cpu_overcommit":          getattr(bc, "cpu_overcommit", 2.0),
+        "memory_threshold":        bc.memory_threshold,
+        "cpu_threshold":           bc.cpu_threshold,
+        "disk_threshold":          bc.disk_threshold,
+        "max_node_inflow":         getattr(bc, "max_node_inflow", 1),
+        "max_parallel_migrations": getattr(bc, "max_parallel_migrations", None),
+        "node_resource_reserve":   _reserve_to_dict(bc.node_resource_reserve),
+        "pools":                   bc.pools,
+    }
+
+    nodes: Dict[str, Any] = {}
+    for name, nd in proxlb_data.nodes.items():
+        nodes[name] = {
+            "cpu_total":                    nd.cpu.total,
+            "memory_used":                  int(nd.memory.used),
+            "memory_free":                  int(nd.memory.free),
+            "memory_total":                 nd.memory.total,
+            "disk_free":                    int(nd.disk.free),
+            "cpu_pressure_some_percent":    nd.cpu.pressure_some_percent,
+            "memory_pressure_some_percent": nd.memory.pressure_some_percent,
+            "disk_pressure_some_percent":   nd.disk.pressure_some_percent,
+            "maintenance":                  nd.maintenance,
+        }
+
+    guests: Dict[str, Any] = {}
+    for name, gd in proxlb_data.guests.items():
+        guests[name] = {
+            "node_current":                 gd.node_current,
+            "node_target":                  gd.node_target,
+            "cpu_total":                    gd.cpu.total,
+            "memory_total":                 gd.memory.total,
+            "cpu_used":                     gd.cpu.used,
+            "disk_used":                    int(gd.disk.used),
+            "cpu_pressure_some_percent":    gd.cpu.pressure_some_percent,
+            "memory_pressure_some_percent": gd.memory.pressure_some_percent,
+            "disk_pressure_some_percent":   gd.disk.pressure_some_percent,
+            "type":                         str(gd.type),
+            "ha_rules": [
+                {"rule": r.rule, "type": str(r.type), "nodes": r.nodes}
+                for r in gd.ha_rules
+            ],
+            "tags":               gd.tags,
+            "pools":              gd.pools,
+            "node_relationships": gd.node_relationships,
+            "ignore":             gd.ignore,
+        }
+
+    return {
+        "meta":     {"balancing": balancing_dict, "cluster_name": "Live Cluster"},
+        "nodes":    nodes,
+        "guests":   guests,
+        "groups":   {},
+        "ha_rules": {},
+        "pools":    {},
+    }
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+def _get_memory_reserve_bytes(node_name: str, reserve_cfg: dict[str, Any]) -> int:
+    """
+    Returns the configured memory reservation for a specific node in bytes.
+
+    Resolution order:
+    1. Node-specific override  (e.g. reserve_cfg['pve-01']['memory'])
+    2. Global default          (reserve_cfg['defaults']['memory'])
+    3. Zero                    (nothing configured)
+    """
+    node_config    = reserve_cfg.get(node_name, {})
+    default_config = reserve_cfg.get("defaults", {})
+    gb = node_config.get("memory") or default_config.get("memory", 0)
+    if not isinstance(gb, (int, float)):
+        gb = 0
+    return int(gb * 1024 ** 3)
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+def from_proxlb_data(
+    proxlb_data: "Dict[str, Any] | ProxLbData",
+    use_reservations: bool = True,
+    pin_vms: set[str] | None = None,
+) -> Cluster:
+    """
+    Convert ProxLB data into a Cluster ready for the solver.
+
+    Accepts either a plain dict (standalone / tests) or a ProxLbData Pydantic
+    model (ProxLB 2.0 integration).  Pydantic models are normalised to a flat
+    dict internally so only one code path exists after this point.
+
+    Args:
+        proxlb_data:      Dict or ProxLbData from the ProxLB main loop.
+        use_reservations: If True, node memory reservations are applied explicitly.
+        pin_vms:          VM names to force-pin to their current node (active-mode
+                          retry: VMs that failed to migrate previously).
+    """
+    if not isinstance(proxlb_data, dict):
+        proxlb_data = _pydantic_to_dict(proxlb_data)
+
+    meta         = proxlb_data.get("meta", {})
+    balancing_cfg = meta.get("balancing", {}) if isinstance(meta, dict) else {}
+
+    # 1. Balancing configuration -------------------------------------------
+    balancing = Balancing(
+        method=balancing_cfg.get("method", "memory"),
+        mode=balancing_cfg.get("mode", "used"),
+        balanciness=balancing_cfg.get("balanciness", 3),
+        cpu_overcommit=balancing_cfg.get("cpu_overcommit", 2.0),
+        memory_threshold=balancing_cfg.get("memory_threshold"),
+        cpu_threshold=balancing_cfg.get("cpu_threshold"),
+        disk_threshold=balancing_cfg.get("disk_threshold"),
+        max_node_inflow=balancing_cfg.get("max_node_inflow", 1),
+        max_parallel_migrations=balancing_cfg.get("max_parallel_migrations"),
+    )
+    reserve_cfg: dict[str, Any] = balancing_cfg.get("node_resource_reserve") or {}
+
+    # 2. Physical nodes --------------------------------------------------------
+    nodes = []
+    for name, nd in proxlb_data.get("nodes", {}).items():
+
+        def _nd(key: str, default: Any = 0, _nd: dict[str, Any] = nd) -> Any:  # noqa: E731
+            return _nd.get(key, default)
+
+        mem_used  = int(_nd("memory_used"))
+        mem_free  = int(_nd("memory_free"))
+        raw_memory = mem_used + mem_free
+
+        if raw_memory > 0:
+            memory_reserve = (
+                int(_get_memory_reserve_bytes(name, reserve_cfg))
+                if use_reservations else 0
+            )
+            memory_reserve = min(memory_reserve, raw_memory)
+        else:
+            raw_memory     = int(_nd("memory_total"))
+            memory_reserve = 0
+
+        nodes.append(Node(
+            name=name,
+            cpu_total=int(_nd("cpu_total")),
+            memory_total=raw_memory,
+            memory_reserve=memory_reserve,
+            storage_free={"local": int(_nd("disk_free"))},
+            cpu_pressure=_nd("cpu_pressure_some_percent", 0.0),
+            memory_pressure=_nd("memory_pressure_some_percent", 0.0),
+            io_pressure=_nd("disk_pressure_some_percent", 0.0),
+            maintenance=bool(_nd("maintenance", False)),
+        ))
+
+    # 3. Guests + constraint extraction ----------------------------------------
+    vms: list[VM] = []
+    affinity_groups:      dict[tuple[str, str], list[str]] = defaultdict(list)
+    anti_affinity_groups: dict[tuple[str, str], list[str]] = defaultdict(list)
+    pin_rules:   list[dict[str, Any]] = []
+    ignore_list: list[str]  = []
+
+    pools_config = balancing_cfg.get("pools") or {}
+
+    for name, gd in proxlb_data.get("guests", {}).items():
+
+        def _gd(key: str, default: Any = 0, _gd: dict[str, Any] = gd) -> Any:  # noqa: E731
+            return _gd.get(key, default)
+
+        vms.append(VM(
+            name=name,
+            node=_gd("node_current", ""),
+            cpu=int(_gd("cpu_total", 1)),
+            memory=int(_gd("memory_total")),
+            cpu_usage=float(_gd("cpu_used")),
+            cpu_pressure=_gd("cpu_pressure_some_percent", 0.0),
+            memory_pressure=_gd("memory_pressure_some_percent", 0.0),
+            io_pressure=_gd("disk_pressure_some_percent", 0.0),
+            disks={"local": int(_gd("disk_used"))},
+            priority=int(_gd("priority", 2)),
+            vm_type=str(_gd("type", "vm")),
+        ))
+
+        # A. Native Proxmox HA rules
+        for rule in _gd("ha_rules", []):
+            r_id   = str(rule.get("rule") if isinstance(rule, dict) else getattr(rule, "rule", ""))
+            r_type = rule.get("type") if isinstance(rule, dict) else str(getattr(rule, "type", ""))
+            if r_type == "affinity":
+                affinity_groups[(r_id, "pve")].append(name)
+            elif r_type == "anti-affinity":
+                anti_affinity_groups[(r_id, "pve")].append(name)
+
+        # B. ProxLB tags  (plb_affinity_*, plb_anti_affinity_*)
+        for tag in _gd("tags", []):
+            if tag.startswith("plb_affinity"):
+                affinity_groups[(tag, "plb")].append(name)
+            elif tag.startswith("plb_anti_affinity"):
+                anti_affinity_groups[(tag, "plb")].append(name)
+
+        # C. Resource pool rules
+        for pool_name in _gd("pools", []):
+            pool_cfg = pools_config.get(pool_name) if isinstance(pools_config, dict) else None
+            if pool_cfg:
+                p_type = pool_cfg.get("type") if isinstance(pool_cfg, dict) else str(getattr(pool_cfg, "type", ""))
+                if p_type == "affinity":
+                    affinity_groups[(pool_name, "plb")].append(name)
+                elif p_type == "anti-affinity":
+                    anti_affinity_groups[(pool_name, "plb")].append(name)
+
+        # D. Node pinning  (tags, pools, HA restricted nodes)
+        node_rels = _gd("node_relationships", [])
+        if node_rels:
+            origins: list[dict[str, Any]] = []
+            for tag in _gd("tags", []):
+                if tag.startswith("plb_pin"):
+                    origins.append({"origin": "tag", "source": tag})
+            for pool in _gd("pools", []):
+                pool_cfg = pools_config.get(pool) if isinstance(pools_config, dict) else None
+                if pool_cfg:
+                    has_pin = pool_cfg.get("pin") if isinstance(pool_cfg, dict) else getattr(pool_cfg, "pin", None)
+                    if has_pin:
+                        origins.append({"origin": "pool", "source": pool})
+            for rule in _gd("ha_rules", []):
+                r_type  = rule.get("type")  if isinstance(rule, dict) else str(getattr(rule, "type", ""))
+                r_nodes = rule.get("nodes") if isinstance(rule, dict) else getattr(rule, "nodes", [])
+                r_id    = str(rule.get("rule") if isinstance(rule, dict) else getattr(rule, "rule", ""))
+                if r_type == "affinity" and r_nodes:
+                    origins.append({"origin": "pve", "source": r_id})
+            pin_rules.append({
+                "vm":      name,
+                "nodes":   node_rels,
+                "origins": origins,
+            })
+
+        # E. Active-mode feedback: pin VMs that failed to migrate previously
+        if pin_vms and name in pin_vms:
+            pin_rules.append({
+                "vm":      name,
+                "nodes":   [_gd("node_current", "")],
+                "origins": [{"origin": "solver", "source": "migration_failed"}],
+            })
+
+        # F. Ignore flag
+        if _gd("ignore", False):
+            ignore_list.append(name)
+
+    # 4. Assemble Constraints --------------------------------------------------
+    constraints = Constraints(
+        affinity=[
+            {"name": k[0], "origin": k[1], "vms": v, "hard": True}
+            for k, v in affinity_groups.items() if len(v) > 1
+        ],
+        anti_affinity=[
+            {"name": k[0], "origin": k[1], "vms": v, "hard": True}
+            for k, v in anti_affinity_groups.items() if len(v) > 1
+        ],
+        pin=pin_rules,
+        ignore=ignore_list,
+    )
+
+    cluster_name = meta.get("cluster_name", "Live Cluster") if isinstance(meta, dict) else "Live Cluster"
+
+    return Cluster(
+        name=cluster_name,
+        description="Auto-generated from ProxLB live data",
+        balancing=balancing,
+        nodes=nodes,
+        vms=vms,
+        constraints=constraints,
+        expect=Expect(feasible=True),
+    )

proxlb_solver/cli.py

@@ -0,0 +1,116 @@
+"""CLI entry point for generating reports."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from .loader import load_scenario
+from .planner import plan_migrations
+from .reporter import (
+    _check_expectations,
+    print_report,
+    write_html_report,
+    write_junit_xml,
+    write_markdown_report,
+)
+from .solver import solve, solve_reachable
+
+# Development fallback: scenarios/ next to the repo root.
+# This path does not exist in an installed package; users must pass --scenarios.
+_DEV_SCENARIOS_DIR = Path(__file__).parent.parent / "scenarios"
+
+
+def collect_scenarios(base: Path) -> list[Path]:
+    return sorted(base.rglob("*.yaml"))
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="ProxLB CP-SAT Solver — run scenarios and generate reports"
+    )
+    parser.add_argument(
+        "--scenarios", type=Path, default=None,
+        help=(
+            "Directory containing YAML scenario files. "
+            "Defaults to scenarios/ relative to the source tree when running "
+            "from a checkout; required when running from an installed package."
+        ),
+    )
+    parser.add_argument(
+        "--markdown", type=Path, default=None,
+        help="Write Markdown report to this path",
+    )
+    parser.add_argument(
+        "--html", type=Path, default=None,
+        help="Write HTML report to this path",
+    )
+    parser.add_argument(
+        "--junit", type=Path, default=None,
+        help="Write JUnit XML report to this path",
+    )
+    parser.add_argument(
+        "--quiet", action="store_true",
+        help="Suppress terminal output",
+    )
+    args = parser.parse_args()
+
+    if args.scenarios is None:
+        if _DEV_SCENARIOS_DIR.is_dir():
+            args.scenarios = _DEV_SCENARIOS_DIR
+        else:
+            parser.error(
+                "--scenarios is required when running from an installed package.\n"
+                "Example: proxlb-solver --scenarios /path/to/scenarios"
+            )
+
+    scenario_files = collect_scenarios(args.scenarios)
+    if not scenario_files:
+        print("No scenarios found in %s" % args.scenarios, file=sys.stderr)
+        sys.exit(1)
+
+    results = []
+    results_junit = []
+    migration_plans = {}
+
+    for path in scenario_files:
+        rel = str(path.relative_to(args.scenarios))
+        cluster = load_scenario(path)
+
+        # Use reachable solver (feedback loop)
+        solution, mig_plan = solve_reachable(cluster, quiet=args.quiet)
+
+        migration_plans[rel] = mig_plan
+
+        if not args.quiet:
+            print_report(cluster, solution)
+
+        results.append((rel, cluster, solution))
+
+        # Evaluate errors for JUnit
+        checks = _check_expectations(cluster, solution, mig_plan)
+        errors = [
+            "%s: %s" % (name, detail)
+            for name, _, passed, detail in checks if not passed
+        ]
+        results_junit.append((rel, cluster, solution, errors))
+
+    if args.markdown:
+        write_markdown_report(results, args.markdown, migration_plans)
+        if not args.quiet:
+            print("\nMarkdown report written to %s" % args.markdown)
+
+    if args.html:
+        write_html_report(results, args.html, migration_plans)
+        if not args.quiet:
+            print("HTML report written to %s" % args.html)
+
+    if args.junit:
+        write_junit_xml(results_junit, args.junit)
+        if not args.quiet:
+            print("JUnit XML written to %s" % args.junit)
+
+
+if __name__ == "__main__":
+    main()

proxlb_solver/loader.py

@@ -0,0 +1,181 @@
+"""YAML scenario loader."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from collections import defaultdict
+
+import yaml
+
+from .models import Balancing, Cluster, Constraints, Expect, Node, VM
+
+_GB = 1024 * 1024 * 1024
+_MB = 1024 * 1024
+
+
+def _gb_to_bytes(value: float) -> int:
+    return int(value * _GB)
+
+
+def load_scenario(path: str | Path) -> Cluster:
+    """Load a YAML scenario file and return a Cluster."""
+    path = Path(path)
+    with open(path) as f:
+        data = yaml.safe_load(f)
+
+    balancing_data = data.get("balancing", {})
+    balanciness = balancing_data.get("balanciness", 3)
+    if not (1 <= balanciness <= 5):
+        raise ValueError(
+            f"balanciness must be 1–5, got {balanciness}"
+        )
+    balancing = Balancing(
+        method=balancing_data.get("method", "memory"),
+        mode=balancing_data.get("mode", "used"),
+        balanciness=balanciness,
+        cpu_overcommit=balancing_data.get("cpu_overcommit", 2.0),
+        memory_threshold=balancing_data.get("memory_threshold"),
+        cpu_threshold=balancing_data.get("cpu_threshold"),
+        disk_threshold=balancing_data.get("disk_threshold"),
+        w_balance=balancing_data.get("w_balance"),
+        w_stickiness=balancing_data.get("w_stickiness"),
+        w_cpu_usage=balancing_data.get("w_cpu_usage", 1),
+        w_cpu_psi=balancing_data.get("w_cpu_psi", 1),
+        w_mem_usage=balancing_data.get("w_mem_usage", 1),
+        w_mem_psi=balancing_data.get("w_mem_psi", 1),
+        w_io_usage=balancing_data.get("w_io_usage", 1),
+        w_io_psi=balancing_data.get("w_io_psi", 1),
+        w_global_mem=balancing_data.get("w_global_mem", 10),
+        w_global_cpu=balancing_data.get("w_global_cpu", 10),
+        w_global_io=balancing_data.get("w_global_io", 1),
+        max_parallel_migrations=balancing_data.get("max_parallel_migrations"),
+        max_node_inflow=balancing_data.get("max_node_inflow", 1),
+    )
+
+    nodes = []
+    for name, nd in data.get("nodes", {}).items():
+        storage_free = {
+            sname: _gb_to_bytes(sval)
+            for sname, sval in nd.get("storage_free", {}).items()
+        }
+
+        reserve_data = nd.get("reserve", {})
+        storage_reserve = {
+            sname: _gb_to_bytes(sval)
+            for sname, sval in reserve_data.get("storage_gb", {}).items()
+        }
+
+        nodes.append(Node(
+            name=name,
+            cpu_total=nd["cpu_total"],
+            memory_total=_gb_to_bytes(nd["memory_total_gb"]),
+            storage_free=storage_free,
+            cpu_reserve=reserve_data.get("cpu", 0),
+            memory_reserve=_gb_to_bytes(reserve_data.get("memory_gb", 0)),
+            storage_reserve=storage_reserve,
+            cpu_pressure=nd.get("cpu_pressure", 0.0),
+            memory_pressure=nd.get("memory_pressure", 0.0),
+            io_pressure=nd.get("io_pressure", 0.0),
+            maintenance=nd.get("maintenance", False),
+        ))
+
+    vms = []
+    tag_affinity = defaultdict(list)
+    tag_anti_affinity = defaultdict(list)
+    tag_pin = []
+
+    for name, vd in data.get("vms", {}).items():
+        disks = {
+            sname: _gb_to_bytes(sval)
+            for sname, sval in vd.get("disks", {}).items()
+        }
+        vms.append(VM(
+            name=name,
+            node=vd["node"],
+            cpu=vd["cpu"],
+            memory=_gb_to_bytes(vd["memory_gb"]),
+            cpu_usage=vd.get("cpu_usage", float(vd["cpu"])),
+            cpu_pressure=vd.get("cpu_pressure", 0.0),
+            memory_pressure=vd.get("memory_pressure", 0.0),
+            io_pressure=vd.get("io_pressure", 0.0),
+            disks=disks,
+            priority=vd.get("priority", 2),
+            vm_type=vd.get("type", "vm"),
+        ))
+
+        # Parse tags for implicit constraints
+        for tag in vd.get("tags", []):
+            if tag.startswith("plb_affinity_"):
+                tag_affinity[tag].append(name)
+            elif tag.startswith("plb_anti_affinity_"):
+                tag_anti_affinity[tag].append(name)
+            elif tag.startswith("plb_pin_"):
+                target_node = tag[len("plb_pin_"):]
+                tag_pin.append({"vm": name, "nodes": [target_node], "origins": [{"origin": "tag", "source": tag}]})
+
+    cd = data.get("constraints", {})
+    ignore_raw = cd.get("ignore", [])
+    ignore_list = []
+    for entry in ignore_raw:
+        if isinstance(entry, dict):
+            ignore_list.append(entry["vm"])
+        else:
+            ignore_list.append(entry)
+
+    affinity = [{**r, "hard": r.get("hard", True), "origin": r.get("origin", "plb")} for r in cd.get("affinity", [])]
+    for tag, t_vms in tag_affinity.items():
+        if len(t_vms) > 1:
+            affinity.append({"name": tag, "vms": t_vms, "hard": True, "origin": "plb"})
+
+    anti_affinity = [{**r, "hard": r.get("hard", True), "origin": r.get("origin", "plb")} for r in cd.get("anti_affinity", [])]
+    for tag, t_vms in tag_anti_affinity.items():
+        if len(t_vms) > 1:
+            anti_affinity.append({"name": tag, "vms": t_vms, "hard": True, "origin": "plb"})
+
+    pin = cd.get("pin", []) + tag_pin
+
+    constraints = Constraints(
+        affinity=affinity,
+        anti_affinity=anti_affinity,
+        pin=pin,
+        ignore=ignore_list,
+    )
+
+    ed = data.get("expect", {})
+    placements_raw = ed.get("placements", {})
+    placements = {k: str(v) for k, v in placements_raw.items()}
+
+    expect = Expect(
+        feasible=ed.get("feasible", True),
+        constraints_satisfied=ed.get("constraints_satisfied", True),
+        spread_improved=ed.get("spread_improved"),
+        max_migrations=ed.get("max_migrations"),
+        placements=placements,
+        node_empty=ed.get("node_empty"),
+        path_feasible=ed.get("path_feasible"),
+    )
+
+    evacuate_node = data.get("evacuate_node")
+
+    # Validate references
+    node_names = {n.name for n in nodes}
+    for vm in vms:
+        if vm.node not in node_names:
+            raise ValueError(
+                f"VM '{vm.name}' references unknown node '{vm.node}'"
+            )
+    if evacuate_node and evacuate_node not in node_names:
+        raise ValueError(
+            f"evacuate_node '{evacuate_node}' is not a known node"
+        )
+
+    return Cluster(
+        name=data.get("name", path.stem),
+        description=data.get("description", ""),
+        balancing=balancing,
+        nodes=nodes,
+        vms=vms,
+        constraints=constraints,
+        expect=expect,
+        evacuate_node=evacuate_node,
+    )