Implement address quality and reversible contact merges

docs/ADDRESS_MODULE_ARCHITECTURE.md

@@ -70,7 +70,8 @@ representation for import/export and conflict handling.
 
 The local baseline implements scoped address books, contacts, normalized
 email/phone/postal-address tables, tags, source kind/reference fields,
-first-class source payload/revision fields, and provenance JSON. Imported
+first-class source payload/revision fields, preserved original contact-point
+values, and append-only field provenance. Imported
 vCards preserve raw source payload and revision metadata for audit/debugging.
 Sync sources, attempt state, tombstones, conflicts, and diagnostics are now
 first-class backend tables and API resources. Connector-specific diffing,
@@ -175,6 +176,32 @@ module retirement audits all remaining owned credential material before table
 removal. An unowned legacy reference is detached rather than passed to an
 external secret provider.
 
+## Quality, Deduplication, And Recovery
+
+Quality is evidence about a concrete contact point, separate from communication
+consent or Policy. Effective decisions use one of `valid`, `invalid`,
+`returned`, `stale`, or `undeliverable`, retain reason/evidence references, and
+end an overlapping prior decision rather than rewriting history. Recipient
+capabilities project the current decision into a stable status and reason code;
+consumers can exclude invalid points or explicitly handle stale points without
+copying Addresses rules.
+
+Duplicate suggestions are bounded to 500 scanned contacts and 100 returned
+pairs. Every score is composed from visible exact-match features such as a
+normalized email, phone, postal address, or name/organization combination. A
+suggestion does not mutate data.
+
+A merge is an explicit, transactional decision. The caller selects a surviving
+contact, scalar-field sources, source precedence, and either union or
+survivor-only contact-point handling. The merge records before/after evidence
+and hashes, field/contact-point decisions, copied quality/governance evidence,
+and stable loser-to-winner redirects. Address-list entries are repointed in the
+same transaction. Undo and split restore the recorded contacts and memberships
+only when the current evidence still matches the post-merge hash; later edits
+must be reconciled first. Core change-sequence evidence is always written. Core
+audit entries are written by HTTP mutation routes without requiring the
+optional Audit module.
+
 ## Connector Direction
 
 Implement connectors in this order:
@@ -218,7 +245,6 @@ those provider-owned facts.
 
 The following are valuable but not required for the first functional milestone:
 
-- automatic deduplication and merge suggestions
 - two-way sync conflict UI
 - Microsoft/Google connectors
 - richer vCard `KIND`/`RELATED` round-trip and provider-reference linking