Merging duplicate people, end to end

The chain#

1. TRIGGER — two records describe one human. duplicates proposes the pair with the reason it looks that way, or somebody finds it while searching.
2. USER / EXTERNAL EVENT — a person opens the pair. Nothing external has happened and nothing external will: this flow never touches a provider.
3. AUTH / WORKSPACE RESOLUTION — both records belong to one workspace. The kernel scopes the query and row-level security backs it; there is no cross-workspace merge to attempt.
4. INGEST / REQUEST — the request names the record to keep and the record to merge. Missing either is refused with a 422 and a plain message rather than a guess about which was meant.
5. CANONICAL RECORD — one Person survives. Every identity from the other re-points to it, so by_handle sends the next message from any of those addresses to one place.
6. CLASSIFICATION / RESEARCH / REASONING — detection contributes the reason a pair looked alike. It does not contribute a verdict; two colleagues at one customer look alike too.
7. KNOWLEDGE + MEMORY + RULES — memory is held at the contact tier and a block lives as a block:<channel> tag, so the surviving record's memory is worth reading before Connect answers on that channel again.
8. AUTONOMY / APPROVAL — no autonomy mode authorises this. A merge is only ever a person's decision, which is why the Assistant's rights stop short of it.
9. ACTION / PROVIDER — none. Nothing is sent, no message goes out, and no customer is notified that their records were tidied.
10. RESULT — one record, immediately. There is no clean undo: separating the two again means working through the underlying rows by hand.
11. RELATIONSHIP / TIMELINE / MEMORY — stages, follow-ups, deals, demos, cases and onboarding are carried from each side; the timeline now assembles both histories in one order, which is why entries appear to arrive all at once.
12. AUDIT / USAGE / NEEDS YOU — the decision is recorded with who made it, because 'who joined these two customers, and when' is a question that gets asked months later.
13. NEXT — verify the survivor, tidy anything the merge deliberately did not resolve, and treat a wrong merge as manual repair work rather than a second merge.

Stage by stage#

The tidying is deliberate. A merge preserves rather than resolves, because choosing which of two lifecycle positions survives is a business decision dressed as a data one — what a merge preserves is the itemised list.

Doing it well#

1. Read the identities on both records first.

   Result Complementary addresses — a work address on one, a mobile on the other — are the strongest ordinary evidence that this is one human.

2. Read the most recent conversation on each.

   Result Two records discussing the same order or the same visit are usually one person. Two people discussing different things at one customer are not.

3. Choose the survivor by what colleagues will search for.

   Result Material from each side is kept either way, so the choice is about the name and addresses people will type months from now.

4. Accept, then verify.

   Result Count identities, check the pipeline and the follow-up queue for that person, confirm open cases are still open, and read the recomposed summary.

What this flow deliberately does not do#

• No bulk acceptance. A queue of proposals is for reading. Accepting a list unread is how a workspace loses the ability to tell two customers apart.
• No background merging. Nothing joins records while nobody is watching, at any confidence.
• No notification. The customer is unaffected — except that the next reply is written with the whole relationship in view.
• No deletion. Nothing is dropped to make the survivor tidier; the untidiness afterwards is visible work, which is the point.

Questions#

Related#

• Duplicate detection
• Merging two records
• What a merge preserves
• An obvious duplicate was not suggested
• Deciding whether two records are one person
• The customer timeline