solverpilot 0.1__py3-none-any.whl

solverpilot/applications/routing/solution.py

@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from math import isfinite
+from types import MappingProxyType
+from typing import Any, Mapping, Sequence
+
+from .errors import VRPValidationError
+
+
+_INDEPENDENT_PROOF_TOKEN = object()
+
+
+@dataclass(frozen=True, slots=True)
+class VRPRoute:
+    vehicle_id: str
+    customer_ids: tuple[str, ...]
+
+    def __init__(self, vehicle_id: str, customer_ids: Sequence[str] = ()) -> None:
+        vehicle = str(vehicle_id).strip()
+        if not vehicle:
+            raise VRPValidationError("route vehicle_id must be non-empty")
+        ids = tuple(str(x).strip() for x in customer_ids)
+        if any(not x for x in ids):
+            raise VRPValidationError("route customer ids must be non-empty strings")
+        object.__setattr__(self, "vehicle_id", vehicle)
+        object.__setattr__(self, "customer_ids", ids)
+
+
+@dataclass(frozen=True, slots=True)
+class VRPSolution:
+    routes: tuple[VRPRoute, ...]
+    objective: float
+    method: str
+    is_exact: bool
+    optimality_proven: bool
+    unassigned_customer_ids: tuple[str, ...] = ()
+    runtime_seconds: float | None = None
+    metadata: Mapping[str, Any] = field(default_factory=dict, compare=False)
+
+    def __init__(
+        self,
+        routes: Sequence[VRPRoute],
+        objective: float,
+        *,
+        method: str,
+        is_exact: bool,
+        optimality_proven: bool,
+        unassigned_customer_ids: Sequence[str] = (),
+        runtime_seconds: float | None = None,
+        metadata: Mapping[str, Any] | None = None,
+        _proof_token: object | None = None,
+    ) -> None:
+        route_tuple = tuple(routes)
+        if any(not isinstance(r, VRPRoute) for r in route_tuple):
+            raise VRPValidationError("routes must contain VRPRoute objects")
+        if isinstance(objective, bool):
+            raise VRPValidationError("VRP objective must be numeric, not bool")
+        obj = float(objective)
+        if not isfinite(obj) or obj < 0.0:
+            raise VRPValidationError("VRP objective must be finite and non-negative")
+        if type(is_exact) is not bool or type(optimality_proven) is not bool:
+            raise VRPValidationError("is_exact and optimality_proven must be bool")
+        if optimality_proven and not is_exact:
+            raise VRPValidationError("optimality_proven requires is_exact=True")
+        if optimality_proven and _proof_token is not _INDEPENDENT_PROOF_TOKEN:
+            raise VRPValidationError(
+                "independent optimality proof may only be issued by SolverPilot verified/reference paths"
+            )
+        method_value = str(method).strip()
+        if not method_value:
+            raise VRPValidationError("VRP solution method must be non-empty")
+        unassigned = tuple(str(x).strip() for x in unassigned_customer_ids)
+        if any(not x for x in unassigned) or len(set(unassigned)) != len(unassigned):
+            raise VRPValidationError("unassigned customer ids must be unique non-empty strings")
+        if runtime_seconds is not None:
+            if isinstance(runtime_seconds, bool):
+                raise VRPValidationError("runtime_seconds must be numeric, not bool")
+            runtime_seconds = float(runtime_seconds)
+            if not isfinite(runtime_seconds) or runtime_seconds < 0.0:
+                raise VRPValidationError("runtime_seconds must be finite and non-negative")
+        object.__setattr__(self, "routes", route_tuple)
+        object.__setattr__(self, "objective", obj)
+        object.__setattr__(self, "method", method_value)
+        object.__setattr__(self, "is_exact", is_exact)
+        object.__setattr__(self, "optimality_proven", optimality_proven)
+        object.__setattr__(self, "unassigned_customer_ids", unassigned)
+        object.__setattr__(self, "runtime_seconds", runtime_seconds)
+        object.__setattr__(self, "metadata", MappingProxyType(dict(metadata or {})))

