run_timing_analysis/near_expiry_rule/README.md

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