govoplan-addresses/docs/QUALITY_AND_MERGE.md

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.