# SPEC-healer: Deterministisches Autohealing

Paket: `knaster.healer`.

## 1. Eingang

Alertmanager-Webhook (Version 4) an `POST /v1/healer/alertmanager`. Pro Alert werden `status` (firing/resolved), `labels`, `annotations` und `fingerprint` verarbeitet.

## 2. Regeln (`config/healer-rules.yaml`)

```yaml
rules:
  - id: slot-endpoint-down
    match: {alertname: SlotEndpointDown}          # alle Labels müssen gleich sein
    ladder:
      - {action: restart_container, params: {host: "{node}", container: "{container}"}, attempts: 2, cooldown: 5m}
      - {action: restart_vm,        params: {vmid: "{vmid}", pve_node: "{pve_node}"}, attempts: 1, cooldown: 15m}
      - {action: mark_slot,         params: {slot: "{slot}", status: degraded}, attempts: 1}
    on_exhausted: notify
    on_resolved: [{action: mark_slot, params: {slot: "{slot}", status: ok}, only_if_set_by_healer: true}]
```

`{label}` wird aus den Alert-Labels ersetzt. Fehlt ein Label, wird die Stufe übersprungen und im Ergebnis vermerkt.

## 3. Ablauf pro Alert (firing)

1. Erste passende Regel suchen (Reihenfolge der Datei). Passt keine, wird nur benachrichtigt (`unmatched`).
2. Zustand pro `(rule_id, fingerprint)`: Versuche pro Stufe und Zeitpunkt der letzten Aktion.
3. Ist der Cooldown der letzten Aktion noch nicht vorbei, passiert nichts (`cooldown`).
4. Sonst wird die erste Stufe genommen, deren Versuchsbudget noch nicht erschöpft ist. Vor der Ausführung entscheidet die **Policy** (SPEC-maintenance §2): Bei `auto` wird ausgeführt, bei `approve` entsteht ein Vorschlag (Quelle `healer`) und die Stufe gilt als verbraucht.
5. Sind alle Stufen erschöpft, wird einmalig benachrichtigt (`exhausted`).
6. Ein globaler Schutz begrenzt die Infrastruktur-Aktionen auf `max_actions_per_hour` (Standard 10). Darüber wird nur noch benachrichtigt.

**resolved:** Die `on_resolved`-Aktionen laufen, und der Zustand des Fingerprints wird gelöscht.

## 4. Treiber (`knaster.healer.drivers`)

| Aktion | Treiber | API |
|---|---|---|
| `restart_container` | Portainer | `POST /api/endpoints/{endpoint}/docker/containers/{container}/restart` |
| `restart_vm` | Proxmox | `POST /api2/json/nodes/{pve_node}/qemu/{vmid}/status/reboot` |
| `reboot_host` | Proxmox | `POST /api2/json/nodes/{pve_node}/status` (`command=reboot`) |
| `mark_slot` | Registry | Laufzeitzustand |
| `notify` | Webhook (n8n) | `POST NOTIFY_WEBHOOK_URL` |

Alle Treiber haben einen **Dry-Run**-Modus (Standard: an). Ein globales `KNASTER_DRY_RUN=false` schaltet die Ausführung frei, zusätzlich muss der Treiber pro Aktion in `config/healer-rules.yaml` unter `enabled_actions` aufgeführt sein.

## 5. Mitgelieferte Alerts (`deploy/prometheus/alerts.yml`)

`SlotEndpointDown`, `SlotCanaryFailing`, `GpuXidError`, `GpuTemperatureHigh`, `VllmKvCacheSaturated`, `NodeDown`, `DiskAlmostFull`.