Implement address quality and reversible contact merges

README.md

@@ -42,6 +42,16 @@ inspection UI are implemented. The conflict review UI compares stored local and
 remote field payloads, can apply a stored remote vCard payload, and supports
 manual per-field local/remote merge choices.
 
+Address quality and duplicate handling are implemented as an operator workflow.
+Contact points retain both their original and normalized values, field-level
+provenance is append-only, and current quality states can mark a point valid,
+invalid, returned, stale, or undeliverable. Those states flow into recipient
+resolution with stable reason codes. The quality dialog shows bounded,
+explainable duplicate suggestions and a correction queue. Merges record explicit
+survivorship decisions, repair address-list memberships, preserve redirects for
+stored contact references, and can be undone or split while the post-merge
+evidence hash still matches.
+
 API-managed CardDAV credentials are encrypted inside the source record. Source
 deletion physically removes that credential material and records a non-secret
 audit event in the same database transaction; destructive module retirement
@@ -72,9 +82,9 @@ It must not own:
   effective function assignments
 - operational distribution lists/`Verteiler` with mixed recipient types
 
-## First Capabilities
+## Capabilities
 
-The module exposes four core-mediated capabilities:
+The module exposes core-mediated capabilities for:
 
 - `addresses.lookup`: read-only contact/recipient lookup for autocomplete.
 - `addresses.recipient_source`: immutable recipient snapshots for campaign,
@@ -84,6 +94,10 @@ The module exposes four core-mediated capabilities:
 - `addresses.contact_point_resolution`: purpose-aware, channel-neutral
   resolution and immutable snapshots for email, postal, internal-mail, and
   portal targets.
+- `addresses.people_search`: privacy-aware contact candidates for shared people
+  pickers.
+- `distribution.recipient_channel_facts`: current channel, governance, and
+  quality facts for distribution and Policy consumers.
 
 `addresses.recipient_source` returns:
 
@@ -131,8 +145,20 @@ The corresponding HTTP API is available below `/api/v1/addresses`:
 - `POST /contact-point-snapshots`
 - `GET /contact-point-snapshots/{snapshot_id}`
 
+Quality, provenance, and reversible merge operations are available through:
+
+- `GET /address-books/{book_id}/quality-summary`
+- `GET /address-books/{book_id}/duplicate-suggestions`
+- `GET|POST /contacts/{contact_id}/quality-decisions`
+- `GET /contacts/{contact_id}/provenance`
+- `GET /contacts/{contact_id}/redirect`
+- `GET|POST /contact-merges`
+- `POST /contact-merges/{merge_id}/undo`
+- `POST /contact-merges/{merge_id}/split`
+
 ## Design Documents
 
 - [Address module architecture](docs/ADDRESS_MODULE_ARCHITECTURE.md)
 - [Implementation plan](docs/IMPLEMENTATION_PLAN.md)
+- [Address quality and reversible merges](docs/QUALITY_AND_MERGE.md)
 - [AdreMa capability assessment and Distribution Lists roadmap](https://git.add-ideas.de/GovOPlaN/govoplan-dist-lists/src/branch/main/docs/ADREMA_CAPABILITY_ASSESSMENT.md)