Add near_expiry_rule/README.md

near_expiry_rule/README.md

@@ -0,0 +1,172 @@
+# Near‑Expiry‑Regel – Datenbasierte Definition und Schwellenwertanalyse
+
+## Purpose
+
+Analyse der Run‑Timings #6–#10 zur Ableitung der Near‑Expiry‑Regel in einem mehrstufigen System.
+
+**Problemstellung:** Negative Time‑Lags (Δt<0) treten gehäuft bei unpinned‑Runs auf. Ziel ist, eine quantitative Grenze für Near‑Expiry‑Fälle zu bestimmen, um deterministisch entscheiden zu können.
+
+**Ziele:**
+- Definition der Near‑Expiry‑Schwelle basierend auf empirischen Δt‑Musteranalysen.
+- Validierung der Stabilität über fünf Runs mit konstanter Instrumentierung.
+- Vorbereitung auf A/B‑Test mit klarer Entscheidungsregel.
+
+## Kontext & Hintergrund
+
+Konsolidierte Run‑Daten #6–#10 aus Systemmessungen, getrennt nach pinned und unpinned Strata.
+
+**Gruppierung:**
+- Run‑Nummer (#6–#10)
+- Stratum: pinned vs. unpinned
+
+**Trace-Metadaten / zusätzliche Tags:**
+- corr_id
+- expires_at_dist_hours
+- sign(t_gate_read − t_index_visible)
+
+**Domänenkontext:**
+- Timing‑Analyse verteilter Systeme
+- Event‑Visibility‑Lag‑Beobachtung
+
+**Outlier-Definition:**
+- Methode: Schwellenwertbeurteilung
+- Beschreibung: Fälle mit expires_at_dist_hours > 24h gelten als Ausreißer in der Δt<0‑Gruppe.
+- Metrik: expires_at_dist_hours
+
+**Motivation:**
+- Präzise Baseline vor Regeländerung sichern.
+- Vermeidung von Zufallseffekten durch Run‑Konsistenz.
+- Einführung einer expliziten, begründeten Near‑Expiry‑Schwelle.
+
+## Methode / Spezifikation
+
+**Übersicht:**
+- Runs #6–#10 wurden mit identischer Instrumentierung durchgeführt.
+- Δt wird berechnet als Differenz zwischen Gate‑Read‑ und Index‑Visibility‑Zeitpunkten.
+- Negative Δt‑Werte signalisieren frühe Gate‑Erkennung vor sichtbarem Index.
+
+**Algorithmen / Verfahren:**
+- Erfassen von Δt<0‑Fällen pro Run.
+- Kategorisierung nach pinned / unpinned.
+- Aggregation aller Δt<0‑Fälle über Runs.
+- Berechnung der expires_at_dist_hours‑Verteilung.
+- Bestimmung der 24h‑Schwelle basierend auf 6/7 Fällen unter dieser Grenze.
+
+## Input / Output
+
+### Input-Anforderungen
+
+**Hardware:**
+- Standard‑Analyseumgebung ohne spezielle Sensorik
+
+**Software:**
+- Data‑Collection‑Pipeline mit Zeitstempel‑Erfassung
+
+**Konfiguration:**
+- Exit‑Regel v1
+- Konstante Instrumentierung während Runs #6–#10
+
+### Erwartete Rohdaten
+
+**Felder pro Run:**
+- run_id
+- stratum
+- corr_id
+- t_gate_read
+- t_index_visible
+- expires_at_dist_hours
+
+**Formatbeispiele:**
+- run=10, stratum=unpinned, corr_id=U10‑A, expires_at_dist_hours=9.4, Δt_sign=negativ
+
+**Trace-Daten:**
+- Format: Tabellarische Textaufzeichnung oder CSV
+- Hinweis: Einträge pro Run konsistent formatiert; keine Feature‑Änderungen zwischen Runs.
+
+### Analyse-Ausgaben
+
+**Pro Gruppe / pro Governor:**
+- warn_rate ≈ 0.06 (pinned)
+- unknown_rate ≈ 0.00 (pinned)
+- Δt<0 count pro Stratum
+
+**Vergleichsausgaben:**
+- pinned vs unpinned
+  - Δ: Δt<0 proportion difference
+  - RR: Erhöhtes Risiko negativer Lags bei unpinned‑Runs
+
+- Trace-Muster: Konsistent negatives Lag‑Vorzeichen in allen Δt<0‑Fällen.
+
+## Workflow / Nutzung
+
+**Analyse-Workflow:**
+- Sammle Δt‑Metriken pro Run.
+- Trenne Daten nach Strata (pinned/unpinned).
+- Prüfe Lag‑Vorzeichenverteilung.
+- Aggregiere Near‑Expiry‑Kandidaten (expires_at_dist_hours < 24h).
+- Setze Schwelle = 24h als Regeldefinition.
+- Dokumentiere Regel für A/B‑Test‑Konfiguration.
+
+### Trace-Template-Anforderungen
+
+**Ziel:** Konsistente Erhebung von Timing‑Differenzen zur Stabilitätsbewertung.
+
+**Erforderliche Tags & Metadaten:**
+- corr_id
+- t_gate_read
+- t_index_visible
+- expires_at_dist_hours
+
+**trace-cmd-Setup:**
+- Verwende gleiche Logging‑Parameter über alle Runs.
+- Deaktiviere Zwischenpuffer für Echtzeit‑Erfassung.
+
+**Run-Design für Contributors:**
+- Halte Instrumentierung konstant.
+- Verändere keine Systemparameter während der Baseline‑Runs.
+
+## Interpretation & erwartete Ergebnisse
+
+**Kernbefunde:**
+- Δt<0‑Fälle ausschließlich bei unpinned‑Runs beobachtet.
+- Kein einziger positiver Lag‑Wert in der beobachteten Serie.
+- 6 von 7 negativen Fällen mit expires_at_dist_hours < 24h.
+
+**Implikationen für Experimente:**
+- Die empirisch begründete Schwelle reduziert Zufallseinflüsse.
+- Die Regel Near‑Expiry := expires_at_dist_hours < 24h kann als deterministische Entscheidungsbasis dienen.
+- Die 24–48h‑Zone bleibt als Monitoring‑Bereich aktiv, jedoch ohne Regelbeteiligung.
+
+**Planungsziel:**
+- Ziel: Schaffung einer sauberen, überprüfbaren Entscheidungslogik für Near‑Expiry‑Erkennung.
+- Vorgehen:
+  - Datengetriebene Schwellenwertbestimmung
+  - Baseline‑Validierung über stabile Run‑Serie
+
+## Limitationen & Fallstricke
+
+**Datenbezogene Limitationen:**
+- Einzelfall mit >24h (31.5h) könnte auf unerkannten Sonderfall hinweisen.
+- Kleine Stichprobe (7 Δt<0‑Fälle) begrenzt statistische Aussagekraft.
+
+**Kausalität & Generalisierbarkeit:**
+- Korrelation zwischen Near‑Expiry und negativem Lag nicht notwendigerweise kausal.
+- Ergebnisse gelten nur für Testsystem mit Exit‑Regel v1.
+
+**Praktische Fallstricke:**
+- Schwellenänderung in späteren Runs erfordert Re‑Kalibrierung der Regel.
+- Fehlerhafte Zeitsynchronisation kann Δt‑Sign verfälschen.
+
+## Nächste Schritte & Erweiterungen
+
+**Geplante Experimente:**
+- Durchführung eines A/B‑Tests mit Near‑Expiry‑Schwelle <24h vs. Kontrollgruppe ohne Schwelle.
+
+**Analyseziele:**
+- Überprüfung der Regelauswirkungen auf Lag‑Verteilung und Fehlerraten.
+
+**Regression & Modellierung:**
+- Langfristig Modellierung der Lag‑Verteilung als Funktion der Restlaufzeit.
+
+**Community-Beiträge:**
+- Validierung durch weitere Runs mit standardisierter Trace‑Template‑Einhaltung.