piecewise_policy_validation/decision_table/README.md

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