@fleetbase/fleetops-engine 0.6.47 → 0.6.49

package/server/src/Orchestration/Engines/CapacityAllocationEngine.php

@@ -0,0 +1,220 @@
+<?php
+
+namespace Fleetbase\FleetOps\Orchestration\Engines;
+
+use Fleetbase\FleetOps\Orchestration\Contracts\OrchestrationEngineInterface;
+use Fleetbase\FleetOps\Orchestration\Support\OrchestrationPayloadBuilder;
+use Illuminate\Support\Collection;
+
+/**
+ * CapacityAllocationEngine.
+ *
+ * Deterministic built-in engine for clients who need feasibility allocation
+ * by capacity, skills, and task limits without route geometry or vehicle GPS.
+ */
+class CapacityAllocationEngine implements OrchestrationEngineInterface
+{
+    public function getName(): string
+    {
+        return 'Capacity (built-in)';
+    }
+
+    public function getIdentifier(): string
+    {
+        return 'capacity';
+    }
+
+    public function allocate(Collection $orders, Collection $vehicles, array $options = []): array
+    {
+        $respectCapacity = (bool) ($options['respect_capacity'] ?? true);
+        $respectSkills   = (bool) ($options['respect_skills'] ?? true);
+        $balanceWorkload = (bool) ($options['balance_workload'] ?? false);
+
+        $tasks       = OrchestrationPayloadBuilder::buildCapacityTasks($orders);
+        $vehiclePool = $this->buildVehiclePool(OrchestrationPayloadBuilder::buildCapacityVehicles($vehicles));
+
+        $assignments = [];
+        $unassigned  = [];
+        $reasons     = [];
+
+        foreach ($this->sortTasks($tasks) as $task) {
+            if (!empty($task['invalid'])) {
+                $this->markUnassigned($task['id'], $task['reason'] ?? 'invalid_task', $unassigned, $reasons);
+                continue;
+            }
+
+            $bestIndex = $this->findVehicleIndex($vehiclePool, $task, $respectCapacity, $respectSkills, $balanceWorkload);
+            if ($bestIndex === null) {
+                $this->markUnassigned($task['id'], $this->resolveFailureReason($vehiclePool, $task, $respectCapacity, $respectSkills), $unassigned, $reasons);
+                continue;
+            }
+
+            $sequence = ++$vehiclePool[$bestIndex]['assigned'];
+            $this->consumeCapacity($vehiclePool[$bestIndex]['remaining'], $task['amount'] ?? [0, 0, 0, 0]);
+
+            $assignments[] = [
+                'order_id'   => $task['id'],
+                'vehicle_id' => $vehiclePool[$bestIndex]['id'],
+                'driver_id'  => $vehiclePool[$bestIndex]['driver_id'],
+                'sequence'   => $sequence,
+                'arrival'    => null,
+                'duration'   => null,
+                'distance'   => null,
+            ];
+        }
+
+        return [
+            'assignments' => $assignments,
+            'unassigned'  => array_values(array_unique($unassigned)),
+            'summary'     => [
+                'engine'               => 'capacity',
+                'allocation_strategy'  => 'capacity_only',
+                'assigned'             => count($assignments),
+                'unassigned'           => count(array_unique($unassigned)),
+                'unassigned_reasons'   => $reasons,
+                'respect_capacity'     => $respectCapacity,
+                'respect_skills'       => $respectSkills,
+                'balance_workload'     => $balanceWorkload,
+            ],
+        ];
+    }
+
+    protected function buildVehiclePool(array $vehicles): array
+    {
+        return array_map(fn (array $vehicle) => [
+            'id'        => $vehicle['id'],
+            'driver_id' => $vehicle['driver_id'] ?? null,
+            'capacity'  => $this->normalizeVector($vehicle['capacity'] ?? [0, 0, 0, 0]),
+            'remaining' => $this->normalizeVector($vehicle['capacity'] ?? [0, 0, 0, 0]),
+            'skills'    => $vehicle['skills'] ?? [],
+            'max_tasks' => $vehicle['max_tasks'] ?? null,
+            'assigned'  => 0,
+        ], $vehicles);
+    }
+
+    protected function sortTasks(array $tasks): array
+    {
+        usort($tasks, fn (array $a, array $b) => ($b['priority'] ?? 0) <=> ($a['priority'] ?? 0));
+
+        return $tasks;
+    }
+
+    protected function findVehicleIndex(array $vehiclePool, array $task, bool $respectCapacity, bool $respectSkills, bool $balanceWorkload): ?int
+    {
+        $eligible = [];
+
+        foreach ($vehiclePool as $index => $vehicle) {
+            if (!$this->isVehicleFeasible($vehicle, $task, $respectCapacity, $respectSkills)) {
+                continue;
+            }
+
+            $eligible[] = $index;
+        }
+
+        if (empty($eligible)) {
+            return null;
+        }
+
+        if (!$balanceWorkload) {
+            return $eligible[0];
+        }
+
+        usort($eligible, function (int $a, int $b) use ($vehiclePool) {
+            $assignedCompare = $vehiclePool[$a]['assigned'] <=> $vehiclePool[$b]['assigned'];
+            if ($assignedCompare !== 0) {
+                return $assignedCompare;
+            }
+
+            return array_sum($vehiclePool[$b]['remaining']) <=> array_sum($vehiclePool[$a]['remaining']);
+        });
+
+        return $eligible[0];
+    }
+
+    protected function isVehicleFeasible(array $vehicle, array $task, bool $respectCapacity, bool $respectSkills): bool
+    {
+        if ($vehicle['max_tasks'] !== null && $vehicle['assigned'] >= $vehicle['max_tasks']) {
+            return false;
+        }
+
+        if ($respectSkills && !$this->hasRequiredSkills($vehicle['skills'], $task['skills'] ?? [])) {
+            return false;
+        }
+
+        if ($respectCapacity && !$this->hasCapacity($vehicle['remaining'], $task['amount'] ?? [0, 0, 0, 0])) {
+            return false;
+        }
+
+        return true;
+    }
+
+    protected function hasRequiredSkills(array $vehicleSkills, array $requiredSkills): bool
+    {
+        if (empty($requiredSkills)) {
+            return true;
+        }
+
+        return empty(array_diff($requiredSkills, $vehicleSkills));
+    }
+
+    protected function hasCapacity(array $remaining, array $demand): bool
+    {
+        foreach ($this->normalizeVector($demand) as $index => $amount) {
+            if ($amount > ($remaining[$index] ?? 0)) {
+                return false;
+            }
+        }
+
+        return true;
+    }
+
+    protected function consumeCapacity(array &$remaining, array $demand): void
+    {
+        foreach ($this->normalizeVector($demand) as $index => $amount) {
+            $remaining[$index] = max(0, ($remaining[$index] ?? 0) - $amount);
+        }
+    }
+
+    protected function resolveFailureReason(array $vehiclePool, array $task, bool $respectCapacity, bool $respectSkills): string
+    {
+        if (empty($vehiclePool)) {
+            return 'no_available_vehicle';
+        }
+
+        $capacityEligible = false;
+        $skillsEligible   = false;
+        $taskEligible     = false;
+
+        foreach ($vehiclePool as $vehicle) {
+            $capacityEligible = $capacityEligible || !$respectCapacity || $this->hasCapacity($vehicle['remaining'], $task['amount'] ?? [0, 0, 0, 0]);
+            $skillsEligible   = $skillsEligible || !$respectSkills || $this->hasRequiredSkills($vehicle['skills'], $task['skills'] ?? []);
+            $taskEligible     = $taskEligible || $vehicle['max_tasks'] === null || $vehicle['assigned'] < $vehicle['max_tasks'];
+        }
+
+        if (!$capacityEligible) {
+            return 'capacity_exceeded';
+        }
+        if (!$skillsEligible) {
+            return 'missing_required_skills';
+        }
+        if (!$taskEligible) {
+            return 'max_tasks_exceeded';
+        }
+
+        return 'no_available_vehicle';
+    }
+
+    protected function normalizeVector(array $vector): array
+    {
+        return array_pad(array_map(fn ($value) => max(0, (int) round((float) $value)), array_values($vector)), 4, 0);
+    }
+
+    protected function markUnassigned(string $orderId, string $reason, array &$unassigned, array &$reasons): void
+    {
+        $unassigned[] = $orderId;
+        $reasons[]    = [
+            'order_id' => $orderId,
+            'reason'   => $reason,
+        ];
+    }
+}

