run_stability_analysis/exit_rule_definition/README.md

# 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.