@fleetbase/fleetops-engine 0.6.65 → 0.6.67

package/server/src/Http/Resources/v1/InspectionLink.php

@@ -0,0 +1,84 @@
+<?php
+
+namespace Fleetbase\FleetOps\Http\Resources\v1;
+
+use Fleetbase\FleetOps\Support\InspectionLinkPin;
+use Fleetbase\Http\Resources\FleetbaseResource;
+use Fleetbase\Support\Http;
+
+/**
+ * A public inspection link, as the console lists it.
+ *
+ * `state` is the computed one — active, expired, used or revoked — not the
+ * stored `status`, because a link that has run out of time still says
+ * `active` in the column. `url` is the link itself, present only for links
+ * minted since the token has been kept.
+ */
+class InspectionLink extends FleetbaseResource
+{
+    /**
+     * Transform the resource into an array.
+     *
+     * @param \Illuminate\Http\Request $request
+     *
+     * @return array
+     */
+    public function toArray($request)
+    {
+        $internal = Http::isInternalRequest();
+
+        return [
+            // Always the public id: it is what identifies a link back to the
+            // revoke endpoint. `$this->id` is the table's auto-increment
+            // column, which no lookup here resolves — a list built from it
+            // could show links but never revoke one.
+            'id'             => $this->public_id,
+            'uuid'           => $this->when($internal, $this->uuid),
+            'public_id'      => $this->when($internal, $this->public_id),
+            'path'           => $this->path,
+            'state'          => $this->state,
+            'status'         => $this->status,
+            'single_use'     => (bool) $this->single_use,
+            'has_pin'        => $this->hasPin(),
+            // Shown in the console, like the link, so a dispatcher can read it
+            // out or send it again. Never on a public request.
+            'pin'            => $this->when($internal, fn () => $this->pin),
+            'pin_sent_via'   => $this->pin_sent_via,
+            'pin_sent_at'    => $this->pin_sent_at,
+            'pin_attempts'   => $this->when($internal, fn () => (int) $this->pin_attempts),
+            'recipient'      => $this->when($internal, function () {
+                $recipient = InspectionLinkPin::recipientFor($this->resource);
+
+                return $recipient ? ['name' => $recipient->name] : null;
+            }),
+            'can_send_pin'   => $this->when($internal, function () {
+                $recipient = InspectionLinkPin::recipientFor($this->resource);
+
+                return [
+                    'email' => InspectionLinkPin::unavailableReason($recipient, 'email') === null,
+                    'sms'   => InspectionLinkPin::unavailableReason($recipient, 'sms') === null,
+                ];
+            }),
+            'assignee'       => $this->assignee ? [
+                'id'   => $this->assignee->public_id,
+                'name' => $this->assignee->name,
+            ] : null,
+            'driver'         => $this->driver ? [
+                'id'   => $this->driver->public_id,
+                'name' => $this->driver->name,
+            ] : null,
+            'vehicle'        => $this->vehicle ? [
+                'id'   => $this->vehicle->public_id,
+                'name' => $this->vehicle->display_name ?? $this->vehicle->name,
+            ] : null,
+            'created_by'     => $this->createdBy ? [
+                'id'   => $this->createdBy->public_id,
+                'name' => $this->createdBy->name,
+            ] : null,
+            'expires_at'     => $this->expires_at,
+            'last_viewed_at' => $this->last_viewed_at,
+            'used_at'        => $this->used_at,
+            'created_at'     => $this->created_at,
+        ];
+    }
+}

package/server/src/Http/Resources/v1/InspectionSubmission.php

