# Portabilitaet: UNIVERSAL
# Zuletzt validiert: 2026-02-15 (Claude)
# Naechste Pruefung: 2026-08-15
# Quellen: [ARCHITECTURE.md], [RecludOS Konzept], [BACH Design-Philosophie]

SELBSTHEILUNG (SELF-HEALING) IN BACH
====================================

Stand: 2026-02-15

WAS IST SELBSTHEILUNG?
----------------------
Selbstheilung ist ein Kernprinzip von BACH, das automatische Konsistenzpruefung
und Reparatur von Systemzustaenden ermoeglicht. Das System erkennt Inkonsistenzen
(fehlende Verlinkungen, verwaiste Dateien, Konfigurationsfehler) und repariert
diese automatisch - aehnlich wie das Immunsystem eines Organismus.

ABGRENZUNG
----------
Nicht zu verwechseln mit:
  - Auto-Repair (Benutzer initiiert Reparatur)
  - Logging (nur Fehler dokumentieren)
  - Self-Service (Benutzer repariert manuell)

Selbstheilung ist PROAKTIV und AUTOMATISCH.

ARTEN DER SELBSTHEILUNG
-----------------------

1. STRUKTURELLE HEILUNG
   Problem: Verwaiste Dateien, fehlende _index.txt
   Beispiel: wiki/thema/ ohne _index.txt
   Loesung: System erstellt leere _index.txt automatisch
   Trigger: Startup, validate-Befehl, manueller Health-Check

2. REFERENTIELLE HEILUNG
   Problem: Tote Links (Verweis auf nicht-existente Datei)
   Beispiel: wiki/_index.txt verweist auf deleted_article.txt
   Loesung: Verweis wird entfernt oder aktualisiert
   Trigger: Health-Check, Skill-Validierung

3. KONFIGURATIONS-HEILUNG
   Problem: Inkompatible Werte in Config-Dateien
   Beispiel: Outdated API-Version in settings.txt
   Loesung: Automatisches Upgrade auf Schema-Version
   Trigger: Startup mit Versionspruefen

4. METADATEN-HEILUNG
   Problem: Veraltete oder fehlende Validierungsmetadaten in Wiki-Artikeln
   Beispiel: "Zuletzt validiert: 2023-01-01" (ueber 2 Jahre alt)
   Loesung: Automatische Markierung zum Ueberpruefen
   Trigger: Wiki-Crawler, quarterly Review

MECHANISMEN
-----------

**Log & Heal Pattern**
  1. System fuehrt Konsistenzcheck durch
  2. Fehler wird in health_log.db dokumentiert
  3. Automatische Reparatur wird versucht
  4. Erfolg/Fehler wird geloggt
  5. Bei Fehlschlag: Alert an Operator

**Watchdog Pattern**
  - Daemon (Background-Prozess) ueberwacht kritische Dateien
  - Bei Aenderung: Validierungslogik wird ausgefuehrt
  - Beispiel: Wenn handler_config.txt aendert -> Neustart bach.py

**Recovery Point Pattern**
  - Vor kritischen Operationen: Backup erstellen
  - Bei Fehler: Automatisches Rollback auf Recovery Point
  - Beispiel: Ordner-Flattening mit Undo-Stack

IMPLEMENTIERUNG IN BACH
-----------------------

Wo ist Selbstheilung implementiert?

  bach.py               Main CLI (Startup-Heilung)
  core/health_check.py  Health-Audit-Engine
  core/validator.py     Struktur- & Schema-Validator
  db/schema_migrate.py  Database-Upgrade mit Rollback
  skills/healing/       Dedicated Healing Skills
  agents/health-agent.* Health-Monitoring Agent

BEST PRACTICES
--------------

1. TRANSPARENZ
   - Heale nicht still. Log die Reparatur.
   - Benutzer sollte durch `bach status` sehen "Fixed: 3 broken links"

2. IDEMPOTENZ
   - Heilung muss mehrfach sicher sein
   - `heal(); heal()` = `heal()` (kein doppelter Effekt)

3. KONSERVATIVISMUS
   - Im Zweifelsfall: Nicht heilen, sondern warnen
   - Kritische Daten: Nur mit Benutzer-Bestaetigung heilen

4. VERSIONIERUNG
   - Jede Heilung hat Versions-Nummer
   - Ermoeglicht Rollback: `bach heal --version 2024-01`

5. AUDIT-TRAIL
   - health_log.db speichert: Wann, Was, Warum, Wer (welcher Agent)
   - Fuer Forensik und Debugging

BEISPIELE AUS DER PRAXIS
------------------------

Beispiel 1: Wiki-Konsistenz
  Problem: wiki/thema/ Ordner ohne _index.txt
  Code:
    if os.path.isdir(f"wiki/{subdir}") and not os.path.exists(f"wiki/{subdir}/_index.txt"):
        create_blank_index(f"wiki/{subdir}")
        log_healing("wiki_index_created", subdir)

Beispiel 2: Verwaiste Dateien
  Problem: Datei in BACH-System aber nicht in _index.txt erwaehnt
  Loesung: Drei Strategien:
    a) Stil-still: Datei bleibt unerwaehnt (OK fuer Backups)
    b) Warnung: "Warning: Orphaned file detected"
    c) Automatisch hinzufuegen: Zu _index.txt adden

Beispiel 3: Zirkulaere Verweise
  Problem: A verweist auf B, B verweist auf A (einfacher Kreis)
  Loesung: Cycle-Detection im Graph, Warning, Verweis brechen

FEHLER-SZENARIEN
----------------

Was kann schiefgehen?

  Szenario 1: Zu aggressive Heilung
    Symptom: Wichtige Datei wurde gel"oscht, obwohl sie nur verloren war
    Verhinderung: Nur loechen mit Bestaetigung, Trash-Ordner nutzen

  Szenario 2: Unvollstaendige Heilung
    Symptom: Link repariert, aber Quelle bleibt kaputt
    Verhinderung: Transaktionale Heilung (alles-oder-nichts)

  Szenario 3: Heilungs-Loop
    Symptom: Heilung erzeugt neuen Fehler, wird wieder geheilt (infinite loop)
    Verhinderung: Schleife detektieren, max 3 Iterationen pro Fehler

SIEHE AUCH
----------
  wiki/was_ist_bach.txt         BACH Philosophie (Herkunft von Self-Healing)
  docs/architecture.md           Technische Architektur
  docs/help/health-check.txt          Health-Check Befehl (CLI)
  docs/help/heal.txt                  Heal Befehl (Manuelle Heilung)
