Rhythm 2.0 Specifications

Appearance

CAP-CRM-DQ-015Keep related records consistent through a merge

Markdown

CAP-CRM-DQ-015

Keep related records consistent through a merge

Markdown
  • DocumentDraft
  • Product intentConfirmed
  • ImplementationPartially observed

Planning

Feature
FEAT-CRM-DQ-03
Exercised by
FAS-CRM-DQ-03-02
Key concepts
CON-CRM-DQ-003
Actors
ACT-CRM-009, ACT-CRM-005
Journeys
JNY-CRM-DQ-002
Depends on
CAP-CRM-DQ-012
Related
CAP-CRM-DQ-008, CAP-CRM-DQ-016
Open questions
OQ-CRM-DQ-003
Proved by
ATS-CRM-DQ-015

Implementation

Executable suites
TST-CRM-DQ-176, TST-CRM-DQ-180, TST-CRM-DQ-181, TST-CRM-DQ-184

KindCapabilityProduct areaCRMModuleDuplicate Review and Record MergingRevision1

Read atservices-crm a8d1364freact-console baf6dae3

Keep related records consistent through a merge ​

Purpose ​

A merge accounts for references to its participants so related work remains attached or deliberately retained as history.

How It Works ​

The planner inspects related records and applies declared policies. Some references move to the survivor; others combine on collision or remain under the original identity as history. A reference without a policy blocks the merge. The preview summarizes the kinds and quantities involved. Other applications describe and execute their changes through functions owned by those applications. Their execution participates in the same transaction as CRM. Required participants that are unavailable prevent the merge, and a refusal rolls back all changes. Portal login decisions arrive through Platform's participant. Applicable outside dismissals carry to the survivor, while pairs internal to the merge disappear. The survivor receives fresh detection after the committed change. Bulk operations do not silently merge look-alike records.

Relationships ​

Contact and organization planners determine owned-record combinations. Platform supplies login handling, while each other application owns its participant. Execution provides the shared commit boundary.

The Formal Contract

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

Outcomes
Declared policies prevent unintended loss of related references.Original historical references remain readable through the survivor.Unsupported application participation prevents execution instead of stranding its references.
Surfaces
consoleapijob
Intent sources
services-crm:docs/merging/decisions.md#D1 (decided 2026-10-11: option 1)services-crm:docs/merging/decisions.md#D2 (decided 2026-10-11: option 1)services-crm:docs/milestones/CRM-M4-duplicates-and-merge.md#CRM-Q3services-crm:docs/merging/experience/functional-requirements.md#REL-1 to REL-6, DIS-8 (package approved by Andrew 2026-10-13)

Controls

29 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-DAT-004 TC-IAM-001 TC-IAM-002 TC-IAM-004 TC-IAM-005 TC-IAM-006 TC-LOG-004 TC-LOG-005 TC-MON-001 TC-MON-002 TC-PI-001 TC-PI-003 TC-PI-004 TC-PI-005 TC-PRV-001 TC-PRV-002 TC-PRV-003 TC-TEN-001 TC-TEN-002 TC-TEN-003

Permissions

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

Business Rules

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