@@ -0,0 +1,173 @@
+<?php
+
+namespace Fleetbase\FleetOps\Http\Resources\v1;
+
+use Fleetbase\FleetOps\Support\InspectionFileStore;
+use Fleetbase\FleetOps\Support\Utils;
+use Fleetbase\Http\Resources\FleetbaseResource;
+use Fleetbase\Http\Resources\User;
+use Fleetbase\Models\CustomFieldValue;
+use Fleetbase\Models\File;
+use Fleetbase\Support\Http;
+
+class InspectionSubmission extends FleetbaseResource
+{
+    /**
+     * Transform the resource into an array.
+     *
+     * @param \Illuminate\Http\Request $request
+     *
+     * @return array
+     */
+    public function toArray($request)
+    {
+        $data = $this->withCustomFields([
+            'id'                   => $this->when(Http::isInternalRequest(), $this->id, $this->public_id),
+            'uuid'                 => $this->when(Http::isInternalRequest(), $this->uuid),
+            'public_id'            => $this->when(Http::isInternalRequest(), $this->public_id),
+            'company_uuid'         => $this->when(Http::isInternalRequest(), $this->company_uuid),
+            'inspection_form_uuid' => $this->when(Http::isInternalRequest(), $this->inspection_form_uuid),
+            'vehicle_uuid'         => $this->when(Http::isInternalRequest(), $this->vehicle_uuid),
+            'driver_uuid'          => $this->when(Http::isInternalRequest(), $this->driver_uuid),
+            'submitted_by_uuid'    => $this->when(Http::isInternalRequest(), $this->submitted_by_uuid),
+            'issue_uuid'           => $this->when(Http::isInternalRequest(), $this->issue_uuid),
+            'work_order_uuid'      => $this->when(Http::isInternalRequest(), $this->work_order_uuid),
+            'form'                 => $this->whenLoaded('form', fn () => new InspectionForm($this->form)),
+            'vehicle'              => $this->whenLoaded('vehicle', fn () => new Vehicle($this->vehicle)),
+            'driver'               => $this->whenLoaded('driver', fn () => new Driver($this->driver)),
+            'submitted_by'         => $this->whenLoaded('submittedBy', fn () => new User($this->submittedBy)),
+            'issue'                => $this->whenLoaded('issue', fn () => new Issue($this->issue)),
+            'work_order'           => $this->whenLoaded('workOrder', fn () => new WorkOrder($this->workOrder)),
+            'item_results'         => InspectionItemResult::collection($this->whenLoaded('itemResults')),
+            'type'                 => $this->type,
+            'status'               => $this->status,
+            'result'               => $this->result,
+            'source'               => $this->source,
+            'odometer'             => $this->odometer,
+            'engine_hours'         => $this->engine_hours,
+            'total_items'          => $this->total_items,
+            'failed_items'         => $this->failed_items,
+            'location'             => data_get($this, 'location', (object) []),
+            'signature'            => data_get($this, 'signature', (object) []),
+            'attachments'          => data_get($this, 'attachments', []),
+            'meta'                 => data_get($this, 'meta', Utils::createObject()),
+            'form_name'            => $this->form_name,
+            'vehicle_name'         => $this->vehicle_name,
+            'driver_name'          => $this->driver_name,
+            'has_failures'         => $this->has_failures,
+            'started_at'           => $this->started_at,
+            'submitted_at'         => $this->submitted_at,
+            'resolved_at'          => $this->resolved_at,
+            'updated_at'           => $this->updated_at,
+            'created_at'           => $this->created_at,
+        ]);
+
+        // The platform's own `withCustomFields` puts the raw value models
+        // under `custom_field_values` for the console. What both consoles and
+        // the app want is the field's identity beside its answer, with file
+        // references resolved, so that projection replaces it.
+        //
+        // A form has `fields`; a submission has `answers` to them. The stored
+        // shape is the platform's custom-field values, but that is how it is
+        // built rather than what it is, and an integrator reading a DVIR
+        // should not have to know the difference.
+        $answers = $this->projectCustomFieldValues();
+        if (Http::isInternalRequest()) {
+            $data['custom_field_values'] = $answers;
+        }
+        $data['answers'] = $answers;
+        $data['files']   = $this->projectFiles();
+
+        return $data;
+    }
+
+    /**
+     * The answers, as the app and the console read them: which field, what it
+     * is called, its type, and the value with every `file:<uuid>` resolved to
+     * something fetchable.
+     */
+    protected function projectCustomFieldValues(): array
+    {
+        // `withCustomFields()` has already loaded the values and the fields
+        // they answer, so there is nothing to guard against here.
+        $internal = Http::isInternalRequest();
+
+        return collect($this->resource?->customFieldValues)->map(function (CustomFieldValue $value) use ($internal) {
+            $field = $value->customField;
+            $row   = [
+                // The field's public id, as the form hands it out. `value_type`
+                // describes how the answer is stored, which is the platform's
+                // business and not an integrator's, so it stays internal.
+                'field'      => $internal ? $value->custom_field_uuid : ($field?->public_id ?? $value->custom_field_uuid),
+                'name'       => $field?->name,
+                'label'      => $field?->label ?? $value->custom_field_label,
+                'type'       => $field?->type ?? $value->value_type,
+                'value'      => static::projectValue($value),
+            ];
+
+            if ($internal) {
+                $row['custom_field'] = $value->custom_field_uuid;
+                $row['value_type']   = $value->value_type;
+                $row['uuid']          = $value->uuid;
+                $row['category_uuid'] = $field?->category_uuid;
+                $row['order']         = $field?->order === null ? null : (int) $field->order;
+                $row['meta']          = is_array($field?->meta) && !empty($field->meta) ? $field->meta : (object) [];
+            }
+
+            return $row;
+        })->values()->all();
+    }
+
+    /**
+     * One stored value, with file references resolved. A pass-fail answer
+     * carries its photos inside it, so those are resolved too.
+     */
+    protected static function projectValue(CustomFieldValue $value): mixed
+    {
+        $raw = $value->getRawOriginal('value');
+
+        if (in_array($value->value_type, ['object', 'array'], true)) {
+            $decoded = is_string($raw) ? json_decode($raw, true) : $raw;
+            if (!is_array($decoded)) {
+                return $decoded;
+            }
+
+            if (isset($decoded['photos']) && is_array($decoded['photos'])) {
+                $decoded['photos'] = array_values(array_map(fn ($photo) => InspectionFileStore::project($photo), $decoded['photos']));
+            }
+
+            return $decoded;
+        }
+
+        // A value column is a string, so a meter reading comes back as one.
+        // The app compares and charts these; hand it the number it wrote.
+        if ($value->value_type === 'number') {
+            return is_numeric($raw) ? $raw + 0 : $raw;
+        }
+
+        if ($value->value_type === 'boolean') {
+            return filter_var($raw, FILTER_VALIDATE_BOOLEAN);
+        }
+
+        return InspectionFileStore::project($raw);
+    }
+
+    /** The photos and signatures filed with the inspection. */
+    protected function projectFiles(): array
+    {
+        if (!$this->resource || !$this->resource->relationLoaded('files')) {
+            return [];
+        }
+
+        return $this->resource->files->map(fn (File $file) => [
+            'id'                => $file->public_id ?? $file->uuid,
+            'uuid'              => $file->uuid,
+            'url'               => $file->url,
+            'original_filename' => $file->original_filename,
+            'content_type'      => $file->content_type,
+            'type'              => $file->type,
+            'caption'           => $file->caption,
+            'created_at'        => $file->created_at,
+        ])->values()->all();
+    }
+}

