Traducción. Autoritativo: fs-core-0003-identity-resolution.md.
Contexto
El cliente de una empresa existe en varios sistemas con llaves distintas, y un visitante anónimo se vuelve cliente conocido en algún punto de su recorrido. Resolver eso es la razón por la que existe un núcleo de clientes. Es también la operación más peligrosa de la plataforma. Una fusión falsa combina dos personas reales —su historial de compras, sus puntos, su consentimiento— y deshacerla es casi imposible porque el estado fusionado ya se leyó, se facturó y se actuó sobre él. Toda decisión aquí se inclina a negarse a fusionar cuando hay incertidumbre, y por eso las importaciones masivas producen una cola de revisión y no una resolución (DEC-A6).Alcance (normativo)
core.contact_identities: pares(proveedor, identificador)apuntando a un contacto.- Promoción anónimo → conocido: un id anónimo adquiere una identidad conocida sin perder historia.
- Resolución determinista sobre identificadores verificados.
core.contact_merges: registro inmutable de superviviente, absorbido y evidencia.- Ejecución de la fusión: identidades y eventos se mueven al superviviente; el absorbido queda como tombstone.
core.contact.mergedpara que los consumidores repunten sus propias referencias.
Fuera de alcance (normativo)
- Matching probabilístico o difuso. F1 fusiona solo sobre identificadores verificados. El matching por similitud de nombres es como ocurren las fusiones falsas, y no vale el recall.
- Deshacer una fusión. Deliberadamente no se construye: es la operación cuya existencia fomenta fusionar sin cuidado. La recuperación es un restore.
- La UI de la cola de revisión — FS-CORE-0013 es dueño de la cola; esto es dueño de la fusión que ejecuta.
Comportamiento (normativo)
- Una identidad es
(proveedor, identificador)único por tenant.proveedornombra el sistema de origen —email,phone,pos,ecommerce,national_id. - Las identidades llevan un flag
verified. Solo las verificadas impulsan resolución automática. Un email no verificado es una afirmación, no una identidad. - La promoción anónimo → conocido nunca pierde historia: la identidad anónima queda adherida al mismo contacto, así que los eventos recolectados antes del login siguen atribuidos.
- La fusión automática ocurre solo con coincidencia exacta de un identificador verificado. Cualquier cosa más débil produce una sugerencia de fusión, nunca una fusión.
- Una fusión es una transacción: las identidades repuntan, los eventos repuntan, el contacto absorbido queda como tombstone, se escribe la fila de fusión, se emite el evento y se escribe la auditoría.
- El superviviente conserva todas las identidades de ambos lados. Perder un identificador en una fusión rompería la integración que lo aportó.
core.contact_mergeses append-only e inmutable, y registra la evidencia que justificó la fusión. Sin evidencia, una fusión es inauditable.- El id del contacto absorbido sigue resolviendo — al superviviente. Una integración que guarde el id viejo no debe romperse.
- Los valores en conflicto se resuelven por una política explícita y documentada (gana el no nulo actualizado más recientemente), y los descartados quedan registrados en la fila de fusión en vez de perderse.
- PROHIBIDO: fusionar entre tenants, bajo cualquier circunstancia.
Datos (normativo)
API (normativo)
Eventos (normativo)
core.contact.merged, disponible como webhook saliente, con los ids de superviviente y absorbido
para que un consumidor repunte sus propias referencias.
Criterios de aceptación (normativo)
- Un contacto anónimo con 50 eventos, promovido por un email verificado, conserva los 50 atribuidos.
- Una coincidencia exacta de identificador verificado fusiona automáticamente; una no verificada produce una sugerencia y ninguna fusión.
- Tras la fusión el superviviente tiene la unión de ambos conjuntos de identidades, sin descartes.
- El id del contacto absorbido sigue resolviendo al superviviente por todo camino de lectura.
- Una fusión con falla inducida en el paso de repunte de eventos revierte por completo — no existe fusión parcial en ningún momento.
- Las filas de
contact_mergesno se pueden actualizar ni borrar. - Los valores en conflicto descartados son recuperables desde la fila de fusión.
- Negativo: un intento de fusión entre dos tenants se rechaza antes de cualquier escritura.