solverpilot/applications/routing/timeline.py

@@ -0,0 +1,79 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from math import isfinite
+
+from .errors import VRPValidationError
+from .model import VRPInstance
+from .solution import VRPRoute
+
+
+@dataclass(frozen=True, slots=True)
+class VRPVisitTimeline:
+    customer_id: str
+    arrival: float
+    waiting: float
+    service_start: float
+    departure: float
+    within_time_window: bool
+
+
+@dataclass(frozen=True, slots=True)
+class VRPRouteTimeline:
+    vehicle_id: str
+    used: bool
+    start_time: float
+    return_time: float
+    route_duration: float
+    visits: tuple[VRPVisitTimeline, ...]
+    violations: tuple[str, ...]
+
+    @property
+    def valid(self) -> bool:
+        return not self.violations
+
+
+def build_route_timeline(instance: VRPInstance, route: VRPRoute, *, tolerance: float = 1e-9) -> VRPRouteTimeline:
+    if isinstance(tolerance, bool):
+        raise VRPValidationError("timeline tolerance must be numeric")
+    tolerance = float(tolerance)
+    if not isfinite(tolerance) or tolerance < 0.0:
+        raise VRPValidationError("timeline tolerance must be finite and non-negative")
+    if instance.travel_times is None:
+        raise VRPValidationError("route timeline requires an explicit travel-time matrix")
+    vehicles = instance.vehicle_map
+    customers = instance.customer_map
+    if route.vehicle_id not in vehicles:
+        raise VRPValidationError(f"unknown vehicle {route.vehicle_id!r}")
+    vehicle = vehicles[route.vehicle_id]
+    current_time = vehicle.start_time
+    previous_node = vehicle.start_node_id
+    visits: list[VRPVisitTimeline] = []
+    violations: list[str] = []
+    for customer_id in route.customer_ids:
+        customer = customers.get(customer_id)
+        if customer is None:
+            raise VRPValidationError(f"unknown customer {customer_id!r}")
+        arrival = current_time + instance.travel_time(previous_node, customer.node_id)
+        service_start = arrival
+        if customer.time_window is not None:
+            service_start = max(arrival, customer.time_window.start)
+        waiting = service_start - arrival
+        within = customer.time_window is None or service_start <= customer.time_window.end + tolerance
+        if not within:
+            violations.append(f"late_arrival:{customer.id}")
+        departure = service_start + customer.service_duration
+        visits.append(VRPVisitTimeline(customer.id, arrival, waiting, service_start, departure, within))
+        current_time = departure
+        previous_node = customer.node_id
+    if route.customer_ids:
+        current_time += instance.travel_time(previous_node, vehicle.end_node_id)
+    # Unused vehicle is not dispatched; it incurs no route duration or depot-to-depot travel.
+    used = bool(route.customer_ids)
+    return_time = current_time if used else vehicle.start_time
+    duration = return_time - vehicle.start_time
+    if vehicle.latest_return is not None and return_time > vehicle.latest_return + tolerance:
+        violations.append("vehicle_shift_late_return")
+    if vehicle.max_route_duration is not None and duration > vehicle.max_route_duration + tolerance:
+        violations.append("max_route_duration_exceeded")
+    return VRPRouteTimeline(route.vehicle_id, used, vehicle.start_time, return_time, duration, tuple(visits), tuple(violations))

solverpilot/applications/routing/validation.py