package/server/src/Orchestration/Engines/VroomOrchestrationEngine.php

@@ -50,7 +50,7 @@ class VroomOrchestrationEngine implements OrchestrationEngineInterface
     /**
      * Run the VROOM VRP solver.
      *
-     * Constructs a VROOM-format payload from the normalized jobs/vehicles
+     * Constructs a VROOM-format payload from the normalized route tasks/vehicles
      * produced by OrchestrationPayloadBuilder, calls the VROOM HTTP API, and
      * maps the response back to the standard OrchestrationEngineInterface result
      * shape.
@@ -59,31 +59,57 @@ class VroomOrchestrationEngine implements OrchestrationEngineInterface
      */
     public function allocate(Collection $orders, Collection $vehicles, array $options = []): array
     {
-        $jobs          = OrchestrationPayloadBuilder::buildJobs($orders);
+        if (($options['allocation_strategy'] ?? null) === 'capacity_only') {
+            return $this->allocateCapacityOnly($orders, $vehicles, $options);
+        }
+
+        $tasks         = OrchestrationPayloadBuilder::buildRouteTasks($orders);
         $vroomVehicles = OrchestrationPayloadBuilder::buildVehicles($vehicles);
 
-        if (empty($jobs)) {
-            return ['assignments' => [], 'unassigned' => [], 'summary' => []];
+        [$routeTasks, $invalidTasks] = $this->partitionRouteTasks($tasks);
+
+        if (empty($routeTasks)) {
+            return $this->mergeInvalidTasks([
+                'assignments' => [],
+                'unassigned'  => [],
+                'summary'     => [],
+            ], $invalidTasks);
         }
 
+        $jobIdReverse = [];
+        $profile      = $options['profile'] ?? env('VROOM_PROFILE', 'driving');
+
         // Map normalized vehicle entries to VROOM vehicle objects.
         // The 'driver_id' key is not part of the VROOM spec — we carry it in
         // a description field and use it when mapping results back.
         $vroomPayload = [
-            'jobs'     => $jobs,
-            'vehicles' => array_map(function (array $v) {
+            'jobs'      => [],
+            'shipments' => [],
+            'vehicles' => array_map(function (array $v) use ($profile) {
                 $vehicle = [
                     'id'          => crc32($v['id']), // VROOM requires integer IDs
                     'description' => json_encode(['vehicle_id' => $v['id'], 'driver_id' => $v['driver_id']]),
                     'start'       => $v['start'],
                     'capacity'    => $v['capacity'],
                 ];
+                if ($profile) {
+                    $vehicle['profile'] = $profile;
+                }
+                if (isset($v['end'])) {
+                    $vehicle['end'] = $v['end'];
+                }
                 if (isset($v['time_window'])) {
                     $vehicle['time_window'] = $v['time_window'];
                 }
                 if (isset($v['skills'])) {
                     $vehicle['skills'] = $v['skills'];
                 }
+                if (isset($v['max_tasks'])) {
+                    $vehicle['max_tasks'] = $v['max_tasks'];
+                }
+                if (isset($v['max_travel_time'])) {
+                    $vehicle['max_travel_time'] = $v['max_travel_time'];
+                }
 
                 return $vehicle;
             }, $vroomVehicles),
@@ -92,48 +118,209 @@ class VroomOrchestrationEngine implements OrchestrationEngineInterface
             ],
         ];
 
-        // Map job IDs to integer IDs for VROOM, keeping a reverse lookup
-        $jobIdMap     = [];
-        $jobIdReverse = [];
-        foreach ($vroomPayload['jobs'] as &$job) {
-            $intId                = crc32($job['id']);
-            $jobIdReverse[$intId] = $job['id'];
-            $job['id']            = $intId;
-            $jobIdMap[$job['id']] = true;
+        foreach ($routeTasks as $task) {
+            if (count($task['stops']) > 1) {
+                $shipment = $this->mapTaskToShipment($task, $jobIdReverse);
+                if ($shipment) {
+                    $vroomPayload['shipments'][] = $shipment;
+                }
+
+                continue;
+            }
+
+            $job = $this->mapTaskToVroomJob($task, $jobIdReverse);
+            if ($job) {
+                $vroomPayload['jobs'][] = $job;
+            }
         }
-        unset($job);
 
-        // ── Resolve connection config ─────────────────────────────────────────
-        $baseUri = $this->resolveVroomBaseUri();
-        $endpointMode = $this->resolveVroomEndpointMode();
-        $timeout = (int) env('VROOM_TIMEOUT', 30);
+        if (empty($vroomPayload['jobs'])) {
+            unset($vroomPayload['jobs']);
+        }
+        if (empty($vroomPayload['shipments'])) {
+            unset($vroomPayload['shipments']);
+        }
 
-        $apiKey = $this->resolveVroomApiKey();
+        $result = $this->callVroom($vroomPayload);
 
-        // Build the solve URL — append api_key as query param when present.
-        $solveUrl = rtrim($baseUri, '/');
-        if ($endpointMode !== 'binary') {
-            $solveUrl .= '/solve';
+        return $this->mergeInvalidTasks(
+            $this->mapVroomResponse($result, $jobIdReverse),
+            $invalidTasks
+        );
+    }
+
+    protected function allocateCapacityOnly(Collection $orders, Collection $vehicles, array $options = []): array
+    {
+        $tasks         = OrchestrationPayloadBuilder::buildCapacityTasks($orders);
+        $vroomVehicles = OrchestrationPayloadBuilder::buildCapacityVehicles($vehicles);
+
+        [$capacityTasks, $invalidTasks] = $this->partitionRouteTasks($tasks);
+
+        if (empty($capacityTasks)) {
+            return $this->mergeInvalidTasks([
+                'assignments' => [],
+                'unassigned'  => [],
+                'summary'     => [
+                    'engine'              => 'vroom',
+                    'allocation_strategy' => 'capacity_only',
+                ],
+            ], $invalidTasks);
         }
-        if ($apiKey) {
-            $solveUrl .= '?api_key=' . urlencode($apiKey);
+
+        $jobIdReverse = [];
+        $vroomPayload = $this->buildCapacityOnlyPayload($capacityTasks, $vroomVehicles, $options, $jobIdReverse);
+
+        if (empty($vroomPayload['vehicles'])) {
+            $vehiclePacking   = $this->resolveVehiclePacking($options);
+            $vehicleFixedCost = $this->resolveVehicleFixedCost($options);
+
+            return $this->mergeInvalidTasks([
+                'assignments' => [],
+                'unassigned'  => array_column($capacityTasks, 'id'),
+                'summary'     => [
+                    'engine'              => 'vroom',
+                    'allocation_strategy' => 'capacity_only',
+                    'vehicle_packing'     => $vehiclePacking,
+                    'vehicle_fixed_cost'  => $vehiclePacking === 'minimize_vehicles' ? $vehicleFixedCost : null,
+                    'assigned'            => 0,
+                    'unassigned'          => count($capacityTasks),
+                    'unassigned_reasons'  => array_map(fn (array $task) => [
+                        'order_id' => $task['id'],
+                        'reason'   => 'no_available_vehicle',
+                    ], $capacityTasks),
+                ],
+            ], $invalidTasks);
         }
 
-        // ── Call VROOM ────────────────────────────────────────────────────────
-        try {
-            $response = Http::timeout($timeout)->post($solveUrl, $vroomPayload);
-        } catch (\Exception $e) {
-            Log::error('[VroomOrchestrationEngine] HTTP request failed: ' . $e->getMessage());
-            throw new \RuntimeException('VROOM allocation engine is unavailable: ' . $e->getMessage() . ' — ensure VROOM_HOST is reachable or switch to the built-in greedy engine.', 0, $e);
+        $result = $this->mapVroomResponse($this->callVroom($vroomPayload), $jobIdReverse);
+
+        $result['summary'] = array_merge($result['summary'] ?? [], [
+            'engine'              => 'vroom',
+            'allocation_strategy' => 'capacity_only',
+            'vehicle_packing'     => $this->resolveVehiclePacking($options),
+            'vehicle_fixed_cost'  => $this->resolveVehiclePacking($options) === 'minimize_vehicles' ? $this->resolveVehicleFixedCost($options) : null,
+        ]);
+
+        return $this->mergeInvalidTasks($result, $invalidTasks);
+    }
+
+    protected function buildCapacityOnlyPayload(array $capacityTasks, array $vroomVehicles, array $options, array &$jobIdReverse): array
+    {
+        $matrixSize      = count($capacityTasks) + 1;
+        $profile         = $options['profile'] ?? 'capacity_only';
+        $respectCapacity = (bool) ($options['respect_capacity'] ?? true);
+        $respectSkills   = (bool) ($options['respect_skills'] ?? true);
+        $vehiclePacking  = $this->resolveVehiclePacking($options);
+        $fixedCost       = $this->resolveVehicleFixedCost($options);
+
+        $vroomPayload = [
+            'jobs'     => [],
+            'vehicles' => array_map(function (array $v) use ($profile, $respectCapacity, $respectSkills, $vehiclePacking, $fixedCost) {
+                $vehicle = [
+                    'id'          => crc32($v['id']),
+                    'description' => json_encode(['vehicle_id' => $v['id'], 'driver_id' => $v['driver_id'] ?? null]),
+                    'profile'     => $profile,
+                    'start_index' => 0,
+                ];
+
+                if ($vehiclePacking === 'minimize_vehicles') {
+                    $vehicle['costs'] = ['fixed' => $fixedCost];
+                }
+
+                if ($respectCapacity) {
+                    $vehicle['capacity'] = $v['capacity'];
+                }
+                if ($respectSkills && isset($v['skills'])) {
+                    $vehicle['skills'] = $v['skills'];
+                }
+
+                foreach (['time_window', 'max_tasks', 'max_travel_time'] as $key) {
+                    if (isset($v[$key])) {
+                        $vehicle[$key] = $v[$key];
+                    }
+                }
+
+                return $vehicle;
+            }, $vroomVehicles),
+            'matrices' => [
+                $profile => [
+                    'durations' => $this->buildUniformMatrix($matrixSize),
+                    'distances' => $this->buildUniformMatrix($matrixSize),
+                ],
+            ],
+            'options' => [
+                'g' => false,
+            ],
+        ];
+
+        foreach ($capacityTasks as $index => $task) {
+            $orderId              = $task['id'];
+            $intId                = crc32($orderId);
+            $jobIdReverse[$intId] = $orderId;
+
+            $job = [
+                'id'             => $intId,
+                'location_index' => $index + 1,
+                'description'    => $task['description'] ?? $orderId,
+            ];
+
+            if ($respectCapacity) {
+                $job['delivery'] = $task['amount'] ?? [0, 0, 0, 0];
+            }
+            if ($respectSkills && isset($task['skills'])) {
+                $job['skills'] = $task['skills'];
+            }
+
+            $this->copyTaskFields($task, $job, ['priority']);
+            $vroomPayload['jobs'][] = $job;
         }
 
-        if (!$response->successful()) {
-            throw new \RuntimeException('VROOM returned an error: HTTP ' . $response->status() . ' — ' . $response->body());
+        return $vroomPayload;
+    }
+
+    protected function resolveVehiclePacking(array $options): string
+    {
+        $packing = strtolower((string) ($options['vehicle_packing'] ?? 'minimize_vehicles'));
+
+        return in_array($packing, ['minimize_vehicles', 'balanced', 'none'], true)
+            ? $packing
+            : 'minimize_vehicles';
+    }
+
+    protected function resolveVehicleFixedCost(array $options): int
+    {
+        return max(0, (int) ($options['vehicle_fixed_cost'] ?? 100000));
+    }
+
+    protected function buildUniformMatrix(int $size): array
+    {
+        $matrix = [];
+
+        for ($row = 0; $row < $size; $row++) {
+            $matrix[$row] = [];
+            for ($column = 0; $column < $size; $column++) {
+                $matrix[$row][$column] = $row === $column ? 0 : 1;
+            }
         }
 
-        $result = $response->json();
+        return $matrix;
+    }
+
+    protected function partitionRouteTasks(array $tasks): array
+    {
+        $routeTasks   = [];
+        $invalidTasks = [];
+
+        foreach ($tasks as $task) {
+            if (!empty($task['invalid'])) {
+                $invalidTasks[] = $task;
+                continue;
+            }
+
+            $routeTasks[] = $task;
+        }
 
-        return $this->mapVroomResponse($result, $jobIdReverse);
+        return [$routeTasks, $invalidTasks];
     }
 
     /**
@@ -152,7 +339,7 @@ class VroomOrchestrationEngine implements OrchestrationEngineInterface
             $sequence    = 0;
 
             foreach ($route['steps'] ?? [] as $step) {
-                if ($step['type'] !== 'job') {
+                if (!in_array($step['type'], ['job', 'delivery'], true)) {
                     continue;
                 }
                 $orderId = $jobIdReverse[$step['id']] ?? null;
@@ -178,11 +365,143 @@ class VroomOrchestrationEngine implements OrchestrationEngineInterface
 
         return [
             'assignments' => $assignments,
-            'unassigned'  => array_values($unassigned),
+            'unassigned'  => array_values(array_unique($unassigned)),
             'summary'     => $vroomResult['summary'] ?? [],
         ];
     }
 
+    protected function mapTaskToVroomJob(array $task, array &$jobIdReverse): ?array
+    {
+        $stop = $task['stops'][0] ?? null;
+        if (!$stop || empty($stop['location'])) {
+            return null;
+        }
+
+        $orderId              = $task['id'];
+        $intId                = crc32($orderId);
+        $jobIdReverse[$intId] = $orderId;
+
+        $vroomJob = [
+            'id'          => $intId,
+            'location'    => $stop['location'],
+            'description' => $task['description'] ?? $orderId,
+        ];
+
+        $this->copyTaskFields($task, $vroomJob, ['service', 'amount', 'time_windows', 'skills', 'priority']);
+
+        return $vroomJob;
+    }
+
+    protected function mapTaskToShipment(array $task, array &$jobIdReverse): ?array
+    {
+        $stops = $task['stops'] ?? [];
+        $first = $stops[0] ?? null;
+        $last  = $stops[count($stops) - 1] ?? null;
+
+        if (!$first || !$last || empty($first['location']) || empty($last['location'])) {
+            return null;
+        }
+
+        $orderId    = $task['id'];
+        $pickupId   = crc32($orderId . ':pickup');
+        $deliveryId = crc32($orderId . ':delivery');
+
+        // We only create one FleetOps assignment per order, so route pickup
+        // steps are ignored while delivery and unassigned entries still map
+        // back to the order public_id.
+        $jobIdReverse[$pickupId]   = $orderId;
+        $jobIdReverse[$deliveryId] = $orderId;
+
+        $shipment = [
+            'pickup' => [
+                'id'          => $pickupId,
+                'location'    => $first['location'],
+                'description' => ($task['description'] ?? $orderId) . ' pickup',
+            ],
+            'delivery' => [
+                'id'          => $deliveryId,
+                'location'    => $last['location'],
+                'description' => ($task['description'] ?? $orderId) . ' delivery',
+            ],
+        ];
+
+        if (array_key_exists('service', $task)) {
+            $shipment['delivery']['service'] = $task['service'];
+        }
+        if (array_key_exists('time_windows', $task)) {
+            $shipment['delivery']['time_windows'] = $task['time_windows'];
+        }
+
+        $this->copyTaskFields($task, $shipment, ['amount', 'skills', 'priority']);
+
+        return $shipment;
+    }
+
+    protected function copyTaskFields(array $task, array &$target, array $keys): void
+    {
+        foreach ($keys as $key) {
+            if (array_key_exists($key, $task)) {
+                $target[$key] = $task[$key];
+            }
+        }
+    }
+
+    protected function mergeInvalidTasks(array $result, array $invalidTasks): array
+    {
+        if (empty($invalidTasks)) {
+            return $result;
+        }
+
+        $invalid = array_map(fn (array $task) => [
+            'order_id' => $task['id'],
+            'reason'   => $task['reason'] ?? 'Order has invalid route coordinates.',
+        ], $invalidTasks);
+
+        $result['unassigned'] = array_values(array_unique(array_merge(
+            $result['unassigned'] ?? [],
+            array_column($invalid, 'order_id')
+        )));
+
+        $summary             = $result['summary'] ?? [];
+        $summary['invalid']  = array_values(array_merge($summary['invalid'] ?? [], $invalid));
+        $result['summary']   = $summary;
+
+        return $result;
+    }
+
+    protected function callVroom(array $vroomPayload): array
+    {
+        // ── Resolve connection config ─────────────────────────────────────────
+        $baseUri      = $this->resolveVroomBaseUri();
+        $endpointMode = $this->resolveVroomEndpointMode();
+        $timeout      = (int) env('VROOM_TIMEOUT', 30);
+
+        $apiKey = $this->resolveVroomApiKey();
+
+        // Build the solve URL — append api_key as query param when present.
+        $solveUrl = rtrim($baseUri, '/');
+        if ($endpointMode !== 'binary') {
+            $solveUrl .= '/solve';
+        }
+        if ($apiKey) {
+            $solveUrl .= '?api_key=' . urlencode($apiKey);
+        }
+
+        // ── Call VROOM ────────────────────────────────────────────────────────
+        try {
+            $response = Http::timeout($timeout)->post($solveUrl, $vroomPayload);
+        } catch (\Exception $e) {
+            Log::error('[VroomOrchestrationEngine] HTTP request failed: ' . $e->getMessage());
+            throw new \RuntimeException('VROOM allocation engine is unavailable: ' . $e->getMessage() . ' — ensure VROOM_HOST is reachable or switch to the built-in greedy engine.', 0, $e);
+        }
+
+        if (!$response->successful()) {
+            throw new \RuntimeException('VROOM returned an error: HTTP ' . $response->status() . ' — ' . $response->body());
+        }
+
+        return $response->json();
+    }
+
     protected function resolveVroomBaseUri(): string
     {
         return $this->resolveVroomSetting('api_host', config('vroom.base_uri', env('VROOM_HOST', 'https://api.verso-optim.com/vrp/v1')));