Skip to content

CAP-CRM-DQ-002Explain the strength of a duplicate suggestion

Markdown

CAP-CRM-DQ-002

Explain the strength of a duplicate suggestion

Markdown
  • DocumentDraft
  • Product intentConfirmed
  • ImplementationObserved

KindCapabilityProduct areaCRMModuleDuplicate Review and Record MergingRevision1

Read atservices-crm a8d1364freact-console baf6dae3

The Formal Contract

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

Outcomes
Confidence separates strong suggestions from weaker resemblance.Contradictory household, spouse and hierarchy evidence limits false confidence.Reasons communicate evidence while masking full private matching values.
Surfaces
jobapiconsole
Intent sources
services-crm:docs/merging/README.md#Status (architecture and plan approved by Andrew 2026-10-11)services-crm:docs/merging/decisions.md#D5 (decided 2026-10-13: option 3)services-crm:docs/merging/experience/functional-requirements.md#REV-1 to REV-3 (package approved by Andrew 2026-10-13)

Controls

17 controls apply, from the corpus control catalogue.

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

Permissions

KeyChecked atScope
crm.duplicates.readapitenant

Business Rules

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

IdRuleKindEnforced atProvenance
01must prove
Confirmed
Contact evidence contributes: shared origin 60; primary e-mail on both 40, another slot 30 or an address shared by at least three contacts 10; shared mobile 20; other phone 10 or zero with at least three holders; exact surname 15, phonetic surname 8, maiden-name match 5 or surname disagreement -20; exact first name 15, nickname 12, phonetic first name 8, initial 3 or disagreement -15; equal birth date 25 or conflict -40; conflicting middle initials -10; conflicting suffixes -30; equal street and postal code 15 or postal code alone 8; equal employer 8; reciprocal spouse evidence -30.
origin: services-crm:docs/merging/README.md#Status (architecture and plan approved by Andrew 2026-10-11)
no proof recorded yet
calculationservicetest
02must prove
Confirmed
Contact scores cannot exceed 49 for conflicting first and last names or birth dates, or 35 for conflicting suffixes; the lowest applicable ceiling wins.
✓ For example, two spouses sharing a household e-mail address score below the lowest band.✗ By comparison, two records of one person with the same e-mail address and names score very high.
origin: services-crm:docs/merging/README.md#Status (architecture and plan approved by Andrew 2026-10-11)
no proof recorded yet
calculationservicetest
03must prove
Confirmed
Organization evidence contributes: shared origin 60; exact normalized name 35, phonetic name 20, close name 15 or disagreement -20; shared non-free-mail domain 30; shared phone 15 or zero with at least three holders; equal street and postal code 20 or postal code alone 5; equal parent 5; ancestor relationship -40; different types -10; domain agreement without name agreement caps the score at 69 and ancestry caps it at 35.
origin: services-crm:docs/merging/README.md#Status (architecture and plan approved by Andrew 2026-10-11)
no proof recorded yet
calculationservicetest
services-crm:modules/duplicates/tests/unit/services/matching/organization-scoring.spec.js#holds a parent and its child to 35, however alike they read
04must prove
Confirmed
Confidence is very high at 90 or above, high at 70–89, medium at 50–69 and low at 35–49; scores below 35 produce no stored candidate.
origin: services-crm:docs/merging/README.md#Status (architecture and plan approved by Andrew 2026-10-11)
no proof recorded yet
calculationservice, databasetest
services-crm:modules/duplicates/tests/unit/services/matching/bands.spec.js#gives 34 no band at all, so the pair is not stored
05must prove
Confirmed
Explanations list a sentence and point contribution for each evidence item in scoring order, then describe every applied score ceiling.
no proof recorded yet
policyservicetest
06must prove
Confirmed
Explanations mask e-mail to its first character and domain and phone to its last four digits, omit full birth dates and retain public organization domains and matching names.
no proof recorded yet
policyservicetest
07
Confirmed
Reason text uses the records' accented and punctuated name spellings where available, falling back to stored evidence when neither record still supplies the name.
policyservicetest
services-crm:modules/duplicates/tests/integration/services/candidates/duplicate-candidate-view.integration.spec.js#names a last name that agrees as the records spell it, never in the lower-case form it is stored in
08must prove
Confirmed
Repeated scoring and reversed record order produce the same score, reasons and limits.
no proof recorded yet
invariantservicetest
services-crm:modules/duplicates/tests/unit/services/matching/contact-scoring.spec.js#answers the same reasons and caps whichever record is first
09
Confirmed
A candidate stores the scoring version associated with its evidence, allowing results from different weight versions to be distinguished.
policyservice, databasetest
10
Confirmed
Detection uses deterministic matching without a language model or database fuzzy-matching extension.
origin: services-crm:docs/merging/decisions.md#Settled by inspection or engineering practice (LLM in detection: none)
policyservicedocumented
services-crm:docs/merging/decisions.md#Settled by inspection or engineering practice (not up for decision)
11
Confirmed
The product should calibrate weights with synthetic examples and Rhythm 2.0 review decisions, excluding Rhythm 1.0 data.
origin: services-crm:docs/merging/decisions.md#D5 (decided 2026-10-13: option 3)
policyserviceunknown
12must prove
Confirmed
The tested household sharing one e-mail address remains low-confidence, while the tested spouse pair falls below the candidate threshold.
no proof recorded yet
calculationservicetest
services-crm:modules/duplicates/tests/unit/services/matching/contact-scoring.spec.js#scores a spouse pair below the band floor, which is what fixes 1.0’s “spouses score 94”
13must prove
Confirmed
The final score sums evidence, clamps the total between zero and 100 and applies the lowest triggered ceiling without permitting a negative result.
no proof recorded yet
calculationserviceobserved

Scenarios

IdGivenWhenThenProvenance
01Two member records share e-mail, names, mobile and birth date.The scorer evaluates their pair.Very-high confidence includes an explanation for each evidence item with masked e-mail.test
02A parent organization and its chapter have nearly identical names.The scorer evaluates their resemblance.The ancestry limit holds the result to 35 and low confidence.test
services-crm:modules/duplicates/tests/unit/services/matching/organization-scoring.spec.js#holds a parent and its child to 35, however alike they read

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.