solverpilot 0.1__py3-none-any.whl

solverpilot/applications/routing/diagnostics.py

@@ -0,0 +1,78 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from math import isfinite
+
+from .model import VRPInstance
+from .solution import VRPSolution
+from .validation import VRPValidationReport, validate_vrp_solution
+
+
+@dataclass(frozen=True, slots=True)
+class VRPDiagnosticAction:
+    code: str
+    target: str
+    severity: str
+    suggestion: str
+    evidence_code: str
+
+
+_ACTIONS = {
+    "capacity_exceeded": ("blocking", "Split the route, reassign customers, or use a vehicle with more capacity."),
+    "time_window_violation": ("blocking", "Resequence the stop earlier, relax its time window, split the route, or reassign it."),
+    "vehicle_shift_late_return": ("blocking", "Split or shorten the route, extend the vehicle shift, or reassign late stops."),
+    "max_route_duration_exceeded": ("blocking", "Split the route, add a vehicle, or explicitly increase the permitted route duration."),
+    "unassigned_customer": ("blocking", "Add capacity/vehicles or relax the blocking routing constraints before retrying assignment."),
+    "duplicate_customer_assignment": ("blocking", "Remove duplicate service and recompute the route plan."),
+    "objective_mismatch": ("blocking", "Discard the reported objective and recompute it from the route and distance matrix."),
+    "unknown_vehicle": ("blocking", "Repair the vehicle reference before using the plan."),
+    "unknown_customer": ("blocking", "Repair the customer reference before using the plan."),
+}
+
+
+def diagnose_vrp_validation(report: VRPValidationReport) -> tuple[VRPDiagnosticAction, ...]:
+    actions: list[VRPDiagnosticAction] = []
+    seen: set[tuple[str, str]] = set()
+    for issue in report.issues:
+        severity, suggestion = _ACTIONS.get(issue.code, ("warning", "Review the validation evidence and repair the route before operational use."))
+        target = issue.customer_id or issue.vehicle_id or "solution"
+        key = (issue.code, target)
+        if key in seen:
+            continue
+        seen.add(key)
+        actions.append(VRPDiagnosticAction(issue.code, target, severity, suggestion, issue.code))
+    return tuple(actions)
+
+
+def diagnose_vrp_solution(instance: VRPInstance, solution: VRPSolution, *, waiting_warning_threshold: float = 30.0) -> tuple[VRPDiagnosticAction, ...]:
+    """Build actionable diagnostics without promoting suggestions to proofs.
+
+    Validation blockers are emitted first.  Feasible waiting time is reported as
+    informational/warning evidence because it can be operationally useful but is
+    not itself an infeasibility.
+    """
+    if isinstance(waiting_warning_threshold, bool):
+        raise ValueError("waiting_warning_threshold must be numeric")
+    threshold = float(waiting_warning_threshold)
+    if not isfinite(threshold) or threshold < 0.0:
+        raise ValueError("waiting_warning_threshold must be finite and non-negative")
+    report = validate_vrp_solution(instance, solution)
+    actions = list(diagnose_vrp_validation(report))
+    seen = {(a.code, a.target) for a in actions}
+    for timeline in report.timelines:
+        for visit in timeline.visits:
+            if visit.waiting <= 1e-12:
+                continue
+            key = ("waiting_time_detected", visit.customer_id)
+            if key in seen:
+                continue
+            seen.add(key)
+            severity = "warning" if visit.waiting >= threshold else "info"
+            actions.append(VRPDiagnosticAction(
+                "waiting_time_detected",
+                visit.customer_id,
+                severity,
+                "Accept the wait if it protects the time window, or consider resequencing; this is a suggestion, not an automatic improvement claim.",
+                "timeline_waiting",
+            ))
+    return tuple(actions)

solverpilot/applications/routing/errors.py

