Address review: complete the node-facing surface, wiring test, comment placement

- read_descriptor and notify_characteristic passthroughs join the frozen
  surface so the first migrated node can subscribe without extending the
  client; the comment now says which ops have callers today
- The choke-point test also validates through the public
  BLE_CLIENT_SCHEMA, so removing the cv.All wiring fails a test
- DOMAIN no longer sits between the BTstack comment and the constant it
  explains

esphome/components/ble_client/ble_client_gatt.h

@@ -83,15 +83,22 @@ class BLEClient : public Component,
   /// continuations must leave that stack first.
   void run_later(std::function<void()> &&f) { this->defer(std::move(f)); }  // NOLINT
 
-  // Backend ops for nodes and actions. read/write_descriptor have no caller
-  // yet; kept as the frozen node-facing surface (like on_notify/on_read_result).
+  // Backend ops for nodes and actions - the frozen node-facing surface.
+  // Only write_characteristic has an in-tree caller today; the rest exist so
+  // the first migrated node codes against a complete interface (subscribing
+  // means notify_characteristic plus a write_descriptor on the CCCD - the
+  // backend contract keeps the CCCD write the caller's responsibility).
   int write_characteristic(uint16_t handle, const uint8_t *data, uint16_t len, bool response) {
     return this->backend_->write_characteristic(handle, data, len, response);
   }
   int read_characteristic(uint16_t handle) { return this->backend_->read_characteristic(handle); }
+  int read_descriptor(uint16_t handle) { return this->backend_->read_descriptor(handle); }
   int write_descriptor(uint16_t handle, const uint8_t *data, uint16_t len) {
     return this->backend_->write_descriptor(handle, data, len);
   }
+  int notify_characteristic(uint16_t handle, bool enable) {
+    return this->backend_->notify_characteristic(handle, enable);
+  }
 
   // Automation callback registration.
   template<typename F> void add_on_connect_callback(F &&callback) {

esphome/components/bluetooth_connection/__init__.py

@@ -36,10 +36,10 @@ CODEOWNERS = ["@bdraco", "@jesserockz"]
 
 bluetooth_connection_ns = cg.esphome_ns.namespace("bluetooth_connection")
 
-# arduino-pico's prebuilt BTstack is compiled with MAX_NR_GATT_CLIENTS 1;
-# raising this needs an upstream change (the layer itself supports N).
 DOMAIN = "bluetooth_connection"
 
+# arduino-pico's prebuilt BTstack is compiled with MAX_NR_GATT_CLIENTS 1;
+# raising this needs an upstream change (the layer itself supports N).
 RP2_MAX_CONNECTIONS = 1
 
 # Slot limits for the hub platforms running the connection-capable proxy;

tests/component_tests/ble_client/test_validation.py

@@ -106,3 +106,6 @@ def test_legacy_node_choke_point_rejects_other_platforms() -> None:
     CORE.data.setdefault(KEY_CORE, {})[KEY_TARGET_PLATFORM] = PLATFORM_RP2
     with pytest.raises(cv.Invalid, match="not been migrated"):
         ble_client._legacy_engine_only(ID("x"))
+    # Through the public schema too, so removing the cv.All wiring fails here.
+    with pytest.raises(cv.Invalid, match="not been migrated"):
+        ble_client.BLE_CLIENT_SCHEMA({})