Review duplicate groups in a shared queue

Purpose

Reviewers can examine connected suggestions together and retain their place while working.

How It Works

A reviewer opens the queue for contacts or organizations. Rhythm presents connected records as groups rather than requiring separate review of each pair. Confidence and other filters narrow the work, while sorting controls which groups appear first. Search matches the beginning of a name or an exact record number. Opening a group reveals its records and all constituent pairs. Group identity survives ordinary growth and keeps the largest contribution when groups split or join. Pair changes and group recalculation commit together. A group can be bounded when the full connection exceeds the review size. The address retains the filters, page and selected group for reloading or sharing. Reading requires duplicate-read authority.

Relationships

Detection creates suggestions and review decisions reshape their groups. Group details provide an entry to merge planning when the reviewer also has merge authority.

Show evidence (sources, provenance, origins, pinned commits)

The Formal Contract

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

Outcomes: Connected records appear together for review instead of as unrelated pairs.Group identity remains useful through growth and recomputation.The product should permit safe merge selection from the review group, explaining any size bound.
Surfaces: consoleapi
Intent sources: services-crm:docs/merging/experience/functional-requirements.md#DQ-2 to DQ-7 (package approved by Andrew 2026-10-13)services-crm:docs/merging/experience/functional-requirements.md#REV-8

Controls

16 controls apply, from the corpus control catalogue.

TC-AZ-001 TC-AZ-002 TC-AZ-003 TC-AZ-004 TC-AZ-006 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

Key	Checked at	Scope
`crm.duplicates.read`	api	tenant

Business Rules

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

Id	Rule	Kind	Enforced at	Provenance
`01`must prove Confirmed	Groups contain records connected by open pairs or by dismissed pairs of the same status, with at most ten records and a bounded indicator when further connections exist. origin: services-crm:docs/merging/experience/functional-requirements.md#REV-8 no proof recorded yet	calculation	service	test services-crm:modules/duplicates/tests/unit/services/groups/group-components.spec.js#says the group it cut short is bounded, so a reader knows there may be more of it
`02`must prove Confirmed	A growing group retains its identity; a split assigns the old identity to the largest contribution, a join keeps the identity contributing most records and fewer than two remaining records removes the group. origin: services-crm:docs/merging/experience/functional-requirements.md#DQ-7 no proof recorded yet	lifecycle	service	test services-crm:modules/duplicates/tests/unit/services/groups/group-components.spec.js#keeps the id for the part holding MORE of the group’s records, the other part being a new group
`03`must prove Confirmed	Pair changes and affected group recomputation share a transaction, keeping group membership and counts consistent for readers. no proof recorded yet	invariant	service, database	test services-crm:modules/duplicates/tests/integration/services/detection/duplicate-detection.integration.spec.js#grouped every pair it stored, the groups of a batch being written in the pass’s own transaction (§14)
`04`must prove Confirmed	Confirmed pairs have no group because their duplicate decision is already settled. no proof recorded yet	policy	service	test services-crm:modules/duplicates/tests/integration/services/persistence/duplicate-groups.integration.spec.js#belongs to no group: a confirmed pair is a decision, not a question the queue asks
`05`must prove Confirmed	Queue reads default to open groups and support dismissed status, confidence, up to ten recognized evidence codes, origin, detection dates and record filters, with strongest-score, newest-detection or size sorting; unknown evidence codes are rejected. origin: services-crm:docs/merging/experience/functional-requirements.md#DQ-4 no proof recorded yet	validation	api	test services-crm:modules/duplicates/tests/e2e/duplicate-groups.e2e.spec.js#refuses an evidence code no pair can carry, naming it rather than answering an empty page
`06`must prove Confirmed	Group pages default to 20 and cannot exceed 50, and a cursor from a different sort order is rejected. origin: services-crm:docs/merging/experience/functional-requirements.md#DQ-5 no proof recorded yet	validation	api	test services-crm:modules/duplicates/tests/e2e/duplicate-groups.e2e.spec.js#refuses a cursor answered for another order, rather than paging in the wrong one
`07`must prove Confirmed	Search matches a record-name prefix, contact names in surname-first form or an exact record number; a name's internal text does not match. no proof recorded yet	calculation	service	test services-crm:modules/duplicates/tests/e2e/duplicate-groups.e2e.spec.js#answers only the groups the records of a typed prefix are in, which is the search box
`08` Confirmed	Queue groups include record numbers, names, masked summaries, creation dates, record and pair counts, highest score and confidence and three leading reasons; details add all group pairs. origin: services-crm:docs/merging/experience/functional-requirements.md#DQ-3	policy	service	test services-crm:modules/duplicates/tests/integration/services/groups/duplicate-group-view.integration.spec.js#states no more reasons than a group may state, however much evidence its pairs carry
`09`must prove Confirmed	Duplicate-read authority is required to list or open groups, and a group absent from the workspace returns not found. origin: services-crm:docs/merging/architecture.md#9. Security and tenant isolation no proof recorded yet	permission	api, console	test services-crm:modules/duplicates/tests/e2e/duplicate-groups.e2e.spec.js#refuses a caller without the duplicates read permission
`10` Confirmed	The page address preserves record type, filters, order, page and selected group so reloads and shared links reproduce the review location. origin: services-crm:docs/merging/experience/functional-requirements.md#DQ-2	policy	console	test react-console:acceptance/crm/playwright/journeys/merging/CRM-ACC-0233.spec.ts#CRM-ACC-0233

Scenarios

Id	Given	When	Then	Provenance
`01`	A reviewer has a three-record group open.	Dismissing a pair leaves a two-record component and an isolated record.	The remaining group keeps the shared identity and the isolated record leaves the queue.	test services-crm:modules/duplicates/tests/unit/services/groups/group-components.spec.js#is no group at all: a group holds at least two records
`02`	Two reviewers open one group.	One reviewer settles it before the other acts.	The later response supplies the group identity the second reviewer follows.	test react-console:acceptance/crm/playwright/journeys/merging/CRM-ACC-0273.spec.ts#CRM-ACC-0273

Edge Cases

Id	Given	When	Then	Provenance
`03`	Eleven records are connected by suggestions.	Rhythm builds their groups.	The displayed group stops at ten, reports its bound and disables Merge with an explanation.	test react-console:acceptance/crm/playwright/journeys/merging/CRM-ACC-0275.spec.ts#CRM-ACC-0275

Planning

Review duplicate groups in a shared queue ​

Purpose ​

How It Works ​

Relationships ​