package/server/src/Jobs/PollTelematicTelemetry.php

@@ -0,0 +1,233 @@
+<?php
+
+namespace Fleetbase\FleetOps\Jobs;
+
+use Fleetbase\FleetOps\Contracts\TelemetryProviderInterface;
+use Fleetbase\FleetOps\Exceptions\TelematicRateLimitExceededException;
+use Fleetbase\FleetOps\Models\Telematic;
+use Fleetbase\FleetOps\Support\Telematics\TelematicProviderRegistry;
+use Fleetbase\FleetOps\Support\Telematics\Telemetry\Configuration;
+use Fleetbase\FleetOps\Support\Telematics\Telemetry\Inbox;
+use Illuminate\Bus\Queueable;
+use Illuminate\Contracts\Queue\ShouldBeUnique;
+use Illuminate\Contracts\Queue\ShouldQueue;
+use Illuminate\Foundation\Bus\Dispatchable;
+use Illuminate\Queue\InteractsWithQueue;
+use Illuminate\Support\Facades\Cache;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Str;
+
+class PollTelematicTelemetry implements ShouldQueue, ShouldBeUnique
+{
+    use Dispatchable;
+    use InteractsWithQueue;
+    use Queueable;
+
+    // Reservations released while earlier batches drain are not provider failures.
+    public int $tries         = 0;
+    public int $maxExceptions = 5;
+    // Keep every attempt below Laravel's baseline Redis retry_after of 90 seconds.
+    public int $timeout          = 80;
+    public int $uniqueFor        = 3600;
+    public ?string $manualJobId  = null;
+    public array $requestOptions = [];
+    public ?int $retryDeadline   = null;
+
+    public function __construct(public string $telematicUuid, ?string $manualJobId = null, array $requestOptions = [])
+    {
+        $this->manualJobId    = $manualJobId;
+        $this->requestOptions = $requestOptions;
+        $this->retryDeadline  = now()->addMinutes(15)->getTimestamp();
+    }
+
+    public function uniqueId(): string
+    {
+        return $this->telematicUuid;
+    }
+
+    public function backoff(): array
+    {
+        // A scheduled retry holds the uniqueness lease that suppresses minute ticks,
+        // so it must not wait longer than the polling interval after a transient failure.
+        return $this->manualJobId ? [15, 60, 180, 300] : [15, 30, 60, 60];
+    }
+
+    public function retryUntil(): \Illuminate\Support\Carbon
+    {
+        if ($this->retryDeadline === null) {
+            // Older serialized jobs have no deadline property. Anchor their first
+            // observed attempt once, rather than extending it on each redelivery.
+            $key                 = 'telemetry:poll:retry-deadline:' . ($this->job?->uuid() ?? $this->manualJobId ?? $this->telematicUuid);
+            $this->retryDeadline = Cache::remember($key, 86400, fn () => now()->addMinutes(15)->getTimestamp());
+        }
+
+        return \Illuminate\Support\Carbon::createFromTimestampUTC($this->retryDeadline);
+    }
+
+    public function handle(TelematicProviderRegistry $registry, Inbox $inbox): void
+    {
+        if (now()->gte($this->retryUntil())) {
+            $error = new \Illuminate\Queue\MaxAttemptsExceededException('Telemetry polling retry deadline exceeded.');
+            if ($this->job) {
+                $this->fail($error);
+            } else {
+                $this->failed($error);
+            }
+
+            return;
+        }
+        $telematic = Telematic::withoutGlobalScopes()->where('uuid', $this->telematicUuid)->first();
+        if (!$telematic || !Inbox::enabled($telematic)) {
+            return;
+        }
+        $provider = $registry->resolve($telematic->provider);
+        if (!$provider instanceof TelemetryProviderInterface) {
+            return;
+        }
+        $options = Configuration::options($provider);
+        if (!($options['polling_enabled'] ?? false)) {
+            return;
+        }
+        // Coalesce ticks while a previous sweep is still being ingested.
+        if (DB::table('telematic_deliveries')->where('telematic_uuid', $this->telematicUuid)->where('source', 'poll')->whereIn('status', ['pending', 'retry', 'processing'])->exists()) {
+            if ($this->manualJobId && $this->job) {
+                $this->manualProgress(['last_sync_result' => 'retrying', 'last_sync_phase' => 'waiting_for_ingestion']);
+                $this->release(15);
+            }
+
+            return;
+        }
+        $lock = Cache::lock('telemetry:poll:' . $this->telematicUuid, 85);
+        if (!$lock->get()) {
+            if ($this->manualJobId && $this->job) {
+                $this->release(15);
+            }
+
+            return;
+        }
+        $run = (string) Str::uuid();
+        try {
+            $started = microtime(true);
+            DB::table('telematic_sync_runs')->insert(['uuid' => $run, 'telematic_uuid' => $telematic->uuid, 'status' => 'fetching', 'created_at' => now(), 'updated_at' => now()]);
+            $this->manualProgress([
+                'last_sync_run_uuid'      => $run, 'last_sync_run_job_id' => $this->manualJobId,
+                'last_sync_result'        => 'running', 'last_sync_phase' => 'fetching_inventory',
+                'last_sync_fetched_total' => 0, 'last_sync_page_count' => 0,
+                'last_sync_linked_total'  => 0, 'last_sync_failed_total' => 0, 'last_sync_error' => null,
+            ]);
+            $provider->connect($telematic);
+            $cursor  = null;
+            $cursors = [];
+            $seen    = [];
+            for ($page = 0; $page < ($options['max_pages'] ?? 100); $page++) {
+                $remaining = $this->remainingBudget($started);
+                // Large fleet responses can exceed 20 seconds. Allow a configured
+                // request timeout without extending the bounded sweep deadline.
+                $timeout  = min(max(1, (int) ($options['request_timeout_seconds'] ?? 45)), $remaining);
+                $response = $provider->fetchDevices([
+                    'limit'             => min(max(1, (int) ($this->requestOptions['limit'] ?? $options['page_size'] ?? 1000)), 1000),
+                    'cursor'            => $cursor, 'filters' => $this->requestOptions['filters'] ?? [],
+                    'refresh_inventory' => $this->manualJobId !== null && $cursor === null,
+                    'timeout'           => $timeout, 'connect_timeout' => min(5, $timeout),
+                ]);
+                $this->remainingBudget($started);
+                $received = now()->utc();
+                $units    = $response['devices'];
+                $ids      = array_map(fn ($unit) => $provider->normalizeDevice($unit)['device_id'] ?? null, $units);
+                foreach ($ids as $id) {
+                    if (!$id || isset($seen[(string) $id])) {
+                        throw new \RuntimeException('Repeated or unidentified unit; sweep incomplete.');
+                    }
+                    $seen[(string) $id] = true;
+                }
+                foreach (array_chunk($units, max(1, (int) ($options['batch_size'] ?? 100))) as $batch) {
+                    $this->remainingBudget($started);
+                    $inbox->accept($telematic, $batch, 'poll', $run, $received->toDateTimeString());
+                }
+                $this->remainingBudget($started);
+                DB::table('telematic_sync_runs')->where('uuid', $run)->update(['pages' => $page + 1, 'units' => count($seen), 'updated_at' => now()]);
+                $this->manualProgress(['last_sync_fetched_total' => count($seen), 'last_sync_page_count' => $page + 1, 'last_sync_phase' => 'fetching_inventory']);
+                if (!$response['has_more']) {
+                    DB::table('telematic_sync_runs')->where('uuid', $run)->update(['status' => 'ingesting', 'updated_at' => now()]);
+                    $this->manualProgress(['last_sync_phase' => 'ingesting', 'last_sync_inventory_total' => count($seen)]);
+                    Inbox::finishRun($run);
+
+                    return;
+                }
+                $next = $response['next_cursor'];
+                if ($next === null || isset($cursors[(string) $next]) || (string) $next === (string) $cursor) {
+                    throw new \RuntimeException('Non-advancing pagination; sweep incomplete.');
+                }
+                $cursors[(string) $next] = true;
+                $cursor                  = $next;
+            }
+            throw new \RuntimeException('Maximum page count reached; sweep incomplete.');
+        } catch (\Throwable $e) {
+            DB::table('telematic_sync_runs')->where('uuid', $run)->update(['status' => 'incomplete', 'error' => $e instanceof TelematicRateLimitExceededException ? 'Rate limited; retry scheduled.' : 'Polling failed; retry scheduled. ' . class_basename($e), 'updated_at' => now()]);
+            $this->manualProgress(['last_sync_result' => 'retrying', 'last_sync_phase' => 'retrying', 'last_sync_error' => 'Polling failed; retry scheduled. ' . class_basename($e)]);
+            if ($e instanceof TelematicRateLimitExceededException && $this->job) {
+                $this->release($e->context()['retry_after'] ?? 60);
+
+                return;
+            }
+            throw $e;
+        } finally {
+            $lock->release();
+        }
+    }
+
+    private function remainingBudget(float $started): int
+    {
+        $remaining = (int) floor(60 - (microtime(true) - $started));
+        if ($remaining < 1) {
+            throw new \RuntimeException('Polling time budget exceeded; sweep incomplete.');
+        }
+
+        return $remaining;
+    }
+
+    private function manualProgress(array $attributes): void
+    {
+        if (!$this->manualJobId) {
+            return;
+        }
+        DB::transaction(function () use ($attributes) {
+            $connection = Telematic::withoutGlobalScopes()->where('uuid', $this->telematicUuid)->lockForUpdate()->first();
+            if (!$connection || !Inbox::enabled($connection) || data_get($connection->meta, 'last_sync_job_id') !== $this->manualJobId) {
+                return;
+            }
+            $connection->status = 'synchronizing';
+            $connection->meta   = array_merge($connection->meta ?? [], $attributes, ['last_sync_progress_at' => now()->toDateTimeString()]);
+            $connection->save();
+        });
+    }
+
+    public function failed(\Throwable $error): void
+    {
+        if (!$this->manualJobId) {
+            return;
+        }
+        $run = null;
+        DB::transaction(function () use ($error, &$run) {
+            $connection = Telematic::withoutGlobalScopes()->where('uuid', $this->telematicUuid)->lockForUpdate()->first();
+            if (!$connection || !Inbox::enabled($connection) || data_get($connection->meta, 'last_sync_job_id') !== $this->manualJobId) {
+                return;
+            }
+            if (data_get($connection->meta, 'last_sync_run_job_id') === $this->manualJobId) {
+                $run = data_get($connection->meta, 'last_sync_run_uuid');
+            }
+            $connection->status = 'error';
+            $connection->meta   = array_merge($connection->meta ?? [], [
+                'last_sync_result'     => 'failed', 'last_sync_phase' => 'failed',
+                'last_sync_error'      => 'Polling retries exhausted. ' . class_basename($error),
+                'last_sync_error_type' => class_basename($error), 'last_sync_failed_at' => now()->toDateTimeString(),
+            ]);
+            $connection->save();
+        });
+        // Do not lock run rows while holding the connection lock: finishRun takes
+        // those locks in the opposite order when the final delivery completes.
+        if ($run) {
+            DB::table('telematic_sync_runs')->where('uuid', $run)->where('status', 'fetching')->update(['status' => 'incomplete', 'error' => 'Polling attempt interrupted.', 'updated_at' => now()]);
+        }
+    }
+}

