diff --git a/plugins/endpoints/api/routes.py b/plugins/endpoints/api/routes.py
index 11b6f6c3..53afb2b0 100644
--- a/plugins/endpoints/api/routes.py
+++ b/plugins/endpoints/api/routes.py
@@ -685,6 +685,17 @@ def _drive_letter(value):
 # Worst-first. The panel shows the worse of the two sources for a drive, so a
 # share that one source calls OK and the other calls Unavailable is reported as
 # Unavailable: a drive that is broken in either view is broken for the operator.
+#
+# WARNING - ranks must stay DISTINCT across statuses that can genuinely differ.
+# _worse_drive_status resolves by min(), which breaks a tie by argument order,
+# so two statuses sharing a rank make the verdict depend on which SOURCE
+# happened to report which - the same drive reads healthy or broken based on
+# enumeration order. Deliberate synonyms are fine (disconnected/unavailable,
+# ok/connected) because either answer is the same answer. Adding a NEW status at
+# an existing rank is not. test_which_source_reported_a_status_does_not_change
+# _the_verdict in tests/test_plugins/test_endpoints_mapped_drives.py asserts
+# both directions of each pair and is what catches this; the single-direction
+# tests stay green through it.
 _DRIVE_STATUS_RANK = {
     'unavailable': 0,
     'disconnected': 0,