Add README.sql.md

README.sql.md

@@ -0,0 +1,15 @@
+# EM Metrics Schema
+
+Dieses Artefakt definiert ein versioniertes PostgreSQL-Schema für kompakte EM-Summary-Metriken in der CI.
+
+## Tabellen
+- **schema_version**: Lightweight-Verlauf der angewendeten Migrationen. Jede Schemaänderung erhält einen Eintrag, damit Pipelines die Kompatibilität prüfen können.
+- **em_metrics**: Persistiert die drei zentralen EM-Features (`peak_amplitude`, `median_bandpower`, `crosscorr_with_clockevents`) zusammen mit CI-Kontext (Pipeline, Job, Commit) und optionaler Metadaten wie Spacer/Sampling-Policy. UNIQUE(run_uuid, job_name, trace_version) schützt vor doppelten Uploads.
+
+## Anwendungsnotizen
+1. **Insertion Flow**: CI-Jobs schreiben pro Run genau einen Datensatz mit `trace_version = 1`. Bei Schema-Erweiterungen kann `trace_version` hochgezogen werden, ohne historische Runs anzufassen.
+2. **Diagnostik**: `hf_outlier_flag` eignet sich für schnelle Alerts, während die numerischen Felder für Trendanalyse/Regressionen herangezogen werden.
+3. **Indices**: Cover typische Filter (Zeitfenster, Pipeline, Outlier). Optional können weitere Matrix-spezifische Indizes ergänzt werden.
+4. **Retention**: Summaries sind klein; empfohlen wird Rotation nach z. B. 180 Tagen (abhängig von Compliance). Rohdaten liegen außerhalb dieses Schemas.
+
+Siehe `demo-data.sql` für exemplarische Inserts, die den Spacer-Effekt (−60 % Peak) sowie baseline Läufe widerspiegeln.