IdRuleKindEnforced atProvenance
01must prove
Confirmed
Each referencing column, including references to owned children, requires one policy covering transfer, survivor reassignment, collision combination, domain combination, retained history, clearing, human decision, blocking or non-reference classification; coverage checks reject undeclared additions.
origin: services-crm:docs/milestones/CRM-M4-duplicates-and-merge.md#CRM-Q3
proved by ATS-CRM-DQ-015-01, ATS-CRM-DQ-015-15, TST-CRM-DQ-184
invariantservice, databasetest
services-crm:tests/integration/db/merge-coverage.integration.spec.ts#declares a policy for every column the catalog holds
02must prove
Confirmed
Undeclared references block both planning and execution with their row counts, allow no override and cease blocking when a policy covers them.
origin: services-crm:docs/milestones/CRM-M4-duplicates-and-merge.md#CRM-Q3
proved by ATS-CRM-DQ-015-02, ATS-CRM-DQ-015-15
validationservicetest
services-crm:modules/merges/tests/unit/services/planning/merge-decisions.spec.js#blocks the merge for a column the registry declares no policy for
03must prove
Confirmed
Tasks, activity links, spouse links, custom references, child organizations and integration mappings follow the survivor; duplicate activity links collapse and retain primary status if either link held it.
origin: services-crm:docs/merging/README.md#Status (architecture and plan approved by Andrew 2026-10-11)
proved by ATS-CRM-DQ-015-03, ATS-CRM-DQ-015-09, ATS-CRM-DQ-015-15, TST-CRM-DQ-176, TST-CRM-DQ-181
lifecycleservicetest
services-crm:modules/merges/tests/integration/services/merges/activity-links-merge.integration.spec.js#collapses a link the survivor already had into the survivor’s own, carrying the primary flag to it
04must prove
Confirmed
Audit entries, change history, import receipts and copied-from provenance retain original identities rather than being rewritten and remain readable through the survivor.
origin: services-crm:docs/merging/README.md#Status (architecture and plan approved by Andrew 2026-10-11)
proved by ATS-CRM-DQ-015-04, ATS-CRM-DQ-015-15, TST-CRM-DQ-176
policyservicetest
react-console:acceptance/crm/playwright/journeys/merging/CRM-ACC-0272.spec.ts#CRM-ACC-0272
05must prove
Confirmed
Other applications supply owned planning and execution functions in the merge transaction; a required missing or inaccessible participant blocks planning and a refusing participant rolls back execution.
origin: services-crm:docs/merging/decisions.md#D1 (decided 2026-10-11: option 1)
proved by ATS-CRM-DQ-015-05, ATS-CRM-DQ-015-15, TST-CRM-DQ-181
policyservice, databasetest
services-crm:modules/merges/tests/integration/services/merges/required-participants.integration.spec.js#blocks it as a participant that is missing, naming the functions it could not call
06must prove
Confirmed
A sole contact portal login is previewed, moved to the survivor and security-audited; multiple logins or record-specific grants block merging pending security administration.
origin: services-crm:docs/merging/decisions.md#D2 (decided 2026-10-11: option 1)
proved by ATS-CRM-DQ-015-06, ATS-CRM-DQ-015-15
policyservice, databasetest
services-crm:modules/merges/tests/unit/services/planning/merge-decisions.spec.js#carries the relink of the one login a participant holds
07must prove
Confirmed
Outside-pair dismissals move from absorbed records with attribution and evidence; existing survivor decisions prevail, otherwise the latest carried decision wins, and internal dismissals end with the merge.
origin: services-crm:docs/merging/experience/functional-requirements.md#DIS-8
proved by ATS-CRM-DQ-015-07, ATS-CRM-DQ-015-09, ATS-CRM-DQ-015-11, ATS-CRM-DQ-015-15, TST-CRM-DQ-176, TST-CRM-DQ-180
lifecycleservicetest
services-crm:modules/duplicates/tests/integration/services/persistence/duplicate-candidates.integration.spec.js#carries the dismissals about records outside the merge and nothing else
08must prove
Confirmed
Absorbed records lose their match keys and open or confirmed pairs, and later survivor detection recomputes its keys, scores and group among remaining records.
proved by ATS-CRM-DQ-015-08, ATS-CRM-DQ-015-10, ATS-CRM-DQ-015-12, ATS-CRM-DQ-015-15, TST-CRM-DQ-181
lifecycleservice, databasetest
services-crm:modules/merges/tests/integration/services/merges/duplicate-groups-after-merge.integration.spec.js#leaves the group holding the two records that are left, counted as it now stands
09
Confirmed
Related-record actions carry business labels, row counts and readable summaries, including explicit no-op actions and participant breakdowns where CRM computes them.
origin: services-crm:docs/merging/experience/functional-requirements.md#REL-1
policyservicetest
services-crm:modules/merges/tests/integration/services/merges/plain-language.integration.spec.js#is marked a no-op, so a screen may leave it out
10
Confirmed
Carried dismissals are excluded from approval binding, so an intervening dismissal alone does not stale a preview.
policyservicedocumented
services-crm:docs/merging/architecture.md#6.1 Policy vocabulary
11
Confirmed
Imports and updates do not merge look-alike records automatically; creation leaves separate records for detection to suggest.
origin: services-crm:docs/merging/README.md#Status (architecture and plan approved by Andrew 2026-10-11)
policyservicedocumented
services-crm:docs/merging/architecture.md#10. Data Operations boundary

Scenarios

IdGivenWhenThenProvenance
01An absorbed contact has tasks and shares an activity with the survivor.Execution combines the contacts.Tasks follow the survivor and one activity link retains primary status from the absorbed link.test
react-console:acceptance/crm/playwright/journeys/merging/CRM-ACC-0258.spec.ts#CRM-ACC-0258
02An absorbed contact has a dismissal concerning someone outside the merge.Execution commits the reviewed combination.The survivor inherits that decision against the outsider.test
react-console:acceptance/crm/playwright/journeys/merging/CRM-ACC-0237.spec.ts#CRM-ACC-0237

Edge Cases

IdGivenWhenThenProvenance
03A test participant refuses its execution.The merge attempts the participant change.Execution records the refusal and both contacts remain unchanged.test
services-crm:modules/merges/tests/integration/services/merges/toy-participant.integration.spec.js#leaves both contacts byte for byte as they were

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