GIA/artifacts/plans/04-identity-resolution-and-merge.md

Feature Plan: Identity Resolution and Merge

Goal

Improve person graph quality by suggesting and applying safe merges across transport identifiers.

Why This Fits GIA

• Core value of universal inbox depends on clean Person identity graph.

Scope

• Heuristic scoring for candidate merges.
• Manual review queue with approve/reject.
• Merge operation with audit trail and undo window.

Implementation

1. Add scoring service using signals: normalized phone, username similarity, name overlap, shared chat co-occurrence.
2. Add IdentityMergeSuggestion model with score + reasons.
3. Add UI panel to review/approve merges.
4. Implement safe merge transaction (PersonIdentifier reassignment, metadata merge rules).
5. Emit audit events and rollback snapshots.

Acceptance Criteria

• Suggestions generated deterministically and explain reasons.
• Merge is idempotent and reversible within configured window.
• No identifier is lost or orphaned.

Out of Scope

• Fully automatic merge without human approval.