@fleetbase/fleetops-engine 0.6.61 → 0.6.63

package/server/tests/Feature/Http/Api/FleetPublicContractTest.php

@@ -0,0 +1,439 @@
+<?php
+
+use Fleetbase\FleetOps\Http\Controllers\Api\v1\FleetController;
+use Fleetbase\FleetOps\Http\Resources\v1\Fleet as FleetResource;
+use Fleetbase\FleetOps\Models\Fleet;
+use Illuminate\Http\Request;
+
+// The query pipeline reaches Fleetbase\Support helpers that call the framework's
+// auth() and session() helpers; neither exists in the bare-container harness.
+if (!function_exists('Fleetbase\Support\auth')) {
+    eval('namespace Fleetbase\Support; function auth() { return new class { public function user() { return null; } public function id() { return null; } }; }');
+}
+
+if (!function_exists('Fleetbase\Support\session')) {
+    eval('namespace Fleetbase\Support; function session($key = null, $default = null) { if ($key === null) { return new class { public function has($k) { return \session($k) !== null; } public function get($k, $d = null) { return \session($k, $d); } }; } return \session($key, $default); }');
+}
+
+if (!Request::hasMacro('getController')) {
+    Request::macro('getController', fn () => new FleetController());
+}
+
+if (!Request::hasMacro('or')) {
+    Request::macro('or', function (array $params = [], $default = null) {
+        foreach ($params as $param) {
+            if ($this->has($param)) {
+                return $this->input($param);
+            }
+        }
+
+        return $default;
+    });
+}
+
+class FleetOpsFleetResourceRouteFixture
+{
+    public array $action = [];
+
+    public function __construct(private string $uri)
+    {
+    }
+
+    public function uri(): string
+    {
+        return $this->uri;
+    }
+
+    public function getAction($key = null): string
+    {
+        return FleetController::class . '@query';
+    }
+
+    public function getActionMethod(): string
+    {
+        return 'query';
+    }
+
+    public function getName(): string
+    {
+        return 'api.v1.fleets.query';
+    }
+
+    public function parameters(): array
+    {
+        return [];
+    }
+}
+
+function fleetopsFleetResourceRequest(bool $internal, array $query = []): Request
+{
+    $uri     = $internal ? 'api/int/v1/fleet-ops/fleets/fleet_123' : 'api/v1/fleets/fleet_123';
+    $request = Request::create('/' . $uri, 'GET', $query);
+    $request->setRouteResolver(fn () => new FleetOpsFleetResourceRouteFixture($uri));
+    app()->instance('request', $request);
+
+    return $request;
+}
+
+/**
+ * Boot an in-memory database holding one fleet with every relationship set.
+ *
+ * The resource resolves each assignment to a public id, which is a real read,
+ * and the custom-field merge and photo accessor both touch the database as
+ * well — so the shape of the public payload can only be asserted against a
+ * real connection.
+ */
+function fleetopsFleetResourceDatabase(): Illuminate\Database\SQLiteConnection
+{
+    $connection = new Illuminate\Database\SQLiteConnection(new PDO('sqlite::memory:'));
+    $resolver   = new Illuminate\Database\ConnectionResolver(['default' => $connection, 'mysql' => $connection]);
+    $resolver->setDefaultConnection('mysql');
+    Illuminate\Database\Eloquent\Model::setConnectionResolver($resolver);
+
+    app()->instance('db', new class($connection) {
+        public function __construct(public Illuminate\Database\SQLiteConnection $c)
+        {
+        }
+
+        public function connection($name = null): Illuminate\Database\SQLiteConnection
+        {
+            return $this->c;
+        }
+
+        public function __call($method, $arguments)
+        {
+            return $this->c->{$method}(...$arguments);
+        }
+    });
+    app()->instance('db.schema', $connection->getSchemaBuilder());
+    Illuminate\Support\Facades\DB::clearResolvedInstance('db');
+
+    $schema = $connection->getSchemaBuilder();
+
+    $schema->create('fleets', function ($blueprint) {
+        $blueprint->increments('id');
+        foreach ([
+            'uuid', '_key', 'public_id', 'company_uuid', 'service_area_uuid', 'zone_uuid',
+            'vendor_uuid', 'parent_fleet_uuid', 'image_uuid', 'name', 'color', 'task', 'status', 'slug',
+        ] as $column) {
+            $blueprint->string($column)->nullable();
+        }
+        $blueprint->timestamps();
+        $blueprint->timestamp('deleted_at')->nullable();
+    });
+
+    foreach (['service_areas', 'zones', 'vendors'] as $table) {
+        $schema->create($table, function ($blueprint) {
+            $blueprint->increments('id');
+            foreach (['uuid', '_key', 'public_id', 'company_uuid', 'service_area_uuid', 'name', 'type', 'border', 'status'] as $column) {
+                $blueprint->string($column)->nullable();
+            }
+            $blueprint->timestamps();
+            $blueprint->timestamp('deleted_at')->nullable();
+        });
+    }
+
+    foreach (['fleet_drivers' => 'driver_uuid', 'fleet_vehicles' => 'vehicle_uuid'] as $table => $subject) {
+        $schema->create($table, function ($blueprint) use ($subject) {
+            $blueprint->increments('id');
+            $blueprint->string('uuid')->nullable();
+            $blueprint->string('fleet_uuid')->nullable();
+            $blueprint->string($subject)->nullable();
+            $blueprint->timestamps();
+            $blueprint->timestamp('deleted_at')->nullable();
+        });
+    }
+
+    foreach (['drivers', 'vehicles', 'users'] as $table) {
+        $schema->create($table, function ($blueprint) {
+            $blueprint->increments('id');
+            foreach (['uuid', 'public_id', 'company_uuid', 'user_uuid', 'name'] as $column) {
+                $blueprint->string($column)->nullable();
+            }
+            $blueprint->boolean('online')->nullable();
+            $blueprint->timestamps();
+            $blueprint->timestamp('deleted_at')->nullable();
+        });
+    }
+
+    // Permission directives are consulted by the query pipeline.
+    $schema->create('directives', function ($blueprint) {
+        $blueprint->increments('id');
+        foreach (['uuid', 'company_uuid', 'permission_uuid', 'subject_type', 'subject_uuid', 'key', 'rules'] as $column) {
+            $blueprint->string($column)->nullable();
+        }
+        $blueprint->timestamps();
+        $blueprint->timestamp('deleted_at')->nullable();
+    });
+
+    // The fleet image relation is eager loaded alongside the others.
+    $schema->create('files', function ($blueprint) {
+        $blueprint->increments('id');
+        foreach (['uuid', 'public_id', 'company_uuid', 'disk', 'path', 'bucket', 'type', 'original_filename'] as $column) {
+            $blueprint->string($column)->nullable();
+        }
+        $blueprint->timestamps();
+        $blueprint->timestamp('deleted_at')->nullable();
+    });
+
+    $schema->create('custom_field_values', function ($blueprint) {
+        $blueprint->increments('id');
+        foreach (['uuid', 'company_uuid', 'custom_field_uuid', 'subject_uuid', 'subject_type', 'value', 'value_type'] as $column) {
+            $blueprint->string($column)->nullable();
+        }
+        $blueprint->timestamps();
+        $blueprint->timestamp('deleted_at')->nullable();
+    });
+
+    $connection->table('service_areas')->insert(['uuid' => 'service-area-uuid', 'public_id' => 'service_area_123', 'company_uuid' => 'company-uuid', 'name' => 'Central']);
+    $connection->table('zones')->insert(['uuid' => 'zone-uuid', 'public_id' => 'zone_123', 'company_uuid' => 'company-uuid', 'name' => 'Downtown']);
+    $connection->table('vendors')->insert(['uuid' => 'vendor-uuid', 'public_id' => 'vendor_123', 'company_uuid' => 'company-uuid', 'name' => 'Acme']);
+    $connection->table('fleets')->insert(['uuid' => 'parent-uuid', 'public_id' => 'fleet_parent123', 'company_uuid' => 'company-uuid', 'name' => 'Parent']);
+
+    return $connection;
+}
+
+function fleetopsFleetResourceFixture(array $overrides = []): Fleet
+{
+    $connection = fleetopsFleetResourceDatabase();
+
+    $connection->table('fleets')->insert(array_merge([
+        'uuid'              => 'fleet-uuid',
+        'public_id'         => 'fleet_123',
+        'company_uuid'      => 'company-uuid',
+        'name'              => 'Carpool',
+        'color'             => '#2563EB',
+        'task'              => 'Employee transport',
+        'status'            => 'active',
+        'service_area_uuid' => 'service-area-uuid',
+        'zone_uuid'         => 'zone-uuid',
+        'vendor_uuid'       => 'vendor-uuid',
+        'parent_fleet_uuid' => 'parent-uuid',
+    ], $overrides));
+
+    return Fleet::where('uuid', 'fleet-uuid')->firstOrFail();
+}
+
+/**
+ * Resolve expansions the way a request does, then serialize.
+ *
+ * Going through the controller matters: it is what maps the public expansion
+ * name onto the relation name and drops anything outside the allowlist, and the
+ * resource is written to trust that mapping.
+ */
+function fleetopsFleetPayload(Fleet $fleet, bool $internal = false, array $query = []): array
+{
+    $request = fleetopsFleetResourceRequest($internal, $query);
+
+    $controller = new FleetController();
+    $reflection = new ReflectionMethod(FleetController::class, 'applyPublicExpansions');
+    $reflection->setAccessible(true);
+    $reflection->invoke($controller, $request, FleetController::EXPANDABLE);
+
+    return (new FleetResource($fleet))->resolve($request);
+}
+
+test('the public fleet resource reports every writable field and each relationship as an additive id', function () {
+    $payload = fleetopsFleetPayload(fleetopsFleetResourceFixture());
+
+    // The identifier is a new key beside the relationship, never a value under
+    // it. The SDK stores whatever the API returns verbatim, so a property that
+    // is an object on one call and a string on another breaks every consumer
+    // that dereferences it.
+    expect($payload)->toMatchArray([
+        'id'              => 'fleet_123',
+        'name'            => 'Carpool',
+        'color'           => '#2563EB',
+        'task'            => 'Employee transport',
+        'status'          => 'active',
+        'service_area_id' => 'service_area_123',
+        'zone_id'         => 'zone_123',
+        'vendor_id'       => 'vendor_123',
+        'parent_fleet_id' => 'fleet_parent123',
+    ])
+        // Unexpanded, the object keys stay absent exactly as they were before
+        // this contract gained the identifiers.
+        ->and($payload)->not->toHaveKeys(['service_area', 'zone', 'vendor', 'parent_fleet', 'photo'])
+        ->and($payload)->not->toHaveKeys([
+            'uuid',
+            'public_id',
+            'company_uuid',
+            'service_area_uuid',
+            'zone_uuid',
+            'vendor_uuid',
+            'parent_fleet_uuid',
+            'image_uuid',
+        ]);
+});
+
+test('the public fleet resource reports a root fleet with null relationship ids', function () {
+    $fleet = fleetopsFleetResourceFixture(['parent_fleet_uuid' => null, 'zone_uuid' => null]);
+
+    $payload = fleetopsFleetPayload($fleet);
+
+    expect($payload)->toHaveKeys(['parent_fleet_id', 'zone_id'])
+        ->and($payload['parent_fleet_id'])->toBeNull()
+        ->and($payload['zone_id'])->toBeNull();
+});
+
+test('the internal fleet resource keeps its nested relationship shape', function () {
+    $fleet   = fleetopsFleetResourceFixture()->load(['serviceArea', 'zone', 'vendor', 'parentFleet']);
+    $payload = fleetopsFleetPayload($fleet, true);
+
+    // The console reads nested objects off these keys, and reads the counters;
+    // expanding the public contract must not reshape either.
+    expect($payload)->toHaveKeys(['uuid', 'public_id', 'drivers_count', 'vehicles_count'])
+        ->and($payload['uuid'])->toBe('fleet-uuid')
+        ->and($payload['service_area'])->toBeObject()
+        ->and($payload['zone'])->toBeObject()
+        ->and($payload['vendor'])->toBeObject()
+        ->and($payload['parent_fleet'])->toBeObject();
+});
+
+test('expanding a fleet relationship adds the object and leaves the id untouched', function () {
+    $payload = fleetopsFleetPayload(
+        fleetopsFleetResourceFixture(),
+        false,
+        ['with' => ['service_area', 'parent_fleet']]
+    );
+
+    expect($payload['service_area'])->toBeObject()
+        ->and($payload['parent_fleet'])->toBeObject()
+        // The identifier is unchanged by expansion, and agrees with the object.
+        ->and($payload['service_area_id'])->toBe('service_area_123')
+        ->and($payload['parent_fleet_id'])->toBe('fleet_parent123')
+        // The expanded object and the identifier agree. Asserted on the parent
+        // fleet: a ServiceArea serializes its border through GEOS, which the
+        // harness has no extension for.
+        ->and($payload['parent_fleet']->resolve()['id'])->toBe($payload['parent_fleet_id'])
+        // A relation that was not asked for is still absent, not a string.
+        ->and($payload)->not->toHaveKey('vendor')
+        ->and($payload['vendor_id'])->toBe('vendor_123');
+});
+
+test('fleet expansion accepts every documented input spelling', function () {
+    $scalar   = fleetopsFleetPayload(fleetopsFleetResourceFixture(), false, ['with' => 'service_area']);
+    $array    = fleetopsFleetPayload(fleetopsFleetResourceFixture(), false, ['with' => ['service_area']]);
+    $csv      = fleetopsFleetPayload(fleetopsFleetResourceFixture(), false, ['with' => 'service_area,vendor']);
+    $expand   = fleetopsFleetPayload(fleetopsFleetResourceFixture(), false, ['expand' => ['service_area']]);
+    $camel    = fleetopsFleetPayload(fleetopsFleetResourceFixture(), false, ['with' => 'serviceArea']);
+
+    // ?with=x, ?with[]=x, ?with=x,y and ?expand=x all mean the same thing.
+    expect($scalar['service_area'])->toBeObject()
+        ->and($array['service_area'])->toBeObject()
+        ->and($csv['service_area'])->toBeObject()
+        ->and($csv['vendor'])->toBeObject()
+        ->and($expand['service_area'])->toBeObject()
+        ->and($camel['service_area'])->toBeObject();
+});
+
+test('an unsupported fleet expansion is ignored rather than reaching eloquent', function () {
+    // Core hands `with` straight to load(), so an unknown name would be a 500
+    // for what is only a typo. The allowlist drops it and the response is
+    // otherwise unchanged.
+    $payload = fleetopsFleetPayload(
+        fleetopsFleetResourceFixture(),
+        false,
+        ['with' => ['not_a_relation', 'company', 'service_area']]
+    );
+
+    expect($payload['service_area'])->toBeObject()
+        ->and($payload)->not->toHaveKeys(['not_a_relation', 'company'])
+        ->and($payload['id'])->toBe('fleet_123');
+});
+
+test('public fleet membership routes are registered with public id parameters', function () {
+    $routes = file_get_contents(dirname(__DIR__, 4) . '/src/routes.php');
+
+    expect($routes)
+        ->toContain("\$router->post('{id}/vehicles/{vehicle}', 'FleetController@assignVehicle');")
+        ->toContain("\$router->delete('{id}/vehicles/{vehicle}', 'FleetController@removeVehicle');")
+        ->toContain("\$router->post('{id}/drivers/{driver}', 'FleetController@assignDriver');")
+        ->toContain("\$router->delete('{id}/drivers/{driver}', 'FleetController@removeDriver');");
+
+    $fleetGroup = substr($routes, strpos($routes, '// fleets routes'));
+    $fleetGroup = substr($fleetGroup, 0, strpos($fleetGroup, '// labels routes'));
+
+    // The literal segments have to be declared before the `{id}` patterns, or
+    // `vehicles` is swallowed as a fleet id.
+    expect(strpos($fleetGroup, '{id}/vehicles/{vehicle}'))->toBeLessThan(strpos($fleetGroup, "\$router->get('{id}'"));
+});
+
+test('the public fleet controller exposes the membership actions', function () {
+    foreach (['create', 'query', 'find', 'update', 'delete', 'assignVehicle', 'removeVehicle', 'assignDriver', 'removeDriver'] as $method) {
+        expect(method_exists(FleetController::class, $method))->toBeTrue();
+    }
+});
+
+test('the fleet controller lookup query and eager-load helpers run their real bodies', function () {
+    $connection = fleetopsFleetResourceDatabase();
+    session(['company' => 'company-uuid']);
+
+    $connection->table('fleets')->insert([
+        ['uuid' => 'fleet-uuid', 'public_id' => 'fleet_123', 'company_uuid' => 'company-uuid', 'name' => 'Haulers', 'service_area_uuid' => 'service-area-uuid', 'parent_fleet_uuid' => 'parent-uuid'],
+        ['uuid' => 'other-company-fleet', 'public_id' => 'fleet_elsewhere', 'company_uuid' => 'another-company', 'name' => 'Theirs', 'service_area_uuid' => null, 'parent_fleet_uuid' => null],
+    ]);
+    $connection->table('vehicles')->insert(['uuid' => 'vehicle-uuid', 'public_id' => 'vehicle_123', 'company_uuid' => 'company-uuid']);
+    $connection->table('users')->insert(['uuid' => 'user-uuid', 'company_uuid' => 'company-uuid']);
+    $connection->table('drivers')->insert(['uuid' => 'driver-uuid', 'public_id' => 'driver_123', 'company_uuid' => 'company-uuid', 'user_uuid' => 'user-uuid']);
+
+    $controller = new FleetController();
+    $call       = function (string $method, ...$arguments) use ($controller) {
+        $reflection = new ReflectionMethod(FleetController::class, $method);
+        $reflection->setAccessible(true);
+
+        return $reflection->invoke($controller, ...$arguments);
+    };
+
+    $fleet = $call('findFleet', 'fleet_123');
+
+    expect($fleet->uuid)->toBe('fleet-uuid')
+        ->and($call('findVehicle', 'vehicle_123')->uuid)->toBe('vehicle-uuid')
+        ->and($call('findDriver', 'driver_123')->uuid)->toBe('driver-uuid');
+
+    // A fleet in another company is unavailable, not forbidden.
+    expect(fn () => $call('findFleet', 'fleet_elsewhere'))
+        ->toThrow(Illuminate\Database\Eloquent\ModelNotFoundException::class);
+
+    // The relations the public resource reports as public ids are eager loaded
+    // rather than resolved one query at a time.
+    $loaded = $call('withPublicRelations', $fleet);
+
+    expect($loaded->relationLoaded('serviceArea'))->toBeTrue()
+        ->and($loaded->relationLoaded('zone'))->toBeTrue()
+        ->and($loaded->relationLoaded('vendor'))->toBeTrue()
+        ->and($loaded->relationLoaded('parentFleet'))->toBeTrue()
+        ->and($loaded->relationLoaded('photo'))->toBeTrue()
+        ->and($loaded->serviceArea->public_id)->toBe('service_area_123');
+
+    // The query pipeline scopes to the caller's company and eager loads the
+    // same relations for every row in the page.
+    $uri     = 'v1/fleets';
+    $request = Request::create('/' . $uri, 'GET');
+    $store   = app('session.store');
+    $store->put('company', 'company-uuid');
+    $request->setLaravelSession($store);
+    $request->setRouteResolver(fn () => new FleetOpsFleetResourceRouteFixture($uri));
+    app()->instance('request', $request);
+
+    $results = $call('queryFleets', $request);
+
+    $returned = $results->pluck('uuid')->all();
+
+    expect($returned)->toContain('fleet-uuid', 'parent-uuid')
+        ->and($returned)->not->toContain('other-company-fleet')
+        ->and($results->first()->relationLoaded('serviceArea'))->toBeTrue()
+        ->and($results->first()->relationLoaded('parentFleet'))->toBeTrue();
+});
+
+test('the fleet resource accepts a scalar with parameter it was handed directly', function () {
+    // The controller normalises `with` into an array before the resource runs,
+    // but the resource is also reachable from code that passes the raw scalar
+    // through — it must read the same list either way.
+    $request = fleetopsFleetResourceRequest(false, ['with' => 'serviceArea,parentFleet']);
+    $payload = (new FleetResource(fleetopsFleetResourceFixture()))->resolve($request);
+
+    expect($payload['service_area'])->toBeObject()
+        ->and($payload['parent_fleet'])->toBeObject()
+        ->and($payload['service_area_id'])->toBe('service_area_123');
+});

