run_timing_experiment/results_documentation/README.md

# 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