Add results_documentation/README.md

results_documentation/README.md

@@ -0,0 +1,176 @@
+# Ergebnisdokumentation der Laufanalyse (Run #3)
+
+## Purpose
+
+Analyse der Timing-Differenzen und Zustandseffekte zwischen pinned und unpinned Läufen zur Beurteilung der Policy‑Entscheidung.
+
+**Problemstellung:** Unklare Zuordnung der Warn‑Rate‑Spitzen zu spezifischen Timing‑Zuständen in unpinned Läufen verursachte unpräzise Systementscheidungen.
+
+**Ziele:**
+- Validierung der Hypothese, dass der WARN‑Spike durch unpinned + Δt < 0 verursacht wurde
+- Überprüfung der Auswirkung des unpinned‑2‑Phase‑Read‑Delay‑Commits auf die Δt‑Verteilung
+- Definition einer versionierbaren Entscheidungsregel für zukünftige Runs
+
+## Kontext & Hintergrund
+
+Messdaten aus mehreren Runs mit identischen policy_hash‑Werten, Gruppierung nach pinned vs. unpinned und Δt‑Status.
+
+**Gruppierung:**
+- pinned / unpinned
+- Δt ≥ 0 / Δt < 0
+
+**Trace-Metadaten / zusätzliche Tags:**
+- t_index_visible
+- t_gate_read
+- policy_hash
+
+**Domänenkontext:**
+- Timing‑Optimierung in Systementscheidungsprozessen
+- Policy‑Regler‑Verfeinerung basierend auf Δt‑Verteilungen
+
+**Outlier-Definition:**
+- Methode: Δt‑Signum‑Vergleich
+- Beschreibung: Negative Δt werden als zeitlich rückläufige, potenziell fehlerhafte Ereignisse klassifiziert.
+- Metrik: Δt = t_index_visible − t_gate_read
+
+**Motivation:**
+- Reduktion von False Positives in Warn‑Entscheidungen
+- Sicherung der Vergleichbarkeit zwischen Runs
+- Stabilisierung der Systemantwort durch konsistente Timing‑Verhältnisse
+
+## Methode / Spezifikation
+
+**Übersicht:**
+- Analyse der Kennzahlen warn_rate und unknown_rate getrennt nach pinned und unpinned Läufen
+- Berechnung und Vergleich der Δt‑Verteilungen zwischen Runs #2 und #3
+- Erstellung einer 2×2‑Matrix: pinned/unpinned × Δt ≥ 0 / Δt < 0 zur Identifikation dominanter Quadranten
+
+**Algorithmen / Verfahren:**
+- Vergleich des policy_hash zwischen Runs zur Sicherstellung identischer Bedingungen
+- Aggregierte Auswertung von Δt‑Signen zur Quadrantenermittlung
+- Proportionsvergleich der Quadrantenanteile ( insbesondere unpinned & Δt < 0)
+
+### Abgeleitete Effektgrößen
+
+**Risk Difference (Differenz der Raten):**
+- Definition: Differenz der negativen Δt‑Anteile zwischen Run #2 und Run #3 innerhalb des unpinned‑Stratums.
+- Bootstrap: Optionales Bootstrap‑Resampling möglich, zur robusten Schätzung von Konfidenzintervallen über Quadrantenanteile.
+
+**Risk Ratio:**
+- Definition: Verhältnis der Wahrscheinlichkeit für Δt < 0 im unpinned‑Stratum zwischen Run #2 und Run #3.
+- Bootstrap: Bootstrap‑Resampling zur Bestimmung der Unsicherheitsbreite implementierbar.
+
+## Input / Output
+
+### Erwartete Rohdaten
+
+**Felder pro Run:**
+- t_index_visible
+- t_gate_read
+- policy_hash
+- pinned_flag
+- warn_rate
+- unknown_rate
+
+**Formatbeispiele:**
+- {run_id:3, pinned: false, t_index_visible: 171.253, t_gate_read: 171.268, policy_hash: 'd9acb2', warn_rate: 0.042}
+
+**Trace-Daten:**
+- Format: strukturierte Logdateien oder CSV‑Exports pro Lauf
+- Hinweis: Zeitstempel konsistent in gleicher Auflösung (z. B. ns‑basiert).
+
+### Analyse-Ausgaben
+
+**Pro Gruppe / pro Governor:**
+- warn_rate
+- unknown_rate
+- Anteile pro Δt‑Quadrant
+
+**Vergleichsausgaben:**
+- Run #2 (unpinned) vs Run #3 (unpinned)
+  - Δ: Δ Anteil Δt < 0 = −x%
+  - CI(Δ): 95% CI [−y%, −z%]
+  - RR: r ≈ 0.XX
+  - CI(RR): 95% CI [a, b]
+
+- Trace-Muster: Quadrantenmatrix‑Visualisierung zur schnellen Erkennung dominanter Ausreißerzonen
+
+## Workflow / Nutzung
+
+**Analyse-Workflow:**
+- Run-Datensatz mit Referenzpolicy (Run #2) vergleichen
+- policy_hash‑Abgleich durchführen
+- Δt‑Differenzen pro Stratum berechnen
+- 2×2‑Matrix erstellen
+- Differenzen und Verteilungen bewerten
+- Policy‑Entscheidung dokumentieren
+
+### Trace-Template-Anforderungen
+
+**Ziel:** Reproduzierbare Umgebung mit identischem timing‑logging setup
+
+**Erforderliche Tags & Metadaten:**
+- policy_hash
+- run_id
+- t_index_visible
+- t_gate_read
+
+**trace-cmd-Setup:**
+- logging‑frequenz definieren
+- timestamp precision auf Nanosekundenebene sicherstellen
+
+**Run-Design für Contributors:**
+- mindestens drei konsekutive Runs mit gleichem policy_hash durchführen
+- keine zusätzlichen Messgrößen zwischen den Runs einführen
+
+## Interpretation & erwartete Ergebnisse
+
+**Kernbefunde:**
+- Deutlicher Rückgang negativer Δt im unpinned‑Stratum
+- Pinned‑Stratum bleibt unverändert
+- Quadrant unpinned & Δt < 0 signifikant geschrumpft
+- Mechanismus validiert: 2‑Phase‑Delay beeinflusst Ursache, nicht Symptom
+
+**Implikationen für Experimente:**
+- Beibehaltung des unpinned‑Delay und MODE=warn
+- Einführung einer versionierbaren Exit‑Regel für die Policy
+- Ziel: stabile Warnraten ohne höhere Fehlklassifikation
+
+**Planungsziel:**
+- Ziel: Reduktion von Fehlalarmen durch präzise Timing‑Stratifizierung
+- Vorgehen:
+  - nur noch Warnungen bei Δt < 0 im unpinned‑Stratum nach Stabilitätsnachweis
+  - Verifikation über drei Folgeruns mit konstantem policy_hash
+
+## Limitationen & Fallstricke
+
+**Datenbezogene Limitationen:**
+- Run‑Drift durch unbewusste Parameteränderungen möglich
+- Δt‑Schwankungen empfindlich gegenüber Messauflösung
+
+**Bootstrap-spezifische Limitationen:**
+- Bootstrap‑CI‑Breite abhängig von Run‑Anzahl und Δt‑Varianz
+
+**Kausalität & Generalisierbarkeit:**
+- Ergebnisse spezifisch für das verwendete policy_hash‑Setup
+- keine direkte Übertragbarkeit auf abweichende Hardware‑Konfigurationen
+
+**Praktische Fallstricke:**
+- Fehlende Reproduzierbarkeit bei neuen Seeds
+- Verwechslung von Symptom (Δt‑Verzögerung) und Ursache (Scheduling‑Effekt)
+
+## Nächste Schritte & Erweiterungen
+
+**Geplante Experimente:**
+- Durchführung von zwei bis drei weiteren Läufen mit identischen Bedingungen
+- Vergleich der 2×2‑Drift‑Matrix als Zeitreihe
+
+**Analyseziele:**
+- Überprüfung der Stabilität des unpinned‑Quadranten
+- Evaluierung langfristiger Reduktion der warn_rate ohne Δt‑Verschlechterung
+
+**Regression & Modellierung:**
+- Erweiterung der Δt‑Analyse um lineare Drift‑Modelle oder Zeitverlaufs‑Regression
+
+**Community-Beiträge:**
+- Bereitstellung der Drift‑Matrix‑Analyse als reproduzierbares Template für Run‑Vergleiche