Signal YAML Referenz

Vokabular-Hinweis

Signals (frueher Probes) und Perspectives (frueher Assessments) werden in YAML mit dem unten beschriebenen Format deklariert. Die YAML-Feldnamen (probe_id, assessment, usw.) bleiben unveraendert — die Umbenennung ist konzeptionell, nicht strukturell.

Feld-Level-Spezifikation fuer Signal (Probe) und Perspective (Assessment) YAML-Definitionen.

Uebersicht

Eigenschaft	Wert
Dateiort	probes/probe_*.yaml (Signals) oder probes/assessment_*.yaml (Perspectives)
ID-Regel	probe_id muss mit Dateiname (ohne .yaml) uebereinstimmen
Validator	python3 scripts/probecheck.py
Compiler	python3 scripts/probecompile.py
Compiler Trockenlauf	python3 scripts/probecompile.py --check
Registry Compiler	python3 scripts/proberegistry.py

Kernfelder

Alle Felder in dieser Tabelle sind bei jedem Signal erforderlich.

Feld	Typ	Gueltige Werte
probe_id	string	Muss mit Dateiname uebereinstimmen; Praefix probe_ oder assessment_
version	string	Semantische Version (z.B. "1.0.0")
contract	string	"gold.v1" (Signals), "findings.v1" (Perspectives), "silver.v1" (silver_audit)
type	string	Einer der 13 Typen (siehe Signal-Typen)
severity	string	high | medium | low
description	string	Freier Text, was das Signal erkennt

Scope-Block

Erforderlich bei allen Signals.

Feld	Typ	Erforderlich	Beschreibung
scope.entity_type	string	ja	Entity-Label fuer die Findings-Ausgabe
scope.group_by	list	ja	Felder, die eine Finding-Zeile definieren (min 1)
scope.time.entity	string	ja	Entity mit dem Zeitfeld
scope.time.field	string	ja	Datums-/Zeitstempelfeld
scope.time.bucket	string	ja	week | month | quarter | raw

Signal-Typen

Alle 13 gueltigen Typen und ihre erforderlichen typspezifischen Bloecke:

Typ	Contract	Typspezifische Schluessel	Zweck
balance	gold.v1	left, right, join_key, tolerance_pct	Zwei Aggregate pro Entity vergleichen
assessment	findings.v1	source_probes	Findings ueber Signals aggregieren
duplicate	gold.v1	duplicate	Duplikate nach Feldkombination finden
reconciliation	gold.v1	left, right, join, derived, flag	Cross-Entity-Abstimmung
temporal_sequence	gold.v1	sequence	Ereignisreihenfolge validieren
distribution_outlier	gold.v1	metric, distribution	Statistische Ausreisser markieren
ratio	gold.v1	numerator, denominator, expected_ratio, tolerance_pct, direction	Verhaeltnis gegen Erwartungswert
mandatory_item	gold.v1	qualifying, required	Pflichtartikel pruefen
trend	gold.v1	metric, trend	Verschlechternde Trends erkennen
silver_audit	silver.v1	source, audit-spezifische Felder	Silver-Layer Datenqualitaet pruefen
entity_filter	gold.v1	filter	Entities nach Bedingung filtern
enrichment	gold.v1	dimension, fact, derived, flag	Entities mit berechneten Feldern anreichern
hand_written	gold.v1	(keine — liest probes/{probe_id}.sql)	Rohes SQL Escape Hatch

Severity Rules

Regeln werden von oben nach unten ausgewertet; erster Treffer gewinnt. Muss mit einem default-Eintrag enden.

severity_rules:
  - above: 10.0
    level: high
  - above: 2.0
    level: medium
  - default: low

Money at Risk

Form	Beispiel	Typischer Einsatz
Ausdruck	"abs(left_total - right_total)"	balance, ratio
Feldreferenz	total_risk	assessment
Fester Betrag	money_at_risk_fixed: 500	mandatory_item

Findings-Ausgabe-Contract

Jedes kompilierte Signal gibt Zeilen mit diesen Spalten aus:

Spalte	Typ	Beschreibung
finding_id	string	Deterministischer Surrogatschluessel
tenant_id	string	Tenant-Bezeichner
probe_id	string	Signal-Bezeichner
probe_version	string	Semantische Version
severity	string	high | medium | low
entity_type	string	Aus scope.entity_type
entity_id	string	Entity-Bezeichner
time_bucket	string	Formatierter Zeitabschnitt
money_at_risk	numeric	Finanzielle Exposition
evidence	string	JSON-Objekt mit Signal-spezifischen Feldern

Siehe die englische Referenz fuer vollstaendige Dokumentation aller Typen (balance, assessment, duplicate, reconciliation, temporal_sequence usw.) mit Feldlisten und Beispielen.