Check drafts and account for block overrides

Purpose

Staff can inspect possible matches before creation, and authorized exceptions retain their reasons.

How It Works

A draft check compares the entered details with existing records using ordinary matching. The response contains a small ranked set of suggestions. It includes enough identity information and reasons for staff to recognize each match. No candidate is stored merely because a form was checked. Blocking settings can refuse creation. An authorized person can choose Create Anyway and supply a reason. The override records that person, the blocking rules and the existing records involved. The create and its override record commit together, so an audit failure also prevents creation. The exception details remain separate from the new contact or organization. The service owns authorization and refusal; the console presents the available action.

Relationships

Duplicate settings determine blocking. Entities owns record creation and its refusal. This capability owns the check response and the override record.

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: Draft matching reveals likely counterparts without retaining form checks.Authorized blocking exceptions retain their author, time and explanation.
Surfaces: consoleapi
Intent sources: services-crm:docs/milestones/CRM-M4-duplicates-and-merge.md#D-32services-crm:docs/merging/experience/functional-requirements.md#CON-6 (package approved by Andrew 2026-10-13)

Controls

22 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-CRY-004 TC-DAT-001 TC-DAT-002 TC-DAT-003 TC-LOG-001 TC-LOG-002 TC-LOG-003 TC-LOG-004 TC-LOG-005 TC-PI-001 TC-PI-003 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
`crm.contacts.create-despite-duplicate-block`	service	tenant
`crm.organizations.create-despite-duplicate-block`	service	tenant

Business Rules

13 rules, 10 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.

Id	Rule	Kind	Enforced at	Provenance
`01`must prove Confirmed	Draft checks use detection's keys and scoring within the workspace and exclude the edited record from its own results. origin: services-crm:docs/merging/experience/functional-requirements.md#CON-6 no proof recorded yet	calculation	service	test services-crm:modules/duplicates/tests/integration/services/detection/duplicate-checks.integration.spec.js#does not answer the record itself, a record never being its own duplicate
`02`must prove Confirmed	A check returns at most five matches in descending score order, using the weakest active-rule confidence floor for that type or medium when there are no active rules. no proof recorded yet	calculation	service	test services-crm:modules/duplicates/tests/integration/services/detection/duplicate-checks.integration.spec.js#answers at most the five a form shows, however many the tenant holds
`03` Confirmed	Each result supplies record number, name, score, confidence and reasons, and the response indicates whether a blocking rule applies.	policy	api, service	test services-crm:modules/duplicates/tests/e2e/duplicates.e2e.spec.js#says the tenant’s block rule fires on it, which is what makes the create refuse
`04`must prove Confirmed	Checking a draft writes no record, match key or review candidate. no proof recorded yet	invariant	service	test services-crm:modules/duplicates/tests/e2e/duplicates.e2e.spec.js#writes nothing: the draft is not a record, so the queue is as it was
`05`must prove Confirmed	The duplicate-read permission is required for a draft check, and callers lacking it are refused. origin: services-crm:docs/merging/architecture.md#9. Security and tenant isolation no proof recorded yet	permission	api	test services-crm:modules/duplicates/tests/e2e/duplicates.e2e.spec.js#answers 403 to a caller with no duplicates permission at all
`06`must prove Confirmed	An overridden create and its override record share a transaction; the record retains the author, time, trimmed reason, distinct blocking rules and bypassed matches, and an audit-write failure rolls back creation. origin: services-crm:docs/milestones/CRM-M4-duplicates-and-merge.md#D-32 no proof recorded yet	invariant	service, database	test services-crm:modules/duplicates/tests/integration/services/persistence/duplicate-block-overrides.integration.spec.js#leaves no contact behind, the record and its audit sharing one transaction
`07`must prove Confirmed	An override requires a nonempty reason and at least one rule, with at most one override record for a created record. origin: services-crm:docs/milestones/CRM-M4-duplicates-and-merge.md#D-32 no proof recorded yet	validation	service, database	test services-crm:modules/duplicates/tests/integration/services/persistence/duplicate-block-overrides.integration.spec.js#refuses an override naming no rule, naming the field
`08`must prove Confirmed	Application updates cannot alter an existing override record. origin: services-crm:docs/milestones/CRM-M4-duplicates-and-merge.md#D-32 no proof recorded yet	invariant	database	test services-crm:modules/duplicates/tests/integration/services/persistence/duplicate-block-overrides.integration.spec.js#is not rewritable by the application, which holds no UPDATE on the audit
`09` Confirmed	The created record does not store override confirmation or explanation; the separate override record stores those details.	policy	service	test services-crm:modules/duplicates/tests/e2e/duplicates.e2e.spec.js#stores neither the confirmation nor the reason on the record, both being about the create and not fields
`10`must prove Confirmed	Organization creation uses organization matching settings and requires the organization-specific override permission. origin: services-crm:docs/milestones/CRM-M4-duplicates-and-merge.md#D-32 no proof recorded yet	policy	api, service	test services-crm:modules/duplicates/tests/e2e/organization-block-rules.e2e.spec.js#audits the override with its reason, its rule and the organization it was let past
`11`must prove Confirmed	The console presents Create Anyway with a required explanation only when the refusal reports override authority; service checks decide whether creation proceeds. origin: services-crm:docs/milestones/CRM-M4-duplicates-and-merge.md#D-32 no proof recorded yet	permission	console	observed react-console:components/records/create/duplicate-block-refusal.tsx:onCreateAnyway
`12` Confirmed	Workspace data exports include duplicate-block override records.	policy	service	observed services-crm:modules/duplicates/export/duplicate-block-overrides.dataset.ts
`13`must prove Confirmed	A draft check rejects record types other than contacts or organizations as an invalid request. no proof recorded yet	validation	api	observed services-crm:modules/duplicates/aws/api/duplicates.routes.ts:objectTypeOf

Scenarios

Id	Given	When	Then	Provenance
`01`	A coordinator enters a new contact resembling an existing member's name and postal code.	The form requests matching suggestions.	The member appears with score and reasons without a write.	test react-console:acceptance/crm/playwright/journeys/merging/CRM-ACC-0243.spec.ts#CRM-ACC-0243
`02`	An authorized administrator encounters a blocked create.	They choose an exception and supply its explanation.	The contact and override retain administrator, reason, rule and bypassed match.	test services-crm:modules/duplicates/tests/e2e/duplicates.e2e.spec.js#audits the override with its reason and the record it was let past

Planning

Check drafts and account for block overrides ​

Purpose ​

How It Works ​

Relationships ​