@@ -0,0 +1,169 @@
+from __future__ import annotations
+
+from collections import Counter
+from dataclasses import dataclass
+from math import isclose, isfinite
+from typing import Sequence
+
+from .model import VRPInstance
+from .solution import VRPRoute, VRPSolution
+from .timeline import VRPRouteTimeline, build_route_timeline
+
+
+@dataclass(frozen=True, slots=True)
+class VRPValidationIssue:
+    code: str
+    message: str
+    vehicle_id: str | None = None
+    customer_id: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class VRPValidationReport:
+    valid: bool
+    issues: tuple[VRPValidationIssue, ...]
+    objective_recomputed: float | None
+    objective_reported: float | None
+    objective_difference: float | None
+    route_loads: tuple[tuple[str, float], ...]
+    route_distances: tuple[tuple[str, float], ...]
+    timelines: tuple[VRPRouteTimeline, ...]
+    validated_dimensions: tuple[str, ...]
+
+    @property
+    def errors(self) -> tuple[str, ...]:
+        return tuple(i.message for i in self.issues)
+
+
+def route_distance(instance: VRPInstance, route: VRPRoute) -> float:
+    if route.vehicle_id not in instance.vehicle_map:
+        from .errors import VRPValidationError
+        raise VRPValidationError(f"unknown vehicle {route.vehicle_id!r}")
+    unknown = [cid for cid in route.customer_ids if cid not in instance.customer_map]
+    if unknown:
+        from .errors import VRPValidationError
+        raise VRPValidationError(f"unknown customer(s) in route: {sorted(set(unknown))}")
+    if not route.customer_ids:
+        return 0.0
+    vehicles = instance.vehicle_map
+    customers = instance.customer_map
+    vehicle = vehicles[route.vehicle_id]
+    total = 0.0
+    previous = vehicle.start_node_id
+    for cid in route.customer_ids:
+        c = customers[cid]
+        total += instance.distance(previous, c.node_id)
+        previous = c.node_id
+    total += instance.distance(previous, vehicle.end_node_id)
+    return float(total)
+
+
+def _route_load(instance: VRPInstance, route: VRPRoute) -> float:
+    customers = instance.customer_map
+    return float(sum(customers[cid].demand for cid in route.customer_ids if cid in customers))
+
+
+def validate_vrp_solution(
+    instance: VRPInstance,
+    solution_or_routes: VRPSolution | Sequence[VRPRoute],
+    *,
+    reported_objective: float | None = None,
+    atol: float = 1e-8,
+    rtol: float = 1e-8,
+) -> VRPValidationReport:
+    if isinstance(atol, bool) or isinstance(rtol, bool):
+        raise ValueError("VRP validation tolerances must be numeric")
+    atol = float(atol); rtol = float(rtol)
+    if not isfinite(atol) or not isfinite(rtol) or atol < 0.0 or rtol < 0.0:
+        raise ValueError("VRP validation tolerances must be finite and non-negative")
+    if isinstance(solution_or_routes, VRPSolution):
+        solution = solution_or_routes
+        routes = solution.routes
+        if reported_objective is None:
+            reported_objective = solution.objective
+        declared_unassigned = set(solution.unassigned_customer_ids)
+    else:
+        solution = None
+        routes = tuple(solution_or_routes)
+        declared_unassigned = set()
+    issues: list[VRPValidationIssue] = []
+    vehicle_map = instance.vehicle_map
+    customer_map = instance.customer_map
+    seen_vehicles: Counter[str] = Counter()
+    served: list[str] = []
+    route_loads: list[tuple[str, float]] = []
+    route_distances: list[tuple[str, float]] = []
+    timelines: list[VRPRouteTimeline] = []
+    objective = 0.0
+    for route in routes:
+        if not isinstance(route, VRPRoute):
+            issues.append(VRPValidationIssue("invalid_route_type", "solution routes must contain VRPRoute objects"))
+            continue
+        seen_vehicles[route.vehicle_id] += 1
+        vehicle = vehicle_map.get(route.vehicle_id)
+        if vehicle is None:
+            issues.append(VRPValidationIssue("unknown_vehicle", f"route references unknown vehicle {route.vehicle_id!r}", route.vehicle_id))
+            continue
+        if seen_vehicles[route.vehicle_id] > 1:
+            issues.append(VRPValidationIssue("duplicate_vehicle_route", f"vehicle {route.vehicle_id!r} has multiple routes", route.vehicle_id))
+        local = Counter(route.customer_ids)
+        for cid, count in local.items():
+            if cid not in customer_map:
+                issues.append(VRPValidationIssue("unknown_customer", f"route references unknown customer {cid!r}", route.vehicle_id, cid))
+            elif count > 1:
+                issues.append(VRPValidationIssue("duplicate_customer_in_route", f"customer {cid!r} is repeated in one route", route.vehicle_id, cid))
+        if any(cid not in customer_map for cid in route.customer_ids):
+            continue
+        served.extend(route.customer_ids)
+        load = _route_load(instance, route)
+        route_loads.append((route.vehicle_id, load))
+        if load > vehicle.capacity + atol:
+            issues.append(VRPValidationIssue("capacity_exceeded", f"vehicle {route.vehicle_id!r} load {load} exceeds capacity {vehicle.capacity}", route.vehicle_id))
+        dist = route_distance(instance, route)
+        route_distances.append((route.vehicle_id, dist))
+        objective += dist
+        if instance.has_time_constraints:
+            timeline = build_route_timeline(instance, route, tolerance=atol)
+            timelines.append(timeline)
+            for code in timeline.violations:
+                customer_id = code.split(":", 1)[1] if code.startswith("late_arrival:") else None
+                base_code = "time_window_violation" if customer_id is not None else code
+                issues.append(VRPValidationIssue(base_code, f"route {route.vehicle_id!r} violates {code}", route.vehicle_id, customer_id))
+    served_counts = Counter(served)
+    duplicated_global = sorted(cid for cid, count in served_counts.items() if count > 1)
+    for cid in duplicated_global:
+        issues.append(VRPValidationIssue("duplicate_customer_assignment", f"customer {cid!r} is assigned more than once", customer_id=cid))
+    required = set(customer_map)
+    served_set = set(served_counts)
+    missing = sorted(required - served_set)
+    for cid in missing:
+        issues.append(VRPValidationIssue("unassigned_customer", f"customer {cid!r} is not assigned", customer_id=cid))
+    unknown_unassigned = sorted(declared_unassigned - required)
+    for cid in unknown_unassigned:
+        issues.append(VRPValidationIssue("unknown_unassigned_customer", f"unassigned list contains unknown customer {cid!r}", customer_id=cid))
+    contradictory = sorted(declared_unassigned & served_set)
+    for cid in contradictory:
+        issues.append(VRPValidationIssue("served_and_unassigned", f"customer {cid!r} is both served and declared unassigned", customer_id=cid))
+    if solution is not None and set(missing) != declared_unassigned:
+        issues.append(VRPValidationIssue("unassigned_declaration_mismatch", "declared unassigned customers do not exactly match missing coverage"))
+    reported: float | None = None
+    difference: float | None = None
+    if reported_objective is not None:
+        if isinstance(reported_objective, bool):
+            issues.append(VRPValidationIssue("invalid_objective", "reported objective must be numeric, not bool"))
+        else:
+            try:
+                reported = float(reported_objective)
+            except (TypeError, ValueError):
+                issues.append(VRPValidationIssue("invalid_objective", "reported objective must be numeric"))
+            else:
+                if not isfinite(reported):
+                    issues.append(VRPValidationIssue("invalid_objective", "reported objective must be finite"))
+                else:
+                    difference = reported - objective
+                    if not isclose(reported, objective, abs_tol=atol, rel_tol=rtol):
+                        issues.append(VRPValidationIssue("objective_mismatch", "reported objective does not match independently recomputed route distance"))
+    dims = ["coverage", "vehicle_references", "capacity", "distance", "objective"]
+    if instance.has_time_constraints:
+        dims.extend(("travel_time", "customer_time_windows", "vehicle_shift", "route_duration"))
+    return VRPValidationReport(not issues, tuple(issues), objective, reported, difference, tuple(route_loads), tuple(route_distances), tuple(timelines), tuple(dims))

