ACT-001: actuator-first sensor lifecycle

docs/ml_api.md

@@ -1,7 +1,7 @@
 # ML-Serving-API
 
 Diese Dokumentation beschreibt die REST-Endpunkte der aktuellen
-Modell-Artefakt- und Vorhersage-Schnittstelle.
+Modell-Artefakt-, Vorhersage- und aktor-zentrierten Lifecycle-Schnittstelle.
 
 Das Serving verwendet ein lokal trainiertes statistisches Baseline-Modell.
 
@@ -15,6 +15,8 @@ Das Serving verwendet ein lokal trainiertes statistisches Baseline-Modell.
 - Einzelvorhersage: `/predict`
 - Batchvorhersage: `/batch`
 
+Die aktor-zentrierte API liegt unter `/v1/actuators`.
+
 Der Standard-Start erfolgt über `uvicorn app.main:app`, danach stehen HA- und
 ML-Routen in derselben Anwendung bereit.
 
@@ -168,14 +170,45 @@ Batch-Vorhersage für mehrere Sensorwerte.
 - `422 Unprocessable Content`: Sensor wird vom Modell nicht unterstützt oder Eingabe ist ungültig.
 - `503 Service Unavailable`: Registry ist nicht initialisiert.
 
+## Aktuator-zentrierte API
+
+### `GET /v1/actuators/discovery`
+
+Listet unterstützte Aktuatoren mit angereicherter HA-Metadatenbasis.
+
+### `POST /v1/actuators`
+
+Registriert einen Aktuator, ermittelt passende numerische Sensoren und
+Kontext-Entities, trainiert bei ausreichender History automatisch ein Modell und
+liefert Zuordnung, Confidence, Evidenz und Lifecycle-Status zurück.
+
+**Request**
+```json
+{
+  "actuator_entity_id": "light.abstellkammer",
+  "enabled": true
+}
+```
+
+### `POST /v1/actuators/{actuator_entity_id}/override`
+
+Persistiert manuelle Overrides. Diese haben Vorrang vor der automatischen
+Heuristik und überstehen Neustarts.
+
+### `POST /v1/actuators/reconciliation/run`
+
+Führt eine sichere globale Reconciliation aus. Die periodische Add-on-Schleife
+ruft denselben idempotenten Ablauf auf, startet aber keine Services in Home
+Assistant.
+
 ## Betrieb
 
-Die produktive App lädt Artefakte aus `SILLYHOME_MODEL_STORE`. Neue Artefakte
-werden über `/ml/retrain`, `RetrainingService` oder direkt über
-`ModelRegistry.register(...)` registriert. Die Registry speichert validiertes
-JSON atomisch und lädt es beim Neustart. Die API sollte nur in einem
-vertrauenswürdigen Netz oder hinter einem authentifizierenden Reverse Proxy
-erreichbar sein.
+Die produktive App lädt Artefakte aus `SILLYHOME_MODEL_STORE`. Aktuator-,
+Override- und Reconciliation-Zustände liegen atomisch in
+`SILLYHOME_ACTUATOR_STORE`. Neue Artefakte werden über `/ml/retrain`,
+`RetrainingService` oder den aktor-zentrierten Lifecycle registriert. Die API
+sollte nur in einem vertrauenswürdigen Netz oder hinter einem
+authentifizierenden Reverse Proxy erreichbar sein.
 
 ## Verweise