package/server/tests/Feature/Http/Api/FuelTransactionControllerContractsTest.php

@@ -44,14 +44,14 @@ class FleetOpsApiFuelTransactionControllerProbe extends FuelTransactionControlle
         ];
     }
 
-    protected function resolveUuid(string $modelClass, ?string $id): ?string
+    protected function resolveUuid(string $modelClass, ?string $id, ?string $companyUuid = null): ?string
     {
         $this->resolvedUuids[] = [$modelClass, $id];
 
         return filled($id) ? $id . '-uuid' : null;
     }
 
-    protected function resolveModel(string $modelClass, string $id): EloquentModel
+    protected function resolveModel(string $modelClass, string $id, ?string $companyUuid = null): EloquentModel
     {
         $key = $modelClass . ':' . $id;
 

package/server/tests/Feature/Http/Api/NullRelationshipInputTest.php

@@ -0,0 +1,191 @@
+<?php
+
+use Fleetbase\FleetOps\Http\Controllers\Api\v1\EntityController;
+use Fleetbase\FleetOps\Http\Controllers\Api\v1\FuelReportController;
+use Fleetbase\FleetOps\Http\Controllers\Api\v1\IssueController;
+use Fleetbase\FleetOps\Http\Controllers\Api\v1\OrderController;
+use Fleetbase\FleetOps\Http\Controllers\Api\v1\ServiceAreaController;
+use Fleetbase\FleetOps\Http\Controllers\Api\v1\TrackingStatusController;
+use Fleetbase\FleetOps\Http\Controllers\Api\v1\ZoneController;
+use Illuminate\Database\ConnectionResolver;
+use Illuminate\Database\Eloquent\Model as EloquentModel;
+use Illuminate\Database\Eloquent\ModelNotFoundException;
+use Illuminate\Database\SQLiteConnection;
+use Illuminate\Support\Facades\DB;
+
+/**
+ * A relationship sent as `""` or `null` must never be a 5xx.
+ *
+ * `ConvertEmptyStringsToNull` is global middleware, so `"driver": ""` reaches
+ * the controller as null and `$request->has('driver')` is still true — `has()`
+ * means the key is present, not that it holds anything. Every public
+ * relationship input therefore arrives as null sooner or later, usually from a
+ * form that serialises an unselected dropdown as an empty string.
+ *
+ * That was fine for years because the lookups were plain queries:
+ * `where('public_id', null)` matches nothing and the caller's `if ($driver)`
+ * skips. It broke when a coverage pass extracted one of those queries into
+ * `findDriverByPublicId(string $publicId)` — the *return* type was made
+ * nullable, the parameter was not — turning "no driver" into a TypeError on
+ * `POST /v1/orders`.
+ *
+ * The static test below is the one that would have caught it: it holds the
+ * property rather than the instance, so the next extraction cannot reintroduce
+ * the class.
+ */
+function fleetopsNullRelationshipBoot(): SQLiteConnection
+{
+    $connection = new SQLiteConnection(new PDO('sqlite::memory:'));
+    $resolver   = new ConnectionResolver(['default' => $connection, 'mysql' => $connection]);
+    $resolver->setDefaultConnection('mysql');
+    EloquentModel::setConnectionResolver($resolver);
+
+    app()->instance('db', new class($connection) {
+        public function __construct(public SQLiteConnection $c)
+        {
+        }
+
+        public function connection($name = null): SQLiteConnection
+        {
+            return $this->c;
+        }
+
+        public function __call($method, $arguments)
+        {
+            return $this->c->{$method}(...$arguments);
+        }
+    });
+    app()->instance('db.schema', $connection->getSchemaBuilder());
+    DB::clearResolvedInstance('db');
+
+    $schema = $connection->getSchemaBuilder();
+    foreach (['drivers', 'users', 'payloads', 'orders', 'service_areas', 'entities', 'waypoints', 'places'] as $table) {
+        $schema->create($table, function ($blueprint) {
+            $blueprint->increments('id');
+            foreach (['uuid', 'public_id', 'internal_id', 'company_uuid', 'user_uuid', 'tracking_number_uuid', 'payload_uuid', 'place_uuid', 'name', '_key'] as $column) {
+                $blueprint->string($column)->nullable();
+            }
+            $blueprint->timestamps();
+            $blueprint->timestamp('deleted_at')->nullable();
+        });
+    }
+
+    session(['company' => 'company-uuid']);
+    $connection->table('users')->insert(['uuid' => 'user-uuid', 'company_uuid' => 'company-uuid']);
+    $connection->table('drivers')->insert(['uuid' => 'driver-uuid', 'public_id' => 'driver_real01', 'company_uuid' => 'company-uuid', 'user_uuid' => 'user-uuid']);
+    $connection->table('payloads')->insert(['uuid' => 'payload-uuid', 'public_id' => 'payload_real01', 'company_uuid' => 'company-uuid']);
+    $connection->table('orders')->insert(['uuid' => 'order-uuid', 'public_id' => 'order_real01', 'company_uuid' => 'company-uuid', 'tracking_number_uuid' => 'tracking-uuid']);
+    $connection->table('service_areas')->insert(['uuid' => 'sa-uuid', 'public_id' => 'service_area_r1', 'company_uuid' => 'company-uuid']);
+
+    return $connection;
+}
+
+function fleetopsInvokeSeam(object $controller, string $method, ...$arguments)
+{
+    $reflection = new ReflectionMethod($controller, $method);
+    $reflection->setAccessible(true);
+
+    return $reflection->invoke($controller, ...$arguments);
+}
+
+test('every request-fed lookup seam answers rather than raising when handed nothing', function () {
+    fleetopsNullRelationshipBoot();
+
+    // Each of these is reached from `$request->input('<relationship>')`. A null
+    // means the caller sent an empty relationship, which is a question with an
+    // answer — "there is no such record" — not a programming error.
+    expect(fleetopsInvokeSeam(new OrderController(), 'findDriverByPublicId', null))->toBeNull()
+        ->and(fleetopsInvokeSeam(new EntityController(), 'findPayloadByPublicId', null))->toBeNull()
+        ->and(fleetopsInvokeSeam(new TrackingStatusController(), 'getOrderTrackingNumberUuid', null))->toBeNull()
+        ->and(fleetopsInvokeSeam(new ServiceAreaController(), 'serviceAreaUuid', null, ['public_id' => null, 'company_uuid' => 'company-uuid']))->toBeNull()
+        ->and(fleetopsInvokeSeam(new ZoneController(), 'serviceAreaUuid', null, ['public_id' => null, 'company_uuid' => 'company-uuid']))->toBeNull();
+
+    // Issue and FuelReport reach their seam only from `create`, where `driver`
+    // is `required` — validation answers 422 long before a null could arrive.
+    // Widening them is defence-in-depth for a future call site, so the claim
+    // here is only the one that matters: whatever they answer, it is not a
+    // TypeError. A TypeError would escape this block and fail the test.
+    foreach ([new IssueController(), new FuelReportController()] as $controller) {
+        try {
+            fleetopsInvokeSeam($controller, 'findDriverRecord', null);
+        } catch (ModelNotFoundException) {
+            // "No such driver" — the call sites already translate this into a 404.
+        }
+    }
+});
+
+test('a real identifier still resolves through the widened seams', function () {
+    fleetopsNullRelationshipBoot();
+
+    // Widening the parameter must not have widened the lookup: a present
+    // identifier resolves exactly as before, and one that does not exist still
+    // resolves to nothing.
+    expect(fleetopsInvokeSeam(new OrderController(), 'findDriverByPublicId', 'driver_real01')->uuid)->toBe('driver-uuid')
+        ->and(fleetopsInvokeSeam(new OrderController(), 'findDriverByPublicId', 'driver_missing'))->toBeNull()
+        ->and(fleetopsInvokeSeam(new EntityController(), 'findPayloadByPublicId', 'payload_real01')->uuid)->toBe('payload-uuid')
+        ->and(fleetopsInvokeSeam(new TrackingStatusController(), 'getOrderTrackingNumberUuid', 'order_real01'))->toBe('tracking-uuid')
+        ->and(fleetopsInvokeSeam(new ServiceAreaController(), 'serviceAreaUuid', 'service_area_r1', ['public_id' => 'service_area_r1', 'company_uuid' => 'company-uuid']))->toBe('sa-uuid');
+});
+
+test('no public api lookup seam fed from the request refuses a null identifier', function () {
+    // The systemic guard. Rather than pinning the eight seams that exist today,
+    // it derives them: every call of the form `$this->someSeam($request->input(...))`
+    // in the public v1 controllers, checked for a nullable first parameter.
+    //
+    // An extraction that types a new seam `string` fails here, at the commit
+    // that introduces it, instead of in production on an empty dropdown.
+    // Exempt only where the *call site* already excludes null, and say which
+    // guard does it — an exemption without a named guard is how this test would
+    // rot into a rubber stamp.
+    $exempt = [
+        // Not an identifier lookup — it geocodes a free-text address, and a null
+        // address has no meaning to geocode. Its call sites guard with
+        // `$request->isString(...)`, which a null can never satisfy.
+        'PlaceController::createPlaceFromGeocodingLookup',
+        // Both call sites are behind `$request->isArray('payload')`. A payload
+        // sent as `""` fails that guard and is skipped, never unpacked.
+        'OrderController::payloadShapeFromArray',
+    ];
+
+    $offenders = [];
+    $inspected = [];
+
+    foreach (glob(dirname(__DIR__, 4) . '/src/Http/Controllers/Api/v1/*.php') as $path) {
+        $source     = file_get_contents($path);
+        $controller = basename($path, '.php');
+
+        preg_match_all('/\$this->([A-Za-z_]+)\(\s*\$request->(?:input|or)\(/', $source, $matches);
+
+        foreach (array_unique($matches[1]) as $seam) {
+            if (in_array($controller . '::' . $seam, $exempt, true)) {
+                continue;
+            }
+
+            if (!preg_match('/(?:protected|public|private) function ' . preg_quote($seam, '/') . '\(([^),]*)/', $source, $signature)) {
+                continue;
+            }
+
+            $firstParameter = trim($signature[1]);
+            $inspected[]    = $controller . '::' . $seam;
+
+            // `mixed`, an untyped parameter, and anything explicitly nullable all
+            // accept null already; only a narrow non-nullable type is a problem.
+            $accepts = $firstParameter === ''
+                || str_starts_with($firstParameter, '?')
+                || str_starts_with($firstParameter, '$')
+                || str_contains($firstParameter, 'null')
+                || str_starts_with($firstParameter, 'mixed');
+
+            if (!$accepts) {
+                $offenders[] = $controller . '::' . $seam . '(' . $firstParameter . ')';
+            }
+        }
+    }
+
+    // A guard that scans nothing passes for the wrong reason, so make the scan
+    // prove itself: the seam this bug was reported against has to be among what
+    // it looked at. If the glob or the pattern ever stops matching, this fails
+    // instead of going quietly green.
+    expect($inspected)->toContain('OrderController::findDriverByPublicId')
+        ->and($offenders)->toBe([], 'these seams are handed a request value and would raise a TypeError on an empty relationship: ' . implode(', ', $offenders));
+});