diff --git a/artifact.validation_checklist/README.md b/artifact.validation_checklist/README.md new file mode 100644 index 0000000..727389c --- /dev/null +++ b/artifact.validation_checklist/README.md @@ -0,0 +1,147 @@ +# Validitätscheckliste für den Vergleich der Evidence Cards #40 und #42 + +## Purpose + +Dokumentation der Prüf- und Validitätskriterien für den direkten Vergleich zweier Evidence-Card-Runs (#40 und #42) mit identischem Setup und Policy-Konfiguration. + +**Problemstellung:** Unterschiedliche Ergebnisse zwischen Runs können nur dann statistisch interpretiert werden, wenn alle Rahmenbedingungen konstant gehalten und geprüft sind. + +**Ziele:** +- Sicherstellen der Vergleichbarkeit zwischen Runs durch technische Validierung +- Prüfen der Setup-Konsistenz und Policy-Identität +- Vermeidung von Fehlinterpretationen durch unkontrollierte Variablen + +## Kontext & Hintergrund + +Experiment-Logs und Preflight-Daten der Evidence-Card-Runs #40 (aux=2) und #42 (aux=3). + +**Gruppierung:** +- Run #40: Basis-Konfiguration +- Run #42: identisches Setup mit 2×‑ok‑Preflight‑Regel + +**Trace-Metadaten / zusätzliche Tags:** +- Run‑Header‑Metadaten aus Preflight‑Logs +- Fingerprint‑ und Policy‑Hashes zur Setup‑Verifikation + +**Domänenkontext:** +- Vergleichsstudien in automatisierten Performance‑Experimenten +- Freeze‑Band‑Überwachung der Messgrößen zur Validitätssicherung + +**Motivation:** +- Minimierung von Drift und Rauschen bei zeitversetzten Experimenten +- Überprüfung der Effektstabilität vor Interpretation von Leistungsunterschieden + +## Methode / Spezifikation + +**Übersicht:** +- Validierung erfolgt durch binäre Prüfungen ('Ja/Nein') anhand einer festen Checkliste. +- Kriterium 1: measured_p innerhalb des definierten Freeze‑Bands (0,10 ±0,02). +- Kriterium 2: setup_fingerprint identisch in beiden Runs. +- Kriterium 3: policy_hash identisch, gleicher Freeze‑Guard aktiv. + +**Algorithmen / Verfahren:** +- Ermittlung der Parameter measured_p, setup_fingerprint, policy_hash aus Preflight‑Logs. +- Abgleich der Werte für Runs #40 und #42. +- Klassifikation des Vergleichs als 'valide' bei vollständiger Übereinstimmung. + +## Input / Output + +### Input-Anforderungen + +**Hardware:** +- Identische Hardware‑Instanz oder virtualisierte Umgebung mit fixed allocation + +**Software:** +- Gleiches Experiment‑Framework +- identischer Policy‑Hash +- Freeze‑Guard aktiviert + +**Konfiguration:** +- aux=2 (Run #40) vs aux=3 (Run #42) +- 2×‑ok‑Preflight‑Regel bei Run #42 + +### Erwartete Rohdaten + +**Felder pro Run:** +- measured_p +- setup_fingerprint +- policy_hash +- retry_tail_p99 +- band_width +- Δband_width + +**Formatbeispiele:** +- {"measured_p": 0.101, "setup_fingerprint": "fp_12345", "policy_hash": "ph_abc"} + +**Trace-Daten:** +- Format: JSON‑basierte Run‑Logeinträge +- Hinweis: Metriken werden aus Preflight‑ und Main‑Run‑Logs extrahiert. + +### Analyse-Ausgaben + +**Pro Gruppe / pro Governor:** +- retry_tail_p99 (Hotspot / Rest getrennt) +- band_width +- Δband_width + +**Vergleichsausgaben:** +- Run #40 (aux=2) vs Run #42 (aux=3) + - Δ: Hotspot‑Tail p99 schlechter bei #42 + +## Workflow / Nutzung + +**Analyse-Workflow:** +- Preflight‑Validierung beider Runs durchführen. +- Checkliste vollständig ausfüllen. +- Nur bei validiertem Setup Vergleich der Kernmetriken starten. +- Ergebnisse für Hotspot‑Tail und Bandbreite dokumentieren. + +### Trace-Template-Anforderungen + +**Ziel:** Sicherstellung der Run‑Konsistenz für reproduzierbare Vergleichsexperimente. + +**Erforderliche Tags & Metadaten:** +- measured_p +- setup_fingerprint +- policy_hash +- aux +- freeze_band + +**trace-cmd-Setup:** +- Einrichtung der 2×‑ok‑Preflight‑Regel für konservative Runs. +- Konfiguration fixer Random‑Seeds zur Minimierung zufälliger Schwankungen. + +**Run-Design für Contributors:** +- Neue Runs müssen Fingerprint‑ und Policy‑Hash‑Übereinstimmung nachweisen. +- Validitätsklasse (z. B. 'aux‑Aussage') im Header dokumentieren. + +## Interpretation & erwartete Ergebnisse + +**Kernbefunde:** +- Runs #40 und #42 sind validiert vergleichbar. +- Run #42 zeigt erhöhte Latenz im Hotspot‑Tail‑Bereich, keine globale Verlangsamung. +- Freeze‑Band‑Stabilität bestätigt. + +**Implikationen für Experimente:** +- Der Effekt aux=3 verstärkt lokale Empfindlichkeiten, keine generelle Performance‑Degradation. +- Replikation (#43) notwendig, um Richtung und Stärke des Effekts zu bestätigen. + +## Limitationen & Fallstricke + +**Datenbezogene Limitationen:** +- Kleine Stichprobe (nur zwei Runs) verhindert statistische Generalisierung. + +**Praktische Fallstricke:** +- Interpretation ohne Replikation riskant. +- Preflight‑Gate erhöht Validität, reduziert aber Iterationsgeschwindigkeit. + +## Nächste Schritte & Erweiterungen + +**Geplante Experimente:** +- Run #43 als aux=3‑Replikat bei identischem Gate und Setup durchführen. + +**Analyseziele:** +- Überprüfung der Stabilität des Hotspot‑Effekts über mehrere Replikate. + +**Community-Beiträge:** +- Standardisierung der ValidationChecklist als JSON‑Template für Folgeexperimente.