Implement address quality and reversible contact merges

2026-08-02 07:03:27 +02:00
parent 2e78b9ae50
commit 19e9096572
15 changed files with 4369 additions and 31 deletions
@@ -0,0 +1,57 @@
+# Address Quality And Reversible Merges
+
+## Operator Workflow
+
+Open the shield action for a selected address book to review its quality. The
+dialog shows:
+
+- the number of contacts and contact points in the bounded scan
+- current invalid, returned, stale, and undeliverable contact points
+- explainable duplicate suggestions with their score inputs
+- active and recovered merge records
+
+Each contact point also has a `Quality` action in the contact detail. Recording
+a new state ends an overlapping current state and retains both entries in
+history. Use a stable reason code and an evidence reference when the state came
+from delivery, import, or correction evidence.
+
+`valid` makes the point normally usable. `invalid`, `returned`, and
+`undeliverable` make it invalid for recipient resolution. `stale` remains a
+distinct status so a downstream workflow can warn, request confirmation, or
+block according to Policy. A later `valid` decision is a correction; it does
+not delete the earlier evidence.
+
+## Duplicate Review
+
+Suggestions do not merge automatically. The score is the bounded sum of named
+exact-match features. The operator chooses the surviving contact and whether to
+combine unique contact points or retain only the survivor's points. The API can
+additionally select the source contact for each scalar field and rank source
+kinds.
+
+A successful merge:
+
+- archives each duplicate and redirects its stable contact ID to the survivor
+- records scalar and contact-point survivorship decisions
+- carries field and contact-point source provenance forward
+- copies applicable quality and communication-governance evidence
+- repoints address-list entries to the survivor and mapped contact point
+- stores deterministic before/after evidence hashes
+- emits core change-sequence and audit evidence
+
+The merge history offers `Undo` and `Split`. Both restore the exact recorded
+pre-merge contacts and list memberships. Recovery is deliberately rejected when
+the contact or membership evidence changed after the merge. Reconcile those
+later edits before retrying; the system does not silently discard them.
+
+## Consumer Contract
+
+Consumers resolve live contacts through `addresses.contact_point_resolution` or
+`distribution.recipient_channel_facts`. They receive quality status, stable
+reason codes, evidence provenance, and the current source revision. Consumers
+must not read Addresses tables or recreate quality rules. A workflow requiring
+historical proof freezes a contact-point snapshot before delivery.
+
+The duplicate and quality endpoints are bounded. `truncated=true` means the
+operator should narrow the source or run a staged API review; it does not mean
+that the unreturned contacts were found clean.