Add sql/README.sql.md

sql/README.sql.md

@@ -0,0 +1,44 @@
+# Gate V1 Log-Datenbank (Experiment-Key: `run_17_gates_default`)
+
+⚠️ **Experimentell & KI-generiert – kein produktiver Einsatz!** Dieses Repository enthält ein minimalistisches PostgreSQL-Schema plus Seed-Daten zur Analyse der Gate V1-Retries rund um die Runs #14–#17.
+
+## Inhalt
+- `schema.sql` – Tabellen `runs`, `strata`, `log_entries` inkl. Constraints & Indizes.
+- `demo-data.sql` – Kleine Beispieldaten zur direkten Auswertung (Run 16 & Run 17).
+
+## Datenmodell
+| Tabelle         | Zweck                                                                                         |
+|-----------------|-----------------------------------------------------------------------------------------------|
+| `runs`          | Metadaten zu Experiment-Läufen (Fingerprint, Policy-Hash, Mode, Decision-Card-URL).           |
+| `strata`        | Referenz der Strata (pinned, near-expiry, …) inklusive Flags für `is_pinned` und `near_expiry`.|
+| `log_entries`   | Einzelne Log-Zeilen mit den entscheidungsrelevanten Feldern: Retry-Status, Overhead, Δt usw.  |
+
+Wesentliche Constraints:
+- `runs_mode_chk` stellt sicher, dass nur bekannte Modi (`warn`, `observe`, `enforce`) eingetragen werden.
+- `log_entries_*_chk` begrenzen Messwerte auf realistische Fenster (z. B. Δt zwischen −500 ms und +500 ms).
+- Foreign Keys mit `ON DELETE CASCADE/RESTRICT` sichern Konsistenz zwischen Runs, Strata und Logs.
+
+## Nutzung
+1. PostgreSQL 15+ bereitstellen.
+2. Schema anwenden: `psql -f schema.sql`
+3. Seed-Daten laden (optional): `psql -f demo-data.sql`
+4. Beispielabfragen:
+   ```sql
+   -- Δt<0 ausschließlich im near-expiry-unpinned Stratum?
+   SELECT stratum_code, COUNT(*) FILTER (WHERE delta_t < 0) AS negative_delta_t
+   FROM log_entries
+   GROUP BY stratum_code;
+
+   -- Retry-Overhead-Verteilung pro Run
+   SELECT r.run_label,
+          percentile_cont(0.95) WITHIN GROUP (ORDER BY retry_total_overhead_ms) AS p95_ms,
+          percentile_cont(0.99) WITHIN GROUP (ORDER BY retry_total_overhead_ms) AS p99_ms
+   FROM log_entries le
+   JOIN runs r ON r.run_id = le.run_id
+   GROUP BY r.run_label;
+   ```
+
+## Hinweise
+- Die Tabellen bilden bewusst nur die für die Gate-V1-Decision-Card genannten Felder ab.
+- Erweiterungen (z. B. zusätzliche Metriken oder Views) sollten stets neue Migrationen erhalten – **niemals** `schema.sql` nachträglich ändern.
+- Bei eigenen Daten immer die Warnung beachten: keine produktiven oder personenbezogenen Inhalte einspielen.