--- id: CON-CRM-DQ-004 name: Merge feature: FEAT-CRM-DQ-04 product_area: crm module: data-quality revision: 1 status: draft product_intent: confirmed implementation_evidence: observed source_sha: services-crm: a8d1364f1dd44b723bb5f9acba12f983e9ec8d69 react-console: baf6dae382d6f41dce976c7f848667ccc37e076f definition: >- A merge executes one reviewed plan atomically and retains an accountable outcome, including the identities absorbed by the survivor. owned_by: MOD-CRM-DQ synonyms: - record merge - merge record not_to_be_confused_with: - 'Distinguish this from the merge plan, which is the working state a person approves before a merge exists' - >- Distinguish this from deleting a record, which removes it without leaving an alias or moving what pointed at it facets: - name: Merge status and failure meaning: 'Attempt standing is queued, running, succeeded or failed, with readable failure reasons.' used_for: Understanding settlement and required remediation. - name: Merge job meaning: A durable job executes the merge and exposes four progress steps with reconciliation. used_for: Following long work and settling lost starts. - name: Original values meaning: Original snapshots retain participant information at execution time. used_for: Explaining omissions and supporting recreation after mistakes. - name: Outcome meaning: 'Field and collection results preserve sources, losses and attributed decisions.' used_for: Inspecting what the survivor received and why. - name: Related-record and login actions meaning: 'Applied actions retain moved, combined and preserved references and identity changes.' used_for: Tracing related work after absorption. - name: Merge pointer and announcement meaning: Audit pointers identify the merge and contacts publish a committed outcome event. used_for: Connecting record history and subscriber reactions. - name: Merge history and retention meaning: Workspace and record-lineage history preserve outcomes over workspace lifetime. used_for: Supporting accountability and later investigation. - name: Survivor pointer meaning: The absorbed identity points directly to the current survivor and redirects after later merges. used_for: Resolving older identities without a chain. - name: Merge reference meaning: The alias retains its own merge event and time. used_for: Explaining the original absorption. - name: Old number and integration identity meaning: 'Original number, source identity and external identity remain available on the alias.' used_for: Finding current identity through historical references. - name: Reuse guard meaning: The database prohibits assigning an absorbed identity to a new same-type record in the workspace. used_for: Preventing replayed payloads from recreating an absorbed person. - name: The merged answer meaning: Record responses distinguish merging from simple absence and identify the destination. used_for: Helping links and clients handle old references. - name: History through the survivor meaning: Absorbed record history remains accessible through the survivor lineage. used_for: Inspecting the earlier information behind the current record. relationships: - to: CON-CRM-DQ-003 statement: >- Each attempt executes one plan, with at most one active or successful attempt and retained failed attempts. provenance: test source: >- services-crm:modules/merges/tests/integration/db/record-merges.table.integration.spec.js#takes a new merge of a plan whose every earlier merge failed, which is how a failed merge is retried - to: CON-CRM-DQ-005 statement: Every absorbed record leaves an alias identifying its merge and survivor. provenance: test source: >- services-crm:modules/merges/tests/integration/services/merges/worked-example.integration.spec.js#names the merge that wrote each alias - to: CON-CRM-ENT-033 statement: The merge groups each record's captured changes with a common merge correlation. provenance: documented source: 'services-crm:docs/merging/architecture.md#8. Auditing' - to: CON-CRM-ENT-002 statement: Organization execution updates hierarchy and moves affiliations to its survivor. provenance: test source: >- services-crm:modules/merges/tests/integration/services/merges/organization-merge-execution.integration.spec.js#makes the child of the organization that went a child of the survivor lifecycle: - state: queued meaning: The confirmed attempt awaits execution. how_it_changes: Its job claims work or reconciliation starts or fails a lost job. - state: running meaning: The merge transaction is applying locked changes. how_it_changes: Commit succeeds or failure rolls the transaction back. - state: succeeded meaning: The complete combination has committed. how_it_changes: This attempt remains permanently settled. - state: failed meaning: The combination is unapplied and its reason is recorded. how_it_changes: The restored plan can create another distinct attempt. acted_on_by: - CAP-CRM-DQ-016 - CAP-CRM-DQ-017 - CAP-CRM-DQ-019 - CAP-CRM-DQ-011 - CAP-CRM-DQ-018 visible_to: - ACT-CRM-009 - ACT-CRM-008 - ACT-CRM-002 evidence: - repository: services-crm source_sha: a8d1364f1dd44b723bb5f9acba12f983e9ec8d69 paths: - docs/merging/README.md - docs/merging/architecture.md - docs/merging/experience/README.md - modules/merges/tests/integration/db/record-merges.table.integration.spec.js - modules/merges/tests/integration/services/merges/organization-merge-execution.integration.spec.js - modules/merges/tests/integration/services/merges/worked-example.integration.spec.js note: >- Static examination uses the cited records and implementation anchors; repository tests are not executed by this corpus check. supersedes: - CON-CRM-DQ-005 intent_sources: - 'services-crm:docs/merging/README.md#Status' - 'services-crm:docs/merging/experience/README.md#Status' --- # Merge ## What It Is A merge is the attempt to carry out an approved plan and the retained account of that attempt. Success combines participating contacts or organizations into one survivor and removes the other records. Failure records a reason without applying a partial combination. The survivor keeps its own identity, while aliases identify where the absorbed records went. Staff can distinguish the attempted work from the plan that described it. A plan may have failed attempts before a successful one, and each attempt retains its own outcome. The merge record preserves the originals and explains the result rather than requiring staff to reconstruct it from a collection of unrelated edits. That account matters because the absorbed records no longer exist as ordinary records. ## What It Is Not A merge is not an ordinary deletion or an archive action. It moves or deliberately retains related references according to the preview and leaves identity aliases. It is also not a reversible operation. The retained originals support investigation and recreation, but they do not supply an automatic undo that reconstructs the entire earlier situation across applications. ## How It Is Used An administrator confirms the reviewed plan and follows the background job. The worker locks affected records, recomputes the material preview and performs the approved changes in one transaction. Changed data or a participant refusal ends the attempt without partial record movement. Reconciliation prevents a lost job start from remaining indefinitely unexplained. After success, staff inspect the outcome to understand values kept, gaps filled and information discarded. A record reader can see the successful merges in that record's lineage without management authority. Management readers receive additional execution details. Integrations and old console links use absorbed identities to reach the survivor, even when it has subsequently been merged again. ## Its Facets **Status and failure** distinguish queued, running, succeeded and failed attempts and explain refusals. **The job** supplies visible progress and recovery for lost execution. **Original values** preserve the records as they were, while **the outcome** connects final values to sources and attributed choices. **Relationship and login actions** record movement, combination and preserved references. **Audit pointers and announcements** connect the merge to record history and contact-event subscribers. **History and retention** make those outcomes inspectable over the workspace lifetime. **Absorbed identity** is a facet of the merge. Its survivor pointer is redirected when that survivor merges again, so earlier identities resolve directly. Its merge reference keeps the original absorption event and time. Original numbers and integration identities support older lookups. The reuse guard prevents an absorbed identity from being assigned to a new record of the same type. Record responses identify merging rather than ordinary absence, and lineage remains readable through the survivor. ## How It Relates The merge executes a plan, changes records owned by Entities and invokes related changes owned by other applications. Duplicate review decisions about outsiders can transfer to the survivor. Platform owns the durable job infrastructure and audit trail, while CRM retains the merge outcome. Workspace export includes that retained evidence and its aliases. ## What It Could Become The product should implement the recorded privacy-removal commitment for individual original values. It should repair alias destinations after hard deletion of a survivor and expose survivor resolution for reports retaining absorbed identities. Product also needs to settle whether organization merges should announce an event like contact merges. These extensions should preserve atomic execution and the distinction between retained history and current identity.