@@ -0,0 +1,14 @@
+class VRPError(Exception):
+    """Base error for the SolverPilot routing application pack."""
+
+
+class VRPValidationError(VRPError, ValueError):
+    """Raised for invalid VRP data or solution objects."""
+
+
+class VRPCompileError(VRPError, RuntimeError):
+    """Raised when a VRP formulation cannot be compiled or decoded safely."""
+
+
+class VRPReferenceLimitError(VRPError, RuntimeError):
+    """Raised when an exact reference solve exceeds its declared safety limit."""

solverpilot/applications/routing/heuristics.py

@@ -0,0 +1,167 @@
+from __future__ import annotations
+
+from time import perf_counter
+
+from .model import VRPInstance
+from .solution import VRPRoute, VRPSolution
+from .validation import route_distance, validate_vrp_solution
+
+
+def _partial_valid(instance: VRPInstance, routes: list[list[str]]) -> bool:
+    # Check each route locally without requiring global coverage by constructing only capacity/timeline facts.
+    customers = instance.customer_map
+    for vehicle, ids in zip(instance.vehicles, routes):
+        if sum(customers[c].demand for c in ids) > vehicle.capacity + 1e-9:
+            return False
+        if instance.has_time_constraints:
+            from .timeline import build_route_timeline
+            if not build_route_timeline(instance, VRPRoute(vehicle.id, ids)).valid:
+                return False
+    return True
+
+
+def nearest_feasible_insertion(instance: VRPInstance, *, improve: bool = True) -> VRPSolution:
+    started = perf_counter()
+    routes: list[list[str]] = [[] for _ in instance.vehicles]
+    unassigned: list[str] = []
+    for customer in instance.customers:
+        options: list[tuple[float, int, int, list[list[str]]]] = []
+        for vi, vehicle in enumerate(instance.vehicles):
+            for pos in range(len(routes[vi]) + 1):
+                candidate_routes = [list(r) for r in routes]
+                candidate_routes[vi].insert(pos, customer.id)
+                if not _partial_valid(instance, candidate_routes):
+                    continue
+                before = route_distance(instance, VRPRoute(vehicle.id, routes[vi]))
+                after = route_distance(instance, VRPRoute(vehicle.id, candidate_routes[vi]))
+                options.append((after - before, vi, pos, candidate_routes))
+        if not options:
+            unassigned.append(customer.id)
+            continue
+        options.sort(key=lambda x: (x[0], x[1], x[2]))
+        routes = options[0][3]
+    if improve and not unassigned:
+        routes = _local_search(instance, routes)
+    route_objects = tuple(VRPRoute(v.id, ids) for v, ids in zip(instance.vehicles, routes))
+    objective = sum(route_distance(instance, r) for r in route_objects)
+    return VRPSolution(
+        route_objects,
+        objective,
+        method="nearest-feasible-insertion+local-search" if improve else "nearest-feasible-insertion",
+        is_exact=False,
+        optimality_proven=False,
+        unassigned_customer_ids=tuple(unassigned),
+        runtime_seconds=perf_counter() - started,
+        metadata={"heuristic": True},
+    )
+
+
+def _local_search(instance: VRPInstance, routes: list[list[str]], *, max_passes: int = 20) -> list[list[str]]:
+    current = [list(r) for r in routes]
+    for _ in range(max_passes):
+        best = [list(r) for r in current]
+        best_obj = sum(route_distance(instance, VRPRoute(v.id, ids)) for v, ids in zip(instance.vehicles, current))
+        improved = False
+        # Intra-route reversal; full recomputation is used so asymmetric costs are safe.
+        for vi, ids in enumerate(current):
+            for i in range(len(ids)):
+                for j in range(i + 1, len(ids)):
+                    cand = [list(r) for r in current]
+                    cand[vi] = ids[:i] + list(reversed(ids[i : j + 1])) + ids[j + 1 :]
+                    if not _partial_valid(instance, cand):
+                        continue
+                    obj = sum(route_distance(instance, VRPRoute(v.id, x)) for v, x in zip(instance.vehicles, cand))
+                    if obj < best_obj - 1e-12:
+                        best_obj, best, improved = obj, cand, True
+        # Relocate one customer across any two routes (or within a route).
+        for src in range(len(current)):
+            for idx in range(len(current[src])):
+                cid = current[src][idx]
+                for dst in range(len(current)):
+                    base_without = [list(r) for r in current]
+                    base_without[src].pop(idx)
+                    for pos in range(len(base_without[dst]) + 1):
+                        cand = [list(r) for r in base_without]
+                        cand[dst].insert(pos, cid)
+                        if not _partial_valid(instance, cand):
+                            continue
+                        obj = sum(route_distance(instance, VRPRoute(v.id, x)) for v, x in zip(instance.vehicles, cand))
+                        if obj < best_obj - 1e-12:
+                            best_obj, best, improved = obj, cand, True
+        current = best
+        if not improved:
+            break
+    return current
+
+
+def clarke_wright_savings(instance: VRPInstance) -> VRPSolution:
+    """Classic parallel Clarke-Wright savings heuristic under explicit preconditions.
+
+    S8 intentionally limits this implementation to the classical symmetric,
+    single-depot, homogeneous-capacity CVRP.  It fails closed outside those
+    assumptions rather than implying a guarantee for heterogeneous/asymmetric or
+    time-window routing.
+    """
+    from .errors import VRPValidationError
+    if instance.has_time_constraints:
+        raise VRPValidationError("Clarke-Wright S8 heuristic is qualified only for CVRP without time constraints")
+    starts={v.start_node_id for v in instance.vehicles}; ends={v.end_node_id for v in instance.vehicles}
+    if len(starts)!=1 or starts!=ends:
+        raise VRPValidationError("Clarke-Wright S8 heuristic requires one common start/end depot")
+    capacities={v.capacity for v in instance.vehicles}
+    if len(capacities)!=1:
+        raise VRPValidationError("Clarke-Wright S8 heuristic requires homogeneous vehicle capacities")
+    vals=instance.distances.values
+    n=len(vals)
+    for i in range(n):
+        for j in range(i+1,n):
+            if abs(vals[i][j]-vals[j][i])>1e-9:
+                raise VRPValidationError("Clarke-Wright S8 heuristic requires a symmetric distance matrix")
+    depot=next(iter(starts)); cap=next(iter(capacities)); cmap=instance.customer_map
+    routes: dict[int,list[str]]={i:[c.id] for i,c in enumerate(instance.customers)}
+    loads: dict[int,float]={i:c.demand for i,c in enumerate(instance.customers)}
+    owner={c.id:i for i,c in enumerate(instance.customers)}
+    savings=[]
+    for a in instance.customers:
+        for b in instance.customers:
+            if a.id>=b.id: continue
+            s=instance.distance(depot,a.node_id)+instance.distance(depot,b.node_id)-instance.distance(a.node_id,b.node_id)
+            savings.append((-s,a.id,b.id))
+    savings.sort()
+    for neg_s,a,b in savings:
+        # Once the fleet limit is met, do not accept a non-positive merge.
+        # Before that point a non-positive merge may still be necessary to
+        # reduce the number of routes to the available vehicle count.
+        if -neg_s <= 1e-12 and len(routes) <= len(instance.vehicles):
+            break
+        ra=owner[a]; rb=owner[b]
+        if ra==rb or ra not in routes or rb not in routes: continue
+        A=routes[ra]; B=routes[rb]
+        if loads[ra]+loads[rb] > cap+1e-9: continue
+        candidates=[]
+        # Classical endpoint merges, including route reversal because costs are symmetric.
+        if A[-1]==a and B[0]==b: candidates.append(A+B)
+        if A[0]==a and B[-1]==b: candidates.append(B+A)
+        if A[0]==a and B[0]==b: candidates.append(list(reversed(A))+B)
+        if A[-1]==a and B[-1]==b: candidates.append(A+list(reversed(B)))
+        if not candidates: continue
+        merged=min(candidates, key=lambda ids: (route_distance(instance, VRPRoute(instance.vehicles[0].id,ids)), tuple(ids)))
+        routes[ra]=merged; loads[ra]+=loads[rb]
+        del routes[rb]; del loads[rb]
+        for cid in merged: owner[cid]=ra
+    route_lists=sorted(routes.values(), key=lambda ids: (tuple(ids),len(ids)))
+    if len(route_lists)>len(instance.vehicles):
+        fallback = nearest_feasible_insertion(instance, improve=True)
+        return VRPSolution(
+            fallback.routes, fallback.objective, method="clarke-wright-savings:fallback-nearest",
+            is_exact=False, optimality_proven=False,
+            unassigned_customer_ids=fallback.unassigned_customer_ids,
+            runtime_seconds=fallback.runtime_seconds,
+            metadata={"qualified_scope":"symmetric-single-depot-homogeneous-cvrp","fallback":"nearest-feasible-insertion"},
+        )
+    assigned=route_lists; unassigned=()
+    route_objects=[]
+    for i,v in enumerate(instance.vehicles):
+        route_objects.append(VRPRoute(v.id, assigned[i] if i<len(assigned) else ()))
+    objective=sum(route_distance(instance,r) for r in route_objects)
+    return VRPSolution(route_objects,objective,method="clarke-wright-savings",is_exact=False,optimality_proven=False,unassigned_customer_ids=unassigned,metadata={"qualified_scope":"symmetric-single-depot-homogeneous-cvrp"})

