feat: define matchmaking state transitions

server/contracts/v1/test_contracts.py

@@ -13,6 +13,7 @@ class ContractTest(unittest.TestCase):
     def setUpClass(cls):
         cls.openapi = json.loads((ROOT / "openapi.json").read_text())
         cls.events = json.loads((ROOT / "websocket-events.json").read_text())
+        cls.transitions = json.loads((ROOT / "state-transitions.json").read_text())
 
     def test_openapi_is_versioned_and_has_core_surfaces(self):
         self.assertEqual(self.openapi["openapi"], "3.1.0")
@@ -58,6 +59,27 @@ class ContractTest(unittest.TestCase):
         self.assertNotIn("web_api_ticket", serialized)
         self.assertNotIn("relay_ticket", serialized)
 
+    def test_state_machine_has_explicit_recovery_and_terminal_edges(self):
+        for resource, states in self.transitions["resource_states"].items():
+            graph = self.transitions["transitions"][resource]
+            self.assertEqual(set(states), set(graph))
+            for state, targets in graph.items():
+                self.assertTrue(set(targets) <= set(states))
+                if state in {"COMPLETED", "CANCELLED", "EXPIRED", "FAILED"}:
+                    self.assertEqual(targets, [], state)
+
+        queue = self.transitions["transitions"]["queue_ticket"]
+        self.assertIn("QUEUED", queue["PROPOSED"])
+        self.assertIn("QUEUED", queue["ACCEPTED"])
+        self.assertEqual(
+            self.transitions["mutation_rules"]["same_key_same_payload"],
+            "return_original_result_without_new_revision",
+        )
+        self.assertEqual(
+            self.transitions["mutation_rules"]["same_key_different_payload"],
+            "reject_conflict_without_state_change",
+        )
+
 
 if __name__ == "__main__":
     unittest.main()