Rhythm 2.0 Specifications

Appearance

DOM-CRM-DQ-003Merge Plan

Markdown

DOM-CRM-DQ-003

Merge Plan

Markdown
  • DocumentDraft
  • ImplementationObserved

Planning

Specified by
CON-CRM-DQ-003

Design

Owned by
SVC-CRM-DQ-merges

KindDomain objectProduct areaCRMModuleDuplicate Review and Record MergingRevision1

Read atservices-crm a8d1364freact-console baf6dae3

Merge Plan ​

What It Models ​

A merge plan is a shared working preview of a proposed combination. It records the selected participants, survivor and answers while the planner derives the values and reference changes that execution would apply.

Identity and Attributes ​

The plan identity supports returning to the same workspace. Decisions carry their authors, and optimistic versions protect edits. Open-plan reads can persist a refreshed preview and approval hash, so reading is an observable write when underlying data changes.

Relationships ​

Participants and affiliations remain owned by Entities. Plans describe their proposed treatment and can generate multiple attempts after failure; merge history remains even if a plan is later removed.

Invariants ​

Database checks constrain participant count, survivor membership and preview/hash pairing. The service additionally enforces distinct selections, version checks, valid answers and execution readiness.

How It Is Stored and Shared ​

The merges module owns the working row in CRM. Any qualified workspace administrator can access it regardless of creator, and it is excluded from workspace exports. No custom fields are declared.

Open Design Questions ​

Product still needs to resolve creator-only versus shared editing and whether another administrator’s read renews approval. Implementation must reconcile creation-based expiry and missing cleanup with the approved lifetime and retention rules.

Relationships

ToCardinalityOwnershipCrosses a serviceOn archive or delete
DOM-CRM-ENT-001One contact plan selects two to ten contacts.Entities retains contact ownership; the plan stores selected identities and a computed preview.no
DOM-CRM-ENT-002One organization plan selects two to ten organizations.Entities retains organization ownership; the plan holds references and copied preview values.no
DOM-CRM-ENT-003A plan can describe moves or combinations for many participant affiliations.Entities owns affiliations; planning describes proposed treatment without applying it.no
DOM-CRM-DQ-004One plan can have many attempts, with at most one active or successful attempt.Merge history retains the plan identity without a foreign key and can outlive the plan.no
DOM-CRM-DQ-001Selections may originate from review groups without a stored association.The duplicates module remains the owner of review evidence.no

Invariants

InvariantProtectsEnforced atProvenance
INV-DOM-CRM-DQ-003-01
A plan selects two to ten distinct participants and retains one of them as survivor.
service, databaseobserved
services-crm:modules/merges/services/persistence/record-merge-plans.ts:createRecordMergePlan; modules/merges/db/record-merge-plans.table.ts:record_merge_plans_record_ids_check
INV-DOM-CRM-DQ-003-02
A stored computed preview and its hash must either both exist or both be absent.
databaseobserved
services-crm:modules/merges/db/record-merge-plans.table.ts:record_merge_plans_plan_hash_check
INV-DOM-CRM-DQ-003-03
Plan changes reject an outdated version before applying the requested decisions.
api, servicetest
services-crm:modules/merges/tests/integration/services/merges/merge-plan-decisions.integration.spec.js#leaves both decisions on the plan, at the version it was refused against
INV-DOM-CRM-DQ-003-04
Decisions accumulate by question until cleared, and a request cannot answer and clear the same question.
api, servicetest
services-crm:modules/merges/tests/e2e/merges.e2e.spec.js#keeps the first answer when the second request answers only the other conflict
INV-DOM-CRM-DQ-003-05
Field choices are restricted to participating values or an empty choice for optional fields.
servicetest
services-crm:modules/merges/tests/unit/services/planning/contact-fields.spec.js#offers clearing the field as well as each value held
INV-DOM-CRM-DQ-003-06
Plans cannot be edited after entering executing, executed or expired standing.
serviceobserved
services-crm:modules/merges/services/merges/merge-plans.ts:assertPlanIsOpen
INV-DOM-CRM-DQ-003-07
Open-plan reads, changes and validation recompute current data and store changed results; settled plans retain their stored preview.
servicetest
services-crm:modules/merges/tests/e2e/merges.e2e.spec.js#answers the validation with the plan as it is now, ready to execute
INV-DOM-CRM-DQ-003-08
Execution requires cleared blockers and required questions, with explicit acceptance of defaulted decisions.
api, servicetest
services-crm:modules/merges/tests/e2e/merges.e2e.spec.js#names the conflict that is still open, so a console can take the reader to it
INV-DOM-CRM-DQ-003-09
Execution refuses a current material preview that differs from the stored reviewed preview.
servicetest
services-crm:modules/merges/tests/integration/services/merges/approval-binding.integration.spec.js#refuses an execution that submits no hash too, because the stored plan is the one last shown
INV-DOM-CRM-DQ-003-10
Presentation changes, estimates, survivor recommendations and carried dismissals are excluded from material hashing.
servicetest
services-crm:modules/merges/tests/integration/services/merges/lookup-labels.integration.spec.js#answers the same material hash, a name being no part of what staff are approving
INV-DOM-CRM-DQ-003-11
A reference lacking a merge policy creates a blocker with no override.
servicetest
services-crm:modules/merges/tests/unit/services/planning/merge-decisions.spec.js#blocks the merge for a column the registry declares no policy for
INV-DOM-CRM-DQ-003-12
The expiry sweep closes overdue working plans at an instant fixed one week after creation, including plans edited since then.
serviceobserved
services-crm:modules/merges/services/persistence/record-merge-plans.ts:defaultExpiry, updateRecordMergePlan, expireRecordMergePlans
INV-DOM-CRM-DQ-003-13
Plan routes require both read and merge authority for the relevant record type.
apitest
services-crm:modules/merges/tests/e2e/merges.e2e.spec.js#refuses the plan to a caller who may merge contacts but not organizations
INV-DOM-CRM-DQ-003-14
Workspace policy limits access to a plan’s own workspace.
databaseobserved
services-crm:db/row-level-security.ts (record_merge_plans forced workspace policy)

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