MtoRagSystem/RETRIEX_PATCH_61_GENRE_SOURCE_OF_TRUTH_GUARD_README.md

RetrieX Patch p61 - Genre Source-of-Truth Guard

Ziel

p61 schliesst die Genre-Source-of-Truth-Arbeit nach p59/p60/p60b ab.

Der Patch verschiebt keine fachlichen Werte mehr. Stattdessen erzwingt er per Validate/Audit, dass genre.yaml die zentrale Pflegequelle fuer genreabhaengige Werte bleibt und Legacy-Pfade nur noch als leere oder explizit eingefrorene Fallbacks dienen.

Umfang

Geaendert bzw. ergaenzt:

• config/retriex/governance.yaml
• src/Config/GenreSourceOfTruthGuard.php
• src/Config/RetriexEffectiveConfigProvider.php
• src/Config/ConfigSourceAuditProvider.php
• src/Command/ConfigSourceAuditCommand.php

Was der Guard prueft

1. Vollstaendige Genre-Werte

genre.configuration_values muss eine nicht-leere Map sein.

Fuer jede Gruppe in genre.adaptation_surface muss eine entsprechende Gruppe in genre.configuration_values existieren.

2. Source-Path-Abdeckung

Genre-Wertknoten mit direkter Payload muessen selbst source_paths deklarieren oder von einem Parent-Knoten mit source_paths abgedeckt sein.

source_paths muessen nicht-leere Strings sein und duerfen innerhalb eines Wertknotens nicht doppelt vorkommen.

3. Gueltige Source-Pfade

Alle source_paths werden gegen die effektive bzw. roh geladene RetrieX-Konfiguration validiert.

Unbekannte Source-Pfade erzeugen jetzt einen Validate-Fehler.

4. Legacy-Fallbacks sind leer oder eingefroren

Fuer jeden deklarierten Source-Pfad gilt:

• leerer Legacy-Wert: OK, Status legacy_fallback_empty
• runtime-/env-aufgeloester Pfad: OK, Status legacy_runtime_resolved_allowed
• nicht-leerer Legacy-Wert mit passendem Hash: OK, Status legacy_frozen_non_empty
• nicht-leerer Legacy-Wert ohne registrierten Hash: Fehler
• nicht-leerer Legacy-Wert mit abweichendem Hash: Fehler

Damit brechen Validate/Audit, wenn neue fachliche Listen wieder ausserhalb von genre.yaml landen oder eingefrorene Legacy-Werte veraendert werden.

Warum eingefrorene Fallback-Hashes?

Einige Legacy-Pfade enthalten weiterhin technische Fallback-/Wiring-Werte oder noch nicht entfernte Legacy-Defaults, die im aktuellen gruenen Stand nicht geloescht werden sollten. p61 friert diese Werte per SHA-256-Hash ein.

Dadurch bleibt der aktuelle Stand kompatibel, aber kuenftige Aenderungen an diesen Legacy-Pfaden muessen bewusst ueber genre.yaml erfolgen.

Audit-Ausgabe

mto:agent:config:audit-source --details zeigt zusaetzlich:

• genre_source_of_truth_violations
• genre_source_of_truth_fallback_empty
• genre_source_of_truth_frozen_non_empty
• Detailtabelle Genre source-of-truth guard

Die Detailtabelle zeigt pro Genre-Wert:

• Genre value path
• Legacy/effective source path
• State
• Hash

Validate-/Audit-Verhalten

mto:agent:config:validate fuehrt den Guard aus und gibt Fehler aus, wenn die Source-of-Truth-Regeln verletzt sind.

mto:agent:config:audit-source gibt bei Source-of-Truth-Fehlern jetzt Command::FAILURE zurueck.

Lokale Checks

Ausgefuehrt:

php -l src/Config/GenreSourceOfTruthGuard.php
php -l src/Config/RetriexEffectiveConfigProvider.php
php -l src/Config/ConfigSourceAuditProvider.php
php -l src/Command/ConfigSourceAuditCommand.php

Alle PHP-Lints: OK.

python3 - <<'PY'
# YAML parse config/retriex/*.yaml
PY

YAML parse: OK.

Zusatzcheck:

• Source-of-Truth-Guard-Simulation gegen den aktuellen Stand: 0 Fehler
• Ergebnisstatus der Simulation: leer/frozen/runtime erlaubt

Nicht lokal ausfuehrbar:

php bin/console mto:agent:config:validate
php bin/console mto:agent:regression:test
php bin/console mto:agent:config:audit-source --details
php bin/console mto:agent:config:audit-patterns --details

Grund:

Das ZIP enthaelt kein vendor/.

Fehler:

Dependencies are missing. Try running "composer install".

Empfohlene Checks nach Einspielen

bin/console cache:clear
bin/console mto:agent:config:validate
bin/console mto:agent:regression:test
bin/console mto:agent:config:audit-source --details
bin/console mto:agent:config:audit-patterns --details

Abschlussbild

Nach p61 gilt:

• genre.yaml ist die zentrale fachliche Source of Truth.
• Legacy-YAMLs sind technische Verarbeitungsschichten bzw. leere/eingefrorene Fallbacks.
• Neue fachliche Listen ausserhalb von genre.yaml werden durch Validate/Audit verhindert.
• Technische Runtime-/Model-/Vector-/Index-Konfiguration bleibt weiterhin ausserhalb von genre.yaml.