Clarify Service Contracts And Security Invariants

src/serial_service.c

@@ -284,6 +284,7 @@ static void serial_event_task(void *context)
         poll_modem_state();
     }
 
+    /* Account for software TX abandoned on stop before acknowledging quiescence. */
     size_t discarded = (pending_size - pending_offset) +
                        xStreamBufferBytesAvailable(s_tx_stream);
     if (discarded > 0) {
@@ -431,6 +432,7 @@ static esp_err_t stop_locked(bool restore_static_mode)
         return ESP_OK;
     }
 
+    /* Keep the driver and buffers intact unless the I/O task acknowledges stop. */
     s_stop_requested = true;
     if (xSemaphoreTake(s_task_stopped, pdMS_TO_TICKS(SERIAL_STOP_TIMEOUT_MS)) != pdTRUE) {
         ESP_LOGE(TAG, "UART service task did not quiesce within %d ms", SERIAL_STOP_TIMEOUT_MS);
@@ -561,6 +563,7 @@ esp_err_t serial_service_stop(void)
 
     xSemaphoreTake(s_state_mutex, portMAX_DELAY);
     esp_err_t result = stop_locked(true);
+    /* Diagnostics may reclaim the port only after driver removal and safe GPIO restoration. */
     if (!s_running &&
         !uart_is_driver_installed(RS232_UART_PORT) &&
         rs232_port_get_owner() == RS232_PORT_OWNER_SERVICE) {
@@ -594,6 +597,7 @@ esp_err_t serial_service_apply_config(const serial_config_t *config)
     serial_config_t previous = s_config;
     bool restart = s_running;
 
+    /* Retain port ownership across restart; service buffers are discarded, not broker sessions. */
     esp_err_t result = ESP_OK;
     if (restart) {
         result = stop_locked(false);
@@ -602,6 +606,7 @@ esp_err_t serial_service_apply_config(const serial_config_t *config)
         s_config = *config;
         if (restart) {
             result = start_locked(false);
+            /* Retry the old configuration only while cleanup has not faulted ownership. */
             if (result != ESP_OK &&
                 rs232_port_get_owner() == RS232_PORT_OWNER_SERVICE) {
                 esp_err_t original_error = result;