From 2b9b1d12e62c371260d8b60312284e4da2f37b3b Mon Sep 17 00:00:00 2001
From: "J. Nick Koston" <nick@koston.org>
Date: Wed, 11 Jun 2025 13:32:47 -0500
Subject: [PATCH] lets be sure

---
 esphome/components/esp32_ble/ble.cpp     |  1 +
 esphome/components/esp32_ble/ble_event.h | 20 ++++++++++++++++++++
 2 files changed, 21 insertions(+)

diff --git a/esphome/components/esp32_ble/ble.cpp b/esphome/components/esp32_ble/ble.cpp
index 3b561883f8..41e4ddc930 100644
--- a/esphome/components/esp32_ble/ble.cpp
+++ b/esphome/components/esp32_ble/ble.cpp
@@ -339,6 +339,7 @@ void ESP32BLE::loop() {
                    gap_event == ESP_GAP_BLE_SCAN_STOP_COMPLETE_EVT) {
           // All three scan complete events have the same structure with just status
           // The scan_complete struct matches ESP-IDF's layout exactly, so this reinterpret_cast is safe
+          // This is verified at compile-time by static_assert checks in ble_event.h
           // The struct already contains our copy of the status (copied in BLEEvent constructor)
           ESP_LOGV(TAG, "gap_event_handler - %d", gap_event);
           for (auto *gap_handler : this->gap_event_handlers_) {
diff --git a/esphome/components/esp32_ble/ble_event.h b/esphome/components/esp32_ble/ble_event.h
index effcb43aea..ae988f2a2a 100644
--- a/esphome/components/esp32_ble/ble_event.h
+++ b/esphome/components/esp32_ble/ble_event.h
@@ -13,6 +13,26 @@
 namespace esphome {
 namespace esp32_ble {
 
+// Compile-time verification that ESP-IDF scan complete events only contain a status field
+// This ensures our reinterpret_cast in ble.cpp is safe
+static_assert(sizeof(esp_ble_gap_cb_param_t::ble_scan_param_cmpl_evt_param) == sizeof(esp_bt_status_t),
+              "ESP-IDF scan_param_cmpl structure has unexpected size");
+static_assert(sizeof(esp_ble_gap_cb_param_t::ble_scan_start_cmpl_evt_param) == sizeof(esp_bt_status_t),
+              "ESP-IDF scan_start_cmpl structure has unexpected size");
+static_assert(sizeof(esp_ble_gap_cb_param_t::ble_scan_stop_cmpl_evt_param) == sizeof(esp_bt_status_t),
+              "ESP-IDF scan_stop_cmpl structure has unexpected size");
+
+// Verify the status field is at offset 0 (first member)
+static_assert(offsetof(esp_ble_gap_cb_param_t, scan_param_cmpl.status) ==
+                  offsetof(esp_ble_gap_cb_param_t, scan_param_cmpl),
+              "status must be first member of scan_param_cmpl");
+static_assert(offsetof(esp_ble_gap_cb_param_t, scan_start_cmpl.status) ==
+                  offsetof(esp_ble_gap_cb_param_t, scan_start_cmpl),
+              "status must be first member of scan_start_cmpl");
+static_assert(offsetof(esp_ble_gap_cb_param_t, scan_stop_cmpl.status) ==
+                  offsetof(esp_ble_gap_cb_param_t, scan_stop_cmpl),
+              "status must be first member of scan_stop_cmpl");
+
 // Received GAP, GATTC and GATTS events are only queued, and get processed in the main loop().
 // This class stores each event with minimal memory usage.
 // GAP events (99% of traffic) don't have the vector overhead.