# RX-CLN-001 – Ist-Analyse Reconciliation Semantics **Status:** FOR DISCUSSION **Stand:** 2026-08-30 **Basis:** Datenbankdump `reconcilix01(1).sql`, aktueller Rx-Code nach QDR-001A/B/C sowie DM001 v0.7 / DM002 v0.6. ## 1. Ziel Vor der Integration des klassischen Vokabularabgleichs in die **Rx Discovery Testbench** sollen die aktuell verwendeten Begriffe, URI-Felder und Statusattribute auf semantische Konsistenz geprüft werden. Im Fokus stehen insbesondere: - `reconciliation_result.matching_strategy_uri` - `reconciliation_result.success` - `interpretation_graph.status_uri` - `interpretation_node.status_uri` - `interpretation_node.technique_uri` - `source_value.preferred_entity_type_uri` - `candidate_item.entity_type_uri` - Abgrenzung von **Discovery Method**, **Matching Strategy**, **Interpretation Technique** und technischer Adapterkonfiguration Ziel dieses Papiers ist zunächst **keine Migration**, sondern eine belastbare Ist-Beschreibung und ein möglichst kleiner Cleanup-Schnitt. --- ## 2. Datenbestand im Dump Der Dump zeigt zwei relevante Verarbeitungspfade nebeneinander. ### 2.1 Vector-Run Ein persistierter Qdrant-Run enthält: - 1 `ReconciliationRun` - 10 `ReconciliationRunItem` - 10 `InterpretationGraph` - 10 `InterpretationNode` - 10 `ReconciliationResult` - 100 `CandidateItem` Beispiel Run-Konfiguration: ```json { "discovery_method": "VECTOR_SIMILARITY", "adapter_id": "vector-qdrant", "client_id": "qdrant-marburg", "context_type_uris": [ "https://reconcilix.vocnet.org/context/0001" ], "context_roles": [ "item_discovery" ], "language": "*", "offset": 0, "limit": 10, "candidate_limit": 10, "output_language": "de", "rerank": true } ``` Der Run ist damit bereits technisch gut reproduzierbar beschrieben. ### 2.2 Klassischer OR-Pfad Der Dump enthält außerdem einen OpenRefine-Reconcile für `Bogen`. Dabei gilt aktuell: ```text SourceDelivery → SourceValue → InterpretationGraph (reconciliation_run_id = NULL) → InterpretationNode → ReconciliationResult → CandidateItem ``` Der bestehende OR-Pfad ist damit weiterhin run-los und bildet die Legacy-Kompatibilität ab. --- ## 3. Befund A – `matching_strategy_uri` ist aktuell semantisch inkonsistent Im Dump stehen im selben Feld zwei unterschiedliche Wertarten: ```text Qdrant: VECTOR_SIMILARITY OR: https://reconcilix.example/strategy/legacy ``` Das Feld heißt ausdrücklich `matching_strategy_uri`, enthält bei Qdrant aber eine **Notation**, keine URI. Hinzu kommt: `VECTOR_SIMILARITY` ist im aktuellen Code bereits die definierte **Discovery Method** des `VectorCandidateDiscoveryAdapter`. ```text VectorCandidateDiscoveryAdapter::DISCOVERY_METHOD = VECTOR_SIMILARITY ``` Im `ReconciliationRun.configuration_json` wird derselbe Wert korrekt als ```json "discovery_method": "VECTOR_SIMILARITY" ``` gespeichert. ### Bewertung Der aktuelle Qdrant-Pfad verwendet `VECTOR_SIMILARITY` doppelt: 1. als **Discovery Method** auf Run-/Routing-Ebene, 2. als vermeintliche **Matching Strategy** auf Result-Ebene. Diese Gleichsetzung ist fachlich nicht hinreichend begründet. DM001 beschreibt `ReconciliationResult.matchingStrategy` als „verwendete Matching Strategy“. Ein `InterpretationNode` kann mehrere Results beispielsweise aufgrund unterschiedlicher Target Vocabularies oder Matching Strategies besitzen. Eine Discovery Method wird dort nicht gleichgesetzt mit einer Matching Strategy. ### Empfehlung **Nicht einfach `VECTOR_SIMILARITY` durch eine URI ersetzen.** Zunächst sollte die Rolle des Feldes präzisiert werden. Arbeitsdefinition: ```text Discovery Method = Verfahren zur Ermittlung von CandidateItems z. B. VECTOR_SIMILARITY, LEXICAL_LOOKUP Matching Strategy = fachliche Strategie eines konkreten ReconciliationResult z. B. EXACT, TRUNCATED_RIGHT, ... Technical Adapter = konkrete technische Implementierung z. B. vector-qdrant, xtree-json-api ``` Damit wäre `VECTOR_SIMILARITY` primär eine Discovery Method und sollte nicht automatisch als `matching_strategy_uri` persistiert werden. **Priorität: hoch.** Vor DTB-002 klären. --- ## 4. Befund B – `ReconciliationResult.success` ist absichtlich undefiniert Alle zehn erfolgreich verarbeiteten Qdrant-Results stehen im Dump auf: ```text success = 0 ``` obwohl jeweils zehn CandidateItems erzeugt wurden und die zugehörigen RunItems `COMPLETED` sind. Das wirkt zunächst widersprüchlich, ist nach DM001 aber aktuell **kein Fehler**. Dort steht ausdrücklich: > `success` ist ein vorläufiges Attribut ohne abschließend definierte fachliche Semantik. und: > `success` wird in der ersten Implementierungsphase nicht für fachliche Entscheidungen, Evaluationen oder Workflow-Steuerung verwendet. Der Domain-Code bestätigt dies: `ReconciliationResult::create()` setzt `success` nicht und lässt damit den Default `false` bestehen. ### Bewertung `success` darf derzeit **nicht** interpretiert werden als: - technischer Erfolg des Requests, - „Candidates gefunden“, - „Match gefunden“, - „fachlich akzeptiert“. Diese Zustände sind bereits oder künftig anders modelliert: ```text technischer Verarbeitungserfolg → ReconciliationRunItem.status Candidates vorhanden → CandidateItem count fachliche Entscheidung → MatchDecision ``` ### Empfehlung Für den kommenden Cleanup **keine neue Semantik erfinden**. Kurzfristig: - `success` weiterhin nicht für Evaluation oder UI verwenden. - In neuer Logik nicht setzen. - Als „deprecated / semantics unresolved“ dokumentieren. Mittelfristig sollte entschieden werden, ob das Feld: 1. ganz entfernt wird, oder 2. eine eng definierte neue Semantik erhält. Mein Votum tendiert derzeit zu **Entfernung**, weil RunItem-Status + CandidateItems + MatchDecision die relevanten Zustände bereits präziser ausdrücken. **Priorität: mittel; heute kein Schema-Umbau erforderlich.** --- ## 5. Befund C – temporäre `reconcilix.example`-URIs sind produktiv geworden Im aktuellen Bestand stehen unter anderem: ```text https://reconcilix.example/status/created https://reconcilix.example/status/initial https://reconcilix.example/strategy/legacy ``` Die ersten beiden werden sowohl vom klassischen Runtime-Pfad als auch von der Discovery Testbench erzeugt. Im Code sind sie derzeit an mehreren Stellen als String-Konstanten hinterlegt, u. a. in: ```text ReconciliationCompositionRoot DiscoveryTestbenchService Tests ``` ### Bewertung Das Problem ist weniger der konkrete String als die fehlende kontrollierte Semantik. Bei Graph und Node heißt das Attribut jeweils `status_uri`, obwohl die Status fachlich unterschiedliche Aggregate betreffen: ```text InterpretationGraph.status_uri = .../created InterpretationNode.status_uri = .../initial ``` DM001 beschreibt beide lediglich als „Bearbeitungsstatus“, definiert aber noch kein kontrolliertes Statusvokabular. ### Empfehlung Zunächst zentralisieren, nicht übermodellieren. Beispielsweise: ```text InterpretationGraphStatus InterpretationNodeStatus ``` oder gemeinsame kontrollierte Konstanten, falls die Status fachlich tatsächlich identisch verwendbar sind. Erst danach endgültige Reconcilix-URIs definieren. Wichtig: Nicht mehr an neuen Stellen `reconcilix.example` hardcoden. **Priorität: mittel-hoch.** --- ## 6. Befund D – `technique_uri` ist derzeit leer, aber fachlich wichtig Im Dump ist bei allen InterpretationNodes: ```text technique_uri = NULL ``` DM001 beschreibt `InterpretationNode.technique` als optional verwendete Matching Technique. Zugleich stellt DM001 klar: > Eine InterpretationNode repräsentiert keinen Bearbeitungsschritt, sondern einen fachlich interpretierbaren Zustand. Das Feld wird wichtig, sobald die geplanten deterministischen Interpretationspfade umgesetzt werden, z. B.: ```text exact SourceValue right truncation left truncation bidirectional truncation / contains similarity-derived interpretation ``` ### Bewertung `technique_uri` ist der fachlich plausiblere Ort für **die Methode, durch die ein abgeleiteter InterpretationNode entstanden ist**. Das ist etwas anderes als: ```text Discovery Method → wie werden Candidates gesucht? ``` und etwas anderes als: ```text Matching Strategy des Resultats → wie ist der konkrete Reconciliation-Versuch charakterisiert? ``` ### Empfehlung `technique_uri` behalten. Heute nicht umbenennen. Vor Umsetzung der Interpretation-Pfade kontrolliertes Vokabular definieren. **Priorität: später, aber konzeptionell schützen.** --- ## 7. Befund E – `*_entity_type_uri` enthält Notationen statt URIs Der aktuelle Bestand zeigt: ```text source_value.preferred_entity_type_uri = CONCEPT candidate_item.entity_type_uri = CONCEPT ``` Damit besteht dieselbe formale Inkonsistenz wie bei `matching_strategy_uri`: Der Spaltenname verspricht eine URI, der Wert ist eine kontrollierte Notation. Das ist kein Qdrant-spezifisches Problem. Der aktuelle Rx-/OR-Contract verwendet `CONCEPT` bereits durchgängig als Entity-Type-Kennung. ### Bewertung Hier sollte **nicht kurzfristig der Contract gebrochen** werden. `CONCEPT` ist inzwischen Bestandteil des Source-Delivery-Formats und der externen Vector-Schnittstelle. ### Empfehlung Für RX-CLN-001 zunächst nur dokumentieren: ```text preferred_entity_type_uri entity_type_uri ``` sind derzeit historisch benannte Felder, deren tatsächliche Werte **Entity Type Identifiers / Notations** sind. Später gibt es zwei saubere Varianten: A. Spalten/Domain-Properties zu `preferred_entity_type` / `entity_type` umbenennen. B. Tatsächlich kontrollierte URIs einführen und Contracts migrieren. Für die aktuelle Implementierungsphase halte ich **A langfristig für weniger invasiv**, aber nicht für einen notwendigen Schritt vor DTB-002. **Priorität: niedrig-mittel.** --- ## 8. Befund F – `candidate_provider_uri` enthält beim Vector-Pfad einen Endpoint Im Dump steht bei Vector-Candidates: ```text candidate_provider_uri = https://halimede.digicult-verbund.de/qdrant/api/mct-reconcile/reconcile ``` Das ist technisch eine Endpoint-URL. Parallel kennt der Run bereits: ```text adapter_id = vector-qdrant client_id = qdrant-marburg ``` ### Bewertung Es ist zu klären, ob `candidate_provider_uri` fachlich bezeichnet: 1. den fachlichen Candidate Provider / Knowledge Source, 2. den technischen Service-Endpunkt, 3. oder die konkrete Adapterinstanz. Der aktuelle Vector-Wert spricht für Variante 2. Die Bezeichnung `candidate_provider_uri` legt aber eher Variante 1 nahe. ### Empfehlung Nicht sofort ändern, aber für DTB-002 explizit prüfen. Klassischer xTree- und Vector-Pfad sollten hier dieselbe Semantik haben. **Priorität: mittel.** --- ## 9. Vorgeschlagene begriffliche Ebenen Aus dem aktuellen Modell lassen sich fünf Ebenen sauber unterscheiden: ```text 1. Interpretation Technique Woher stammt ein interpretierter/abgeleiteter Node? → InterpretationNode.technique_uri 2. Discovery Method Wie werden CandidateItems technisch/funktional gesucht? → ReconciliationRun.configuration.discovery_method → Routing 3. Technical Adapter / Client Welche Implementierung bzw. Instanz führt Discovery aus? → adapter_id / client_id 4. Matching Strategy Wie ist ein konkreter Reconciliation-Versuch fachlich charakterisiert? → ReconciliationResult.matching_strategy_uri 5. Match Decision Welche fachliche Entscheidung wurde zu einem Result getroffen? → MatchDecision ``` Diese Ebenen sollten künftig nicht mehr durch denselben Identifier repräsentiert werden, solange sie nicht tatsächlich dieselbe Semantik besitzen. --- ## 10. Empfohlener Cleanup-Schnitt vor DTB-002 Ich empfehle einen bewusst kleinen **RX-CLN-001A**-Implementierungsschritt. ### Muss vor klassischem Run-Vergleich geklärt werden 1. `matching_strategy_uri` nicht mehr mit `VECTOR_SIMILARITY` befüllen. 2. Festlegen, welcher Matching-Strategy-Wert für den unveränderten Root-Node bei reiner Candidate Discovery sinnvoll ist – möglicherweise zunächst `NULL`. 3. Klassischen Pfad ebenfalls nicht pauschal mit `.../strategy/legacy` als fachlicher Matching Strategy fortschreiben, wenn „legacy“ lediglich den alten technischen Pfad bezeichnet. 4. Temporäre Statuswerte zentralisieren, damit Qdrant- und klassischer Testbench-Pfad dieselben Konstanten verwenden. 5. Semantik von `candidate_provider_uri` im klassischen und Vector-Pfad vergleichen. ### Kann bewusst später erfolgen - endgültige Entfernung/Neudefinition von `ReconciliationResult.success` - Migration von `CONCEPT` auf echte Entity-Type-URIs - endgültiges URI-Vokabular für Interpretation Techniques - struktureller Kontext / LLM - Prompt-/Model-Metadaten --- ## 11. Vorläufiges Votum für `matching_strategy_uri` Für die unmittelbar bevorstehende Discovery-Testbench erscheint folgende Trennung am saubersten: ### Run ```json { "discovery_method": "VECTOR_SIMILARITY", "adapter_id": "vector-qdrant", "client_id": "qdrant-marburg" } ``` bzw. klassisch beispielsweise: ```json { "discovery_method": "LEXICAL_LOOKUP", "adapter_id": "xtree-json-api" } ``` ### InterpretationNode Root Node, unveränderter SourceValue: ```text technique_uri = NULL ``` weil keine Ableitung/Interpretation stattgefunden hat. ### ReconciliationResult Solange keine eigenständige fachliche Matching Strategy vorliegt: ```text matching_strategy_uri = NULL ``` Das ist semantisch sauberer als eine technische Discovery Method oder `legacy` in ein URI-Feld zu schreiben. Sobald beispielsweise ein konkreter Interpretationspfad erzeugt wurde, kann dessen fachliche Semantik über `InterpretationNode.technique_uri` und – falls tatsächlich erforderlich – eine zusätzliche Matching Strategy des Results dokumentiert werden. **Diese Empfehlung ist bewusst vorläufig und sollte vor Implementierung gegen die vorhandenen Matching-/Interpretationspapiere geprüft werden.** --- ## 12. Konsequenz für DTB-002 Nach RX-CLN-001A kann die Rx Discovery Testbench zwei vergleichbare Runs erzeugen: ```text SourceDelivery ├── ReconciliationRun A │ discovery_method = LEXICAL_LOOKUP │ adapter = xTree │ └── ReconciliationRun B discovery_method = VECTOR_SIMILARITY adapter = vector-qdrant ``` Beide Runs können dann dieselbe Run-Population besitzen und über `ReconciliationRunItem` sauber verglichen werden, ohne technische Providerbegriffe in `ReconciliationResult.matching_strategy_uri` zu missbrauchen. Damit ist die Grundlage für EV-002 / run-basiertes Expertenfeedback deutlich stabiler. --- ## 13. Entscheidungspunkte für die nächste Runde Für die Umsetzung müssen aus meiner Sicht nur fünf Fragen entschieden werden: 1. Darf `matching_strategy_uri` bei reiner Candidate Discovery `NULL` sein? **Votum: ja.** 2. Soll `VECTOR_SIMILARITY` ausschließlich als `DiscoveryMethod` behandelt werden? **Votum: ja.** 3. Soll `legacy` aus neuen `ReconciliationResult` verschwinden? **Votum: ja.** 4. Sollen die aktuellen Graph-/Node-Status zunächst nur zentralisiert oder sofort durch endgültige Reconcilix-URIs ersetzt werden? **Votum: zunächst zentralisieren.** - siehe docs/transport/vocabulary/VOC002_Administrative_Status_Vocabulary.md 5. Was bezeichnet `candidate_provider_uri` exakt? **Noch offen; anhand xTree/LocalStore/Vector-Code prüfen.** Im Anhang habe ich das Modell vom ReconcilationStore (Vorsicht, der Begriff ist neu) skizziert. (A) Uns fehlen im Moment die Definitionen für matching_strategy_uri, vocabulary_matching_pattern_uri, technique_uri Im Modell im Anhang mit grünem Rahmen. Ist matching_strategy eher die Suchtypen (B) Bevor wir weitermachen sollten wir uns payload_json im Zusammenspiel mit candidate_provider_uri etwas genauer anschauen. Ich schlage vor, dass wir uns zunächst um (A) kümmern. Erst danach um (B)