# Captain Dispatch Algorithm — Phase 1 Task List

Ordered by dependency. Every task lists scope, dependencies, files touched, test plan,
acceptance criteria and an estimate. Statuses are updated as Phase 2 progresses:
`[ ]` todo · `[~]` in progress · `[x]` done (tests green).

Decisions this list is built on (from `docs/analysis.md`): Laravel 13 + MySQL; multi-pickup
orders modelled as **one order, many pickup stops**; `FakeRoutingEngine` as the working engine
until Google keys exist; Redis installed locally (client `predis`); FCM + Laravel Reverb for
the repaint; ranking by Adjusted ETA (FR-07 deviation approved); `BATCH_REJECTED_POLICY =
rank_lower`.

**Feature folder name: `Dispatch`.** Everything new lives in `app/*/Dispatch/`,
`config/dispatch.php`, `routes/dispatch-*.php`, `tests/{Unit,Feature}/Dispatch/`,
`resources/lang/{en,ar}/dispatch.php`, following the project's repository → service →
thin-controller rules (`.claude/skills/create-laravel-feature`).

**Estimates** are engineering days (d) for one engineer including tests. Total ≈ 27 d.

**Codebase-wide skill compliance pass (2026-09-16).** Not a task on this list: the skill was
applied to every file, including those the dispatch work never wrote. `DeviceTokenData` moved
into a feature folder, `OtpService`'s cache calls moved into a new `OtpRepository`, and the
dashboard `OrderController` stopped taking a route-bound `Order` model. The `base-repository`
rule of `scripts/check-architecture.php` was narrowed to the repositories that inject a model,
with tests for both halves. What was deliberately left alone — the three outcome enums without
`label()`/`options()`, the flat `routes/<feature>.php` convention, the unused `BaseJsonService`,
and a teammate's uncommitted `DashboardStatsService` — is recorded in `docs/runbook.md` §4.1.

---

## Epic 1 — Foundations

### T1.1 Local Redis + client configuration `[x]` — 0.25 d
- **Done (2026-09-14):** Chocolatey needed an elevated shell, so a **portable Redis 8.10.1**
  (`redis-windows` msys2 build, SHA-256 verified against the GitHub release digest) was placed
  in `C:\Users\DELL\redis\Redis-8.10.1-Windows-x64-msys2` with `kapitano-local.conf`
  (`bind 127.0.0.1`, no persistence). It runs as a foreground process, not a Windows service —
  it must be started again after a reboot (runbook). `REDIS_CLIENT=predis` in `.env` and
  `.env.example`. `php artisan dispatch:redis-check` → PING, version 8.10.1, GEOADD,
  GEOSEARCH, SET NX EX all OK. `RedisCheckCommandTest` 2/2 green; Pint + checker clean.
  **Starting it:** the msys2 build reads a Windows absolute path as relative, so start it from
  its own folder: `Set-Location C:\Users\DELL\redis\Redis-8.10.1-Windows-x64-msys2;
  .\redis-server.exe kapitano-local.conf`. When it is down, `RedisCheckCommandTest` reports
  itself **skipped** — run `php artisan dispatch:redis-check` before the suite.
- **Scope:** Redis running as a Windows service (Chocolatey `redis` 8.x, which has
  `GEOSEARCH`); switch `.env` / `.env.example` to `REDIS_CLIENT=predis` (the `phpredis`
  extension is absent, `predis/predis` 3.5 is installed); a `dispatch:redis-check` artisan
  command that runs `PING`, `GEOADD`, `GEOSEARCH`, `SET NX EX` and reports.
- **Depends on:** admin rights to install the service (or a portable binary).
- **Files:** `.env.example`, `config/database.php` (no change expected),
  `app/Console/Commands/Dispatch/RedisCheckCommand.php`.
- **Tests:** integration test skipped automatically when Redis is unreachable
  (`RedisAvailable` trait) — no silent pass: the skip is reported.
- **Accept:** `php artisan dispatch:redis-check` prints OK for all four commands.

### T1.2 Schema & migrations `[x]` — 1.5 d
- **Done (2026-09-14):** 8 migrations `2026_09_14_0900xx_*` (the counter backfill lives in the
  drivers migration, the pickup backfill in its own); models `OrderPickup`,
  `OrderSuggestion`, `OrderSuggestionCandidate`, `RoutePlan`, `DriverLocationHistory`,
  `DispatchSetting` + factories; `Driver` / `Order` / `DriverAvailability` fillable, casts,
  relations. **Structural choices (no business rule changed):**
  - Status-like columns are real `enum` columns (project rule), so the enums
    `CaptainDispatchState`, `GpsFreshness`, `BatchVerdict`, `DegradedReason`,
    `RoutingEngineType`, `RoutePlanTrigger`, `DispatchSettingKey` exist from now (cases +
    labels only; their behaviour stays in T2.2 / T3.1 / T5.2 / T7.1 / T1.3) with
    `resources/lang/{en,ar}/dispatch.php`.
  - `drivers.active_orders` is backfilled from the in-progress orders and is **not fillable**
    (only the atomic assignment may change it); `idle_since` backfilled from the latest
    delivered / failed order of a free captain.
  - Every order has ≥ 1 pickup from now on: `OrderService::create` (via
    `OrderRepository::attachPickups`), `OrderFactory` (mirror unless pickups are given) and
    `OrderSeeder` write the first stop. `order_pickups.address` added (a stop needs one).
  - `route_plans.trigger` is named `trigger_type` (TRIGGER is reserved in MySQL);
    `total_meters`, `routing_engine`, `closed_at` added for the cost KPI and plan closing.
  - `orders.suggestion_id` and `drivers.current_route_plan_id` are indexed but carry **no FK
    constraint**: the child tables already cascade from them, and a constraint back would
    make a delete cascade into the row being deleted. Plans and suggestions are never deleted
    on their own.
  - Candidates store times in seconds; flags `at_store_batch`, `eta_estimated` instead of
    extra enums.
  - Non-null timestamps use `useCurrent()`: local MariaDB has
    `explicit_defaults_for_timestamp = 0`, which would otherwise add `ON UPDATE
    CURRENT_TIMESTAMP` and rewrite `computed_at` on every update (verified absent).
- **Tests:** `DispatchSchemaMigrationTest` (rollback → re-migrate on SQLite, pickup backfill
  + idempotence, counter backfill) and `DispatchModelsTest` (factories, relations, casts,
  unique `(driver_id, version)`, candidate once per list, setting key once, counter not
  mass-assignable, service / factory / seeder pickups): **13 passed, 115 assertions**
  (`--filter=Dispatch`). Full suite **274 passed, 1474 assertions**. Checker 0 errors.
  **MariaDB 10.4.32:** migrate → rollback → migrate clean; 7 orders → 7 pickups, 0
  mismatching the order columns, 12 captains, 0 counter mismatches (3 busy).
- **Scope:** all structural changes in one migration set:
  - `drivers`: `active_orders` (unsigned tiny int, default 0, indexed), `idle_since`
    (timestamp, nullable), `current_route_plan_id` (nullable FK).
  - `driver_availabilities`: `on_break` (bool, default false).
  - `orders`: `promised_at` (nullable), `customer_eta_at` (nullable), `suggestion_id`
    (nullable FK), `chosen_rank` (nullable tiny int).
  - **`order_pickups`** (new): `order_id`, `sequence` (nullable, system-optimised),
    `store_name`, `store_ref` (nullable external id), `lat`, `lng`, `ready_at` (nullable),
    `picked_up_at` (nullable). The existing `orders.pickup_lat/lng` + `pickup_address`
    become **the first pickup**; a backfill migration copies them into `order_pickups` and
    the columns stay for backward compatibility (read-only from now on).
  - `order_suggestions` + `order_suggestion_candidates` (Suggestion Log — see analysis §2).
  - `route_plans` (versioned; `driver_id`, `version`, `trigger`, `stops` JSON, `polyline`,
    `total_seconds`, `degraded`, `computed_at`, unique `(driver_id, version)`).
  - `driver_location_history` (batch-flushed GPS history; `driver_id, lat, lng, accuracy,
    speed_mps, heading, captured_at`, indexed on `(driver_id, captured_at)`).
  - `dispatch_settings` (`key` unique, `value` JSON, `updated_by`) for ✱ keys.
- **Depends on:** —
- **Files:** `database/migrations/2026_09_14_*.php` (×8), models `OrderPickup`,
  `OrderSuggestion`, `OrderSuggestionCandidate`, `RoutePlan`, `DriverLocationHistory`,
  `DispatchSetting`; `Driver`, `Order`, `DriverAvailability` fillable/casts/relations;
  factories for each new model.
- **Tests:** migrate → rollback → migrate on MySQL and SQLite; backfill test: an order with
  legacy pickup columns gets exactly one `order_pickups` row.
- **Accept:** `php artisan migrate` clean both ways; all existing 200+ tests still green.

### T1.3 Config service (`DispatchSettings`) `[x]` — 0.75 d
- **Done (2026-09-14):** `config/dispatch.php` (all 17 analysis §4 keys, env-backed, plus
  `settings_cache_ttl_s` 60 and `editable_bounds`); `DispatchSettings` (typed getter per
  key, `overview()`, `effective()`, `applyOverrides()`); `DispatchSettingRepository`
  (untagged `Cache::remember` — the local `file` / `database` stores cannot tag; forgotten
  after the write commits); `GET /api/dashboard/dispatch/settings` (`dispatch.view`) and
  `PUT` (`dispatch.settings`; null resets a key; at least one editable key required);
  `BatchRejectedPolicy` enum; `AdminPermission` + `RoleSeeder` (operations-manager: both,
  support: view); lang en/ar; OpenAPI; `.env.example` `DISPATCH_*` block.
  **Choices to confirm:** dashboard bounds handoff buffers 0–15 min, batch detour 0–20 min
  (config, not the algorithm doc); GET needs only `dispatch.view`.
- **Checker rule `dispatch-settings`:** numeric tokens in `app/Services/Dispatch` (and, since
  2026-09-15, `app/Repositories/Dispatch`) equal to a
  number in `config/dispatch.php` are errors (comments / strings ignored; `DispatchSettings`
  exempt; unit literals 0, 1, 60, 1000 allowed; `@dispatch-literal` opts a line out).
  Verified on a fixture: flagged `2`, `7`, `1.3`; ignored the comment, `0`, `60`, the
  opted-out `30`, the string and the exempt file. ⚠ `.claude/` is gitignored, so T1.5 must
  un-ignore the checker (or vendor it) for CI to run it.
- **Tests:** `DispatchSettingsApiTest` **11 passed, 72 assertions** (12 / 80 after the skill review added the missing-headers test) (config defaults, live
  config, DB override wins, 60 s cache + travel + invalidation on PUT, GET body, override
  + reset, numeric string, out-of-range / non-numeric 422, nothing editable 422, 403 per
  permission, 401). Full suite **285 passed, 1548 assertions**; checker 0 errors;
  `l5-swagger:generate` OK. Local smoke on MariaDB + `file` cache: override 6 → 6.5 →
  reset 6, table left empty.
- **Scope:** `config/dispatch.php` with every key from analysis §4 (env-backed);
  `DispatchSettings` service that reads config and overlays the `dispatch_settings` table
  for ✱ keys (`HANDOFF_BUFFER_*`, `MAX_BATCH_DETOUR_MIN`), cached 60 s; dashboard endpoints
  `GET/PUT /api/dashboard/dispatch/settings` (permission `dispatch.settings`); validation
  bounds per key. **No business value is read anywhere except through this service** — the
  architecture checker gets a new rule that greps `app/Services/Dispatch` for numeric
  literals matching the config defaults.
- **Depends on:** T1.2.
- **Files:** `config/dispatch.php`, `app/Services/Dispatch/DispatchSettings.php`,
  `app/Repositories/Dispatch/DispatchSettingRepository{,Interface}.php`,
  `app/Http/Controllers/Dashboard/Dispatch/DispatchSettingController.php`,
  `app/Http/Requests/Dashboard/Dispatch/UpdateDispatchSettingsRequest.php`,
  `routes/dispatch-management.php`, `AdminPermission` (+`dispatch.view`,
  `dispatch.settings`), `RoleSeeder`, lang files, `.claude/.../check-architecture.php`.
- **Tests:** defaults resolve from config; DB override wins; invalid value → 422; permission
  → 403; cache invalidated on update.
- **Accept:** every key in analysis §4 resolves through `DispatchSettings`; checker passes.

### T1.4 Seed data & factories for dispatch scenarios `[x]` — 0.75 d
- **Done (2026-09-14):** `DispatchScenarioSeeder` — Store A (King Fahd Road) with C1 idle GPS
  1.5 km, C2 busy drop-off 4.0 km (GPS 4.5 km past it), C3 busy drop-off 0.5 km, C4 full at
  0.8 km, plus fixtures C5 idle stale GPS (240 s), C6 idle aging GPS (120 s), C7 on a break,
  C8 offline; orders to dispatch `ORD-990001` (Store A, COD, promised +45 min) and
  `ORD-990002` (Store A + Store B 1.2 km away, prepaid, promised +60 min). Points are placed
  by km + bearing on the same sphere `DistanceService` measures, so the distances measure back
  exactly. Keyed on phone / order number / (order, sequence): re-seeding **resets** the
  scenario (orders back to pending, counters recomputed). Scenario order numbers (`ORD-9801xx`
  carried, `ORD-99000x` to dispatch) keep the next real number (`ORD-990003`) clear of them.
  Not part of `DatabaseSeeder` — run with `--class=DispatchScenarioSeeder`.
  **Fixed 2026-09-15:** a re-seed also clears the delivery / failure / item-count fields and
  deletes the timeline and suggestion rows of the scenario orders (before, a delivered demo
  order went back to pending with its old `delivered_at`).
  `DriverFactory`: `idle()`, `busy($dropoff)`, `full($dropoffs)` (capacity from config),
  `onBreak()`, `offline()`, `withGps($lat, $lng, $ageSeconds)`; `OrderFactory`:
  `withPickups([...])`.
- **Found for T5.1 (not changed):** v2.1 §21 computes C2 = 12 + **4** + 9 = 25 and C3 = 2 +
  **4** + 3 = 9 with a flat 4-minute handoff, while the configured buffers are prepaid 3 /
  COD 5. With COD 5, C3 = 10 — and 8 vs 9 (or 10) is inside the 2-minute tie band either way.
  T5.1 / T5.4 tests will reproduce §21 by overriding the buffer to 4 and must settle how a
  tie between an idle and a busy captain is broken (busy captains have no `idle_since`).
- **Tests:** `DispatchFactoryStatesTest` (6), `DispatchScenarioSeederTest` (4: geometry,
  states + counter = in-progress orders for every captain, pickups in visiting order, re-seed
  resets), `DatabaseSeederTest` + scenario on top of the demo data (next number
  `ORD-990003`): **13 passed, 85 assertions**. Full suite **296 passed, 1620 assertions**;
  checker 0 errors. MariaDB: seeded twice → identical counts (drivers 20, availabilities 11,
  locations 11, orders 13, pickups 14).
- **Scope:** `DispatchScenarioSeeder` building the v2.1 §17–23 example: one store, C1 idle
  1.5 km, C2 busy 4 km, C3 busy 0.5 km, C4 full; plus a multi-pickup order (2 vendors); GPS
  fixtures fresh/aging/stale; `Driver` factory states `idle()`, `busy()`, `full()`,
  `onBreak()`, `withGps($lat,$lng,$ageSeconds)`; `Order` factory `withPickups([...])`.
- **Depends on:** T1.2.
- **Files:** `database/seeders/DispatchScenarioSeeder.php`, factories.
- **Tests:** `DatabaseSeederTest` extended.
- **Accept:** `php artisan db:seed --class=DispatchScenarioSeeder` idempotent.

### T1.5 CI pipeline skeleton `[x]` — 0.5 d (pipeline run pending the first push)
- **Done (2026-09-14), with approved changes:** the remote is **GitLab**, so the pipeline is
  `.gitlab-ci.yml`, not GitHub Actions: `lint` (`pint --test`, architecture checker) and `test`
  (`php:8.4-cli` + `exif gd intl pcov pdo_mysql zip`, services `mysql:8.0` / `redis:7-alpine`,
  `dispatch:redis-check`, every suite in one PHPUnit run with JUnit + Clover, then
  `scripts/check-coverage.php` failing under 80 % on `app/Services/Dispatch`). Validated by
  parsing it with symfony/yaml (jobs, stages, coverage regex) — it has **not run on GitLab yet**
  because nothing is pushed.
  - The checker moved to the tracked **`scripts/check-architecture.php`**; the `.claude` skill
    script forwards to it.
  - `phpunit.xml`: `E2E` suite on `tests/Feature/Dispatch/E2E` (excluded from `Feature`;
    empty until T9.1, so `--testsuite=E2E` alone says "No tests found"), `DB_CONCURRENCY_*`
    defaults; `config/database.php`: `mysql_concurrency` connection for T6.2.
  - Pint was not clean on 55 older files: formatted in its own commit
    `77a1856 style: apply Pint to existing files`, so `lint` can block. The dispatch work so far
    is commit `d66ba81`.
  - `docs/runbook.md` started: local services (Redis start), local checks, the CI stages and
    what fails them.
- **Tests:** `CheckCoverageScriptTest` (4) and `ArchitectureCheckScriptTest` (2, locks the
  `dispatch-settings` rule): **6 passed, 17 assertions**. Full suite **302 passed, 1637
  assertions**, none skipped; `pint --test` clean on the whole repo; checker 0 errors from
  both entry points.
- **Found:** two full runs hung while another PHP test run was going at the same time; alone,
  the suite finishes in 65–82 s. Runbook says to run one suite at a time.