solverpilot/applications/tsp/__init__.py

@@ -0,0 +1,41 @@
+"""Trust-aware Traveling Salesperson Problem application pack.
+
+The pack deliberately keeps exact references, heuristics, formulation compilers,
+and independent validation separate. It does not replace SolverPilot's canonical
+optimization runtime or backend registries.
+"""
+
+from .compile_cp import (
+    MAX_CP_OBJECTIVE,
+    MAX_EXACT_BINARY64_INTEGER,
+    TSPCPCompilation,
+    TSPCPSolveResult,
+    compile_tsp_cp,
+    decode_tsp_cp_solution,
+    solve_tsp_cp,
+)
+from .compile_milp import (
+    TSPMILPCompilation,
+    TSPMILPSolveResult,
+    compile_tsp_milp,
+    decode_tsp_milp_solution,
+    solve_tsp_milp,
+)
+from .distance import TSPDistanceAnalysis, analyze_distance_matrix, route_cost
+from .errors import TSPCompileError, TSPError, TSPReferenceLimitError, TSPValidationError
+from .heuristics import solve_tsp_multistart_nearest_neighbor, solve_tsp_nearest_neighbor, solve_tsp_two_opt
+from .model import TSPDistanceMatrix, TSPInstance, TSPNode
+from .reference import solve_tsp_brute_force, solve_tsp_held_karp
+from .solution import TSPSolution
+from .validation import TSPValidationReport, validate_tsp_route
+
+__all__ = [
+    "MAX_CP_OBJECTIVE", "MAX_EXACT_BINARY64_INTEGER",
+    "TSPCPCompilation", "TSPCPSolveResult", "TSPCompileError", "TSPDistanceAnalysis",
+    "TSPDistanceMatrix", "TSPError", "TSPInstance", "TSPMILPCompilation", "TSPMILPSolveResult",
+    "TSPNode", "TSPReferenceLimitError", "TSPSolution", "TSPValidationError", "TSPValidationReport",
+    "analyze_distance_matrix", "compile_tsp_cp", "compile_tsp_milp", "decode_tsp_cp_solution",
+    "decode_tsp_milp_solution", "route_cost", "solve_tsp_brute_force", "solve_tsp_cp",
+    "solve_tsp_held_karp", "solve_tsp_milp", "solve_tsp_multistart_nearest_neighbor",
+    "solve_tsp_nearest_neighbor", "solve_tsp_two_opt", "validate_tsp_route",
+]

