Give Person a set of stable UUIDs (one primary) as the external identifier, durable across merges

[rjsparks]

Description

Background

Sometimes a workflow causes a new Person object to be created when an existing Person should have been used. We have tooling to merge these duplicate Person objects (and the objects associated with them). We're only acknowledging here that duplicates happen and get merged — preventing them is out of scope for this issue.

Problem

Systems outside the datatracker — e.g. MeetEcho and purple — pass Person references around using the datatracker's database pk. When we merge duplicate Person records, a pk that an external system is holding disappears. Without synchronous, coordinated changes across every relying system, there is no simple way to reattach a reference to a Person pk that has gone away (because of a merge) to the right surviving pk. Merging people in those external systems is difficult, and the pk was the wrong thing to export in the first place.

Proposal

Add a set of UUIDs to Person, with exactly one marked primary.

• Relying applications are handed the primary UUID as the person identifier — never the pk.
• When two Person records are merged, the UUIDs from both records are added to the surviving record's set (union). A single primary is retained.
• When a relying application later asks about a UUID it holds and a merge has since happened, the lookup consults the whole set, so the old UUID still finds the right (surviving) Person.
• On such a lookup, the application can then be told the new primary UUID so it can update its own stored reference at its own pace — no synchronous cross-system migration required.

Relationship to #6087

This replaces #6087 ("Capture Person/User merges going forward"). #6087 proposed MergedPersons/MergedUsers tables so APIs could follow old_pk → new_pk; a UUID set decouples external identity from the pk entirely and makes old identifiers self-resolving, so relying systems no longer need to chase a merge chain keyed on an internal pk. Adopting this obviates #6087, which should be closed in favor of this issue.

Sketch of work

1. Add UUID storage to Person (a related PersonUUID table or equivalent) with a uniqueness constraint and a single "primary" flag; migration to backfill one UUID per existing Person.
2. Update the merge flow to union the UUID sets of the merged records and keep exactly one primary.
3. Add a resolver (API + internal helper): UUID → Person, returning the current primary UUID so callers can self-heal.
4. Expose the primary UUID through the API surfaces that MeetEcho and purple consume; document the "we may hand you back a new primary UUID" contract.

Code of Conduct

• I agree to follow the IETF's Code of Conduct

[rjsparks]

This is being explored at #10558

[jennifer-richards]

A wrinkle that I'm not sure is covered by this description is a situation where a user has interacted with an application by logging in via two different accounts, which are later merged. E.g., someone sets up a datatracker account with UUID1 and logs in to zulip or meetecho. Later, then create an account with UUID2 and log in with that to another session. When they later merge accounts making (say) UUID1 the primary, zulip will be left with an orphaned account because at login, they'll never log in with UUID2.

It's definitely out of scope to actually solve how to merge accounts on external services, but we should be sure it's possible if the application can support it.

What's missing is "when logging in with a primary UUID, its synonyms are made available". That way an aware app could scan its accounts to see if any of those also have a separate account that requires merging.

[rjsparks]

this is going to interact with what we're building at Authentik (cc: @NGPixel). Do we really need a claim that has all the UUIDs from the set in the OIDC claims, or is it sufficient for an application to get whatever the primary UUID is and then hit an API to get the full set?