Add decision_table/README.md

decision_table/README.md

@@ -0,0 +1,153 @@
+# Entscheidungstabelle für Piecewise-Policy-Auswahl und Validierung
+
+## Purpose
+
+Dokumentation der Auswahl- und Validierungsentscheidungen für Piecewise-Policies zur Steuerung von Performance-Tails und Unknowns.
+
+**Problemstellung:** Unkontrollierte lange Tails bei unpinned‑Runs verursachen hohe Worst‑Case‑Werte trotz guter Durchschnittsmetriken. Ziel ist eine Policy, die Tails begrenzt und Unknowns minimiert.
+
+**Ziele:**
+- Reduktion von Unknowns auf ≤1 %
+- Sicherstellung einer Sichtbarkeit von ≥99 %
+- Optimierung von Worst‑Case‑Wartezeiten bei akzeptabler p99‑Performance
+
+## Kontext & Hintergrund
+
+Systemmetriken aus grid_results.csv mit Sichtbarkeit, Unknown‑Rate, Worst‑Case‑ und p99‑Werten je Policy‑Variante.
+
+**Gruppierung:**
+- pinned
+- unpinned
+
+**Trace-Metadaten / zusätzliche Tags:**
+- policy_variant
+- grace
+- delay
+- visibility
+- unknown
+- worst_case
+- p99
+
+**Domänenkontext:**
+- System-Performance-Test bei unterschiedlicher Thread‑Affinität (pinned/unpinned)
+- Evaluierung von delay‑ und grace‑basierten Steuerparametern
+
+**Motivation:**
+- Reduktion extremer Ausreißer in Latenzverteilungen
+- Vermeidung unklarer (Unknown) Zustände im Testbetrieb
+- Versionierte Policy‑Kontrolle zur Nachvollziehbarkeit
+
+## Methode / Spezifikation
+
+**Übersicht:**
+- Systematische Filterung des Policy‑Grids nach definierten Hard Constraints.
+- Optimierung innerhalb des gültigen Subsets nach minimalem Worst‑Case.
+- Sekundäre Bewertung über p99 bei Gleichstand.
+
+**Algorithmen / Verfahren:**
+- Filter: visibility ≥99 %, unknown ≤1 %.
+- Sortierung: Primär nach Worst‑Case, sekundär nach p99.
+- Finale Auswahl: Ein Policy‑Kandidat pro Stratum (pinned/unpinned).
+
+## Input / Output
+
+### Input-Anforderungen
+
+**Hardware:**
+- Standard-Testplattform mit CPU-Affinitätssteuerung
+
+**Software:**
+- Analyse-Tooling mit grid_results.csv-Auswertung
+
+**Konfiguration:**
+- policy_constants.json mit getrennten Parametern für pinned/unpinned
+
+### Erwartete Rohdaten
+
+**Felder pro Run:**
+- policy_variant
+- grace
+- delay
+- visibility
+- unknown
+- worst_case
+- p99
+
+**Formatbeispiele:**
+- Variante B, 2.0, 1.0, 99.3, 0.8, 810, 560
+
+**Trace-Daten:**
+- Format: CSV mit numerischen und boolean Feldern
+- Hinweis: Ergänzt um policy_hash zur Versionierung
+
+### Analyse-Ausgaben
+
+**Pro Gruppe / pro Governor:**
+- Visibility
+- Unknown
+- Worst‑Case
+- p99
+
+**Vergleichsausgaben:**
+- unpinned: Variante B + moderater 2‑Phase‑Delay + moderate Grace vs unpinned: Variante B + höhere Grace, kein Delay
+  - Δ: bessere Worst‑Case‑Reduktion mit Delay
+- pinned: Variante A + moderate Grace + minimaler Delay vs pinned: Variante A + erhöhter Delay
+  - Δ: ähnliche p99, jedoch höhere Unknowns bei erhöhtem Delay
+
+## Workflow / Nutzung
+
+**Analyse-Workflow:**
+- 1. grid_results.csv einlesen.
+- 2. Filterung nach definierten Hard Constraints.
+- 3. Kennzahlenbewertung (Worst‑Case, p99).
+- 4. Entscheidung je Stratum treffen.
+- 5. policy_constants.json aktualisieren.
+- 6. policy_hash neu berechnen.
+- 7. mini‑validation (8 Runs) durchführen.
+
+## Interpretation & erwartete Ergebnisse
+
+**Kernbefunde:**
+- Unpinned‑Delay reduziert die langen Tails signifikant bei stabiler Unknown‑Rate.
+- Pinned‑Grace erhöht Sichtbarkeit ohne Tail‑Verschlechterung.
+- Beide Policies liegen innerhalb der spezifizierten Constraints.
+
+**Implikationen für Experimente:**
+- Die Piecewise‑Policy kann als stabiler Baseline‑Default eingesetzt werden.
+- Weiterführende Validierungen mit 6–10 Runs empfohlen, um Varianz zu quantifizieren.
+
+**Planungsziel:**
+- Ziel: Validierung des Stabilitätsbereichs („Sweet Spot“) zur Rollout‑Freigabe.
+- Vorgehen:
+  - Cross‑Stratum‑Validierung mit gleichbleibender Testkonfiguration.
+  - Keine Setup‑ oder Logging‑Änderung während Validierung.
+
+## Limitationen & Fallstricke
+
+**Datenbezogene Limitationen:**
+- Begrenzte Stichprobe (8 Runs) kann seltene Ausreißer verdecken.
+- Abhängigkeit von spezifischen Grid‑Konfigurationen.
+
+**Kausalität & Generalisierbarkeit:**
+- Ergebnisse gelten nur für getestete Hardware‑ und Affinitäts‑Setups.
+- Kein Nachweis für kausale Effekte zwischen Delay und Unknown‑Reduktion außerhalb der Testbedingungen.
+
+**Praktische Fallstricke:**
+- Übermäßige Delay‑Erhöhung destabilisiert p99.
+- Fehlerhafte oder fehlende Policy‑Hash‑Versionierung erschwert Reproduzierbarkeit.
+
+## Nächste Schritte & Erweiterungen
+
+**Geplante Experimente:**
+- Erweiterte Validierungsserie mit 6–10 Runs je Stratum.
+- Rollout‑Simulation mit gemischten Lastprofilen.
+
+**Analyseziele:**
+- Quantifizierung der Varianzreduktion durch Delay‑Tuning.
+- Mehrdimensionale Bewertung von Worst‑Case‑Trade‑offs.
+
+**Regression & Modellierung:**
+- Automatische Policy‑Regressionstests gegen historische decision tables.
+
+**Community-Beiträge:**
+- Austausch von Unknown‑Handling‑Strategien (WARN vs REVIEW‑Schwelle).