solverpilot/applications/tsp/compile_cp.py

@@ -0,0 +1,121 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from types import MappingProxyType
+from typing import Mapping
+
+from solverpilot.cp import CPModel, CPProblem, CPSolveResult, ReferenceCPBackend, validate_cp_solution
+
+from .distance import route_cost
+from .errors import TSPCompileError, TSPValidationError
+from .model import TSPInstance
+from .solution import TSPSolution, _INDEPENDENT_PROOF_TOKEN
+from .validation import TSPValidationReport, validate_tsp_route
+
+MAX_EXACT_BINARY64_INTEGER = (1 << 53) - 1
+MAX_CP_OBJECTIVE = (1 << 63) - 1
+
+
+@dataclass(frozen=True, slots=True)
+class TSPCPCompilation:
+    problem: CPProblem
+    arc_variables: Mapping[tuple[int, int], int]
+    start_index: int
+
+
+@dataclass(frozen=True, slots=True)
+class TSPCPSolveResult:
+    solution: TSPSolution | None
+    validation: TSPValidationReport | None
+    core_result: CPSolveResult
+
+
+def _start(instance: TSPInstance, start_index: int) -> int:
+    if isinstance(start_index, bool) or not isinstance(start_index, int) or not 0 <= start_index < instance.n_nodes:
+        raise TSPValidationError("start_index must be an in-range integer")
+    return start_index
+
+
+def _exact_costs(instance: TSPInstance) -> dict[tuple[int,int],int]:
+    costs: dict[tuple[int,int],int] = {}
+    max_cost=0
+    for i in range(instance.n_nodes):
+        for j in range(instance.n_nodes):
+            if i==j: continue
+            value=instance.distances.values[i][j]
+            if not value.is_integer():
+                raise TSPCompileError("CP TSP compiler requires exactly integer-valued distances; use MILP for float costs")
+            integer=int(value)
+            if integer > MAX_EXACT_BINARY64_INTEGER:
+                raise TSPCompileError("CP TSP distance exceeds the conservative exact binary64 integer range")
+            max_cost=max(max_cost,integer)
+            costs[(i,j)]=integer
+    if instance.n_nodes * max_cost > MAX_CP_OBJECTIVE:
+        raise TSPCompileError("CP TSP objective can overflow signed int64")
+    return costs
+
+
+def compile_tsp_cp(instance:TSPInstance, *, start_index:int=0) -> TSPCPCompilation:
+    start=_start(instance,start_index)
+    costs=_exact_costs(instance)
+    model=CPModel(name=f"tsp-circuit:{instance.name}")
+    literals={arc:model.bool_var(name=f"x_{arc[0]}_{arc[1]}") for arc in costs}
+    model.add_circuit((i,j,literals[(i,j)]) for i,j in costs)
+    objective=0
+    for arc,lit in literals.items():
+        objective = objective + costs[arc]*lit
+    model.minimize(objective)
+    problem=model.compile()
+    # CPModel metadata cannot currently be set through the builder; keep the canonical IR untouched.
+    return TSPCPCompilation(problem, MappingProxyType({arc:lit.var_id for arc,lit in literals.items()}), start)
+
+
+def decode_tsp_cp_solution(instance:TSPInstance, compilation:TSPCPCompilation, assignment:Mapping[int,int]) -> tuple[int,...]:
+    for key, value in assignment.items():
+        if isinstance(key, bool) or not isinstance(key, int):
+            raise TSPCompileError("CP assignment keys must be integer variable ids")
+        if isinstance(value, bool):
+            continue
+        if not isinstance(value, int):
+            raise TSPCompileError("CP assignment values must be exact integers")
+    canonical = validate_cp_solution(compilation.problem, assignment)
+    if not canonical.valid:
+        raise TSPCompileError("CP candidate failed canonical formulation validation")
+    selected={(i,j) for (i,j),vid in compilation.arc_variables.items() if int(assignment.get(vid,0))==1}
+    n=instance.n_nodes
+    outgoing:dict[int,int]={}; incoming:dict[int,int]={}
+    for i,j in selected:
+        if i in outgoing or j in incoming:
+            raise TSPCompileError("CP candidate does not encode exactly one incoming/outgoing arc")
+        outgoing[i]=j; incoming[j]=i
+    if set(outgoing)!=set(range(n)) or set(incoming)!=set(range(n)):
+        raise TSPCompileError("CP candidate does not cover every TSP node")
+    route=[compilation.start_index]; cur=compilation.start_index
+    for _ in range(n):
+        cur=outgoing[cur]; route.append(cur)
+    if cur!=compilation.start_index or len(set(route[:-1]))!=n:
+        raise TSPCompileError("CP candidate contains a subtour instead of one Hamiltonian cycle")
+    return tuple(route)
+
+
+def solve_tsp_cp(instance:TSPInstance, *, backend=None, start_index:int=0, **solve_kwargs) -> TSPCPSolveResult:
+    compilation=compile_tsp_cp(instance,start_index=start_index)
+    cp_backend=ReferenceCPBackend() if backend is None else backend
+    core=cp_backend.solve(compilation.problem,**solve_kwargs)
+    if core.assignment is None:
+        return TSPCPSolveResult(None,None,core)
+    if getattr(core.validation, "valid", False) is not True:
+        raise TSPCompileError("CP backend returned a candidate that failed SolverPilot CP validation")
+    route=decode_tsp_cp_solution(instance,compilation,core.assignment)
+    objective=route_cost(instance,route)
+    independent_proof = bool(core.optimality_proven and isinstance(cp_backend, ReferenceCPBackend))
+    solution=TSPSolution(
+        route, objective, method=f"cp-circuit:{core.backend}", is_exact=True,
+        optimality_proven=independent_proof,
+        _proof_token=_INDEPENDENT_PROOF_TOKEN,
+        metadata={"cp_status":core.status, "backend_optimality_proven": bool(core.optimality_proven), "independent_reference_proof": independent_proof},
+    )
+    report=validate_tsp_route(instance,solution)
+    if not report.valid:
+        raise TSPCompileError("decoded CP solution failed independent TSP validation")
+    return TSPCPSolveResult(solution,report,core)

