Rhythm 2.0 Specifications

Appearance

CAP-CRM-DQ-012Prepare a merge and choose its survivor

Markdown

CAP-CRM-DQ-012

Prepare a merge and choose its survivor

Markdown
  • DocumentDraft
  • Product intentConfirmed
  • ImplementationObserved

Planning

Feature
FEAT-CRM-DQ-03
Key concepts
CON-CRM-DQ-003
Actors
ACT-CRM-009
Journeys
JNY-CRM-DQ-002
Related
CAP-CRM-DQ-010, CAP-CRM-DQ-013, CAP-CRM-DQ-016
Open questions
OQ-CRM-DQ-001, OQ-CRM-DQ-004
Proved by
ATS-CRM-DQ-012
Exercised by
JNY-CRM-DQ-003, JNY-CRM-DQ-004

KindCapabilityProduct areaCRMModuleDuplicate Review and Record MergingRevision1

Read atservices-crm a8d1364freact-console baf6dae3

Prepare a merge and choose its survivor ​

Purpose ​

Administrators can assemble the records to combine and choose the identity that remains.

How It Works ​

An administrator selects two to ten contacts or two to ten organizations. The service verifies distinct participants and rejects an unavailable or absorbed record. Planning requires both read and merge authority for the selected type. Rhythm recommends a survivor using login, integration, reference and age signals in order. The administrator may keep that recommendation or choose another participant. Each record has a summary of its identity, dates and related information. Changing participants or survivor recomputes the plan and retains decisions that still apply. The plan has a stable console address so work can resume later. Administrators can list unfinished plans through the API, normally their own. Abandoned open plans expire after seven days, but the stored working copies are not deleted. Another administrator with the necessary permissions may edit the same plan; the product decision about that shared access remains open.

Relationships ​

Decision review fills out the plan. Contact and organization combination determine its result. Execution consumes the approved preview rather than a fresh selection of records.

The Formal Contract

The narrative above explains; the sections below are authoritative — the rules, scenarios and tests this document binds.

Outcomes
A complete participant set is reviewed in one plan rather than successive pairwise choices.Survivor suggestions prioritize continuity while retaining administrator choice.Stored addresses and API listings support resumption, and overdue open plans expire.
Surfaces
consoleapi
Intent sources
services-crm:docs/merging/README.md#Status (architecture and plan approved by Andrew 2026-10-11)services-crm:docs/merging/conflict-resolution.md#8. Which record the system recommends keeping (decided by Andrew 2026-10-13)services-crm:docs/merging/experience/functional-requirements.md#SUR-1 to SUR-4, GEN-4, MAN-4 (package approved by Andrew 2026-10-13)

Controls

19 controls apply, from the corpus control catalogue.

TC-AZ-001 TC-AZ-002 TC-AZ-003 TC-AZ-004 TC-AZ-005 TC-AZ-006 TC-DAT-001 TC-DAT-002 TC-DAT-003 TC-LOG-004 TC-LOG-005 TC-PI-001 TC-PI-003 TC-PI-005 TC-PRV-001 TC-PRV-002 TC-TEN-001 TC-TEN-002 TC-TEN-003

Permissions

KeyChecked atScope
crm.contacts.mergeapitenant
crm.contacts.readapitenant
crm.organizations.mergeapitenant
crm.organizations.readapitenant

Business Rules

12 rules, 7 to be proved before approval. A rule's product intent is derived from its origin: 12 confirmed by a product decision, the rest inheriting this capability's confirmed.

