# WP3-001-003 – Candidate Discovery Adapter Contract and Registry

- **Status:** Draft
- **Version:** 0.2
- **Scope:** WP3 – Discovery Framework Foundation
- **Owner:** ED
- **Review:** PL, LA

## Änderungsstand

### Version 0.2

Bezug zu v0.1 geändert:
- Name Version 0.1: WP3-001-003-Candidate_Discovery_Adapter_Contract_v0.1.md
- Name Version 0.2: WP3-001-003-Candidate_Discovery_Adapter_Contract_and_Registry_v0.2.md

Einarbeitung von LA Review 001.

**Änderungen**

- Work Package um `CandidateDiscoveryAdapterRegistry` erweitert.
- Rückgabetyp auf `DiscoveredCandidate[]` umgestellt.
- Adapter Registry als neue Kernkomponente ergänzt.
- Testimplementierung präzisiert.
- Klassenübersicht erweitert.
- Deliverables und Akzeptanzkriterien ergänzt.

---

## Referenzen

- WP3-001 – Discovery Framework Foundation
- WP3-001-001 – Discovery Route Model
- WP3-001-002 – Discovery Configuration Registry
- PRE_WP3-001 – Architekturübersicht Discovery Framework
- DM001 – Domain Model

---

# 1. Ziel

Dieses Work Package definiert den gemeinsamen technischen Vertrag für alle Candidate Discovery Adapter.

Zusätzlich führt es eine zentrale Registry zur Verwaltung aller Candidate Discovery Adapter ein.

Der Vertrag stellt sicher, dass unterschiedliche technische Implementierungen über eine einheitliche Schnittstelle angesprochen werden können.

Die konkrete Discovery-Logik ist nicht Bestandteil dieses Work Packages.

---

# 2. Scope

Dieses Work Package umfasst ausschließlich

- Einführung des Interface `CandidateDiscoveryAdapter`
- Einführung der Klasse `CandidateDiscoveryAdapterRegistry`
- Definition des gemeinsamen Adapter Contracts
- Bereitstellung einer Testimplementierung
- Contract Tests
- Registry Tests

Nicht Bestandteil sind

- produktive Adapter
- Candidate Discovery Router
- Runtime Integration
- HTTP
- REST
- SPARQL

---

# 3. Architekturbezug

PRE_WP3 beschreibt den **Technical Adapter** als technische Umsetzung einer Discovery Route.

WP3-001-003 konkretisiert diesen Architekturbaustein durch

- das Interface `CandidateDiscoveryAdapter`
- die `CandidateDiscoveryAdapterRegistry`

Alle zukünftigen technischen Discovery-Implementierungen verwenden diesen gemeinsamen Vertrag.

---

# 4. Klassenübersicht

| Klasse | Typ | Status | Verantwortung |
|---------|-----|--------|----------------|
| CandidateDiscoveryAdapter | Interface | Neu | Gemeinsamer technischer Vertrag |
| CandidateDiscoveryAdapterRegistry | Class | Neu | Verwaltung registrierter Adapter |
| DummyCandidateDiscoveryAdapter | Testimplementierung | Neu | Testimplementierung des Contracts |
| DiscoveryRoute | Class | Bestehend | Referenziert Adapter über `adapterKey` |

---

# 5. Verantwortung

Ein `CandidateDiscoveryAdapter` ist verantwortlich für

- Entgegennahme einer Discovery-Anfrage
- Durchführung der technischen Discovery
- Rückgabe von `DiscoveredCandidate[]`

Ein `CandidateDiscoveryAdapter` ist nicht verantwortlich für

- Auswahl einer Discovery Route
- Verwaltung der Discovery Configuration
- Routing
- Match Decisions
- Persistenz
- Runtime Configuration

---

Die `CandidateDiscoveryAdapterRegistry` ist verantwortlich für

- Registrierung von Candidate Discovery Adaptern
- Auflösung eines Adapters anhand des `adapterKey`
- Bereitstellung registrierter Adapter

Sie ist nicht verantwortlich für

- Discovery Routes
- Candidate Discovery
- Routing
- Adapter-Auswahl

---

# 6. Adapter Contract und Registry

Alle technischen Candidate Discovery Adapter implementieren denselben Vertrag.

Die `CandidateDiscoveryAdapterRegistry` verwaltet diese Adapter.

Beispiel:

```text
CandidateDiscoveryAdapterRegistry

├── local-reconciliation-store
├── xtree-json
├── lobid-gnd
├── qlever
└── qdrant
```

Der CandidateDiscoveryRouter kennt ausschließlich die Registry.

Er kennt keine konkreten Adapterimplementierungen.

---

# 7. Invarianten

Alle CandidateDiscoveryAdapter

- implementieren denselben Contract,
- liefern `DiscoveredCandidate[]`,
- kennen keine DiscoveryConfigurationRegistry,
- kennen keine weiteren Adapter,
- treffen keine Routingentscheidung.

Die CandidateDiscoveryAdapterRegistry

- kennt ausschließlich registrierte Adapter,
- kennt keine Discovery Routes,
- führt keine Candidate Discovery aus.

---

# 8. Implementierungsreihenfolge

1. Interface `CandidateDiscoveryAdapter` erstellen.
2. Klasse `CandidateDiscoveryAdapterRegistry` erstellen.
3. Registrierung von Adaptern implementieren.
4. Testimplementierung ergänzen.
5. Contract Tests ergänzen.
6. Registry Tests ergänzen.

---

# 9. Deliverables

## Neue Klassen

- CandidateDiscoveryAdapter
- CandidateDiscoveryAdapterRegistry

## Testimplementierung

- DummyCandidateDiscoveryAdapter

Offene Architekturfrage (LA Review 002):

Soll der DummyCandidateDiscoveryAdapter Bestandteil des Produktivcodes (src/) sein oder ausschließlich als Testimplementierung innerhalb der Teststruktur existieren?


## Neue Tests

- CandidateDiscoveryAdapterContractTest
- CandidateDiscoveryAdapterRegistryTest

---

# 10. Akzeptanzkriterien

Das Work Package ist abgeschlossen, wenn

- das Interface implementiert ist,
- Adapter registriert werden können,
- Adapter über `adapterKey` aufgelöst werden können,
- die Testimplementierung den Contract erfüllt,
- Contract Tests erfolgreich sind,
- Registry Tests erfolgreich sind,
- alle bestehenden Tests weiterhin erfolgreich sind.

---

# 11. Out of Scope

Nicht Bestandteil sind

- produktive Adapter
- Local Reconciliation Store
- xTree
- HTTP
- REST
- SPARQL
- CandidateDiscoveryRouter
- Runtime Integration

---

# 12. Auswirkungen auf Folgepakete

## WP3-001-004 – Candidate Discovery Router

Verwendet die `CandidateDiscoveryAdapterRegistry`, um den in einer DiscoveryRoute referenzierten CandidateDiscoveryAdapter aufzulösen.

## WP3-001-005 – Runtime Integration

Registriert alle produktiven Candidate Discovery Adapter im Composition Root.

## WP3-002

Implementiert den ersten produktiven CandidateDiscoveryAdapter für den Local Reconciliation Store.

## WP3-003

Implementiert den ersten produktiven CandidateDiscoveryAdapter für die xTree JSON API.