package/server/src/Jobs/ProcessTelematicDelivery.php

@@ -0,0 +1,176 @@
+<?php
+
+namespace Fleetbase\FleetOps\Jobs;
+
+use Fleetbase\FleetOps\Models\Telematic;
+use Fleetbase\FleetOps\Support\Telematics\TelematicService;
+use Fleetbase\FleetOps\Support\Telematics\Telemetry\Configuration;
+use Fleetbase\FleetOps\Support\Telematics\Telemetry\Inbox;
+use Fleetbase\FleetOps\Support\Telematics\Telemetry\Ingestor;
+use Illuminate\Bus\Queueable;
+use Illuminate\Contracts\Queue\ShouldBeUnique;
+use Illuminate\Contracts\Queue\ShouldQueue;
+use Illuminate\Foundation\Bus\Dispatchable;
+use Illuminate\Queue\InteractsWithQueue;
+use Illuminate\Support\Facades\Cache;
+use Illuminate\Support\Facades\Crypt;
+use Illuminate\Support\Facades\DB;
+
+class ProcessTelematicDelivery implements ShouldQueue, ShouldBeUnique
+{
+    use Dispatchable;
+    use InteractsWithQueue;
+    use Queueable;
+
+    public int $uniqueFor = 300;
+
+    public function uniqueId(): string
+    {
+        return $this->deliveryUuid;
+    }
+
+    public int $tries   = 1;
+    public int $timeout = 60;
+
+    public function __construct(public string $deliveryUuid)
+    {
+    }
+
+    public function handle(Ingestor $ingestor, TelematicService $service): void
+    {
+        $started = microtime(true);
+        $lock    = Cache::lock('telemetry:delivery:' . $this->deliveryUuid, 90);
+        if (!$lock->get()) {
+            return;
+        }
+        try {
+            $row = DB::table('telematic_deliveries')->where('uuid', $this->deliveryUuid)->first();
+            if (!$row || !in_array($row->status, ['pending', 'retry', 'processing'], true) || ($row->available_at && now()->lt($row->available_at))) {
+                return;
+            }
+            if ($row->attempts >= 5) {
+                $this->update(['status' => 'quarantined', 'failed' => max(1, $row->failed), 'error' => 'Worker retry budget exhausted; inspect and replay.']);
+                Inbox::finishRun($row->run_uuid);
+
+                return;
+            }
+            $telematic = Telematic::withoutGlobalScopes()->where('uuid', $row->telematic_uuid)->first();
+            if (!$telematic || !Inbox::enabled($telematic)) {
+                $this->update(['status' => 'quarantined', 'error' => 'Connection disabled or removed.', 'failed' => 1]);
+                Inbox::finishRun($row->run_uuid);
+
+                return;
+            }
+            $provider = Configuration::provider($telematic);
+            $options  = Configuration::options($provider);
+            if ($row->source === 'webhook' && !($options['webhooks_enabled'] ?? false)) {
+                return;
+            }
+            $this->update(['status' => 'processing', 'attempts' => $row->attempts + 1, 'available_at' => now()->addSeconds(120)]);
+            $failed       = [];
+            $failureTypes = [];
+            try {
+                $payload = json_decode(Crypt::decryptString($row->retry_payload ?? $row->payload), true, 512, JSON_THROW_ON_ERROR);
+                if ($row->retry_payload && ($payload['checkpoint_version'] ?? null) === 1) {
+                    // This envelope is internal and encrypted; the original webhook
+                    // contract was already validated before creating the checkpoint.
+                    $units        = $payload['remaining'] ?? null;
+                    $failed       = $payload['failed'] ?? null;
+                    $failureTypes = $payload['failure_types'] ?? null;
+                    foreach ([$units, $failed, $failureTypes] as $items) {
+                        if (!is_array($items) || !array_is_list($items)) {
+                            throw new \InvalidArgumentException('Invalid delivery checkpoint.');
+                        }
+                    }
+                } elseif ($row->source === 'poll') {
+                    // Polling persists the provider's inventory records, including units
+                    // that have never reported a position. Validate this internal envelope
+                    // here and let ingestion report invalid positions per unit below.
+                    if (!is_array($payload) || !array_is_list($payload) || $payload === []) {
+                        throw new \InvalidArgumentException('Expected a non-empty polling unit list.');
+                    }
+                    $units = $payload;
+                } else {
+                    // External deliveries must still pass the provider's position contract.
+                    $units = $provider->telemetryUnits($payload);
+                }
+            } catch (\Throwable) {
+                $this->update(['status' => 'quarantined', 'failed' => 1, 'error' => 'Unsupported or unreadable position payload; inspect and replay after adapter correction.']);
+                Inbox::finishRun($row->run_uuid);
+
+                return;
+            }
+            $applied      = 0;
+            $invalid      = (int) $row->invalid_count;
+            // Polled inventory legitimately includes units without a valid fix (for example,
+            // never reported). They stay counted, but only pushed samples are failures to replay.
+            $pushed       = $row->source !== 'poll';
+            $sourceDelay  = $row->source_delay_seconds;
+            $queueDelay   = max(0, now()->timestamp - \Illuminate\Support\Carbon::parse($row->received_at, 'UTC')->timestamp);
+            $checkpointAt = $started;
+            foreach ($units as $index => $unit) {
+                try {
+                    $result      = $ingestor->ingest($telematic, $provider, $unit, $service, $row->received_at, $row->source);
+                    $sourceDelay = max($sourceDelay ?? 0, data_get($result['device']->meta, 'telemetry.source_delay_seconds', 0));
+                    if ($result['invalid_position']) {
+                        $invalid++;
+                    } else {
+                        $applied++;
+                    }
+                } catch (\Throwable $e) {
+                    $failed[]       = $unit;
+                    $failureTypes[] = class_basename($e);
+                }
+                $elapsed = microtime(true);
+                $yield   = $elapsed - $started >= 40 && $index + 1 < count($units);
+                if ($yield || ($index + 1) % 10 === 0 || $elapsed - $checkpointAt >= 2) {
+                    // Persist progress independently of the worker reservation. A
+                    // restart resumes the remaining tail rather than replaying a
+                    // growing prefix until the delivery exhausts its retry budget.
+                    $this->update([
+                        'retry_payload' => Crypt::encryptString(json_encode([
+                            'checkpoint_version' => 1, 'remaining' => array_slice($units, $index + 1),
+                            'failed'             => $failed, 'failure_types' => array_values(array_unique($failureTypes)),
+                        ], JSON_THROW_ON_ERROR)),
+                        'applied'             => $row->applied + $applied, 'failed' => count($failed) + ($pushed ? $invalid : 0), 'invalid_count' => $invalid,
+                        'queue_delay_seconds' => $queueDelay, 'source_delay_seconds' => $sourceDelay,
+                        'status'              => $yield ? 'retry' : 'processing',
+                        // Cooperative continuation is not a failed attempt. Actual
+                        // crashes keep the increment persisted at the start above.
+                        'attempts'     => $yield ? $row->attempts : $row->attempts + 1,
+                        'available_at' => $yield ? now() : now()->addSeconds(120),
+                    ]);
+                    $checkpointAt = $elapsed;
+                }
+                if ($yield) {
+                    // The normal inbox drain queues the continuation after this
+                    // job releases its uniqueness lease; it uses the same queue.
+                    return;
+                }
+            }
+            $this->update(['queue_delay_seconds' => $queueDelay, 'source_delay_seconds' => $sourceDelay]);
+            if ($failed && $row->attempts < 4) {
+                $this->update([
+                    'status'  => 'retry', 'retry_payload' => Crypt::encryptString(json_encode($failed, JSON_THROW_ON_ERROR)),
+                    'applied' => $row->applied + $applied, 'failed' => count($failed) + ($pushed ? $invalid : 0), 'invalid_count' => $invalid,
+                    'error'   => 'Some units failed ingestion; retry scheduled. ' . implode(', ', array_unique($failureTypes)), 'available_at' => now()->addSeconds(15 * (2 ** $row->attempts)),
+                ]);
+            } else {
+                $this->update([
+                    'status'       => ($failed || ($pushed ? $invalid : 0)) ? 'quarantined' : 'processed',
+                    'applied'      => $row->applied + $applied, 'failed' => count($failed) + ($pushed ? $invalid : 0), 'invalid_count' => $invalid,
+                    'error'        => ($failed || ($pushed ? $invalid : 0)) ? 'Invalid positions or exhausted ingestion retries; inspect and replay.' : null,
+                    'processed_at' => now(),
+                ]);
+            }
+            Inbox::finishRun($row->run_uuid);
+        } finally {
+            $lock->release();
+        }
+    }
+
+    private function update(array $attributes): void
+    {
+        DB::table('telematic_deliveries')->where('uuid', $this->deliveryUuid)->update(array_merge($attributes, ['updated_at' => now()]));
+    }
+}