IdRuleKindEnforced atProvenance
01must prove
Confirmed
A merge plan requires two to ten distinct records of one type and a survivor among them; invalid counts, repeats and outside survivors are rejected, missing records return not found and absorbed records report their survivor.
✓ For example, four records of one member are planned as one merge.✗ By comparison, eleven records are refused; the plan states the limit of ten.
origin: services-crm:docs/merging/README.md#Status (architecture and plan approved by Andrew 2026-10-11)
no proof recorded yet
validationapi, service, databasetest
services-crm:modules/merges/tests/integration/services/persistence/record-merge-plans.integration.spec.js#refuses more records than a merge takes
02must prove
Confirmed
All plan operations require the relevant type's read and merge permissions, deny cross-type authority and reject callers who can merge neither type before looking up a plan.
origin: services-crm:docs/merging/architecture.md#9. Security and tenant isolation
no proof recorded yet
permissionapitest
services-crm:modules/merges/tests/e2e/merges.e2e.spec.js#refuses the plan to a caller who may merge contacts but not organizations
03must prove
Confirmed
Survivor recommendation chooses the sole portal-linked participant, then the sole integration-addressed participant, then the uniquely most referenced participant, then the oldest; organizations omit the login criterion.
origin: services-crm:docs/merging/conflict-resolution.md#8. Which record the system recommends keeping (decided by Andrew 2026-10-13)
no proof recorded yet
calculationservicetest
services-crm:modules/merges/tests/unit/services/planning/survivor-recommendation.spec.js#keeps the participant the most rows outside the merge name, when no identity separates them
04must prove
Confirmed
A requested participant remains survivor even when the recommendation differs; without an explicit survivor, planning uses the recommendation.
origin: services-crm:docs/merging/conflict-resolution.md#8. Which record the system recommends keeping (decided by Andrew 2026-10-13)
no proof recorded yet
policyservicetest
services-crm:modules/merges/tests/integration/services/merges/survivor-recommendation.integration.spec.js#leaves the survivor the request named alone, the recommendation being advisory
05must prove
Confirmed
Recommendations explain their reasons using record names and numbers, mark an age-only choice as weak and never favor recency or completeness.
origin: services-crm:docs/merging/experience/functional-requirements.md#SUR-3
no proof recorded yet
policyservicetest
services-crm:modules/merges/tests/unit/services/planning/survivor-recommendation.spec.js#ignores how complete a record is: the fuller participant is not preferred
06
Confirmed
Participant summaries include creation and modification times, named status and type, login and integration presence, inbound reference counts and the information each contributes.
origin: services-crm:docs/merging/experience/functional-requirements.md#SUR-2
policyservicetest
services-crm:modules/merges/tests/integration/services/merges/participant-summary.integration.spec.js#says what it carries, by business concept and in the words staff read them by
07
Confirmed
Merge-authorized callers read service limits of two to ten participants, 100,000 related rows and 100,000 organization employees; the console obtains those limits from the service.
origin: services-crm:docs/merging/experience/functional-requirements.md#GEN-4
policyapitest
services-crm:modules/merges/tests/e2e/merges.e2e.spec.js#answers the numbers the engine itself enforces
08must prove
Confirmed
Participant or survivor changes recompute the plan, carry decisions for surviving questions and report discarded decisions while enforcing at least two participants.
origin: services-crm:docs/merging/experience/functional-requirements.md#SUR-4
no proof recorded yet
lifecycleservicetest
services-crm:modules/merges/tests/unit/services/planning/merge-decisions.spec.js#is dropped and reported when the plan is simply read again after the data moved on
09
Confirmed
Unfinished plans with decisions-needed, ready or blocked status list one type, default to the caller's plans and sort by latest change with 25 default and 50 maximum per page; editing does not transfer ownership.
policyapi, servicetest
services-crm:modules/merges/tests/integration/services/merges/merge-plan-lists.integration.spec.js#answers the reader’s own open plans, the one touched last at the top
10must prove
Confirmed
A five-minute sweep expires open plans seven days after their last change, preventing further changes or execution while leaving executed plans unchanged.
origin: services-crm:docs/merging/README.md#Status (architecture and plan approved by Andrew 2026-10-11)
no proof recorded yet
lifecycleservicetest
services-crm:modules/merges/tests/integration/services/merges/merge-plan-expiry.integration.spec.js#expires a blocked plan too, a plan nobody cleared being as abandoned as one nobody decided
11
Confirmed
Any workspace caller with both read and merge permissions for the plan's type may read and edit it regardless of its creator.
permissionapiobserved
services-crm:modules/merges/aws/api/merges.routes.ts:requireAccessToPlan
12
Confirmed
Once created, the console replaces the launcher with the plan's own address so the administrator can leave and resume it.
policyconsoletest
react-console:acceptance/crm/playwright/journeys/merging/CRM-ACC-0274.spec.ts#CRM-ACC-0274

Scenarios

IdGivenWhenThenProvenance
01Four records describe one member and exactly one has a portal login.An administrator creates a plan without selecting a survivor.The login-linked record is decisively recommended to avoid relinking the login.test
react-console:acceptance/crm/playwright/journeys/merging/CRM-ACC-0248.spec.ts#CRM-ACC-0248
02An open plan has received no changes for seven days.The expiry sweep evaluates it.Its status becomes expired and it no longer appears among unfinished plans.test
services-crm:modules/merges/tests/integration/services/merges/merge-plan-expiry.integration.spec.js#expires the plan whose seven days are up, which is what takes it off the reader’s list

Edge Cases

IdGivenWhenThenProvenance
03An administrator retains contact-merge authority but loses contact-read authority.They attempt contact and organization planning.Contact planning fails while authorized organization planning remains available.test
react-console:acceptance/crm/playwright/journeys/merging/CRM-ACC-0285.spec.ts#CRM-ACC-0285

The Markdown files under specs/ in rhythmsoftware/rhythm-v2-docs are the canonical source of truth. This reader is a generated, read-only projection of them.

Rhythm Software