fix(dashboard): total_tokens-KPI zaehlt nur DB-gejointe Laeufe (#198 P3, Option A)

[TillQuandel]

Setzt #198 P3 um (letzter offener Punkt; P1+P2 in PR #218). Closes #198.

Problem

Die Lifetime-KPI „Gesamt-Tokens" summierte ALLE Trace-JSONL-Dateien — auch 490 verwaiste Traces ohne pipeline_runs-DB-Zeile (+21,3 % vs. Versions-Chart). (Zahlen aus dem Issue-Snapshot 2026-07-11; heutige Rohdaten: 438 token-tragende Waisen-Traces, +28,4 % — die Vorher/Nachher-Tabelle unten ist dagegen exakt reproduziert, Kontrollrunden-Beleg.) Der Chart hatte den if not ver: continue-Guard (_chart_tokens_by_version), die KPI nicht.

Fix (Option A — Entscheidung des Maintainers)

• Server-Left-Join markiert jetzt explizit tr["db_matched"] = True/False (Kriterium: run_id in pipeline_runs; DB-only-Runs True).
• _calc_kpis summiert total_tokens nur über tr.get("db_matched", True) — Default True hält den deprecaten Legacy-Standalone-Pfad (einziger weiterer _calc_kpis-Aufrufer, per Grep verifiziert) unverändert.
• Strip-Hint benennt die neue Basis (nur DB-zugeordnete Läufe).
• Keine Orphan-Ausweisung (Option B bewusst nicht gebaut).

Bewusste Semantik-Entscheidung (Review-Fund, per Regressionstest fixiert): Eine DB-Zeile mit leerer pipeline_version zählt in der Lifetime-Summe (DB-Mitgliedschaft = Kriterium), während der Versions-Chart sie mangels Version ausschließt — Lifetime ist nicht „Summe der Versions-Buckets". In den echten Daten existiert der Fall aktuell nicht (Summen exakt deckungsgleich, s. u.); Kommentar an der Join-Stelle dokumentiert die Divergenz. Zweite latente Divergenzquelle gleicher Klasse (Kontrollrunden-Fund, Info): foss-/extractive-Versionen zählen in der Lifetime-Summe, der Versions-Chart schließt sie zusätzlich via is_foss_version aus — aktuell folgenlos (foss-Läufe tragen 0 Token-Traces, DB-verifiziert).

RED-Beweis (TDD)

3/5 neue Tests initial rot (Waisen-Trace wurde mitgezählt, db_matched-Marker fehlte); nach Fix 5/5 grün. Nachbesserung: +2 Tests (NULL-Version-Regressionstest, fehlender run_id-Key) + direkte db_matched-Asserts in den build_data-Tests → 7/7.

Zahlen (echte Daten, read-only)

	Vorher	Nachher
KPI „Gesamt-Tokens"	10.997.819	8.564.227
Versions-Chart-Summe	8.564.227	8.564.227 (exakt deckungsgleich)

Suite

pytest generative lib/decision_engine/tests shared/tests -q: 5773 passed, 3 skipped, 4 deselected; ruff format+check sauber.

Playwright-Sichtverifikation (hell+dunkel)

Server aus Worktree auf Port 8062 (genau 1 Listener-PID), echte DB read-only. Screenshots: C:/tmp/198-verify/198-strip-{light,dark}.png + 198-strip-tokens-hint-{light,dark}.png — Tokens 8,56 M, Hint mit DB-Zuordnungs-Text.

Reviews

• Task-Review (Sonnet): 1 Important (NULL-Version-Divergenz — per Orchestrator-Entscheid als gewollte Semantik geklärt, Regressionstest + Kommentar) → Re-Review Approved; Minors: Fail-open bei DB-Fehler im Join (vorbestehendes Muster) + Strip-Zelle mischt Filterbasen Tokens/Laufzeit (hängt am total_dur_h-Entscheid, s. u.) — dokumentiert, nicht blockierend.
• Cross-Model (Mistral magistral-medium): Runde 1 über Haupt-Diff und Runde 2 über Nachbesserungs-Diff — je 0 Funde.

Offener Entscheid für den Maintainer

total_dur_h hat denselben Waisen-Bug (31,2 h DB-gejoint vs. 40,1 h angezeigt, 22 % Differenz) — bewusst NICHT mitgefixt (Mandat nannte nur total_tokens). Empfehlung: gleiche Behandlung (3-Zeilen-Follow-up). Wird als separates Issue erfasst, falls kein Go für Direkt-Nachtrag kommt.

Kontrollrunde (2026-07-12, zweite unabhängige Review-Ebene)

• Opus-Kontroll-Review (Fehlerfindung + Behauptungs-Drift, Selbstverifikationspflicht, Runtime-Proben gegen echte DB read-only): 0 Korrektheitsbugs. Kernzahlen exakt reproduziert (10.997.819 / 8.564.227 / Chart-Summe bit-genau deckungsgleich); DB-Fakten: 0 leere run_ids, 118 distinct run_ids (kollisionsfrei), 0 NULL-Versionen. 6 Kandidaten aktiv widerlegt (leerer-run_id-Match, Kollisionen, DB-only-Zeilen, fail-open-Regress, partielle Join-Exception, leere token_runs). Info-Funde in diesen Body eingearbeitet (Snapshot-Zahlen-Annotation, latente foss-Divergenz); trivial notiert: Kommentar-Wortlaut „main()/_build_html" leicht ungenau (nur main() ruft _calc_kpis, _build_html bekommt das Ergebnis) — bewusst kein Extra-Commit dafür.
• Mistral-Schwerpunkt-Resample (Linse Join-Kanten / run_id-Format / Summen-Konsistenz): 0 Funde. (Mistral-Runde 1 über Haupt-Diff + Runde 2 über Nachbesserung: ebenfalls je 0.)