solverpilot/applications/routing/model.py

@@ -0,0 +1,259 @@
+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
+
+
+def _meta(value: Mapping[str, Any] | None) -> Mapping[str, Any]:
+    return MappingProxyType(dict(value or {}))
+
+
+def _clean_id(value: object, label: str) -> str:
+    text = str(value).strip()
+    if not text:
+        raise VRPValidationError(f"{label} must be a non-empty string")
+    return text
+
+
+def _number(value: object, label: str, *, positive: bool = False) -> float:
+    if isinstance(value, bool):
+        raise VRPValidationError(f"{label} must be numeric, not bool")
+    try:
+        out = float(value)
+    except (TypeError, ValueError) as exc:
+        raise VRPValidationError(f"{label} must be numeric") from exc
+    if not isfinite(out):
+        raise VRPValidationError(f"{label} must be finite")
+    if positive and out <= 0.0:
+        raise VRPValidationError(f"{label} must be positive")
+    if not positive and out < 0.0:
+        raise VRPValidationError(f"{label} must be non-negative")
+    return out
+
+
+@dataclass(frozen=True, slots=True)
+class VRPTimeWindow:
+    start: float
+    end: float
+
+    def __post_init__(self) -> None:
+        start = _number(self.start, "time-window start")
+        end = _number(self.end, "time-window end")
+        if end < start:
+            raise VRPValidationError("time-window end must be >= start")
+        object.__setattr__(self, "start", start)
+        object.__setattr__(self, "end", end)
+
+
+@dataclass(frozen=True, slots=True)
+class VRPNode:
+    id: str
+    metadata: Mapping[str, Any] = field(default_factory=dict, compare=False)
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "id", _clean_id(self.id, "node id"))
+        object.__setattr__(self, "metadata", _meta(self.metadata))
+
+
+@dataclass(frozen=True, slots=True)
+class VRPCustomer:
+    id: str
+    node_id: str
+    demand: float = 0.0
+    service_duration: float = 0.0
+    time_window: VRPTimeWindow | None = None
+    metadata: Mapping[str, Any] = field(default_factory=dict, compare=False)
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "id", _clean_id(self.id, "customer id"))
+        object.__setattr__(self, "node_id", _clean_id(self.node_id, "customer node_id"))
+        object.__setattr__(self, "demand", _number(self.demand, f"customer {self.id} demand"))
+        object.__setattr__(self, "service_duration", _number(self.service_duration, f"customer {self.id} service_duration"))
+        if self.time_window is not None and not isinstance(self.time_window, VRPTimeWindow):
+            raise VRPValidationError("customer time_window must be VRPTimeWindow or None")
+        object.__setattr__(self, "metadata", _meta(self.metadata))
+
+
+@dataclass(frozen=True, slots=True)
+class VRPVehicle:
+    id: str
+    start_node_id: str
+    end_node_id: str | None = None
+    capacity: float = 1.0
+    shift_window: VRPTimeWindow | None = None
+    max_route_duration: float | None = None
+    metadata: Mapping[str, Any] = field(default_factory=dict, compare=False)
+
+    def __post_init__(self) -> None:
+        vehicle_id = _clean_id(self.id, "vehicle id")
+        start = _clean_id(self.start_node_id, f"vehicle {vehicle_id} start_node_id")
+        end = start if self.end_node_id is None else _clean_id(self.end_node_id, f"vehicle {vehicle_id} end_node_id")
+        capacity = _number(self.capacity, f"vehicle {vehicle_id} capacity", positive=True)
+        if self.shift_window is not None and not isinstance(self.shift_window, VRPTimeWindow):
+            raise VRPValidationError("vehicle shift_window must be VRPTimeWindow or None")
+        duration = None
+        if self.max_route_duration is not None:
+            duration = _number(self.max_route_duration, f"vehicle {vehicle_id} max_route_duration", positive=True)
+        object.__setattr__(self, "id", vehicle_id)
+        object.__setattr__(self, "start_node_id", start)
+        object.__setattr__(self, "end_node_id", end)
+        object.__setattr__(self, "capacity", capacity)
+        object.__setattr__(self, "max_route_duration", duration)
+        object.__setattr__(self, "metadata", _meta(self.metadata))
+
+    @property
+    def start_time(self) -> float:
+        return 0.0 if self.shift_window is None else self.shift_window.start
+
+    @property
+    def latest_return(self) -> float | None:
+        return None if self.shift_window is None else self.shift_window.end
+
+
+@dataclass(frozen=True, slots=True)
+class VRPMatrix:
+    values: tuple[tuple[float, ...], ...]
+
+    def __init__(self, values: Sequence[Sequence[float]], *, label: str = "matrix") -> None:
+        try:
+            raw = tuple(tuple(row) for row in values)
+        except TypeError as exc:
+            raise VRPValidationError(f"{label} must be a sequence of rows") from exc
+        if len(raw) < 2:
+            raise VRPValidationError(f"{label} must contain at least two nodes")
+        n = len(raw)
+        if any(len(row) != n for row in raw):
+            raise VRPValidationError(f"{label} must be square")
+        rows: list[tuple[float, ...]] = []
+        for i, row in enumerate(raw):
+            out: list[float] = []
+            for j, value in enumerate(row):
+                if isinstance(value, bool):
+                    raise VRPValidationError(f"{label}[{i},{j}] must be numeric, not bool")
+                try:
+                    v = float(value)
+                except (TypeError, ValueError) as exc:
+                    raise VRPValidationError(f"{label}[{i},{j}] must be numeric") from exc
+                if not isfinite(v) or v < 0.0:
+                    raise VRPValidationError(f"{label}[{i},{j}] must be finite and non-negative")
+                out.append(v)
+            rows.append(tuple(out))
+        object.__setattr__(self, "values", tuple(rows))
+
+    @property
+    def n_nodes(self) -> int:
+        return len(self.values)
+
+    def edge(self, i: int, j: int) -> float:
+        if isinstance(i, bool) or isinstance(j, bool) or not isinstance(i, int) or not isinstance(j, int):
+            raise VRPValidationError("matrix indices must be integers")
+        if not 0 <= i < self.n_nodes or not 0 <= j < self.n_nodes:
+            raise VRPValidationError("matrix index out of range")
+        return self.values[i][j]
+
+
+@dataclass(frozen=True, slots=True)
+class VRPInstance:
+    nodes: tuple[VRPNode, ...]
+    customers: tuple[VRPCustomer, ...]
+    vehicles: tuple[VRPVehicle, ...]
+    distances: VRPMatrix
+    travel_times: VRPMatrix | None = None
+    name: str = "vrp"
+    metadata: Mapping[str, Any] = field(default_factory=dict, compare=False)
+
+    def __init__(
+        self,
+        nodes: Sequence[VRPNode],
+        customers: Sequence[VRPCustomer],
+        vehicles: Sequence[VRPVehicle],
+        distances: VRPMatrix | Sequence[Sequence[float]],
+        *,
+        travel_times: VRPMatrix | Sequence[Sequence[float]] | None = None,
+        name: str = "vrp",
+        metadata: Mapping[str, Any] | None = None,
+    ) -> None:
+        node_tuple = tuple(nodes)
+        customer_tuple = tuple(customers)
+        vehicle_tuple = tuple(vehicles)
+        if len(node_tuple) < 2:
+            raise VRPValidationError("VRP requires at least two nodes")
+        if not customer_tuple:
+            raise VRPValidationError("VRP requires at least one customer")
+        if not vehicle_tuple:
+            raise VRPValidationError("VRP requires at least one vehicle")
+        node_ids = tuple(n.id for n in node_tuple)
+        customer_ids = tuple(c.id for c in customer_tuple)
+        vehicle_ids = tuple(v.id for v in vehicle_tuple)
+        if len(set(node_ids)) != len(node_ids):
+            raise VRPValidationError("VRP node ids must be unique")
+        if len(set(customer_ids)) != len(customer_ids):
+            raise VRPValidationError("VRP customer ids must be unique")
+        if len(set(vehicle_ids)) != len(vehicle_ids):
+            raise VRPValidationError("VRP vehicle ids must be unique")
+        node_set = set(node_ids)
+        unknown_customer_nodes = sorted({c.node_id for c in customer_tuple} - node_set)
+        unknown_vehicle_nodes = sorted({x for v in vehicle_tuple for x in (v.start_node_id, v.end_node_id)} - node_set)
+        if unknown_customer_nodes:
+            raise VRPValidationError(f"customers reference unknown nodes: {unknown_customer_nodes}")
+        if unknown_vehicle_nodes:
+            raise VRPValidationError(f"vehicles reference unknown nodes: {unknown_vehicle_nodes}")
+        d = distances if isinstance(distances, VRPMatrix) else VRPMatrix(distances, label="distance matrix")
+        if d.n_nodes != len(node_tuple):
+            raise VRPValidationError("distance matrix size must match node count")
+        tt = None
+        if travel_times is not None:
+            tt = travel_times if isinstance(travel_times, VRPMatrix) else VRPMatrix(travel_times, label="travel-time matrix")
+            if tt.n_nodes != len(node_tuple):
+                raise VRPValidationError("travel-time matrix size must match node count")
+        requires_time = any(c.time_window is not None for c in customer_tuple) or any(
+            v.shift_window is not None or v.max_route_duration is not None for v in vehicle_tuple
+        )
+        if requires_time and tt is None:
+            raise VRPValidationError("time-constrained VRP requires an explicit travel-time matrix; distance is never used as implicit time")
+        clean_name = _clean_id(name, "VRP name")
+        object.__setattr__(self, "nodes", node_tuple)
+        object.__setattr__(self, "customers", customer_tuple)
+        object.__setattr__(self, "vehicles", vehicle_tuple)
+        object.__setattr__(self, "distances", d)
+        object.__setattr__(self, "travel_times", tt)
+        object.__setattr__(self, "name", clean_name)
+        object.__setattr__(self, "metadata", _meta(metadata))
+
+    @property
+    def node_index(self) -> Mapping[str, int]:
+        return MappingProxyType({node.id: i for i, node in enumerate(self.nodes)})
+
+    @property
+    def customer_map(self) -> Mapping[str, VRPCustomer]:
+        return MappingProxyType({c.id: c for c in self.customers})
+
+    @property
+    def vehicle_map(self) -> Mapping[str, VRPVehicle]:
+        return MappingProxyType({v.id: v for v in self.vehicles})
+
+    @property
+    def has_time_constraints(self) -> bool:
+        return any(c.time_window is not None for c in self.customers) or any(
+            v.shift_window is not None or v.max_route_duration is not None for v in self.vehicles
+        )
+
+    def distance(self, from_node_id: str, to_node_id: str) -> float:
+        idx = self.node_index
+        try:
+            return self.distances.values[idx[from_node_id]][idx[to_node_id]]
+        except KeyError as exc:
+            raise VRPValidationError(f"unknown node in distance lookup: {exc.args[0]}") from exc
+
+    def travel_time(self, from_node_id: str, to_node_id: str) -> float:
+        if self.travel_times is None:
+            raise VRPValidationError("travel-time matrix is unavailable")
+        idx = self.node_index
+        try:
+            return self.travel_times.values[idx[from_node_id]][idx[to_node_id]]
+        except KeyError as exc:
+            raise VRPValidationError(f"unknown node in travel-time lookup: {exc.args[0]}") from exc

