Add exit_rule_definition/README.md

exit_rule_definition/README.md

@@ -0,0 +1,217 @@
+# Deterministische Exit-Regel für Stabilitätsbewertung von Systemmetriken
+
+## Purpose
+
+Definition einer deterministischen Exit-Regel zur Bewertung der Stabilität von unpinned Systemmetriken über mehrere Runs.
+
+**Problemstellung:** Fehlende definierte Exit‑Bedingungen führen zu inkonsistenten Entscheidungen und erschweren die Automatisierung der Stabilitätsbewertung.
+
+**Ziele:**
+- Überwachung der Stabilität über eine Zeitreihe von Runs
+- Einführung eines reproduzierbaren Entscheidungsmechanismus für den Statuswechsel (z. B. WARN → PARTIAL‑BLOCK)
+- Vermeidung von Reaktionen auf zufällige Schwankungen
+
+## Kontext & Hintergrund
+
+Messwerte pro Run, getrennt nach pinned und unpinned Strata.
+
+**Gruppierung:**
+- pinned
+- unpinned
+
+**Trace-Metadaten / zusätzliche Tags:**
+- policy_hash
+- setup_fingerprint (policy_hash + runner_image + kernel + python + gate_version)
+
+**Domänenkontext:**
+- Kontinuierliche Stabilitätsüberwachung in CI-Umgebungen
+- Bewertung temporaler Metriken in sequentiellen Testläufen
+
+**Outlier-Definition:**
+- Methode: Visuelle und metrische Auswertung von Warnraten und negativen Δt-Anteilen.
+- Beschreibung: Messpunkte mit außergewöhnlich hohen warn_rate oder Δt<0 werden als potenzielle Instabilitäten betrachtet.
+- Metrik: warn_rate, unknown_rate, Anteil Δt<0
+
+**Motivation:**
+- Vermeidung unkontrollierten Umgebungs-Drifts
+- Reproduzierbare, deterministische Bewertungslogik
+- Trennung zwischen stabiler Referenz (pinned) und Testbereich (unpinned)
+
+## Methode / Spezifikation
+
+**Übersicht:**
+- Die Exit-Regel beschreibt ein deterministisches Verfahren, das nach N=3 aufeinanderfolgenden Runs angewendet wird.
+- Bewertet werden drei Kennzahlen für unpinned-Messungen.
+
+**Algorithmen / Verfahren:**
+- Berechne warn_rate, unknown_rate und Anteil Δt<0 pro Run.
+- Erzeuge Zeitreihe über N=3 aufeinanderfolgende Runs.
+- Vergleiche jede Metrik mit den Schwellen X, Y, Z.
+- Wenn alle drei Werte unter den Schwellen liegen → Status bleibt WARN.
+- Andernfalls → Einleitung Eskalationsprüfung.
+
+### Bootstrap-Übersicht
+
+Bootstrap-Resampling kann zur Stabilitätsprüfung der Kennzahlen-Verteilung verwendet werden.
+
+**Zielgrößen:**
+- Varianz der warn_rate
+- Varianz des Anteils Δt<0
+
+### Resampling-Setup
+
+- unpinned
+
+**Stichprobeneinheit:** Run
+
+**Resampling-Schema:**
+- Rolling window über die letzten 3 Runs
+- Bootstrap über Metrikwerte innerhalb jedes Windows
+
+**Konfidenzintervalle:**
+- Niveau: 0.95
+- Typ: percentile
+- Ableitung: aus wiederholtem Bootstrap über Run-Mittelwerte
+
+### Abgeleitete Effektgrößen
+
+**Risk Difference (Differenz der Raten):**
+- Definition: Differenz der Proportion von Δt<0 zwischen zwei Runs oder Zuständen.
+- Bootstrap: Berechnung des Konfidenzintervalls der Differenz durch Bootstrap über Stichproben der Einzelwerte.
+
+**Risk Ratio:**
+- Definition: Verhältnis der Warnhäufigkeiten (warn_rate) zwischen Runs.
+- Bootstrap: Abschätzung eines 95%-Konfidenzintervalls für das Verhältnis durch resampling der Fallzahlen.
+
+### C-State-Kontrolle
+
+**Ziel:** Sicherstellen, dass Unterschiede nicht durch Energiesteuerungszustände (C‑States) verursacht werden.
+
+**Vorgehen:**
+- Korrelieren von C‑State-Anteilen mit Δt<0 und warn_rate.
+- Ausschluss signifikanter drifthafter Trends über Runs.
+
+## Input / Output
+
+### Input-Anforderungen
+
+**Hardware:**
+- konstante Runner-Instanz ohne dynamische Frequenzskalierung
+
+**Software:**
+- stabile Gate- und Python-Versionen
+- identischer Kernel pro Testserie
+
+**Konfiguration:**
+- policy_hash fixiert pro Run-Serie
+- setup_fingerprint validiert nach jedem Durchlauf
+
+### Erwartete Rohdaten
+
+**Felder pro Run:**
+- run_id
+- stratum
+- warn_rate
+- unknown_rate
+- delta_t_negative_share
+- policy_hash
+- setup_fingerprint
+
+**Formatbeispiele:**
+- {run_id:4, stratum:'unpinned', warn_rate:0.07, unknown_rate:0.01, delta_t_negative_share:0.03}
+
+**Trace-Daten:**
+- Format: CSV oder JSON mit aggregierten Run-Metriken
+- Hinweis: Lauf-identische Fingerprints dienen der Konsistenzprüfung
+
+### Analyse-Ausgaben
+
+**Pro Gruppe / pro Governor:**
+- Zeitreihe der warn_rate
+- Zeitreihe des Anteils Δt<0
+- Stabilitätsindikatoren pro Run-Gruppe
+
+**Vergleichsausgaben:**
+- pinned vs unpinned
+  - Δ: warn_rate_diff
+  - CI(Δ): [low, high]
+  - RR: warn_rate_ratio
+  - CI(RR): [low, high]
+
+- C-State-Korrelation: Korrelationskoeffizient zwischen aktivem C‑State und Metrikabweichungen
+- Trace-Muster: Erkennung stabiler Fingerprint-Sequenzen über Runs
+
+## Workflow / Nutzung
+
+**Analyse-Workflow:**
+- Daten aus drei jüngsten Runs sammeln.
+- Schwellen X, Y, Z aus definierter Parameterdatei einlesen.
+- Berechnungsmodul für Kennzahlen ausführen.
+- Ergebnis mit Exit-Regel evaluieren.
+- Statusentscheidung dokumentieren (WARN / Eskalation).
+
+### Trace-Template-Anforderungen
+
+**Ziel:** Reproduzierbare Run-Struktur mit stabilen Fingerprint-Metadaten.
+
+**Erforderliche Tags & Metadaten:**
+- policy_hash
+- setup_fingerprint
+- run_id
+
+**trace-cmd-Setup:**
+- Run-Setup einfrieren bevor Serie startet.
+- Nach jedem Lauf fingerprint prüfen.
+
+**Run-Design für Contributors:**
+- Mindestens drei konsekutive Runs mit identischem Setup.
+- Pinned als Referenz immer miterheben.
+
+## Interpretation & erwartete Ergebnisse
+
+**Kernbefunde:**
+- Unpinned stabilisiert sich über mehrere Runs.
+- Warn- und Unknown-Raten bleiben innerhalb definierter Schwellen.
+- Δt<0 Anteil zeigt keine anhaltenden Ausreißer mehr.
+
+**Implikationen für Experimente:**
+- Die deterministische Exit-Regel kann für automatisierte Stabilitätsprüfungen eingesetzt werden.
+- Pinned dient zuverlässig als Kontrollgruppe.
+
+**Planungsziel:**
+- Ziel: Entscheidung über Eskalation oder Fortführung basierend auf stabilen Metriken.
+- Vorgehen:
+  - Analyse nach Run #6 zur finalen Regelvalidierung.
+  - Festlegung finaler Schwellenwerte X/Y/Z.
+
+## Limitationen & Fallstricke
+
+**Datenbezogene Limitationen:**
+- Kleine Stichprobenumfänge (N=3) erhöhen Varianzrisiko.
+- Änderungen im Laufzeit-Environment können Fingerprint trotz stabiler Policy verändern.
+
+**Bootstrap-spezifische Limitationen:**
+- Bootstrap-Konfidenzintervalle instabil bei wenigen Runs.
+- Schätzungen können bei extremer Schiefe unpräzise sein.
+
+**Kausalität & Generalisierbarkeit:**
+- Korrelation der Metriken belegt keine Kausalität.
+- Regel gilt nur für getestete Systemtopologie.
+
+**Praktische Fallstricke:**
+- Zu enge Schwellen führen zu Fehlalarmen.
+- Nichtbeachtung des pinned-Control-Stratums verzerrt Stabilitätseindruck.
+
+## Nächste Schritte & Erweiterungen
+
+**Geplante Experimente:**
+- Durchführung von Run #5 und #6 zur Validierung der Draft-Regel.
+
+**Analyseziele:**
+- Überprüfung der Schwellenrobustheit bei realen Fluktuationen.
+
+**Regression & Modellierung:**
+- Modellierung der Zeitreihenentwicklung der warn_rate zur Prognose künftiger Stabilität.
+
+**Community-Beiträge:**
+- Diskussion und Validierung der Exit-Regel im Gate‑Lab‑Forum.