solverpilot/applications/tsp/compile_milp.py

@@ -0,0 +1,139 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from types import MappingProxyType
+from typing import Mapping
+
+import numpy as np
+from scipy import sparse
+
+from solverpilot.backends import ScipyHighsBackend
+from solverpilot.problem import LinearProblem, ObjectiveSense, VariableDomain
+from solverpilot.runtime import SolveResult, execute
+from solverpilot.validate import CandidateSolution, validate_solution
+
+from .errors import TSPCompileError, TSPValidationError
+from .model import TSPInstance
+from .solution import TSPSolution, _INDEPENDENT_PROOF_TOKEN
+from .validation import TSPValidationReport, validate_tsp_route
+from .distance import route_cost
+
+
+@dataclass(frozen=True, slots=True)
+class TSPMILPCompilation:
+    problem: LinearProblem
+    arc_variables: Mapping[tuple[int, int], int]
+    order_variables: Mapping[int, int]
+    start_index: int
+
+
+@dataclass(frozen=True, slots=True)
+class TSPMILPSolveResult:
+    solution: TSPSolution | None
+    validation: TSPValidationReport | None
+    core_result: SolveResult
+
+
+def _start(instance: TSPInstance, start_index: int) -> int:
+    if isinstance(start_index, bool) or not isinstance(start_index, int) or not 0 <= start_index < instance.n_nodes:
+        raise TSPValidationError("start_index must be an in-range integer")
+    return start_index
+
+
+def compile_tsp_milp(instance: TSPInstance, *, start_index: int = 0) -> TSPMILPCompilation:
+    start = _start(instance, start_index)
+    n = instance.n_nodes
+    arcs = {(i, j): k for k, (i, j) in enumerate(( (i,j) for i in range(n) for j in range(n) if i != j ))}
+    order_nodes = tuple(i for i in range(n) if i != start)
+    orders = {node: len(arcs) + k for k, node in enumerate(order_nodes)}
+    nvars = len(arcs) + len(orders)
+    c = np.zeros(nvars, dtype=np.float64)
+    lower = np.zeros(nvars, dtype=np.float64)
+    upper = np.ones(nvars, dtype=np.float64)
+    domains: list[VariableDomain] = [VariableDomain.BINARY] * len(arcs) + [VariableDomain.CONTINUOUS] * len(orders)
+    for (i, j), idx in arcs.items():
+        c[idx] = instance.distances.values[i][j]
+    for node, idx in orders.items():
+        lower[idx] = 1.0
+        upper[idx] = float(max(1, n - 1))
+    row_i: list[int] = []
+    col_i: list[int] = []
+    data: list[float] = []
+    cl: list[float] = []
+    cu: list[float] = []
+    row = 0
+    for i in range(n):
+        for j in range(n):
+            if i != j:
+                row_i.append(row); col_i.append(arcs[(i,j)]); data.append(1.0)
+        cl.append(1.0); cu.append(1.0); row += 1
+    for j in range(n):
+        for i in range(n):
+            if i != j:
+                row_i.append(row); col_i.append(arcs[(i,j)]); data.append(1.0)
+        cl.append(1.0); cu.append(1.0); row += 1
+    # MTZ subtour elimination on non-start nodes: u_i - u_j + n*x_ij <= n-1.
+    for i in order_nodes:
+        for j in order_nodes:
+            if i == j:
+                continue
+            row_i.extend((row,row,row))
+            col_i.extend((orders[i],orders[j],arcs[(i,j)]))
+            data.extend((1.0,-1.0,float(n)))
+            cl.append(-np.inf); cu.append(float(n-1)); row += 1
+    A = sparse.csr_matrix((data,(row_i,col_i)), shape=(row,nvars), dtype=np.float64)
+    problem = LinearProblem.from_data(
+        A=A,
+        c=c,
+        variable_lower=lower,
+        variable_upper=upper,
+        constraint_lower=np.asarray(cl,dtype=np.float64),
+        constraint_upper=np.asarray(cu,dtype=np.float64),
+        domains=domains,
+        objective_sense=ObjectiveSense.MINIMIZE,
+        name=f"tsp-mtz:{instance.name}",
+        metadata={"application":"tsp","formulation":"directed-mtz","n_nodes":n,"start_index":start},
+    )
+    return TSPMILPCompilation(problem, MappingProxyType(dict(arcs)), MappingProxyType(dict(orders)), start)
+
+
+def decode_tsp_milp_solution(instance: TSPInstance, compilation: TSPMILPCompilation, x: np.ndarray) -> tuple[int, ...]:
+    values = np.asarray(x, dtype=np.float64)
+    if values.ndim != 1 or values.shape[0] != compilation.problem.n_variables or not np.isfinite(values).all():
+        raise TSPCompileError("MILP candidate vector has invalid shape or non-finite values")
+    canonical = validate_solution(compilation.problem, CandidateSolution(x=values))
+    if not canonical.valid:
+        raise TSPCompileError("MILP candidate failed canonical formulation validation: " + "; ".join(canonical.warnings))
+    selected = {(i,j) for (i,j), idx in compilation.arc_variables.items() if values[idx] > 0.5}
+    n = instance.n_nodes
+    outgoing: dict[int,int] = {}
+    incoming: dict[int,int] = {}
+    for i,j in selected:
+        if i in outgoing or j in incoming:
+            raise TSPCompileError("MILP candidate does not encode exactly one incoming/outgoing arc")
+        outgoing[i]=j; incoming[j]=i
+    if set(outgoing) != set(range(n)) or set(incoming) != set(range(n)):
+        raise TSPCompileError("MILP candidate does not cover every TSP node")
+    route=[compilation.start_index]
+    cur=compilation.start_index
+    for _ in range(n):
+        cur=outgoing[cur]; route.append(cur)
+    if cur != compilation.start_index or len(set(route[:-1])) != n:
+        raise TSPCompileError("MILP candidate contains a subtour instead of one Hamiltonian cycle")
+    return tuple(route)
+
+
+def solve_tsp_milp(instance: TSPInstance, *, backend=None, start_index: int = 0) -> TSPMILPSolveResult:
+    compilation = compile_tsp_milp(instance, start_index=start_index)
+    core = execute(compilation.problem, ScipyHighsBackend() if backend is None else backend)
+    if core.x is None:
+        return TSPMILPSolveResult(None, None, core)
+    if core.validation is None or not core.validation.valid:
+        raise TSPCompileError("MILP backend returned a candidate that failed SolverPilot core validation")
+    route = decode_tsp_milp_solution(instance, compilation, core.x)
+    objective = route_cost(instance, route)
+    solution = TSPSolution(route, objective, method="milp-mtz", is_exact=True, optimality_proven=core.optimality_evidence.independently_verified_optimal, _proof_token=_INDEPENDENT_PROOF_TOKEN, metadata={"backend_status": core.backend_status, "backend": core.trace.backend})
+    report = validate_tsp_route(instance, solution)
+    if not report.valid:
+        raise TSPCompileError("decoded MILP solution failed independent TSP validation")
+    return TSPMILPSolveResult(solution, report, core)