- **Scope:** `.github/workflows/ci.yml`: PHP 8.4, MySQL 8 and Redis 7 services, composer
  install, `pint --test`, architecture checker, then `php artisan test` in three suites
  (`--testsuite=Unit`, `Feature`, `E2E`); coverage report on `app/Services/Dispatch` with
  PCOV, failing under 80 %. `phpunit.xml` gains the `E2E` suite and a MySQL connection for
  the concurrency test.
- **Depends on:** T1.1.
- **Files:** `.github/workflows/ci.yml`, `phpunit.xml`, `composer.json` (`pcov` dev dep
  note), `docs/runbook.md` (CI section).
- **Tests:** the workflow itself runs on push.
- **Accept:** green pipeline on the branch with the existing suite; red suite blocks.

---

## Epic 2 — Location layer

### T2.1 GPS ingestion endpoint (adaptive ping contract) `[x]` — 1 d
- **Done (2026-09-14):** `POST /api/driver/location` accepts `speed_mps` (0–100) and `heading`
  (0–359) and answers `speed_mps`, `accepted` and `next_ping_seconds`; each ping upserts
  `driver_locations` and writes Redis — `captains_live` GEO (member = captain id) and the hash
  `captain:{id}:gps` (lat, lng, accuracy, speed_mps, heading, captured_at unix). New:
  `RedisGateway` (raw commands + the app's key prefix, same for predis and phpredis),
  `GeoIndex` (add / remove / position / search), `CaptainGpsStore` (record / latest / forget),
  `AdaptivePingPolicy`. The Redis classes are data access, so they live in
  `app/Repositories/Dispatch/` (moved there from `app/Services/Dispatch/Geo` after the skill
  review; see runbook §4); the policy is in `app/Services/Dispatch/`.
  `POST /api/driver/availability` accepts `on_break` (omitted = unchanged;
  going offline ends it and removes the captain from `captains_live`). Contract in
  `docs/api.md`; OpenAPI updated.
  **Choices to confirm (config, not in the algorithm doc):** `ping_moving_s` 8 and
  `ping_stationary_s` 45 (v2.1 ranges 5–10 / 30–60); `moving_speed_mps` **2 m/s** (the doc does
  not define "moving"). **Behaviour added:** without a reported speed it is derived from the
  previous point; a late ping captured before the stored point answers `accepted: false` and
  writes nothing; a future `captured_at` counts as now; Redis failures are reported, never
  returned to the app (the SQL row is still written).
  Pushing pings onto a Redis list for the SQL history flush is left to T2.3.
  **Fixed 2026-09-15:** a `captured_at` sent with another offset (e.g. UTC `…Z`) is converted
  to the application time zone (Asia/Damascus) before it is stored or compared — it used to be
  saved 3 hours off, which would have broken the late-ping check and GPS freshness;
  `CaptainGpsStore::latest()` now answers in the application time zone too.
- **Tests:** `GpsIngestionApiTest` (6: Redis + SQL in the request, interval follows speed and
  config, derived speed, late ping ignored, future time clamped, break / offline vs the live
  map), `GeoIndexTest` (3: radius search nearest first, move / remove, key prefix),
  `AdaptivePingPolicyTest` (5), `DriverPresenceApiTest` (+4: validation, break, 401, Redis
  down still stores and reports; +1 missing-headers test from the skill review). Redis tests run on **database 15** (`REDIS_DB` in
  `phpunit.xml`) via `Tests\Concerns\InteractsWithDispatchRedis`, skipping visibly when Redis
  is down. T2.1 set **33 passed**; full suite **321 passed, 1729 assertions** (323 after the skill review), none skipped;
  checker 0 errors; `l5-swagger:generate` OK.
- **Scope:** extend `POST /api/driver/location` to accept `speed_mps`, `heading`,
  `captured_at`; response carries `next_ping_seconds` (moving 5–10 s, stationary 30–60 s,
  from config `PING_MOVING_S` / `PING_STATIONARY_S`); writes go to Redis GEO
  (`captains_live`) + a Redis hash per captain (`captain:{id}:gps` → lat, lng, accuracy,
  speed, captured_at); SQL `driver_locations` still upserted (existing readers) but no longer
  the hot path; also `POST /api/driver/availability` gains `on_break`.
- **Depends on:** T1.1, T1.2.
- **Files:** `app/Repositories/Dispatch/GeoIndex.php` (Redis GEO wrapper: add / search /
  remove / position), `app/Repositories/Dispatch/CaptainGpsStore.php`,
  `app/Repositories/Dispatch/RedisGateway.php`, `app/Services/Dispatch/AdaptivePingPolicy.php`,
  `DriverLocationService`, `DriverPresenceController`, requests/resources/DTOs, OpenAPI.
- **Tests:** integration (Redis): ping → `GEOPOS` returns it; `next_ping_seconds` follows
  the speed; feature: validation, 401.
- **Accept:** a ping is visible in Redis and SQL within the request; contract documented in
  `docs/api.md`.

### T2.2 Effective-location set + staleness tagging `[x]` — 1 d
- **Done (2026-09-15):** `EffectiveLocationResolver` (`resolve`, `refresh`, `forget`,
  `freshness`) keeps `captains_effective`: idle → newest GPS point, busy → drop-off of the order
  **furthest along** (on the way → picked up → assigned, oldest first; read from the orders, not
  from `active_orders`, which T6.1 will maintain); a busy captain whose order has no drop-off
  coordinates is placed at their GPS; offline, or idle with no GPS → off the map (a busy captain is placed at the drop-off even
  before any GPS point, tagged `missing`); a stale point stays on
  the map (T3.2 lists stale captains separately). Re-pointed on every accepted ping
  (`DriverLocationService`), on going online / offline (`DriverAvailabilityService`), and on
  every order status change: `OrderService::transition()` now fires `OrderStatusChanged`
  (after commit), handled by `Listeners\Dispatch\RefreshCaptainEffectiveLocation` — run
  synchronously, best effort (Redis failure reported, the order still moves; exception to the
  skill's queued-listener rule recorded in runbook §4). New: `EffectiveLocationSource` enum
  (gps / dropoff, en + ar labels), `EffectiveLocationData` DTO,
  `OrderRepository::currentOrderFor()`, `DriverAvailabilityRepository::isOnline()`,
  `GpsFreshness::forAge()` + `isRankable()`.
  **Boundary follows v2.1 §27, not the test plan above:** fresh < 90 s, aging 90–180 s
  **inclusive** ("1.5–3 min"), stale > 180 s ("> 3 min") — so 180 s is aging, 181 s stale (the
  plan's "180 s stale" contradicted the document).
- **Tests:** `GpsFreshnessTest` (2: every boundary incl. 89.9 / 90 / 180 / 180.1, rankable);
  `EffectiveLocationTest` (8 — Test Group 3: idle follows GPS; busy stays at the drop-off while
  GPS moves, through pickup and on the way, back to GPS when delivered; missing GPS off the map;
  freshness 0 / 89 / 90 / 180 / 181 / 600 s with a stale captain kept on the map; offline /
  online; order without drop-off → GPS; two orders → the one furthest along; Redis down while
  an order moves → reported, order still assigned). Order / presence / ingestion tests: 69
  passed. Full suite **335 passed, 1841 assertions**, none skipped; checker 0 errors.
- **Scope:** `captains_effective` GEO set maintained by `EffectiveLocationResolver`:
  Idle → GPS (updated on each ping), Busy → current order's **drop-off** (updated on
  assignment / stop completion / plan change); `GpsFreshness` enum (`fresh < 1.5 min`,
  `aging 1.5–3`, `stale > 3`, `missing`) computed from `captured_at`.
- **Depends on:** T2.1.
- **Files:** `app/Services/Dispatch/EffectiveLocationResolver.php`,
  `app/Enums/Dispatch/GpsFreshness.php`, listeners on `OrderAssigned` / order-status
  events to re-point the effective location.
- **Tests:** unit: freshness boundaries (89 s fresh, 90 s aging, 180 s stale…); integration:
  idle captain's effective point follows GPS, busy captain's stays at the drop-off while
  GPS moves.
- **Accept:** Test Group 3 (Location) passes.

### T2.3 Batch flush of GPS history to SQL `[x]` — 0.5 d
- **Done (2026-09-15):** every ping — a late one too, it is a point the captain really
  reported — pushes its point (JSON) onto the Redis list `captains:gps_history`
  (`GpsHistoryBuffer::push`, best effort, no SQL on the hot path). `php artisan
  dispatch:flush-gps` (`FlushGpsHistoryCommand` → `GpsHistoryFlusher::flush`) takes up to
  `gps_history_flush_batch` (1000) points with one atomic `LPOP key count` and writes each batch
  with one insert (`DriverLocationHistoryRepository::insertMany`), looping until the list is
  empty; points of a captain who no longer exists are dropped and counted; a failed insert puts
  the batch back at the front of the list in its original order and exits 1. `--prune` deletes
  history older than `gps_history_retention_days` in chunks (0 keeps everything). Scheduled in
  `routes/console.php` (the project's first scheduled tasks): flush `everyThirtySeconds()
  ->withoutOverlapping()`, prune `dailyAt('03:00')`. Runbook §1 "Scheduler" explains
  `schedule:work` / cron and that unflushed points are lost if the local Redis restarts.
  **To confirm:** retention **30 days** (the design document sets none).
  **Hardened after the explanation review (2026-09-15):** a batch size of 0 counts as 1 (it
  used to loop forever); the failure message no longer claims points were put back when Redis
  failed before taking any; each Redis write of a ping and of going offline runs on its own
  (one failing never skips the others); new migration `2026_09_15_090000` indexes
  `driver_location_history.captured_at` so the prune does not scan the table. Known limits:
  a batch taken from Redis is lost if the process dies before the insert, and an unreadable
  list entry is skipped without a count.
- **Tests:** `GpsHistoryFlushTest` (8: 50 queued pings → 50 rows and an empty list; empty buffer
  twice; 45 points with a batch of 20; API pings, a late one included, reach history rows with
  their values and the UTC capture time; unknown captain dropped; insert failure → points back in
  order; prune with retention off, then on with a chunk of 1; flush every 30 s and prune daily at
  03:00 in the schedule). Related tests 44 passed; full suite **343 passed, 1891 assertions**;
  checker 0 errors. **MariaDB smoke:** one point flushed (07:00Z stored as 10:00 local, the same
  moment), prune SQL ran, smoke row removed; `schedule:list` shows both tasks.
- **Scope:** scheduled command `dispatch:flush-gps` every 30–60 s: drains a Redis list of
  pings into `driver_location_history` in one insert; retention config.
- **Depends on:** T2.1.
- **Files:** `app/Console/Commands/Dispatch/FlushGpsHistoryCommand.php`, `routes/console.php`.
- **Tests:** integration: 50 queued pings → 50 rows, list emptied; idempotent on empty.
- **Accept:** history grows without touching the hot path.

---

## Epic 3 — Candidate pipeline (Phase 1 of the algorithm)

### T3.1 Eligibility + capacity `[x]` — 0.75 d
- **Done (2026-09-16):** `CaptainDispatchState::for(approved, online, onBreak, activeOrders,
  maxActiveOrders)` is the rule as a pure decision (v2.1 §5.1 + §6), in this order: not allowed
  to work → `Unapproved`, off duty → `Offline`, break → `OnBreak`, then capacity — at or above
  the maximum → `Full`, 1…max−1 → `Batchable`, 0 → `Idle`. `isEligible()` is true only for idle
  and batchable, so **full is never returned**; `reason()` gives the dashboard sentence
  (en + ar, e.g. "Carrying 2 of 2 orders."). `EligibilityService::evaluate()` /
  `isEligible()` / `pool()` and `CaptainEligibilityData` (state, eligible, active_orders,
  max_active_orders, reason). SQL pre-filter `DriverRepository::eligibleForDispatch($max)`:
  approved + active + online + not on break + fewer than `$max` orders in progress, with
  `active_orders_count`, availability and location loaded — so an ineligible captain never
  reaches a Redis lookup. New reads: `DriverAvailabilityRepository::flagsFor()`,
  `OrderRepository::countInProgressFor()`. The maximum always comes from `DispatchSettings`.
  - **Orders in hand are counted from the orders**, not from `drivers.active_orders`: nothing
    maintains that column until T6.1, and the counted answer is always true. T6.1 keeps the
    column in the assignment transaction, and the two must agree from then on.
  - **Approved also means the account is switched on** (`is_active`), matching the existing
    assignment guard.
  - A captain with **no reported position is still eligible** — eligibility says nothing about
    location; the geo filter (T3.2) simply will not find them.
  - `suggestableCaptains()` / `countReadyToAssign()` (the old idle-only pool behind the
    assignment screen and the dashboard count) are **left untouched** until T5.5 replaces the
    suggestion endpoint, so the dashboard-stats feature keeps working.
- **Tests:** `CaptainDispatchStateTest` (3: the rule matrix incl. precedence and 3 orders → full,
  the maximum deciding where batchable ends, only idle/batchable eligible) and `EligibilityTest`
  (7 — Test Group 1: idle, on a break, offline, never online, pending, rejected, switched off;
  Test Group 2: 0 / 1 / 2 / 3 orders; the pool carries `active_orders_count`; the maximum comes
  from the settings; the reason text in en + ar; a captain without GPS stays eligible; the
  seeded v2.1 scenario pool is exactly C1, C2, C3, C5, C6): **10 passed, 52 assertions**. Full
  suite **355 passed, 1951 assertions**, none skipped; checker 0 errors; Pint clean.
- **Tidied after the explanation review (2026-09-16):** `flagsFor()` no longer carries the
  docblock that belongs to `isOnline()`; the `CaptainDispatchState` class comment says the rule
  now lives on the enum; `eligibleForDispatch()` uses `newQuery()->with(['availability',
  'location'])` instead of the shared `query()`, which would also eager load the vehicle no
  dispatch step reads. Left as is: the in-progress count is built twice per pool query (filter
  and `withCount`), and an over-full captain's reason reads "Carrying 3 of 2 orders."
- **Scope:** `EligibilityService::isEligible(Driver)` = approved ∧ online ∧ ¬on_break ∧
  `active_orders < MAX_ACTIVE_ORDERS`; `CaptainDispatchState` enum (idle / batchable / full
  / offline / on_break / unapproved) with a reason string for the dashboard; SQL-side
  pre-filter in `DriverRepository::eligibleForDispatch()` so ineligible captains never reach
  Redis lookups.
- **Depends on:** T1.2, T1.3.
- **Files:** `app/Services/Dispatch/EligibilityService.php`, `app/Enums/Dispatch/
  CaptainDispatchState.php`, `DriverRepository{,Interface}`.
- **Tests:** unit eligibility matrix (every combination of the four flags); Test Groups 1–2.
- **Accept:** exactly the v2.1 §5.1 rule, MAX from config, `full` never returned.

### T3.2 Geo filter with radius expansion + detour index + Top N `[x]` — 1 d
- **Done (2026-09-16):** `CandidateFinder` + `GeoPoint`, `CandidateData`, `CandidateSearchData`.
  Searches `captains_effective` around every pickup at each radius in turn, keeps a captain once
  at their nearest pickup (the anchor), intersects with the T3.1 eligibility pool, and cuts to
  Top N. `road_km_estimate` = straight-line × `detour_index`; no routing engine is touched.
  **Three rules confirmed by the product owner before coding (none guessed):**
  1. The `RoutingEngine` **interface is pulled forward from T4.1** (contract only) so the
     zero-calls guarantee is enforced by a spy from day one, not deferred.
  2. **Stale GPS sets aside only GPS-anchored captains.** A busy captain judged from their
     order's drop-off stays rankable however old their point is — the drop-off is not a GPS
     reading. The badge still shows.
  3. **Stale captains do not count toward Top N** when deciding to widen, so they never stop the
     search and shorten the dispatcher's list.
  **Deviations, recorded not hidden:** the DTO is `CandidateData`, not the list's shorthand
  `Candidate`, because every DTO in this codebase carries the `...Data` suffix. The pulled-forward
  interface returns arrays; T4.1 replaces them with the typed `MatrixResult` / `RouteResult` it
  owns. `road_km_estimate` is left unrounded: `round($km, 2)` would trip the checker's
  `dispatch-settings` rule, since `2` is the `max_active_orders` default.
  **New repository reads (queries stay in repositories):** `OrderRepository::pickupPointsFor()`
  and `currentOrdersFor()` — the latter answers for every found captain in **one** query, because
  asking per captain would be an N+1 on the hot path.
  **Worth knowing:** with the shipped Top N of 7 and only 4 rankable captains in the scenario, the
  search widens through 5 → 8 → 12 km and returns the 4 it has; a short list is an answer, and
  `search_expanded` + `radius_km` say so. Freshness still costs one Redis read per candidate.
- **Tests:** `CandidateFinderTest` (13 — ranking order; the ineligible C4/C7/C8 never appear;
  aging ranked and stale set aside; a busy captain with stale GPS still ranked from the drop-off;
  anchor = nearest pickup, verified independently against `DistanceService`; a captain near two
  pickups listed once; the radius widening; a stale captain not stopping it; the Top N cut; the
  detour arithmetic; the routing spy at **0 calls**; an order with nowhere to search → 422).
  Dispatch suite **83 passed, 536 assertions**; Order suite **46 passed, 293 assertions**;
  checker 0 errors; Pint clean.
- **Accept met in full (2026-09-16):** routing spy **0 calls**, and a median of **43.7 ms** for 500
  captains (min 39.6, max 56.3 over nine timed runs) against the 100 ms budget.
  The first honest measurement was **624.5 ms** — six times over. Three fixes, each one measured
  before and after rather than guessed at:
  1. `CaptainGpsStore::capturedAtTimestamps()` asks Redis **once** for every capture time, through
     a small Lua script, instead of one `HMGET` per captain: **183.9 ms → 15.5 ms**. A script
     rather than a pipeline because the gateway sends raw commands (the GEO commands need that)
     and raw commands cannot be pipelined. It answers with Unix timestamps, not dates: building
     500 `CarbonImmutable` objects cost more than the round trip that fetched them, so only the
     captains that survive the Top N cut are turned into dates.
  2. `DriverRepository::eligibleForDispatchAmong()` asks only about the captains the radius
     already found, selects three columns, and returns **plain rows** rather than hydrated
     `Driver` models: **92.8 ms → 7.8 ms**. Deviation recorded in runbook §4.
  3. Candidates stay arrays of scalars until the Top N cut; only the survivors (and the stale
     ones that are reported) become `CandidateData`.
  `CandidateFinder` no longer depends on `EffectiveLocationResolver`: freshness comes straight
  from `GpsFreshness::forAge()` — the same enum the resolver's own one-line wrapper delegates to,
  so the rule still lives in exactly one place — with the thresholds read once per pass instead of
  once per captain.
  **The benchmark judges the median of nine runs, not a single one.** Measured back to back on
  this machine the same code came in at 90 ms and at 350 ms; a one-sample timing test reports the
  machine's mood, not the algorithm's cost. Every sample is printed, with a per-phase breakdown,
  so a future regression says which step grew. What is left is dominated by parsing 500 GEOSEARCH
  rows (17.6 ms) and the script round trip (15.5 ms).
- **Scope:** `CandidateFinder`: for the order's pickups, `GEOSEARCH captains_effective`
  BYRADIUS 5 km around **each pickup** (K ≤ 3 searches, union by captain, keep the nearest
  pickup per captain = ranking anchor); expand 8 → 12 km until ≥ `TOP_N` eligible
  candidates or max reached (`search_expanded` flag + which radius); straight-line ×
  `DETOUR_INDEX`; take Top N. Stale-GPS captains are set aside in `excluded_stale[]`.
  **No routing call in this class** — enforced by a unit test that binds a
  `RoutingEngine` spy and asserts zero calls.
- **Depends on:** T2.2, T3.1.
- **Files:** `app/Services/Dispatch/CandidateFinder.php`, `app/DTOs/Dispatch/{GeoPoint,
  Candidate}.php`, `DistanceService` (reused for the detour math).
- **Tests:** unit: haversine × detour index; radius expansion (0 at 5 km → found at 8);
  Top N cut; anchor = nearest pickup; integration with Redis GEO.
- **Accept:** ≤ 100 ms for 500 captains in the integration benchmark; routing spy = 0 calls.

---

## Epic 4 — Routing layer

### T4.1 `RoutingEngine` contract + `FakeRoutingEngine` `[x]` — 1 d
- **Done (2026-09-16):** the contract declared in T3.2 grew up into its full signature —
  `getMatrix(GeoPoint[], GeoPoint[], ?MatrixOptions): MatrixResult` and
  `getRoute(RouteStop[], ?RouteOptions): RouteResult` — and `FakeRoutingEngine` implements it with
  no network anywhere. Road time is the straight line × `detour_index`, driven at
  `fake_routing_speed_kmh`; distance comes back untouched by penalties, because a slow road is not
  a longer one. `AppServiceProvider` resolves the interface from `dispatch.routing_engine`, and
  asking for `google` or `osrm` **throws** rather than quietly falling back to the simulation —
  a production deploy must not ship fake road times by accident. The T3.2 spy was migrated to the
  new signature in the same change, so the zero-calls guarantee never lapsed.
  **Why the fake is more than a distance calculator:** if it were, every test would agree that the
  nearest captain is the fastest, which is the exact belief the algorithm exists to challenge. The
  per-origin penalty table multiplies the time out of a point, so a test can make the closest
  captain the slow one — there is a test that does precisely that and checks the metres are
  unchanged.
  **Beyond the task's file list, and why:** `RoutingFailureMode` and `MatrixElementStatus` enums
  (a recurring fixed set belongs in an enum — neither gets `label()`/`options()`, since both are
  internal and never cast or rendered, following the compliance pass), and
  `RoutingFailedException`, deliberately **not** an `ApiException`: a maps outage is not the
  client's mistake and must never become the dispatcher's error page. T4.4 catches it and degrades
  the ranking.
  **Two smaller judgements:** `fake_routing_speed_kmh` and `fake_routing_latency_ms` are new config
  keys but are kept **out of** `DispatchSettings::effective()` — they describe the simulation, not
  the business, and the settings screen should not offer a dispatcher a number that means nothing
  once the Google keys arrive. `PolylineEncoder::PRECISION = 5` carries the checker's
  `@dispatch-literal` escape: five decimals is the polyline format's own precision, and it only
  collides with `radius_steps_km` by coincidence.
  A partial matrix answers `null` for the cells it lost, never `0` — a captain nobody could
  measure must not rank as the nearest.
- **Tests:** `FakeRoutingEngineTest` (13 — the container resolves the fake; identical answers on
  repeated calls; further is slower; the plain simulation is symmetric; speed and detour come from
  the settings; a penalty makes the closest origin the slowest while its distance stays put; a
  penalty table loads from `tests/Fixtures/Dispatch/routing-penalties.json` — the fixture
  convention this task establishes; a route is driven in the order given with legs that sum to the
  total; the shape survives a polyline round trip to within 1e-5; a refusal and a timeout are
  raised with their mode; a partial answer reports itself incomplete and hides nothing; a complete
  one says so). Dispatch suite **97 passed, 576 assertions**; checker 0 errors; Pint clean. The
  T3.2 benchmark still holds at a 49.0 ms median.
- **Scope:** interface `getMatrix(GeoPoint[] $origins, GeoPoint[] $destinations, MatrixOptions)`
  → `MatrixResult` (per element: seconds, meters, status) and `getRoute(RouteStop[] $stops,
  RouteOptions)` → `RouteResult` (polyline, per-leg seconds/meters, total). `FakeRoutingEngine`
  is deterministic: road time = haversine × configurable detour (1.3) at 30 km/h, plus a
  per-origin "road penalty" table loadable from a fixture so tests can make "closest ≠
  fastest"; polyline = straight segments encoded (Google polyline algorithm); simulated
  latency and failure modes (`timeout`, `error`, `partial`) switchable per test.
- **Depends on:** T1.3.
- **Files:** `app/Services/Dispatch/Routing/{RoutingEngine,MatrixResult,RouteResult,
  FakeRoutingEngine,PolylineEncoder}.php`, `app/DTOs/Dispatch/{RouteStop,MatrixOptions,
  RouteOptions}.php`.
- **Tests:** unit: determinism (same input → identical output), symmetry, penalty table,
  polyline round-trip, failure modes.
- **Accept:** every later test runs on this engine with no network.

### T4.2 `GoogleRoutesEngine` + recorded fixtures `[x]` — 1.5 d
- **Done (2026-09-16):** `GoogleRoutesEngine` behind the same contract the simulation implements.
  `computeRouteMatrix` prices a whole shortlist in one call (`TRAFFIC_UNAWARE` — the elements are
  N×K and traffic-aware ones are billed at a higher rate each); `computeRoutes` draws the single
  road the chosen captain drives (`TRAFFIC_AWARE`, because that number is promised to a customer).
  Laravel `Http` with the `routing_timeout_ms` deadline. `AppServiceProvider` already resolved the
  engine from config, so switching to Google is `DISPATCH_GOOGLE_MAPS_KEY` plus
  `DISPATCH_ROUTING_ENGINE=google` and no code change.
  **Cost discipline is enforced by tests, not comments.** Two-wheeler routing and toll fields are
  never requested (cost report §12), and a test asserts they appear in neither the body nor the
  field mask of any call. The masks name only the fields that are read — a mask that quietly grows
  shows up on an invoice rather than in a failing feature, so the exact string is asserted.
  **Deviations, both deliberate:**
  1. The matrix field mask adds **`condition`** to the five fields this list named. Google reports
     an unroutable pair as `condition: ROUTE_NOT_FOUND` with an empty `status`, so without it a
     pair that genuinely has no route is hard to tell from a usable one. Same billing tier.
  2. Fixtures live in `tests/Fixtures/Dispatch/google/` (capital D), not the `dispatch/` this list
     wrote, matching the directory T4.1 established rather than creating a near-duplicate.
  3. `routes.optimizedIntermediateWaypointIndex` joins the route mask **only** when the caller
     allows reordering. Without it Google would reorder the stops and never say how, and the plan
     would announce one sequence while its own polyline drove another.
  **Where the key lives:** `config/dispatch.php` under `google.key`, as this list specified, rather
  than `config/services.php` where the project keeps other third-party credentials — it keeps
  `DispatchSettings` the one door to everything the algorithm runs on. It is deliberately **not**
  in `effective()`: that array is serialised into the dashboard settings response, and a maps key
  does not belong in an HTTP payload.
  **Nothing in the suite calls Google.** `phpunit.xml` forces `RUN_REAL_MAPS=0`, so a key left in a
  developer's environment cannot turn the suite into billed traffic. The single test that calls the
  real API skips unless a developer sets it to 1 by hand with a real key.
- **Tests:** `GoogleRoutesEngineTest` (13 — the container resolves it from config; the matrix mask,
  travel mode, preference and waypoint shape; no two-wheeler or toll anywhere; matrix parsing; an
  unroutable cell reported unavailable rather than zero; the route mask, traffic preference and
  encoding, with no reordering asked for unless allowed; reordering requested and read back;
  traffic-aware matrix on request; a call that never answers → `Timeout`; a refusal → `Error`; no
  key → `Error` with nothing sent; a route needs two stops; and the real call, skipped).
  Dispatch suite **110 tests, 108 passed, 1 skipped (the real-maps call)**; checker 0 errors; Pint
  clean.
- **One honest caveat:** the T3.2 benchmark failed in that combined run at a 121 ms median and
  passed at 93.6 ms when run alone. Nothing in T4.2 touches the geo filter's path — the raw
  `GEOSEARCH` and the Lua `EVAL` both slowed by the same factor, which no code here can cause — so
  this is the machine, not a regression. It does mean the 100 ms budget now has little headroom on
  a loaded development machine. See the runbook: run it alone.
- **Scope:** Routes API `computeRouteMatrix` (POST, `X-Goog-FieldMask:
  originIndex,destinationIndex,duration,distanceMeters,status`, `travelMode: DRIVE`,
  `routingPreference: TRAFFIC_UNAWARE`) and `computeRoutes` with `intermediates`,
  `TRAFFIC_AWARE`, `optimizeWaypointOrder` only when precedence allows, field mask limited
  to `routes.polyline.encodedPolyline, routes.legs.duration, routes.legs.distanceMeters,
  routes.duration`. Uses Laravel `Http` with the `ROUTING_TIMEOUT_MS` timeout. Real calls
  only behind `RUN_REAL_MAPS=1`; otherwise `Http::fake()` with recorded JSON fixtures.
  Two-wheel routing and toll fields explicitly forbidden (cost trap, cost report §12).
- **Bug found and fixed on first contact with the real API (2026-09-21).** `computeRoutes`
  answered **400 INVALID_ARGUMENT** — `Unknown name "waypoint" at 'origin'`. The two endpoints of
  the same API disagree about the shape of a point: `computeRouteMatrix` wraps it
  (`origins: [{waypoint: {location: …}}]`) while for `computeRoutes` the origin, destination and
  each intermediate **are** waypoints. One helper was used for both, so **every route call would
  have failed on the first day with a real key**.
  The simulation never reads the payload, and the engine test asserted the field mask,
  `travelMode` and the intermediates count — but not the shape of `origin`. Both shapes are now
  asserted explicitly. A test double that never validates its input cannot catch a contract error;
  only a real call finds these.
- **`ROUTING_TIMEOUT_MS = 1000` is too short for a cold call.** The first attempt failed with
  `cURL error 28: Resolving timed out after 1008 ms` on **both** calls, before Google was reached
  — the budget covers DNS and the TLS handshake, not just the round trip. At 15 s the same calls
  answered in 1.9 s and 5.8 s. Recorded in the runbook rather than changed, because 1000 ms is a
  value the algorithm document specifies and a warm connection may well meet it.
- **Verified against the real engine, partially.** A Maps Demo Key covers `computeRoutes` but not
  `computeRouteMatrix` (403 `BILLING_DISABLED`), so the system ran in the half-state the design
  promises: **route plans real, suggestion lists degraded and saying so**. `dispatch:demo` produced
  two plans `drawn by google`, and the stored polyline decoded to **250 points** against the
  simulation's six — the first real road geometry the deviation detector has ever had to measure
  against.
- **First evidence on the ETA constants — and a correction.** The same two Riyadh points, asked
  twice, answered **8.3 min** and **11.0 min** over an identical 5.5 km: an implied 40 km/h on one
  call and 30 km/h on the other, against the configured 30. The first reading alone looked like
  evidence that `ETA_ESTIMATE_SPEED_KMH` is pessimistic; the second withdraws it. **The spread
  between two readings of one route is wider than the distance from either to the configured
  value.** The constant should not be retuned from live route calls at all — that is what
  `dispatch:measure-speed` over real driving is for. `DETOUR_INDEX = 1.3` overstated the road
  distance on both calls (5.5 km against the simulation's 6.0 km), the one point they agree on,
  and still rests on a single pair of points.
- **Depends on:** T4.1.
- **Files:** `app/Services/Dispatch/Routing/GoogleRoutesEngine.php`,
  `tests/Fixtures/dispatch/google/*.json`, `config/dispatch.php` (`google.key`).
- **Tests:** integration against fixtures: request shape (field mask, mode, preference)
  asserted; response parsing; partial element status; timeout → exception type.
- **Accept:** switching `ROUTING_ENGINE=google` needs config only; suite green without keys.

### T4.3 Engine manager: timeout, fallback signal, `OsrmEngine` stub `[x]` — 0.5 d
- **Done (2026-09-16):** `RoutingEngineManager` is the one door the algorithm asks for road times
  through, and it keeps one promise the engines cannot: **nothing above it throws**. A timeout, a
  refusal, an engine nobody configured, a bug in a client library — all of it comes back as
  `RoutingUnavailable`, carrying the mode, the engine, the reason and how long it took. A caller
  is then written as *did I get times, or do I fall back*, which is a question with two answers
  rather than a try block someone forgets to write. A dispatcher who cannot be given the best list
  must still be given a list.
  **A partial matrix is not a failure.** It comes back as a `MatrixResult` that reports itself
  incomplete: the captains that could be measured rank properly and the rest count as unmeasured.
  Turning the whole call into a fallback would throw away good answers.
  **On the timeout, stated honestly:** PHP cannot interrupt a call that is already blocking, so
  the manager does **not** impose a deadline — claiming otherwise would be a comment the code does
  not honour. The deadline is enforced inside the engine, where the HTTP client can be told to
  stop waiting (`routing_timeout_ms`). What the manager adds is measurement: it times every call
  and marks one that came back late (`over_budget`), so a budget quietly being missed shows up in
  the metrics rather than only in a dispatcher's patience. A late answer is still returned, never
  discarded.
  **`OsrmEngine` refuses loudly.** It implements the interface so that choosing a self-hosted
  server one day is a configuration change, but until `dispatch.osrm.base_url` is set both calls
  throw `RoutingNotConfiguredException` rather than inventing road times — numbers that looked
  real would travel all the way to a customer's promised arrival. The manager still converts it
  into a fallback, so a half-finished deployment is not a dispatcher's error page.
  **Beyond the task's file list, and why:** `RoutingOperation` enum (matrix / route — a recurring
  fixed set, and the two are billed and fail differently), `RoutingCallCompleted` event, and
  `RoutingNotConfiguredException` as a named class rather than the list's shorthand
  `NotConfigured`, kept apart from `RoutingFailedException` because the two need different answers
  from a human: one is the world misbehaving, the other a deployment that was never finished.
  **The KPI event is emitted now; the metrics are not.** `RoutingCallCompleted` fires on **every**
  call, successful or not — a fallback rate needs the successes as its denominator and the maps
  cost needs the elements actually consumed, so counting only failures would answer neither.
  `DispatchMetrics`, the log channel, the Redis counters and the KPI endpoint belong to T8.1,
  which depends on T5.5 / T6.1 / T7.2. Nothing listens yet, deliberately: the event exists from
  the day the calls do, so when the metrics arrive they measure history instead of starting from
  zero. Listeners here are discovered from their `handle()` type hint and never registered by
  hand — `EventServiceProvider` says why.
  **Wiring moved:** the engine binding left `AppServiceProvider` for the new
  `DispatchServiceProvider` (registered in `bootstrap/providers.php`), which the task list asked
  for and which also keeps the dispatch work out of a file another branch edits constantly. All
  three engines now resolve, so the `default => throw` arm from T4.1 is gone.
- **Tests:** `RoutingEngineManagerTest` (11 — the configured engine is the one asked; a matrix and
  a route that work come back as results; a partial answer is still an answer; a timeout, a
  refusal and an unconfigured engine each come back as `RoutingUnavailable` with their mode rather
  than as exceptions; a call that worked and a call that failed are both reported with their
  element count and reason; a late answer is flagged `over_budget` and still returned; a prompt
  one is not flagged). Dispatch suite **121 tests, 120 passed, 1 skipped** (the real Google call);
  checker 0 errors; Pint clean. The T3.2 benchmark ran at a **37.0 ms median** on a quiet machine
  — the 121 ms failure seen during T4.2 was contention, as the per-phase breakdown showed.
- **Scope:** `RoutingEngineManager` resolves the engine from config, wraps calls with the
  timeout, converts failures into a `RoutingUnavailable` result (never an exception to the
  controller), emits the KPI event; `OsrmEngine` implements the interface but throws
  `NotConfigured` until a base URL is set.
- **Depends on:** T4.1, T4.2.
- **Files:** `app/Services/Dispatch/Routing/{RoutingEngineManager,OsrmEngine,
  RoutingUnavailable}.php`, `app/Providers/DispatchServiceProvider.php`.
- **Tests:** timeout path, error path, engine switch by config, stub throws.
- **Accept:** Test Group 5 (Routing: success / timeout / failure / partial) at manager level.

### T4.4 Suggestion cache `[x]` — 0.5 d
- **Done (2026-09-16):** `SuggestionCache` answers a shortlist's road times from Redis when the
  same pickups and the same captains were measured within `suggestion_cache_ttl_s` (75 s), so a
  reopened list, a screen refresh or a second order from the same store costs no second matrix.
  The key is the geohash of each pickup (precision 7 ≈ 150 m, so one store is one key whatever
  the fifth decimal of the order's coordinates) plus a hash of the **sorted** captain ids.
  **Decisions, each made for a reason:**
  1. **Storage lives in a repository**, `SuggestionCacheStore`, not in the service the task list
     named. Cache access belongs to repositories in this codebase — the rule the compliance pass
     enforced by moving `OtpService`'s cache calls into `OtpRepository`. The service decides the
     key and what may be kept; the store decides where it sits.
  2. **The payload is plain JSON, rebuilt into a `MatrixResult` on read.** `cache.serializable_classes`
     is `false`, so an object written to Redis would come back as an incomplete class — a bug the
     `array` cache store used in tests would never show.
  3. **Cells are stored by captain id, not by row.** A shortlist can come back in another order,
     and a matrix is addressed by position; storing positions would hand one captain another
     captain's road time on a reordered hit. A test reverses the shortlist and checks every
     captain gets their own time back.
  4. **Only complete answers are cached.** A fallback or a partial matrix is returned as usual but
     not stored, so a moment's degradation is not pinned in place for 75 seconds.
  5. **Invalidation is by captain, on every order move, not only assignment.** Each entry is
     indexed under every captain it measured; `ForgetCaptainSuggestions` listens to
     `OrderStatusChanged` and drops them all. The task list said "assignment", but a delivery
     turns a batchable captain idle just as surely, and a list describing them as busy would be
     just as wrong.
  6. **Best effort**, like every write to the live layer: with Redis down a lookup is a miss, the
     call goes to the engine, and the failure is reported rather than thrown.
  **Metrics:** `SuggestionCacheLookedUp` fires on hits and misses alike (a hit rate needs both);
  like `RoutingCallCompleted` it has no listener until T8.1.
  **Two literals escaped** for the checker, both format arithmetic that only collides with a
  setting by coincidence: `Geohash::BITS_PER_CHARACTER = 5` and `Geohash::HALVES = 2`. The
  precision itself (7, which would collide with `top_n`) is a config key,
  `suggestion_cache_geohash_precision`, kept out of `effective()` like the other tuning knobs.
  **Also fixed:** T4.3 left the Google comment in `config/dispatch.php` sitting above the `osrm`
  block, where it read as if it described OSRM; it is back above `google`.
- **Tests:** `SuggestionCacheTest` (13 — two requests for the same store and captains within the
  TTL cost **one** matrix call with identical times; a second order from the same store shares
  them; the same captains in reverse order each get their own time back; a bigger shortlist and a
  different store are misses; the TTL expiring forces a new call; an order moving through the
  real `OrderStatusChanged` event forgets its captain's lists while another captain's order does
  not; a failed call and a partial answer are not cached; hits and misses are both reported; with
  Redis down the times still come from the engine and the failure is reported; the geohash
  encoder matches the format's published reference value). Dispatch suite **134 tests, 133
  passed, 1 skipped** (the real Google call); checker 0 errors; Pint clean.
- **Scope:** cache key = order pickup geohash(es) (precision 7) + candidate-id set hash;
  TTL `SUGGESTION_CACHE_TTL_S`; stored in Redis; cache hit skips the matrix call and is
  counted in metrics; invalidated when any candidate's state changes (assignment).
- **Depends on:** T1.1, T3.2.
- **Files:** `app/Services/Dispatch/SuggestionCache.php`.
- **Tests:** hit within TTL, miss after TTL, invalidation on assignment; routing spy counts.
- **Accept:** two requests for the same store within 60 s → one matrix call.

---

## Epic 5 — Ranking & suggestion API (Phase 2 of the algorithm)

### T5.1 Adjusted ETA calculator `[x]` — 1 d
- **Done (2026-09-17):** `AdjustedEtaCalculator` gives each captain on a shortlist the time they
  could be standing at the order's store — Idle: road time from the captain; Busy: remaining
  delivery + handoff buffer + road time from their current drop-off. **One routing call per
  shortlist**, through the suggestion cache: a busy captain is already placed at their drop-off,
  so every candidate's effective location against the order's pickups answers both formulas.
  **Decisions confirmed by the product owner before coding:**
  1. **Handoff stays prepaid 3 / COD 5.** The §21 example assumes a flat 4 minutes; its test sets
     both buffers to 4 for that scenario so C1 = 8, C2 = 25, C3 = 9 match exactly, and the
     configured defaults are tested on their own. No business value changed.
  2. **The §21 leg split is derived, not quoted** — the document gives only totals. C2 = 15 min
     remaining + 4 handoff + 6 to the store; C3 = 3 + 4 + 2. Marked as derived in the test; replace
     it if the document's split differs.
  **Design choices:**
  - **The buffer follows the order the captain is carrying**, not the new one: it is the time at
    the current customer's door, spent before the captain can set off.
  - **`RemainingEtaProvider` is an interface.** `EstimatedRemainingEtaProvider` answers today —
    straight line from the captain's last position to the drop-off, × detour index, at the estimate
    speed, flagged `EtaSource::Estimated`. T7.1 adds the plan-reading implementation without
    touching the calculator. A captain who never reported a position is measured from the order's
    pickup (the whole leg), which ranks the unknown captain later, never earlier.
  - **A captain is busy when placed at a drop-off.** One whose order has no drop-off coordinates is
    placed by GPS and measured like an idle captain — there is no drop-off to route from.
  - **A missing road time is estimated, never zero.** With the engine down or a cell unusable, the
    road time is the straight-line estimate at the estimate speed and the result is `degraded`.
  **New value to confirm:** `eta_estimate_speed_kmh` = **30** (the simulation's speed, so estimate
  and simulated road time agree in development). Kept out of `effective()` like the other values
  added since T1.3, because the dashboard test pins that array.
- **Tests:** `AdjustedEtaCalculatorTest` (9 — the §21 example at 8 / 25 / 9 with every part of C3
  checked; an idle captain is road time alone; buffers are COD 5 / prepaid 3 by default; the buffer
  follows the order being carried; a mixed shortlist costs one routing call; without routing the
  road time is estimated and the list degraded; the remaining delivery never calls the routing
  engine (spy at 0); the estimate formula; a captain with no position counts the whole leg). All 9
  pass; checker 0 errors; Pint clean. Dispatch suite: 143 tests, 141 passed, 1 skipped, and **the
  T3.2 benchmark failed at 202.6 ms (107.3 ms run alone)** while four other PHP processes were
  busy — its code is byte-identical to `c95a0b7`, where it passed at 49.7 ms.
- **Scope:** `AdjustedEtaCalculator`: Idle = matrix ETA(captain → anchor pickup);
  Busy = `RemainingDeliveryEta` + `HandoffBuffer(payment_method)` + matrix ETA(drop-off →
  anchor pickup). `RemainingDeliveryEta` is read from `RemainingEtaProvider` (the captain's
  active RoutePlan: remaining leg seconds from the captain's projected position; fallback to
  haversine estimate flagged `eta_source: estimated`). **A unit test binds a routing spy and
  asserts `RemainingDeliveryEta` never calls it.**
- **Depends on:** T4.3, T1.3, T7.1 (RoutePlan read side — can start with the estimate
  fallback and wire the plan later).
- **Files:** `app/Services/Dispatch/{AdjustedEtaCalculator,RemainingEtaProvider,
  HandoffBuffer}.php`.
- **Tests:** unit: both formulas with the v2.1 §21 numbers (C1 = 8, C2 = 25, C3 = 9);
  prepaid 3 / COD 5 from settings; provider spy.
- **Accept:** numbers match the doc examples exactly.

### T5.2 Batch compatibility (DetourDelta) `[x]` — 1 d
- **Done (2026-09-17):** `BatchCompatibilityService` decides whether a busy captain can take the
  new order on top of the one they carry. Their remaining stops (the current order's uncollected
  pickups if it is still `assigned`, and its drop-off) are joined with the new order's pickups and
  drop-off; `StopSequencer` lists every visiting order that keeps each pickup before its own
  drop-off; the **shortest total route** is the best insertion; then `DetourDelta ≤
  max_batch_detour_min` and "new order delivered by `promised_at`" (no promise passes) are checked
  against it. Verdict, translated reason (en + ar, with the minutes), the judged sequence, and
  `excluded` when the verdict is a rejection under the `exclude` policy.
  **Decisions confirmed by the product owner before coding:**
  1. **One matrix per busy captain, not one route call per sequence.** The task said one
     `getRoute` per permutation; the worst case (current order not yet collected + a three-store
     new order) is 90 sequences, i.e. 90 billed calls for one captain on every suggestion. The
     captain's position and every stop go into one matrix and each sequence is summed from it. The
     comparison uses matrix times (no traffic); the route actually driven is drawn at assignment
     (T7.1).
  2. **Best insertion = shortest total route.** "Least delay to the current customer" was offered
     first and then withdrawn: "finish the current delivery first" always delays that customer by
     zero, so the detour rule could never reject anyone — and T5.1's busy formula already models
     that order.
  **Design choices:** a road time the engine did not give is estimated from distance and the check
  is `degraded` (same rule as T5.1), never zero; `detour_seconds` is floored at 0; the detour rule
  is checked before the promise, so a captain failing both reads as a detour rejection.
  **Added:** `StopKind` enum (internal, no label), `BatchCheckData` DTO,
  `OrderRepository::pendingPickupPointsFor()`, `dispatch.batch_reason.*` in en and ar.
- **Tests:** `StopSequencerTest` (3 — the three ways for a captain on the way and a one-store order;
  a drop-off never precedes its pickup; a property test over 60 random stop sets checking every
  sequence visits each stop once, respects precedence, never repeats, and that the count equals
  `n! / Π(kᵢ + 1)`). `BatchCompatibilityServiceTest` (11 — idle is not applicable and costs no
  call; a small off-line detour is accepted within 6 min and rejected at 1 min; the shortest route
  is the one judged; a missed promise is rejected; no promise always passes; `rank_lower` keeps and
  `exclude` removes; one routing call per captain; with routing down the check still answers,
  degraded; a captain still to collect keeps their pickup before their drop-off; the reason is
  translated). All 14 pass; checker 0 errors; Pint clean. Dispatch + Unit suites: **188 tests, 187
  passed, 1 skipped** (the real Google call); benchmark median 38.5 ms.
- **Scope:** `BatchCompatibilityService` for busy candidates: build current route stops +
  new order's pickups + drop-off; enumerate insertions that respect precedence (each pickup
  before its own drop-off; ≤ 3 pickups → bounded permutations); `DetourDelta = ETA(best) −
  ETA(current)` using **one** `getRoute` call per permutation candidate through the engine
  (Fake in tests); accept iff `DetourDelta ≤ MAX_BATCH_DETOUR_MIN` ∧ new order ETA ≤
  `promised_at` (null promise passes); verdict + reason text; policy `rank_lower` / `exclude`.
- **Depends on:** T4.3, T5.1.
- **Files:** `app/Services/Dispatch/{BatchCompatibilityService,StopSequencer}.php`,
  `app/Enums/Dispatch/BatchVerdict.php`.
- **Tests:** unit: both permutations computed and the cheaper chosen; accept / reject on
  each rule; precedence never violated (property test over random stop sets).
- **Accept:** E2E-13 groundwork; reasons are human-readable and translated.

### T5.3 At-store stacking detector `[x]` — 0.5 d
- **Done (2026-09-17):** `AtStoreStackingDetector::detect(Order)` returns the `at_store_batch`
  candidates for a new order: captains with an in-progress order that still has an **uncollected
  pickup within `at_store_radius_m` (100) of one of the new order's pickups**, whose drop-off is
  within `at_store_dropoff_km` (3) of the new order's drop-off, and who are still eligible
  (approved, online, not on a break, below capacity). Nearest store first, one entry per captain,
  each carrying the order they are collecting and both distances.
  **Choices, recorded:**
  - **It looks beyond the geo shortlist.** A captain carrying an order is placed on the map at that
    order's drop-off, which may be well outside the pickup radius, so the geo filter could miss the
    one captain this task exists for. The detector reads orders with an uncollected pickup
    (`OrderRepository::inProgressWithPendingPickups()`) — bounded by orders on the road right now.
  - **"Left the store" means the pickup was collected.** The match is on the pickup row's
    `picked_up_at`, which also covers the task's "or pickup not `picked_up_at`" case: a multi-store
    order still counts for a shop not yet reached, even when marked picked up at an earlier one.
  - **It does not require the captain to be standing in the shop**, as the task's wording does not:
    a captain still driving to it is going there anyway. Worth confirming.
  - **Pinning #1 and skipping the effective-location / handoff maths is the ranker's job (T5.4)**,
    which the task list gives "at-store candidate pinned #1". The detector supplies the flag and
    evidence; the "rank 1" part of this task's test plan moves to T5.4.
  **New values:** `at_store_radius_m` = 100 and `at_store_dropoff_km` = 3, the task's defaults, read
  through `DispatchSettings` and kept out of `effective()` like the other additions. Distances come
  from `DistanceService`, which rounds to 10 m — fine at a 100 m threshold, noted for tuning.
- **Tests:** `AtStoreStackingDetectorTest` (10 — same store and nearby drop-off is detected with
  its distances; collecting the order ends the match; a store 300 m away and drop-offs 4.5 km
  apart do not match; the radius comes from the settings; a captain on a break, offline, or full is
  not offered it; the new order matches on any of its stores; a multi-stop order counts for the
  store not yet reached; nearest store first, one entry per captain). All 10 pass; checker 0
  errors; Pint clean. Dispatch + Unit suites: **199 tests, 198 passed, 1 skipped** (the real Google
  call).
- **Scope:** a captain assigned an order from the **same pickup point** (within
  `AT_STORE_RADIUS_M`, default 100) who has not picked it up yet (order still `assigned`, or
  pickup not `picked_up_at`), and whose drop-off is within `AT_STORE_DROPOFF_KM` (default 3)
  of the new drop-off → ranked #1 with badge `at_store_batch`; skips effective-location
  math and the handoff buffer.
- **Depends on:** T3.1, T1.3.
- **Files:** `app/Services/Dispatch/AtStoreStackingDetector.php`.
- **Tests:** unit + feature: badge present, rank 1, not triggered once the captain left.
- **Accept:** E2E-8 groundwork.

### T5.4 Ranking + fairness tie-break `[x]` — 0.5 d
- **Done (2026-09-17):** `Ranker::rank()` turns the shortlist, the adjusted ETAs (T5.1), the batch
  verdicts (T5.2) and the at-store matches (T5.3) into the order a dispatcher sees. Four rules, in
  order: a captain the `exclude` policy rejected is dropped; an at-store captain is **pinned #1**
  with no ETA worked out; a **refused batch ranks below every captain who can take the order**,
  however fast, with its reason attached; the rest sort by adjusted ETA, and captains inside the
  tie band are ordered by who has waited longest. Ranks are numbered from 1 and the `degraded`
  flag carries through from the ETA step.
  **The tie band is measured from the fastest captain in its group, not from the previous one.**
  Chaining neighbours would make 8, 10, 12 and 14 minutes one group at a 2-minute band, so a
  captain six minutes slower would count as tied with the fastest — the task's own
  "A~B, B~C, A≁C" case. Each group is anchored on its fastest member, and a test holds that.
  **Choices:** a captain with no `idle_since` (one carrying an order) has not been waiting, so
  inside a band they keep their place behind those who have; the sort is stable, so captains the
  rules cannot separate keep the geo filter's nearest-first order; an at-store captain the geo
  filter never found is still pinned, carrying the store match alone with `candidate` and `eta`
  null for T5.5 to fill in.
  **Added:** `DriverRepository::idleSinceFor()` — one lean query for the tie-break's one column,
  plain rows, captains with no idle time left out rather than carried as nulls.
- **Tests:** `RankerTest` (12 — fastest first; a busy captain with a better adjusted ETA beats an
  idle one ("closest ≠ fastest", "busy beats idle"); the tie band orders by longest wait; a captain
  outside the band keeps their faster place; the band boundary itself is a tie and one second past
  it is not; nearness does not chain; a refused batch ranks below everyone accepted; an excluded
  captain is not shown; an at-store captain is pinned #1 with no ETA; an at-store captain outside
  the shortlist is still pinned; ranks run from 1 and `degraded` carries through; captains the
  rules cannot separate keep the filter order). All 12 pass; checker 0 errors; Pint clean.
- **Note on where it was run:** the other session had this checkout on `dev` at the time, which
  contains this branch plus their work, so the suite ran there; the commit itself was made in a
  separate worktree of `Captain-Approval-And-Authentication` so that nothing of theirs came with
  it.
- **Scope:** sort by Adjusted ETA; group candidates whose ETA differs by ≤
  `TIE_BREAK_BAND_MIN` and order the group by longest `idle_since`; batch-rejected
  candidates moved below all accepted ones (policy); at-store candidate pinned #1.
- **Depends on:** T5.1–T5.3.
- **Files:** `app/Services/Dispatch/Ranker.php`.
- **Tests:** unit: tie band boundaries, transitivity (A~B, B~C, A≁C), stable order.
- **Accept:** Test Group 4 (Ranking) incl. "closest ≠ fastest", "busy beats idle".

### T5.5 Suggestion service + endpoint + Suggestion Log `[x]` — 1.5 d
- **Done (2026-09-18):** `SuggestionService::suggest(Order)` joins T3–T5 into the one answer the
  dispatcher sees, times each phase, writes the Suggestion Log and returns `SuggestionListData`.
  `GET /api/dashboard/orders/{uuid}/captains` keeps its URL and its `orders.assign` permission;
  only the body grew. The three promises the class comment makes are the three the feature tests
  hold it to: it never fails because maps did, an empty list is an answer, and the budgets are
  measured rather than enforced.
  **`routing_elements` and `cache_hit` come from the events, not from return values.** Both are
  facts about calls made two and three layers down, and threading them back up would have meant
  changing the signature of every method in between so the top could report a number it does not
  use. Instead a per-request `DispatchCallTally` (`scoped`, so one per request) listens to the
  `RoutingCallCompleted` and `SuggestionCacheLookedUp` events that T4.3 and T4.4 already emit.
  The listeners are auto-discovered, like every other listener here.
  **The budgets are measured, never enforced.** `budget_filter_ms` (100) and
  `budget_assembly_ms` (200) are recorded next to the timings in the log so a slow phase can be
  found afterwards; nothing is abandoned for being slow, because half a list helps nobody.
  **Removed, as the task said:** `OrderService::suggestCaptains()`, `DriverSuggestionData` and
  `CaptainSuggestionResource`. `OrderService` no longer needs `DistanceService` at all, so that
  constructor dependency went with them. A compliance review then found
  `DriverRepository::suggestableCaptains()` left with no callers — it existed only for the deleted
  service — so it went too, along with its interface method. `countReadyToAssign()` still uses the
  same `readyQuery()` for the dashboard tile; its docblock now says plainly that the tile counts
  the stricter "idle only" pool while the assignment screen no longer does, so the two numbers may
  differ. **T8.1 decided it**: the tile now counts what the assignment screen offers, and the old
  idle pool is reported beside it as `idle`.
  **Also caught by that review:** `CandidateResource` emitted `gps_freshness` and `batch_verdict`
  as raw values with no `_label` beside them, unlike every other resource in the app — so the
  Arabic strings for both existed and were rendered by nothing, and a dispatcher would have read
  `rejected_detour` on screen. Both labels are now sent.
  **Left for T6.1, deliberately:** the list now offers busy captains, but `OrderService::assign()`
  still refuses them. A dispatcher can therefore be shown a name the assignment rejects with 422.
  That seam is tested and documented on both the endpoint and the OpenAPI page rather than being
  papered over here, because stacking an order onto a busy captain needs the atomic capacity
  reservation T6.1 owns, and doing it without one would let two dispatchers overfill a captain.
- **Tests:** new `SuggestionApiTest` (7 — the agreed response shape; a routing **timeout** still
  returns a ranked list flagged `ranking_degraded` with every time an estimate; a routing
  **error** is logged under its own reason; an empty list carries `no_candidates_reason` and a
  log row with `candidates_count` 0; the log row and its children match what was shown, seconds
  against minutes; each request writes exactly one log row; an admin without `orders.assign`
  gets 403 and writes nothing). `OrderAssignmentApiTest` reworked for the new shape (20, up from
  19): the busy-captain test now asserts the seam above rather than exclusion, the captains are
  placed on the Redis map the way a GPS ping places them, and a new test pins the radius rule —
  a captain 30 km out is past the widest search and the list says so. Full suite **561 tests, 560
  passed, 1 skipped** (the opt-in real Google call), 13 322 assertions; checker 0 errors; Pint
  clean. The T3.2 benchmark ran a **36.0 ms median** on the same run.
- **Note:** the fixtures in the two reworked `OrderAssignmentApiTest` cases had captains ~30 km
  from the pickup, which the old unbounded SQL query happily returned. They were moved inside the
  12 km the search reaches. The failure was the fixture meeting a real rule, not a regression.
- **Scope:** `SuggestionService::suggest(Order)` orchestrates T3–T5 with the time budget
  (eligibility+geo ≤ 100 ms, routing ≤ 1000 ms, assembly ≤ 200 ms — measured and logged);
  fallback to Phase-1 ranking with `ranking_degraded: true, degraded_reason`; persists the
  Suggestion Log; response per candidate: rank, captain, state, badge, `distance_km`,
  `road_eta_min`, `remaining_delivery_eta_min`, `handoff_buffer_min`, `adjusted_eta_min`,
  `detour_delta_min`, `batch_verdict`, `gps_freshness`, `reasons[]`; list-level:
  `radius_km`, `search_expanded`, `excluded_stale[]`, `routing_elements`, `cache_hit`,
  `suggestion_id`, phase timings. Replaces the body of the existing
  `GET /api/dashboard/orders/{uuid}/captains` (same URL and permission); the empty-list
  case answers 200 with an explicit `no_candidates` reason, never a blank screen.
- **Depends on:** T4.4, T5.4.
- **Files:** `app/Services/Dispatch/SuggestionService.php`,
  `app/Repositories/Dispatch/SuggestionRepository{,Interface}.php`,
  `app/Http/Resources/Dispatch/{SuggestionResource,CandidateResource}.php`,
  `Dashboard/Order/OrderController::captains()` → delegates, `OrderService::suggestCaptains()`
  removed, `tests/Feature/Order/OrderAssignmentApiTest.php` updated (busy captains are no
  longer excluded), OpenAPI.
- **Tests:** feature: full response shape; degraded flag on timeout; empty list reason;
  log rows written; permission 403.
- **Accept:** endpoint never 500s when the engine fails; a list shown ⇒ a log row exists.

---

## Epic 6 — Assignment

### T6.1 Atomic conditional assignment + 30 s lock `[x]` — 1 d
- **Done (2026-09-18):** `AssignmentService` takes the captain's capacity in one conditional
  `UPDATE` that also re-checks approved, active, online and off-break, so **two dispatchers
  confirming the same captain in the same instant cannot both win** — the database lets exactly
  one of them change a row. `AssignmentLock` holds the captain around it so the loser reads
  "somebody else is confirming this captain" instead of a confusing "full", and the release sits
  in a `finally` so a refused captain is free again at once rather than at the TTL.
  **The seam T5.5 opened is closed:** the list offered busy captains and the assignment refused
  them; stacking is now live up to `max_active_orders`, and `OrderAssignmentApiTest`'s
  busy-captain test asserts the assignment succeeds where it used to assert a 422.
  **409, not 422**, with the reason in `MessageDebug.reason` (`locked` / `at_capacity` /
  `not_eligible`): the dispatcher chose from a list that was true when drawn, so this is a
  conflict, not a bad request — and `locked` is worth retrying while the other two mean "ask for a
  fresh list". `AssignmentFailureReason` carries it.
  **Where the work is split:** the *move* stays in `OrderService::assignTo()` — state machine,
  timeline entry, `OrderStatusChanged` and `OrderAssigned` — because an assignment that wrote its
  own would be the one lifecycle step nothing else could observe (the effective-location listener
  among them). `AssignmentService` owns only what makes the move safe under two dispatchers.
  Capacity is released in `OrderService::transition()` on **any** terminal status, so no future
  step that ends a delivery can forget it, and inside the transaction so the counter cannot
  disagree with the status that freed it.
  **Replaced:** `OrderService::assign()`, `assignByIdentifier()` and `assertCaptainIsAssignable()`
  — the last of which asked `$driver->orders()->whereIn(...)` from inside a service, which the
  layering forbids and which no longer exists.
- **Three bugs found while building, all fixed:**
  1. **`ApiExceptionHandler::handle()` matched on `get_class($e)` — an exact match — so every
     subclass of `ApiException` fell through to the fallback and reached the client as a 500.**
     Pre-existing and latent; the new 409 was simply the first subclass to meet it. It now falls
     back to an `instanceof` scan with exact matches still winning.
  2. The first version of the failure reason asked "is this captain still eligible?" to tell
     *full* from *off-duty* — but the eligibility rule excludes full captains, so a full captain
     was reported as no longer eligible. Added `isEligibleIgnoringCapacity()`, which asks the
     question that actually discriminates.
  3. The first decrement used `GREATEST()` and `NOW()`, which are MariaDB-only and would have
     broken on the SQLite test database. Rewritten as a guarded `active_orders - 1` with a
     `> 0` condition — which is also what stops the unsigned column wrapping to 255 and locking a
     captain out of every future assignment.
- **Resolved (2026-09-19) — `dispatch:reconcile-capacity`.** The open question below was settled
  once the store feed began writing orders directly, which is exactly the door that makes the two
  numbers drift. A command compares each captain's counter with the orders they are really
  carrying, reports by default and corrects with `--fix`; the scheduler runs it hourly and every
  correction is logged at warning level with both numbers.
  **A captain being assigned at that moment is skipped, not corrected.** Between reserving the
  capacity and writing the order the counter is ahead of the orders table *on purpose*, and a naive
  reconciler would undo the reservation and hand the same capacity to a second dispatcher. The
  reconciler takes the same per-captain lock the assignment takes, so it can tell a real drift from
  an assignment in flight, and catches the skipped ones next hour. **A mutation test holds that
  line**: with the lock check removed, the mid-assignment test fails.
  **Also decided:** a correction down to zero does not reset an existing `idle_since`, or an hourly
  pass would keep restarting the clock the fairness tie-break measures and that captain would never
  come first.
  `capacityDrift()` compares in a derived table rather than a `HAVING`, because the counted column
  is a correlated subquery and SQLite refuses `HAVING` on a query that groups nothing — the tests
  run on SQLite and production on MariaDB.
- **The original open question, for the record:** capacity is reserved against the
  `drivers.active_orders` **counter**, which it must be — the reservation happens before the order
  row exists, so a subquery over `orders` would still see the old count and let two callers
  through. But `dispatchEligibleQuery()` (the suggestion list) counts **real orders**. The two
  agree while every assignment goes through this service and every ending through
  `transition()`; they would drift if the third-party order feed writes in-progress orders
  directly. A counter drifting **high** silently makes a captain un-assignable forever, which is
  worse than drifting low. Suggested answer is a `dispatch:reconcile-capacity` command rather than
  changing what "busy" means — **awaiting a decision, nothing changed.**
- **Scope:** `AssignmentService::assign(Order, Driver, Admin, ?suggestionId, ?rank)`:
  Redis `SET dispatch:lock:captain:{id} NX EX 30` (`AssignmentLock`); revalidate; single
  conditional `UPDATE drivers SET active_orders = active_orders + 1 WHERE id = ? AND
  active_orders < ? AND … online/approved` (joined through availability); 0 rows →
  `AssignmentFailed` (409, reason) and the dispatcher is told to refresh; same transaction:
  order → assigned, history row, `orders.suggestion_id/chosen_rank`, `idle_since` cleared;
  lock released in `finally`; `OrderAssigned` dispatched after commit; decrement on
  `delivered` / `delivery_failed` (`OrderService::transition`). Replaces
  `OrderService::assign()` / `assertCaptainIsAssignable()`; `PATCH …/assign` body gains
  optional `suggestion_id`, `rank`.
- **Depends on:** T1.1, T1.2, T3.1, T5.5.
- **Files:** `app/Services/Dispatch/{AssignmentService,AssignmentLock}.php`,
  `DriverRepository::tryReserveCapacity()/releaseCapacity()`, `OrderService`,
  `Dashboard/Order/OrderController::assign()`, `AssignOrderRequest`, lang, OpenAPI.
- **Tests:** feature: happy path; captain went offline between suggest and confirm → 409;
  full → 409; lock held by another dispatcher → 409 `locked`; decrement on completion.
- **Accept:** double assignment impossible by construction; existing assignment tests green.

### T6.2 Concurrency test under real parallelism `[x]` — 0.75 d
- **Done (2026-09-18):** `ParallelAssignmentTest` spawns **eight real PHP processes** against one
  MariaDB database (`kapitano_test`, created for this; in-memory SQLite lives inside a single
  process, so eight of them would each get an empty copy and "succeed" eight times). Each child
  drives the real HTTP kernel in-process — middleware, permission check, controller and all — so
  no web server is needed. Both tests skip, visibly, when MariaDB or Redis is missing; verified by
  pointing the connection at a dead port.
- **The first version was worthless, and finding that out is most of what this task was.** It
  passed — and it still passed with `WHERE active_orders < :max` deleted from the reservation. The
  dump explained why: with the lock in play, six of the eight children are turned away as `locked`
  **before the database is ever asked**, so the test was measuring the Redis lock and the number of
  winners was whatever the scheduler felt like. It would have gone green over a broken capacity
  check roughly half the time, forever.
  **So there are now two tests, and they divide the work:**
  1. `test_only_the_captains_capacity_survives_a_real_race_on_the_reservation` races eight
     processes on `tryReserveCapacity()` with **no lock anywhere near them**, so the only thing
     that can refuse the third caller is the conditional `UPDATE` itself. This is the load-bearing
     claim of T6.1 tested on its own.
  2. `test_eight_dispatchers_confirming_the_same_captain_cannot_overfill_them` races the whole
     endpoint, and a child refused as `locked` **retries** — which is what the API documents and
     what a dashboard should do. Without the retry the success count is nondeterministic; with it,
     the assertion is the one that cannot drift: never more than the capacity is assigned, and the
     counter and the orders agree afterwards.
  **Proved by mutation, not by passing:** with the capacity condition removed both tests fail on
  3 runs out of 3 (all eight reservations succeed, all eight get 200); restored, both pass on 3
  runs out of 3. The repository file was afterwards confirmed byte-identical to the committed T6.1
  version.
- **Two traps worth knowing before editing this test.** A child is started by `php artisan
  invoke-serialized-closure`, so it boots from **`.env`, not `phpunit.xml`** — left alone the
  children would assign orders in the *development* database and take locks in the development
  Redis, so `childBootstrap()` pins both before anything is touched. And `Concurrency::run()`
  **rethrows whatever a child throws**, which would turn one honest 409 into a failure of the whole
  pool, so each child catches its own outcome and returns it as data.
- **Cost:** about 27 s on a full run, most of it two `migrate:fresh` calls on the shared database.
- **Scope:** integration test that spawns **N parallel PHP processes** (Laravel
  `Concurrency::run` with the `process` driver, or `symfony/process`) each calling the assign
  endpoint for the same captain against a **MySQL test database** (`kapitano_test`, since
  in-memory SQLite is per-process); asserts `active_orders ≤ MAX` and exactly MAX
  successes. Skipped with a visible notice when MySQL/Redis are unavailable.
- **Depends on:** T6.1, T1.5.
- **Files:** `tests/Feature/Dispatch/Concurrency/ParallelAssignmentTest.php`,
  `phpunit.xml` (mysql connection env), `docs/runbook.md`.
- **Accept:** Test Group 6 passes with ≥ 8 parallel processes.

---

## Epic 7 — In-flight batch & route repaint (RoutePlan)

### T7.1 `RoutePlanService`: build, sequence, persist v1 `[x]` — 1.5 d
- **Done (2026-09-19):** `RoutePlanBuilder` turns the orders a captain is carrying into the route
  they should drive — every pickup not yet collected plus a drop-off per order — and
  `RoutePlanService` publishes it as version 1, closes the previous version, points
  `drivers.current_route_plan_id` and writes `orders.customer_eta_at` from the plan's own drop-off
  stops. What the customer is told and what the captain drives are therefore the same answer,
  rather than two numbers that can disagree.
  **The stop order is arithmetic, not cartography.** A drop-off cannot precede its own order's
  pickups; inside that rule `StopSequencer` (already built for T5.2) enumerates the possibilities
  and the engine only decides which is quickest. That is why the sequence survives a maps outage.
  **At most two engine calls, usually one.** A captain with one single-pickup order has exactly one
  legal sequence, so there is nothing to choose and the route is asked for directly. With a real
  choice, **one** matrix prices every candidate by arithmetic and **one** route is then drawn for
  the winner — rather than asking the engine to draw every candidate, which is the same trap T5.2
  avoided.
- **Two decisions taken with the user (2026-09-19):**
  1. **Built after the assignment commits, outside the captain's lock** — a listener on
     `OrderAssigned`, not a step inside `AssignmentService`. Building a plan means calling a
     routing engine, and the assignment holds a Redis lock on the captain: a slow maps call inside
     that window would make *other* dispatchers see "somebody else is confirming this captain" for
     as long as Google took. The dispatcher's confirm stays fast and the plan lands a moment later.
     It is also the shape T7.2 needs when it moves the recompute into a queued job.
  2. **A maps outage produces a degraded v1, not nothing** — correct stops in the correct order,
     times estimated from straight-line distance, `degraded = true`, no polyline. The captain still
     knows where to go; only the drawn line and the confidence in the minutes are lost. Writing no
     plan would break "a plan exists for every assigned captain" and leave the captain app with an
     order and nothing to show.
- **Also decided here:** a captain with **no GPS point** still gets a plan. There is no first leg
  to measure, so it is built from the first stop and flagged degraded rather than withheld — the
  stop order is still right. And an order whose **drop-off has no coordinates** contributes its
  pickups and no drop-off: the captain must still collect it, and that order simply gets no
  `customer_eta_at` rather than a made-up one.
- **Tests:** `RoutePlanTest` (9 — v1 has a stop per pickup and per drop-off with the leg that led
  to it; a drop-off never precedes its own pickup even when the illegal route is quicker; the
  customer's ETA comes from the plan; a second order writes v2 and closes v1 rather than appending;
  two orders interleave without breaking precedence; a collected pickup stops being a stop; a maps
  outage still leaves a usable plan; a captain carrying nothing gets no plan; the engine that drew
  it is recorded). All 9 pass.
  **Proved by mutation, not by passing.** With the precedence rule removed from `StopSequencer`,
  three of them fail. The first run of that check caught only two — `test_two_orders_interleave…`
  passed either way, because its fixture put the pickups near the captain and the drop-offs far, so
  the legal route was the cheapest anyway and the rule was never load-bearing. The fixture was
  inverted (drop-offs on the doorstep, pickups far out) so the illegal route is now the tempting
  one; it fails under mutation with "Order 1 is delivered before it is collected." `StopSequencer`
  was afterwards confirmed byte-identical to HEAD.
- **A test-helper bug worth remembering:** every stop count was one too high at first. The `Order`
  factory mirrors a pickup when the order has none, so creating the order and *then* adding pickups
  gets an extra one. `Order::factory()->withPickups([...])` exists for exactly this and writes both
  the stops and the mirrored columns together.
- **Scope:** on assignment build the stop list (all pickups → drop-off), call `getRoute`
  (traffic-aware, intermediates), persist `route_plans` v1, point
  `drivers.current_route_plan_id`, set `orders.customer_eta_at`; `StopSequencer` (shared with
  T5.2) enforces precedence; at-store case = one combined pickup then the cheaper drop-off
  order; en-route case = current GPS → insert new pickup(s) + drop-off at lowest-detour
  positions.
- **Depends on:** T4.3, T6.1, T5.2.
- **Files:** `app/Services/Dispatch/RoutePlan/{RoutePlanService,RoutePlanBuilder}.php`,
  `app/Repositories/Dispatch/RoutePlanRepository{,Interface}.php`,
  `app/Enums/Dispatch/{RoutePlanTrigger,RouteStopType}.php`, `app/DTOs/Dispatch/RoutePlanData.php`.
- **Tests:** unit: sequencing rules; feature: assignment creates v1 with K+1 stops.
- **Accept:** a plan exists for every assigned captain; version starts at 1.

### T7.2 Recompute triggers + versioning + race resolution `[x]` — 1.5 d
- **Done (2026-09-19):** `RecomputeRoutePlan` is a queued job, unique per captain, dispatched by
  `RecomputeRoutePlanOnOrderMoved` whenever one of a captain's orders is assigned, picked up,
  delivered or failed. Both of the algorithm's first two triggers are the same event seen twice —
  an assignment adds stops, a completion takes them away — so they are one listener rather than two
  that would have to agree. T7.1's inline `BuildRoutePlanOnAssignment` is gone; the job replaces it.
  **Coalescing is the point of queueing it.** `ShouldBeUnique` keyed on the captain means a burst of
  triggers leaves **one** job, so a captain is repainted once for one change instead of three times
  and billed one routing call instead of three. The uniqueness lock lives in the **Redis** cache
  store (`uniqueVia()`), because the file and database stores would serialise workers on one machine
  and nothing at all across several.
  **The job carries the captain's id, not the captain.** A queued payload is a photograph; a
  `Driver` frozen into it would be a captain who has since gone offline or finished an order. The
  row is read fresh, and a captain who no longer exists is nothing to do rather than an error.
- **Two gaps in T7.1 closed here:**
  1. **A finished captain now has no route.** `rebuild()` used to return null and leave the old plan
     open with the pointer still on it. It now closes the plan and clears
     `drivers.current_route_plan_id` — a captain with no work has no route, which is a different
     thing from being handed an empty one. The plans stay as history.
  2. **`order_pickups.picked_up_at` had no writer at all.** Nothing in `app/` ever stamped it, so a
     route could never shrink: the builder reads the pickups still outstanding and would have sent
     the captain back to a store they had already emptied. `markPickedUp()` now stamps the order's
     stores through the repository. **This is a deliberate behaviour change and worth knowing:**
     until the captain app can confirm one store at a time, an order marked picked up means all of
     its stores were. The algorithm's "`picked_up` per pickup" trigger arrives when that endpoint
     does.
- **The customer-promise guard, as decided with the user (2026-09-19):** after a recompute, any
  customer already on the route whose arrival slips by more than `max_batch_detour_min` is reported
  with `Log::critical`. **The plan is still published.** The guard should be unreachable — T5.2
  refuses such a batch before the order is ever assigned — so a breach means the batch check and the
  route planner disagree, which is a bug in us. Withholding the route would punish the captain and
  the new customer for that disagreement and leave the captain driving a route without the order
  they are already carrying. The task list said "throw + alert"; alerting without throwing was
  chosen for that reason.
- **Manual reorder:** `PATCH /api/dashboard/dispatch/drivers/{uuid}/route-plan/reorder`, plus a
  `GET` for the current route. **Stops are named, not numbered** — `pickup:{id}` / `dropoff:{id}` —
  because a plan can be recomputed between the screen being drawn and the reorder arriving, and
  position 3 would then mean somewhere else. The request carries the `version` the dispatcher was
  looking at; a stale one is refused `409` rather than applied to a route they never saw. An order
  that delivers before collecting is refused `422`: that is physics, not preference. Reading needs
  `dispatch.view`; reordering needs `orders.assign`, because changing what a captain does next is
  the same authority as handing them an order.
- **Tests:** `RoutePlanRecomputeTest` (12 — assignment writes v1; a second order writes v2 and
  closes v1; a completed stop shrinks the route and moves the version; the last delivery closes the
  route, frees the capacity and sets `idle_since`; three triggers for one captain leave one job;
  two captains get one job each; a dispatcher can read and reorder the route; a stale version is
  409; delivering before collecting is 422; a reorder missing a stop is 422; the permission is
  enforced). All 12 pass.
  **Proved by mutation:** with `ShouldBeUnique` removed from the job, the coalescing test fails with
  three jobs where one was expected. The job was afterwards restored.
  **The coalescing test uses the database queue on purpose** — under the synchronous queue every
  dispatch runs immediately, so there is no burst to coalesce and the test would pass without
  proving anything.
- **`phpunit.xml`:** `REDIS_CACHE_DB` is now forced to 15 alongside `REDIS_DB`. The job's uniqueness
  lock lives in the Redis *cache* store, which otherwise points at `REDIS_CACHE_DB` — a developer's
  own cache, which a test run has no business writing locks into.
- **Scope:** triggers: (1) second order assigned, (2) stop completed (`picked_up` per pickup,
  `delivered` / `delivery_failed`), (3) deviation (T7.4), (4) manual reorder endpoint
  `PATCH /api/dashboard/drivers/{uuid}/route-plan/reorder`; recompute runs in a queued job
  serialised per captain (Redis lock `dispatch:replan:{id}` + `ShouldBeUnique`), reads the
  latest plan under `lockForUpdate`, writes `version + 1`; overlapping triggers coalesce to
  exactly one final plan; when the last stop completes the plan is closed and
  `active_orders` reaches 0 → `idle_since = now()`. Assert customer A's new ETA − old ETA ≤
  `MAX_BATCH_DETOUR_MIN` (throw + alert if violated: it must never happen by rule).
- **Depends on:** T7.1.
- **Files:** `app/Jobs/Dispatch/RecomputeRoutePlan.php`, listeners on order events,
  `Dashboard/Dispatch/RoutePlanController.php`, request, routes.
- **Tests:** feature: each trigger increments the version once; two overlapping triggers →
  one final version; shrink after a completed stop; state 2 → 1.
- **Accept:** E2E-9, E2E-11 groundwork.

### T7.3 Fan-out ("repaint"): FCM + Reverb + customer ETA `[x]` — 1.25 d
- **Done (2026-09-19):** `RoutePlanUpdated` broadcasts every published
  version on the private channels `captain.{id}` and `dispatch.dashboard`;
  `NotifyCaptainOfRoutePlan` pushes the same version to the phone as an FCM **data** message;
  `CustomerEtaUpdated` is raised per order whose arrival actually moved; and
  `GET /api/driver/route-plan` serves the route the app draws. Broadcasting itself had never been
  wired — no `withBroadcasting()`, no `routes/channels.php` — so both are new here, with the auth
  route under `/api` on `auth:driver,admin` so one endpoint serves a captain subscribing to their
  own route and an admin subscribing to the dashboard.
  **A version is never announced twice**, which is the task's acceptance criterion. The
  announcement is tied to *publishing a version* rather than to the triggers that asked for one, so
  the burst T7.2 coalesces into a single plan produces a single repaint. A test drives three real
  triggers and asserts the versions announced are exactly `[1, 2, 3]`.
  **The push carries a pointer, not the plan.** FCM caps a message at 4 KB and a route with a
  polyline can exceed it; an oversized message is rejected outright, so the captain would get
  nothing rather than a truncated route. The phone is told the version and calls the same endpoint
  it calls on open — one way to read a route instead of two that can disagree. Every value in the
  data payload is a string, as FCM requires, and a test asserts that because the failure is
  otherwise a 400 from Google that nothing here would catch.
  **The push is silent on purpose.** It does not extend `BaseFcmNotification`: that base exists to
  give every *visible* push a title, icon, channel and priority, all of which are what this must
  not have. A route is recomputed every time a stop is completed, and a captain buzzed a dozen
  times an hour about work they are already doing would learn to ignore the one that matters.
- **Reverb installed (2026-09-20), after a long fight with Composer.** `laravel/reverb` v1.11.0 is
  in, `php artisan reverb:install` wrote `config/reverb.php` and the `REVERB_*` credentials, and
  `BROADCAST_CONNECTION=reverb` is set. Verified for real rather than assumed: the broadcast
  connection resolves to the `reverb` driver, and `php artisan reverb:start` serves and accepts a
  TCP connection on 127.0.0.1:8080. **`config/broadcasting.php` was not published** — Laravel 13
  ships a `reverb` connection in its own default config, so a published copy would be one more file
  to keep in step for no gain.
  **What actually blocked it was a poisoned Composer cache**, not the network and not the
  dependency graph. `composer require` reached "Loading composer repositories with package
  information" and sat at 0% CPU indefinitely, five times over. Ruled out along the way:
  connectivity (`composer diagnose` clean; the exact URL it stalled on fetched in a second;
  `composer show laravel/reverb --all` answered in 4.7 s), and parallel downloads
  (`COMPOSER_MAX_PARALLEL_HTTP=1` changed nothing). `composer clear-cache` fixed it immediately —
  resolution completed and it moved on to downloading. **If a Composer command hangs here again,
  clear the cache first.**
  **Two traps met on the way, both worth remembering.** A background job started in a PowerShell
  tool call dies when that shell exits, so long installs must be launched detached
  (`Start-Process`) or they are killed silently and look like a hang. And
  `Set-Content -Encoding utf8` writes a **BOM**, which made `composer.json` invalid JSON — edit
  JSON with a BOM-free writer.
- **One deliberate change outside this task:** `darkaonline/l5-swagger` was pinned from `"*"` to
  `"^11.1"` (11.1.0 was already installed). Composer warns about unbound constraints because they
  force it to consider every version of a package when resolving anything. It turned out not to be
  the cause of the hang, but it is a real latent cost on every future `composer require`, and
  leaving a `"*"` in place once noticed would have been the wrong call. `laravel/reverb` is
  `^1.11` for the same reason — `composer require` writes a bare `"*"` when given no version.
- **Two test premises that were wrong before the code was:** "an unchanged arrival is not
  announced" failed at first because an arrival is *now plus the driving left*, so a recompute a
  minute later genuinely lands a minute later — the clock had to be frozen **before** the first
  plan, not after. Then "an arrival that moves is announced" failed twice: with both stores at the
  same point, and again with the second order collected only after the first was delivered. In both
  cases the first customer was not delayed and the silence was correct. The fixture now puts the
  second order's store and customer *between* the captain and the first customer, so the cheapest
  legal route really does slot it in ahead.
- **Tests:** `RoutePlanFanOutTest` (13 — one announcement per publish; three triggers announce
  exactly versions 1, 2, 3 with none repeated; both channels are private and the captain's is
  their own; the payload carries the version, the stops and the stable event name; the captain is
  pushed silently with string-only data; a moved arrival is announced with both times; an unchanged
  one is not; a captain reads their own route; a captain with no work gets `null`; the endpoint
  needs a token; a captain may not listen to another captain's channel and an admin token is not a
  captain; only an admin with `dispatch.view` gets the dashboard channel). All 13 pass.
- **Scope:** `RoutePlanUpdated` event (implements `ShouldBroadcast` on private channels
  `captain.{id}` and `dispatch.dashboard`) carrying `version`, ordered stops, polyline, per-leg
  ETAs; `NotifyCaptainOfRoutePlan` listener sends an FCM **data** message with the same
  payload; `CustomerEtaUpdated` event per affected order (customer app is external — the
  event + `orders.customer_eta_at` are the contract); `GET /api/driver/route-plan` for the
  app to fetch the latest plan on open; clients render only the highest version (documented
  in `docs/api.md`). Installs `laravel/reverb`, `BROADCAST_CONNECTION=reverb`, channel auth
  for the `driver` and `admin` guards.
- **Depends on:** T7.2.
- **Files:** `composer.json` (reverb), `config/broadcasting.php`, `routes/channels.php`,
  `app/Events/Dispatch/{RoutePlanUpdated,CustomerEtaUpdated}.php`,
  `app/Listeners/Dispatch/NotifyCaptainOfRoutePlan.php`,
  `app/Notifications/RoutePlanUpdatedNotification.php`,
  `Mobile/Dispatch/RoutePlanController.php`, routes, OpenAPI.
- **Tests:** feature with `Event::fake` / `Notification::fake`: one broadcast + one FCM per
  version; payload carries the version; channel auth 403 for the wrong captain.
- **Accept:** E2E-7 groundwork; a version is never pushed twice.

### T7.4 Deviation detection → reroute `[x]` — 0.75 d
- **Done (2026-09-20):** every accepted GPS ping now asks whether the captain is still on the route
  they were given. `GeoMath::distanceToPath()` measures the point against the decoded polyline
  (point-to-segment, not point-to-shape-point — a captain halfway along a 3 km straight leg is *on*
  it, and measuring only to the drawn vertices would call that a 1.5 km deviation);
  `DeviationStateStore` keeps the episode in Redis; `DeviationDetector` applies the rule and asks
  `RecomputeRoutePlan` for a new route, reusing the T7.2 job rather than inventing a second path
  to a plan.
- **Distance alone is not deviation, so the rule is *sustained*.** A GPS point bounces off a tower
  block, a captain pulls into a car park, a road sits a few metres from where the polyline drew it.
  Any of those puts a single ping hundreds of metres from the line while the captain is doing
  exactly what was asked. So: further than `REROUTE_DEVIATION_M` **continuously** for at least
  `REROUTE_DEVIATION_S`, and one ping back near the line starts the clock over.
- **The state is keyed by plan version, which is what makes "fire once" free.** Having decided a
  captain is off route, saying so again on the next ping — and the one after — would queue a
  recompute every few seconds for a captain already driving a replanned route. The Redis value
  carries the version it belongs to, so `get()` returns nothing when the version has moved on: a
  new plan is a new question and gets a clean clock, with no expiry to tune and no reset to
  remember to call. TTL is 15 minutes, purely so an abandoned episode cannot outlive the shift.
- **Nothing here calls the routing engine.** This runs on every ping from every captain, the
  busiest path in the system; it decodes a polyline it already has and does arithmetic. The one
  engine call happens later, inside the recompute, and only for a captain who really has gone their
  own way. Longitude is scaled by `cos(latitude)` — at Riyadh's 24.7° a degree of longitude is
  about 101 km against latitude's 111 km, and skipping that would overstate every east-west
  distance by a tenth.
- **A degraded plan has no line to measure against**, so deviation there is unanswerable rather
  than false: the detector clears the episode and says no. The same is true of a captain carrying
  nothing. This matters because T7.5 makes degraded plans a normal state, not an exception.
- **The ping is never failed for it.** The hook in `DriverLocationService::update()` goes through
  the same `bestEffort()` wrapper as the Redis writes beside it: a replan is worth having, never
  worth returning an error to the captain's phone over, and the next ping asks again anyway.
- **Two bugs were in the test, not the code, and both would have passed while proving nothing.**
  The replan test first called the helper that *creates* a captain, so the "new plan" landed on a
  different captain and said nothing about the one whose clock was already spent — split into
  `captainOnARoute()` and `publishRouteFor()`. Then the second recompute vanished: `Queue::fake()`
  never runs a job, so `ShouldBeUnique`'s lock is never released and the dispatch is silently
  swallowed as a duplicate. The test now releases it the way a worker would
  (`app(UniqueLock::class)->release(...)`) with a comment saying why, because the symptom accuses
  the detector of a bug that belongs to the fake queue.
- **Mutation-checked:** deleting the `triggered` guard from `check()` makes
  `test_continued_deviation_asks_for_nothing_more` fail on the second ping. The guard is
  load-bearing and the test is not decorative.
- **Tests:** `GeoMathTest` (9 — a point on the line; a point midway between two distant shape
  points, which is the projection case; metres in longitude and in latitude checked against the
  real numbers; clamping past the end of a segment; a bending path; a single point; an empty path;
  a zero-length segment) and `DeviationDetectionTest` (8 — on route asks for nothing; 25 s asks for
  nothing; 35 s asks for exactly one recompute, tagged `Deviation`; continued deviation asks for
  nothing more; a new plan starts the clock again; returning to the line resets it; a plan with no
  polyline is never a deviation; a captain with no plan is never a deviation). All 17 pass.
- **Scope:** on each GPS ping, distance from the current polyline (point-to-segment on the
  decoded polyline); if > `REROUTE_DEVIATION_M` continuously for ≥ `REROUTE_DEVIATION_S`
  (state kept in Redis) → exactly one recompute trigger, then reset.
- **Depends on:** T2.1, T7.2.
- **Files:** `app/Services/Dispatch/GeoMath.php`,
  `app/Repositories/Dispatch/DeviationStateStore.php`,
  `app/Services/Dispatch/RoutePlan/DeviationDetector.php`,
  `app/Services/Driver/DriverLocationService.php` (the hook),
  `tests/Unit/Dispatch/GeoMathTest.php`, `tests/Feature/Dispatch/DeviationDetectionTest.php`.
- **Accept:** E2E-10 groundwork.

### T7.5 Routing outage during an active batch `[x]` — 0.5 d
- **Done (2026-09-20):** a recompute that cannot reach the map service no longer costs a captain
  the route they are already driving. The plan is kept, marked `degraded` in place, and
  `RecomputeRoutePlan` puts itself back on the queue after 5 s, then 30 s, then 120 s, until the
  engine answers or it gives up.
- **The judgement this task turns on: rebuilding without an engine is a *downgrade*, not an
  update.** T7.1 already made sure a captain is never left holding an order and no route — without
  an engine the stops are sequenced from straight lines and the plan comes back degraded with no
  polyline. That is the right answer for a captain who has *nothing*. It is the wrong answer for
  one mid-delivery: it would take the drawn line off their map, replace measured minutes with
  guessed ones, and repaint every client (T7.3) for a route that had not actually changed. So when
  a plan already exists, it stays.
- **Unless the work changed, and that exception is what stops the rule becoming a bug.** A second
  order assigned or a stop completed makes the old route *wrong* rather than merely stale — a
  captain sent back to a store they have already emptied, or never shown the parcel already in
  their bag. Then the rough plan is published, degraded, exactly as before. The comparison is by
  **stop, not by order of stops**: which stops are left is a fact, while their best order is
  precisely the question the missing engine used to answer.
- **`RoutePlanData` gained `routing_unavailable` beside `degraded`,** because `degraded` covers two
  different failures that the apps rightly treat the same and the system must not. A plan is also
  degraded when the engine answered but the captain's position was unknown — that route is real,
  it has a polyline, and it is better than the old one, so it publishes. Only "the engine could not
  answer" is grounds for keeping what we have.
- **`markDegraded()` is the one edit ever made to a published plan,** and it changes nothing the
  captain drives: one boolean on one row, no new version, no broadcast. A version bump would be
  read by clients as a repaint (they render only the highest version), and there is nothing to
  repaint. The flag needs no clearing code — a successful recompute publishes a fresh version that
  simply is not degraded.
- **The retry is `release()`, not a second dispatch, and that detail is load-bearing.** Laravel
  releases a job's uniqueness lock only `if (! $job->isReleased())`, so a job that releases itself
  *keeps* the lock: a captain still has at most one replan in flight, and triggers arriving during
  the wait still coalesce into it (T7.2). Dispatching a fresh job instead would be swallowed as a
  duplicate — the same trap that cost time in T7.4's test.
- **It stops.** `tries = 4` is the first run plus one attempt per backoff step; the fourth run logs
  a warning and returns rather than waiting a fourth time or failing the job. An outage that has
  lasted through all three waits is not a blip, and a job that asked forever would be a slow leak
  of queue work for every captain on the road. The same `[5, 30, 120]` serves Laravel's ordinary
  retry-after-exception, because a recompute that failed on a database blip wants the same patience
  as one that failed on a maps blip.
- **Tests:** `RoutingOutageTest` (10 — an outage keeps the measured route, same version, same
  polyline, flag set on the row; a kept plan is not announced again; a captain with no plan still
  gets a rough one; an order assigned during the outage is put on the route; a completed stop
  during the outage also rebuilds; the backoff asks 5, then 30, then 120; the retries give up after
  the last step; a healthy plan asks for no retry; a recovered engine publishes version 2 with the
  line back and the flag clear; a captain who finished during the outage keeps no plan). All 10
  pass. The engine under test is a switch rather than an always-failing double, because the whole
  question is what happens on **either** side of the moment the outage ends.
- **Scope:** recompute failure keeps the last valid plan, marks `degraded = true` on the plan and
  the dashboard payload, retries with backoff (job `backoff: [5, 30, 120]`), clears the flag on
  success.
- **Depends on:** T7.2, T4.3.
- **Files:** `app/Jobs/Dispatch/RecomputeRoutePlan.php`,
  `app/Services/Dispatch/RoutePlan/RoutePlanService.php`,
  `app/Services/Dispatch/RoutePlan/RoutePlanBuilder.php`, `app/DTOs/Dispatch/RoutePlanData.php`,
  `app/Repositories/Dispatch/RoutePlanRepository.php` (+ interface),
  `tests/Feature/Dispatch/RoutingOutageTest.php`.
- **Accept:** E2E-12 groundwork.

---

## Epic 8 — Observability & KPIs

### T8.0 Measure the ETA speed instead of assuming it `[x]` — 0.5 d
- **Done (2026-09-20):** `php artisan dispatch:measure-speed [--days=30]` reads the GPS history
  captains have already sent and reports what speed they really drive at, so
  `DISPATCH_ETA_ESTIMATE_SPEED_KMH` can stop being a number somebody picked.
- **Why this came before T8.1 rather than after.** The default 30 was a placeholder of mine, and
  it is not decorative: it is read by `AdjustedEtaCalculator` (**which captain wins an order**),
  `BatchCompatibilityService` (**whether a batch is refused** for exceeding the detour limit),
  `EstimatedRemainingEtaProvider` and `RoutePlanBuilder` (**what the customer is told**). Epic 8 is
  about to report ETA accuracy and on-time rate as KPIs. Computing those from an invented constant
  would make an assumption look like a measurement, and every number would inherit the error
  without showing it.
- **The trap this is built to avoid: it is a *straight-line* speed, not a road speed.** Every
  caller divides a haversine distance by it, so the figure has to already absorb bending roads,
  junctions and one-ways — it is always lower than what a captain's speedometer reads. The obvious
  implementation, averaging the `speed_mps` the phones report, would give a number roughly a third
  too high and make every ETA in the system optimistic. A sample here is **displacement over
  elapsed time**: how far the captain ended up from where they were.
- **What is thrown away, and why each one would lie in its own direction:** windows shorter than
  `speed_sample_window_s` (300 s — one traffic light would dominate); gaps longer than
  `speed_sample_max_gap_s` (900 s — a captain whose app was closed for an hour did not spend that
  hour crawling); displacement under `speed_sample_min_meters` (150 m — parked at a store is real
  time but not travel, and the handoff buffers already price it); anything over
  `speed_sample_max_kmh` (140 — a GPS jump, not a car). Windows do not overlap, so a handful of
  points cannot look like a crowd.
- **The median, not the mean**, and there is a test that shows the difference rather than asserting
  the choice: six ordinary samples at 30 km/h plus one captain on an empty ring road at 108 puts
  the mean at 41 and leaves the median at 30.
- **It reports; it never writes.** `eta_estimate_speed_kmh` is config-only by design — it is not
  one of the three dashboard-editable keys in `DispatchSettingKey` — and changing what every ETA
  in the system rests on is a decision for a person with the sample size in front of them, not a
  side effect of running a diagnostic. Under 200 samples the command says so and recommends
  nothing.
- **Still open:** the command has not been run against real driving, because no captain has driven
  yet. **The 30 km/h default is still a placeholder**, and T8.1's KPIs should be read with that in
  mind until this has an answer from production data.
- **One incidental catch from the architecture checker**, worth recording because it is the rule
  earning its keep: adding `speed_sample_max_gap_s = 900` made T7.4's unrelated
  `DeviationStateStore::TTL_SECONDS = 900` look like a config value. It is not, so it is annotated
  `@dispatch-literal` on the line rather than rewired — the two numbers are the same by
  coincidence and are free to diverge.
- **Tests:** `MeasureSpeedTest` (11 — the arithmetic on a captain covering 500 m a minute reads
  30 km/h; windows do not overlap; a parked captain contributes nothing; a long gap is dropped
  rather than counted as slow; an impossible speed is dropped; one fast outlier moves the mean but
  not the median; only the window asked for is read; the command reports; the command never changes
  the setting; an empty window is an answer, not a crash; a thin sample is flagged as one). All 11
  pass.
- **Files:** `app/Console/Commands/Dispatch/MeasureSpeedCommand.php`,
  `app/Services/Dispatch/EffectiveSpeedSampler.php`, `app/DTOs/Dispatch/SpeedSampleData.php`,
  `app/Repositories/Dispatch/DriverLocationHistoryRepository.php` (+ interface),
  `config/dispatch.php`, `app/Services/Dispatch/DispatchSettings.php`,
  `tests/Feature/Dispatch/MeasureSpeedTest.php`.

### T8.1 Dispatch metrics events + counters `[x]` — 1 d
- **Done (2026-09-20):** every part of the dispatch algorithm now reports itself through one door,
  `DispatchMetrics`, and `GET /api/dashboard/dispatch/kpis` answers what the back office judges it
  by. Nine metrics, a JSON log channel of its own, Redis daily counters, and an endpoint behind
  `dispatch.view`.
- **Two destinations, one call, because they answer different questions.** A **structured log
  line** on the `dispatch` channel is what a person reads when one delivery went wrong — which
  order, which captain, which suggestion, how long. A **Redis daily counter** is what a dashboard
  reads; counting log lines instead would mean parsing a day of JSON to draw one number. Neither
  replaces the other.
- **Two sources for the KPIs, and the split is the design.** Counters answer *how many*, which is
  what every rate needs and what a table of every suggestion ever shown cannot answer cheaply on a
  screen somebody refreshes. The **Suggestion Log** answers *how long*, because a latency
  percentile needs the individual measurements and a counter has thrown them away.
- **The rule the endpoint lives or dies by: a rate with an empty denominator is `null`, never
  `0`.** A quiet Sunday has no batch rate. Reporting zero would tell the back office the fleet
  never batches, and a dashboard that cannot tell "nothing happened" from "it went badly" is worse
  than no dashboard. Every rate in `DispatchKpiData` is nullable for that reason, and a test walks
  all seven of them on an empty window.
- **Denominators are chosen so a rate cannot measure itself.** `assignment.made` counts *every*
  assignment, list or not — without it, a dispatcher who bypasses the algorithm would vanish from
  the statistics and flatter it. Refusals are measured against **attempts** (`made + failed`),
  not against the ones that worked. The fallback rate needs `routing.answered` as well as
  `routing.fallback`, because fifty failures is excellent on a million calls and a catastrophe on
  sixty. And cost is **per delivery**, not per order: two orders on one route cost barely more to
  plan than one, so per-order would flatter a batched fleet and hide the price of a badly batched
  one.
- **Percentiles without loading the set.** `ORDER BY ... LIMIT 1 OFFSET n`, the nearest-rank
  definition. MySQL 5.7/MariaDB has no `PERCENTILE_CONT` and SQLite has none at all, while
  fetching a month of suggestions into PHP to sort them would be a query that only survives on a
  small database. `display_to_assign` joins the Suggestion Log to `order_status_history` for the
  moment of assignment — there is no `assigned_at` column and there does not need to be.
- **It measures; it never decides.** Nothing reads a counter back to change behaviour. A metric
  that steers the algorithm stops being an observation and becomes an input nobody remembers is
  there.
- **It never fails the thing it measures.** Every call sits on the request path — inside a list a
  dispatcher is waiting for, inside an assignment holding a capacity lock. Redis being unreachable
  costs a counter and is reported; it does not cost an assignment. A test proves it by giving the
  counter a Redis that refuses connections **while leaving the application's own Redis working**,
  because breaking both would prove the assignment failed without saying which half stopped it.
- **Tests:** `DispatchMetricsTest` (10 — an answered routing call counts its elements and itself;
  a failed one counts only as a fallback and consumes no elements; a list is counted once when it
  is written; an assignment from a list counts three ways; an assignment without a list still
  counts as an assignment; a second order on the same captain counts as a batch; a refusal counts
  as a failure and not as an assignment; a delivery counts once; every metric also writes a
  structured log line; a broken counter never fails an assignment). `DispatchKpiApiTest` (10 —
  the rates with numbers a reader can check by hand, cost per delivery, an empty window reporting
  unknown rather than zero, summing only the days in the window, the seven-day default, a window
  older than the counters refused, a backwards window refused, permission, token, API headers).
  All 20 pass. The assertions are exact counts, never "greater than zero", because the failure
  mode is **double counting** — it is not obviously wrong anywhere, it simply reports a busier and
  more expensive system than the real one.
- **The `ready_to_assign` tile, decided.** T5.5 left this open: *"T8.1 should decide what that tile
  ought to count."* It now counts **exactly what the assignment screen offers** — approved, on
  duty, not on a break, carrying fewer than the maximum — because the tile and the list are read
  within a second of each other, and a dispatcher who sees "3 ready" above a list of six learns to
  trust neither.
  The old count disagreed with the list in **three** separate ways, not one. It excluded a captain
  carrying one order, who can be batched and is offered. It required a stored location, which the
  pipeline does not, because a captain's position comes from Redis. And it **counted captains on a
  break as ready** — the list has always excluded them, and that one was simply a bug.
  What it deliberately does not do is apply the geo filter: that is per-order, while the tile is a
  fact about the fleet.
  The stricter pool was not thrown away. It is reported beside it as **`idle`**, under a name that
  says what it is: the fleet's slack. The two numbers answer different questions — "can take work"
  is what a dispatcher acts on, "carrying nothing" is how much room there is before the next busy
  hour — and a fleet where they are equal is idle while one where they are far apart is running
  hot on batching.
  **The published contract was already right and the code was wrong**: the OpenAPI description has
  said "Online, approved, and with capacity left" all along. Tests pin the tile to
  `eligibleForDispatch()` rather than to a constant, so a future change to eligibility cannot move
  one without moving the other; reverting the count to the old pool fails two of them.
- **Scope:** `DispatchMetrics` emitting structured events to the log channel `dispatch` (JSON) and
  to Redis daily counters; `GET /api/dashboard/dispatch/kpis` answering: suggestion-to-display ms
  (p50/p95), display-to-assign ms, first-suggestion acceptance rate, batch rate, routing elements
  per assigned order, fallback rate, maps cost per delivery.
- **Depends on:** T5.5, T6.1, T7.2.
- **Files:** `app/Enums/Dispatch/DispatchMetric.php`,
  `app/Repositories/Dispatch/MetricsCounterStore.php`,
  `app/Services/Dispatch/Metrics/{DispatchMetrics,DispatchKpiService}.php`,
  `app/DTOs/Dispatch/{DispatchKpiData,LatencyData}.php`,
  `app/Listeners/Dispatch/{RecordRoutingMetrics,RecordAssignmentMetrics,RecordRoutePlanMetrics,RecordDeliveryMetrics}.php`,
  `app/Http/Controllers/Dashboard/Dispatch/DispatchKpiController.php`,
  `app/Http/Requests/Dashboard/Dispatch/DispatchKpiRequest.php`,
  `app/Repositories/Dispatch/SuggestionRepository.php` (+ interface), `config/logging.php`,
  `config/dispatch.php`, `routes/dispatch-management.php`.
- **Accept:** E2E-14 passes — see `DispatchKpiE2ETest`.

---

## Epic 9 — E2E suite, docs, demo

### T9.1 E2E test suite (full stack, `FakeRoutingEngine`) `[x]` — 2.5 d
- **Epic 7's scenarios landed (2026-09-20): E2E-7, E2E-10, E2E-11 and E2E-12.** Five tasks had
  been built and tested one at a time, each faking whatever came after it, so nothing had ever
  watched one order travel the whole way. These do, over HTTP, with the queue running recomputes
  for real and the repaint caught at the far end of both transports.
- **`RoutePlanLifecycleE2ETest` (4)** — a dispatcher assigns through the real endpoint, the captain
  works two orders to delivered through the real captain endpoints, and the route is rebuilt and
  announced at every step; versions are announced in order with none repeated; the websocket
  payload carries every documented field on both private channels; the push is a silent,
  string-only pointer with no polyline in it. Finishing the last delivery leaves the captain with
  **no** route rather than an empty one, and assignable again.
- **`DeviationRerouteE2ETest` (5)** — a real GPS ping crosses the kernel, is measured against the
  polyline in the database, queues a recompute and produces an announced version. 25 s off route
  does nothing, 35 s produces exactly one new route, continuing off route produces no more, and
  rejoining the line starts the clock again.
- **`MapsOutageE2ETest` (5)** — the engine falls over mid-delivery: the measured route stays, same
  version and same polyline, with `degraded` set; both the dashboard and the captain endpoints
  show it; an order assigned during the outage still reaches the captain as a rough plan; and the
  recovery publishes a real version with the line back.
- **`DispatchKpiE2ETest` (4, E2E-14)** — a real shift over HTTP: a dispatcher opens a suggestion
  list, assigns its first pick, the captain works the order to delivered, and the KPI endpoint is
  asked what happened. `DispatchKpiApiTest` checks the arithmetic against counters put there on
  purpose, which is right for an empty window or a zero denominator; it cannot check that the
  counters are **wired to the code**, and a metric incremented from nowhere reads zero for ever
  and looks exactly like a quiet day.
- **`ChannelAuthorizationE2ETest` (7)** — the half of broadcasting nothing else touched. Runs
  against the **real** Reverb driver, so the returned `auth` is a genuine signature: a captain may
  sign their own channel and not another's, an admin token is refused on a captain's channel, the
  dashboard channel needs `dispatch.view`, a captain is refused it, and an anonymous subscription
  is 401.
- **The group suites landed (2026-09-20): TG1, TG3, TG4, TG5, E2E-8 and E2E-13.** All driven
  through the dispatcher's own endpoint, so what is asserted is what a person is shown.
- **`RankingE2ETest` (7, TG4 + E2E-8)** — the claim the design rests on, in both directions. A busy
  captain 300 m from the store loses to an idle one 3 km away; when nothing complicates it the
  nearest captain *does* win; a captain seconds from free beats an idle one across town. Ranks and
  adjusted ETAs agree, so a screen trusting `rank` cannot disagree with the Suggestion Log. And
  at-store stacking lifts a captain who is walking into that store anyway — with the badge that
  explains the position, and *not* for a captain whose remaining pickup is somewhere else.
  The list also shows its working: `road_eta + remaining_delivery + handoff` adds up to
  `adjusted_eta` to within a tenth of a minute, which is what makes the list readable rather than
  merely trusted.
- **`EligibilityAndLocationE2ETest` (9, TG1 + TG3)** — offline, on a break and at capacity are all
  absent; one below the limit is present and `batchable`. A stale fix takes a captain off the list
  entirely (**a stale position is worse than none, because it is believed**), an aging one is
  offered with the age shown, a recent one is marked fresh. And the effective-location rule in
  both directions: a busy captain is measured from the customer they are driving to, an idle one
  from their own phone.
- **`RoutingFailureE2ETest` (7, TG5 + E2E-13)** — a maps outage costs accuracy, never the ability
  to work: the list still arrives, says it is degraded, names the reason, marks every ETA as
  estimated, stays sensibly ordered, and an order can still be assigned from it. A timeout and an
  error report differently, because the Suggestion Log has to tell them apart afterwards. Then the
  batch policy: `rank_lower` keeps a refused captain on the list below the clean ones with the
  reason attached, `exclude` removes them, and only them.
- **One thing the batch tests deliberately do not contrive.** The detour rejection — delaying the
  customer already on board past `max_batch_detour_min` — is genuinely hard to provoke, and that
  is the system working rather than a gap: the sequencer chooses the visiting order, and
  delivering the customer already in the car first is nearly always the cheapest route, so they
  are rarely delayed at all. Several geometries were tried and every one came back `accepted`,
  correctly. The suite tests the same decision — this captain must not take this order — through
  a promise that cannot be met, which is deterministic. Contriving coordinates until the detour
  rule fired would have been testing the fixture.
- **Two fixture bugs found while writing these, both of which would have passed while proving
  nothing:** `withPickups([])` is not "no pickups" — the factory mirrors the first pickup onto the
  order's own columns and had nothing to read — and stamping passed-in pickups as collected made
  at-store stacking untestable, because the rule needs an *uncollected* one.
- **`LiveServerE2ETest` (10) — the suite that talks to a running server** over real HTTP, opt-in
  through `E2E_BASE_URL`. Everything else here drives Laravel's test kernel, which covers the
  application and stops where the application stops: it never sees a web server parse a request, a
  real `.env` resolve, the real Redis database, the real queue connection, or the middleware stack
  as PHP assembles it outside a harness. Covers the header and token contract, the CORS preflight
  from the dashboard origin, TG1 eligibility (capacity, stale GPS, on a break, offline — all
  absent from the list), batching, TG4 ranking by adjusted ETA rather than distance, assignment
  through to the captain reading their own route, a GPS ping, a 409 at capacity, and the KPI
  screen. **Verified against `artisan serve` on :8001 with a worker running: 10 passed, 55
  assertions.**
- **Four things that had to be solved to make live-server testing work at all**, each of which
  would silently produce a green suite that proved nothing:
  1. **A test process cannot reach the server's database.** `phpunit.xml` forces SQLite in memory,
     Redis 15 and a null broadcaster onto the process, and a subprocess inherits all of it — so
     `db:seed` seeded an in-memory database and reported success while the server saw nothing. The
     suite clears those variables for every subprocess it runs.
  2. **The captains were not on the live map.** The seeder deliberately does not write Redis;
     positions are filled by GPS pings. The suite replays each scenario captain's seeded position
     **and its age** through `POST /api/driver/location` — the age being the point, since a stale
     fix must drop that captain out of the list.
  3. **The candidate payload nests the captain** (`captain.uuid`, `captain.name`), and reading the
     flat keys made every name an empty string. The "must not be offered" assertions were passing
     against nothing; only the positive assertion failed and exposed it.
  4. **`Illuminate\Http\Client\Response` is not a `TestResponse`** and has no `assertStatus()`. The
     replacement prints the response body on failure, because "expected 200, got 422" from a live
     server is not a debuggable sentence.
- **What it deliberately cannot do over HTTP:** seed the scenario, and mint the captain's token.
  Captain sign-in is an SMS code and the code is stored hashed, so a harness can neither receive it
  nor read it back. Both are done by artisan subprocess; everything *asserted* goes over the wire.
- **The gap this work was written to close: `Event::fake()` proves the wrong thing.** It stops the
  event before `ShouldBroadcast` is consulted, so `broadcastOn()`, `broadcastAs()` and
  `broadcastWith()` never run — a mistake in any of them passes every test in T7.3 while no phone
  in the field repaints. `Tests\Support\RecordingBroadcaster` is a real broadcast connection that
  keeps what it was handed, and `Tests\Concerns\RecordsTheRepaint` does the same for FCM through a
  `Messaging` double, so both legs are asserted at the far end instead of at the near one.
- **Two things the E2E found that the unit suites could not:**
  1. A captain handed an order gets **two** pushes — the visible "new order" and the silent
     repaint. That is deliberate and was nowhere asserted; it is now, including that exactly one
     of them carries a `notification` block.
  2. A recovery from a maps outage **cannot be dispatched**, only worked. The degraded run
     releases itself, Laravel keeps a job's uniqueness lock across a release, and a fresh
     `dispatch()` is swallowed as a duplicate. Correct — the released job *is* the pending replan
     — but it means only a worker carries the recovery, which is now written down where the next
     person will look.
- **A false green caught in the writing.** Switching the broadcast connection inside `setUp()`
  builds a *fresh* driver, and `Broadcast::channel()` had registered the callbacks on the one that
  was default at boot. Every auth request answered 403 — so all four refusal tests passed while
  proving nothing. The channel file is re-required against the driver under test, with a comment
  saying why.
- **`RecomputeE2ETest` (7, E2E-9)** — every trigger produces exactly one version and each is
  announced once; nothing is written without being announced; a dispatcher can reorder the route
  by hand; a reorder against a superseded version is refused 409; one that would deliver before
  collecting is refused 422 and changes nothing; one that does not name every remaining stop is
  refused; finishing the work closes the route rather than leaving an empty one.
- **`CapacityE2ETest` (6, TG6 from outside)** — a captain can be filled to the limit with the
  counter following each step; one past it is refused 409 with a reason; **a refusal costs
  nothing** (the order stays pending and unassigned, the counter unchanged); finishing frees them
  again; a full captain is not even offered; and the counter and the orders agree after a full
  cycle.
- **What `CapacityE2ETest` deliberately does not claim.** It covers the contract *around* the
  race, not the race. Two dispatchers confirming in the same instant is settled by the conditional
  capacity update, and the only honest way to test that is with real parallel processes —
  `tests/Feature/Dispatch/Concurrency`, which is written and **cannot run on this machine** because
  of the MariaDB hang recorded in the runbook. A test that claimed to prove atomicity by calling
  the service twice in a row would be worse than no test, because it would look covered.
- **Still open on the acceptance criteria:** coverage ≥ 80 % on `app/Services/Dispatch` has never
  been measured locally — the XAMPP PHP has no coverage driver, and CI measures it. Coverage ≥ 80 % on `app/Services/Dispatch` is still unmeasured locally — the
  XAMPP PHP has no coverage driver, and CI measures it.
- **Scope:** `tests/Feature/Dispatch/E2E/` — one class per group: Eligibility (TG1),
  Capacity (TG2), Location (TG3), Ranking (TG4: closest ≠ fastest via penalty table, closest
  = fastest, busy beats idle, idle beats busy), Routing failure modes (TG5), Concurrency
  (TG6 → T6.2), plus E2E-7 … E2E-14 exactly as specified in the prompt; each test drives the
  HTTP API (dashboard + captain tokens) and asserts DB, Redis, events and payloads. Real
  Google only behind `RUN_REAL_MAPS=1`.
- **Depends on:** everything above.
- **Files:** `tests/Feature/Dispatch/E2E/{DispatchE2ETestCase,RoutePlanLifecycleE2ETest,DeviationRerouteE2ETest,MapsOutageE2ETest,ChannelAuthorizationE2ETest}.php`,
  `tests/Support/RecordingBroadcaster.php`, `tests/Concerns/RecordsTheRepaint.php`.
- **Accept:** all scenarios green in CI; coverage ≥ 80 % on `app/Services/Dispatch`.

### T9.1a Readiness checks for the two things tests cannot reach `[x]` — 0.25 d
- **Done (2026-09-20):** two commands, in the shape of `dispatch:redis-check`, for the two pieces
  of the stack that every test necessarily stops short of.
- **`php artisan dispatch:broadcast-check`** publishes one frame to the websocket server on a
  channel nothing subscribes to. It catches the failure that is silent in the worst direction:
  with a mismatched `REVERB_APP_KEY` nothing errors, no request fails, no log line appears, and
  captains simply stop being told their route changed. Run for real against Reverb on
  127.0.0.1:8080 — **it correctly failed while the server was down and passed once it was up**.
  A `null` or `log` driver is warned about rather than failed, because `log` is a legitimate
  choice on a machine with no websocket server.
- **`php artisan dispatch:routing-check`** asks the configured engine for a matrix and a route
  between two real Riyadh points and prints what came back. It exists because **the algorithm has
  only ever met a simulation** — there are no Google keys yet — and because nothing above the
  routing layer throws, so an engine that is down looks exactly like one that is working, only
  with worse numbers. A configured engine that fell back **fails the command**; the fake engine is
  announced as a simulation rather than reported as a healthy map.
- **Tests:** `BroadcastCheckCommandTest` (3) and `RoutingCheckCommandTest` (3) — success, refusal
  fails the command, and the quiet-driver warning.

### T9.2 Documentation: `docs/api.md`, `docs/runbook.md`, changelog `[x]` — 1 d
- **Scope:** API doc (suggestion, assignment, route-plan, settings, KPI, GPS contract);
  runbook (config keys and ranges, Redis ops, queue worker + Reverb processes, fallback
  behaviour, cost levers, quota guards from the cost report §12, switching engines);
  `docs/CHANGELOG.md` Feature 08 section; OpenAPI regenerated.
- **Depends on:** T9.1.
- **Accept:** docs match the code (spot-checked by the E2E tests reading the same examples).

### T9.3 Demo scenario `[x]` — 0.75 d
- **Done (2026-09-20):** `php artisan dispatch:demo --fresh` drives the algorithm end to end on
  the simulated engine and prints what it decided. `scripts/demo.md` is the walkthrough.
- **It exists to make one claim checkable: the closest captain is not the fastest.** That is the
  insight the design rests on (v2.1 §22), the hardest thing to believe from reading the code, and
  the first thing a dispatcher will argue with. The run prints the ranked list with the arithmetic
  beside each captain — distance, road ETA, time to finish what they are carrying, handoff buffer,
  Adjusted ETA — and then names the nearest captain and the winner. In the seeded example a
  captain **0.01 km** from the store ranks **fourth** while an idle one 1.5 km away wins.
  It says so either way: "nearest also won" is a legitimate outcome, and a demo that only
  announces the happy case is one nobody believes twice.
- **The exclusions show by absence**, which is the honest way to show them: the scenario seeds a
  captain at capacity, one with stale GPS, one on a break and one offline, and none of them reach
  the list.
- **Then the other half:** the order is assigned through `AssignmentService`, the route is printed,
  a second order joins the same captain, and the rebuilt route shows both pickups collected before
  either drop-off. Finally the first customer's arrival time before and after, measured against
  `MAX_BATCH_DETOUR_MIN` — the promise the batch check made before the order was ever assigned.
  A breach printing here would mean the batch check and the route planner disagree.
- **Two things the command had to learn, both worth recording.**
  1. **It runs the queue inline.** The route plan is built by a queued job and a demo has no
     worker, so the first version assigned the order and printed "the captain has no route plan".
  2. **`--fresh` clears the replan locks, and without that the demo is not repeatable.**
     `RecomputeRoutePlan` is unique per captain for two minutes; a run that dispatched it to a real
     queue with no worker leaves the lock held, and the next run's recompute is swallowed as a
     duplicate — the captain is assigned an order and **silently** gets no route. `DemoCommandTest`
     runs the command twice in a row to keep that found.
- **What it deliberately does not do:** hide the rest of the fleet. It runs against whatever
  captains are in the database, so on a development database `DriverSeeder`'s captains share the
  list with the scenario's. That is the same query a dispatcher makes, and the
  nearest-versus-winner line adapts to whoever turns up.
- **Tests:** `DemoCommandTest` (5 — the pipeline reaches the end and the order really is assigned
  with a customer ETA; the claim is stated; a route is produced and then rebuilt for the second
  order; it can be run again immediately; running it twice without `--fresh` refuses rather than
  assigning an order twice). All 5 pass.
- **Scope:** `scripts/demo.md` + `php artisan dispatch:demo` that seeds §17–23 (C1–C4),
  prints the ranked list showing "closest ≠ fastest", assigns, then assigns a second order
  to the busy captain and prints the repaint with the customer-A delay ≤ limit.
- **Depends on:** T9.1.
- **Files:** `app/Console/Commands/Dispatch/DemoCommand.php`, `scripts/demo.md`,
  `tests/Feature/Dispatch/DemoCommandTest.php`.
- **Accept:** runs end-to-end on this machine with Redis + Fake engine — verified, exit code 0.

### T9.4 Desktop explanations `[x]` — 1 d
- **Done (2026-09-20):** `C:\Users\DELL\Desktop\Kapitano\dispatch-algorithm-explained\` — **143
  pages, every link resolving.** The folders mirror the project, so
  `app/Services/Dispatch/Ranker.php` is explained in `app/Services/Dispatch/Ranker.md`.
- **What was already there.** 121 pages covering Epics 1–4 had been written in earlier sessions
  (Redis, eligibility, presence and GPS, the settings table, the schema). This task added the
  README, the "how the simulation works" page the scope asks for, and one page per file for the
  parts that decide things: the suggestion pipeline, ranking, assignment, route plans, deviation,
  routing failures and metrics.
- **The README is the map.** The pipeline as a diagram from "order arrives" to "rebuilt while
  driving"; a *where to start reading* table that answers questions rather than listing files
  ("why was that captain first?" → Ranker → AdjustedEtaCalculator → EffectiveLocationResolver);
  the endpoint tables; the rules worth knowing before reading any code; and a section stating
  plainly what is **not** finished.
- **`how-the-simulation-works.md`** covers what the fake engine computes, the penalty table that
  lets a test make the closest captain the slow one, **what the simulation is not** (no roads, no
  traffic, no barriers — two points either side of a motorway read as 100 m apart), the ETA-speed
  placeholder and how to stop guessing, and exactly what changes the day a Google key arrives.
- **A mistake worth recording: the existing README was overwritten before it was read.** The
  folder is not under version control and there was no backup, so that content is gone. The 121
  pages themselves were untouched, and the rebuilt README indexes all of them — but the original
  text is lost. Look before writing over a file, including outside the repository.
- **Accept:** every README link resolves — checked by walking every `](…md)` in all 143 pages, 0
  broken.
- **Scope:** `C:\Users\DELL\Desktop\Kapitano\dispatch-algorithm-explained\` in the same
  style as the vehicle and order folders: README with the pipeline, one `.md` per file,
  function by function, plus a "how the simulation works" page.
- **Depends on:** T9.3.
- **Accept:** every README link resolves; written after full success.

---

## Order of execution

```
T1.1 → T1.2 → T1.3 → T1.4 → T1.5
T2.1 → T2.2 → T2.3
T3.1 → T3.2
T4.1 → T4.2 → T4.3 → T4.4
T5.1 → T5.2 → T5.3 → T5.4 → T5.5
T6.1 → T6.2
T7.1 → T7.2 → T7.3 → T7.4 → T7.5
T8.1
T9.1 → T9.2 → T9.3 → T9.4
```

## Known impacts on existing code (announced, not silent)

1. **Done in T5.5.** `OrderService::suggestCaptains()` was replaced by the Dispatch services;
   the URL, the permission and the response envelope stayed, the body grew.
   `OrderAssignmentApiTest` was reworked accordingly: busy captains with capacity now appear as
   `batchable` instead of being excluded. `assertCaptainIsAssignable()` **stays** until T6.1 —
   it is the assignment's own rule, and until the atomic capacity reservation exists it still
   refuses a busy captain the list is willing to suggest.
2. `DriverRepository::suggestableCaptains()` / `countReadyToAssign()` (dashboard stats)
   move to the new eligibility rule (MAX = 2, on_break, stale GPS).
3. `orders.pickup_*` columns become read-only mirrors of the first `order_pickups` row.
4. `.env`: `REDIS_CLIENT=predis`, `BROADCAST_CONNECTION=reverb`, `ROUTING_ENGINE=fake`.

**STOP — waiting for approval of this task list before Phase 2.**