MobilityOps/docs/fleet-ops-correction/vehicle-status-decision-table.md

Vehicle status decision table

Authoritative rationale for app/services/vehicle_status.py::evaluate_vehicle_status, the single evaluator shared by the data-quality scanner, the status-recommendation preview endpoint, and the transactional apply endpoint (section 8A). Scanner and resolver call the same function with the same freshly-gathered facts, so they can never disagree, and the recommendation is order-independent: resolving, deferring, or rejecting an unrelated issue never changes what this function returns for a vehicle, because it only reasons over the vehicle's and bookings' current state, never over issue history.

Facts gathered (gather_vehicle_status_facts)

All facts are re-queried from the database on every call, never cached and never derived from "does some other issue happen to be open":

Fact	Source
active_booking_refs	Bookings on this vehicle with status == "active"
overlapping_booking_pairs	Reserved/active bookings on this vehicle whose date ranges genuinely overlap
service_threshold_reached	vehicle.odometer_km >= vehicle.next_service_km
open_booking_overlap_issue_ref	The public_ref of a currently-open booking_overlap issue on this vehicle, if any (excluding the issue being resolved, via exclude_issue_id)

has_active_rental = at least one active booking. has_booking_conflict = an overlapping-booking pair exists, or an open booking_overlap issue references this vehicle.

Decision table

Current status	Active rental?	Service threshold reached?	Booking conflict?	Recommended status	Priority	recommendation_code	Safe to auto-apply?
any except maintenance	yes	no	no	rented (if not already)	1	vehicle.active_rental	yes
maintenance	yes	—	—	(none — manual review)	1	vehicle.manual_review_required	no
any	yes	yes	—	(none — manual review)	1	vehicle.manual_review_required	no
any	yes	—	yes	(none — manual review)	1	vehicle.manual_review_required	no
not maintenance	no	yes	—	maintenance	2	vehicle.service_threshold_reached	yes
maintenance	no	yes	—	(none — already correct)	2	vehicle.no_conflict	n/a
not blocked	no	no	yes	blocked	3	vehicle.booking_conflict	yes
blocked	no	no	yes	(none — already correct)	3	vehicle.no_conflict	n/a
rented	no	no	no	available	4	vehicle.rental_ended	yes
available / cleaning / blocked	no	no	no	(none — already correct)	4	vehicle.no_conflict	n/a
maintenance	no	no	no	(none — stays in maintenance)	4	vehicle.no_conflict	n/a
anything not covered above	—	—	—	(none — manual review)	5	vehicle.manual_review_required	no

Safe-status principles (section 8B) applied

• Maintenance + active booking never auto-resolves to rented. Being currently in maintenance is itself treated as a blocking fact (row 2 above) — an active booking is never proof the vehicle should be marked rented; it is a real contradiction that requires a human to investigate (e.g. was the vehicle released from the workshop without updating status, or is the booking itself stale).
• available + any booking never auto-resolves to rented silently past a real blocker. The rented recommendation only fires when there is no competing blocking fact (no service-threshold breach, no booking conflict, not already in maintenance).
• An open issue disappearing never auto-resolves to available. Leaving maintenance requires a human decision — this evaluator holds no fact that proves maintenance work is actually finished (no completed-service record is modelled), so a vehicle sitting in maintenance with no active rental and no other blocker stays vehicle.no_conflict (left alone) rather than being auto-promoted to available.
• Every branch re-derives facts; nothing is cached. blocking_reasons is always computed fresh from service_threshold_reached, has_booking_conflict, and the current status itself — never from a proxy like "is some other high-severity issue still open".

Statuses used

Only statuses that exist in the current domain model are referenced: available, rented, cleaning, maintenance, blocked. cleaning is never a recommendation target from this evaluator (no fact here proves cleaning is required or complete); it is only ever an input current_status that, absent any blocker, is left alone (vehicle.no_conflict).

Concurrency: recommendation token

compute_recommendation_token(vehicle, facts) hashes the vehicle's optimistic-lock version plus every fact the recommendation was based on (sha256, truncated to 16 hex chars). The preview endpoint returns this token; the apply endpoint recomputes it from freshly-gathered facts inside the same transaction and rejects the request (RECOMMENDATION_STALE) if it no longer matches — the frontend must never assume a previously-shown preview is still valid without server revalidation (section 8F).

MO-016: order independence

MO-016 carries both an open booking_overlap issue and an open vehicle_status_conflict issue at once (two overlapping reserved bookings). Because gather_vehicle_status_facts re-queries overlapping_booking_pairs and open_booking_overlap_issue_ref fresh every call, resolving the booking-overlap issue first vs. resolving the status-conflict issue first both converge on the same final vehicle status — see test_mo_016_status_conflict_recommendation_is_order_independent in backend/tests/test_data_quality.py.