solverpilot/applications/routing/reference.py

@@ -0,0 +1,81 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from itertools import permutations
+from math import comb, factorial
+from time import perf_counter
+
+from .errors import VRPReferenceLimitError
+from .model import VRPInstance
+from .solution import VRPRoute, VRPSolution, _INDEPENDENT_PROOF_TOKEN
+from .validation import route_distance, validate_vrp_solution
+
+
+@dataclass(frozen=True, slots=True)
+class VRPReferenceResult:
+    solution: VRPSolution | None
+    evaluations: int
+    search_space_upper_bound: int
+
+
+def _compositions(total: int, parts: int):
+    if parts == 1:
+        yield (total,)
+        return
+    for first in range(total + 1):
+        for rest in _compositions(total - first, parts - 1):
+            yield (first,) + rest
+
+
+def solve_vrp_reference(
+    instance: VRPInstance,
+    *,
+    max_customers: int = 8,
+    max_evaluations: int = 2_000_000,
+) -> VRPReferenceResult:
+    n = len(instance.customers)
+    m = len(instance.vehicles)
+    if isinstance(max_customers, bool) or not isinstance(max_customers, int) or max_customers < 1:
+        raise ValueError("max_customers must be a positive integer")
+    if isinstance(max_evaluations, bool) or not isinstance(max_evaluations, int) or max_evaluations < 1:
+        raise ValueError("max_evaluations must be a positive integer")
+    if n > max_customers:
+        raise VRPReferenceLimitError(f"reference VRP solver is limited to {max_customers} customers")
+    search_space = factorial(n) * comb(n + m - 1, m - 1)
+    if search_space > max_evaluations:
+        raise VRPReferenceLimitError(f"reference VRP search-space upper bound {search_space} exceeds max_evaluations={max_evaluations}")
+    customer_ids = tuple(c.id for c in instance.customers)
+    best_routes: tuple[VRPRoute, ...] | None = None
+    best_objective = float("inf")
+    evaluations = 0
+    started = perf_counter()
+    for order in permutations(customer_ids):
+        for sizes in _compositions(n, m):
+            evaluations += 1
+            routes: list[VRPRoute] = []
+            pos = 0
+            for vehicle, size in zip(instance.vehicles, sizes):
+                route_ids = order[pos : pos + size]
+                pos += size
+                routes.append(VRPRoute(vehicle.id, route_ids))
+            objective = sum(route_distance(instance, route) for route in routes)
+            if objective >= best_objective - 1e-12:
+                continue
+            candidate = VRPSolution(routes, objective, method="reference-exhaustive", is_exact=True, optimality_proven=True, _proof_token=_INDEPENDENT_PROOF_TOKEN)
+            report = validate_vrp_solution(instance, candidate)
+            if report.valid:
+                best_objective = objective
+                best_routes = tuple(routes)
+    if best_routes is None:
+        return VRPReferenceResult(None, evaluations, search_space)
+    solution = VRPSolution(
+        best_routes,
+        best_objective,
+        method="reference-exhaustive",
+        is_exact=True,
+        optimality_proven=True,
+        runtime_seconds=perf_counter() - started,
+        _proof_token=_INDEPENDENT_PROOF_TOKEN,
+        metadata={"evaluations": evaluations, "search_space_upper_bound": search_space},
+    )
+    return VRPReferenceResult(solution, evaluations, search_space)