Skip to content

CAP-CRM-REG-011Apply the current policy across existing records

Markdown

CAP-CRM-REG-011

Apply the current policy across existing records

Markdown
  • DocumentDraft
  • Product intentProposed
  • ImplementationObserved

KindCapabilityProduct areaCRMModuleRegionsRevision2

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
Eligible records are reconciled against the current policy.Overrides, update locks and records with no past or present deciding address are preserved.Processing can resume and coordinate with concurrent saves.
Surfaces
consoleapijob
Intent sources
services-crm:docs/migrations/crm-regions/README.md#2026-10-08 — Final acceptance (decision 2026-10-08, Andrew: saving rules changes no record; staff press Recalculate)services-crm:docs/migrations/crm-regions/README.md#2026-10-12 — Final acceptance (second pass), decision 2026-10-11: rule or setting changes move no record; manual Recalculate with a recalculation-needed bannerservices-crm:docs/migrations/crm-regions/README.md#2026-10-12 — Final acceptance (second pass), decision 2026-10-11: the region follows an address change after the save, through the change-event queue

Controls

27 controls apply, from the corpus control catalogue.

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

Permissions

KeyChecked atScope
crm.regions.recalculateapitenant
crm.regions.recalculateconsoletenant

Business Rules

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

IdRuleKindEnforced atProvenance
01must prove
Proposed
Starting recalculation requires the administrator-tier recalculation permission.
permissionapitest
services-crm:tests/unit/regions-authorization.spec.ts#requires crm.regions.recalculate to start a recalculation
02must prove
Proposed
A workspace permits one running recalculation; another start returns that run and can advance its remaining batches within the request budget.
invariantservice, databasetest
services-crm:modules/regions/tests/integration/services/region-assignment/region-assignment.integration.spec.js#a recalculation resumed in batches › answers the running run to a second request instead of starting another
03must prove
Proposed
A small recalculation can finish during its start request, while remaining work continues in the background.
policyservicetest
services-crm:modules/regions/tests/integration/services/region-assignment/region-assignment.integration.spec.js#rule changes and the recalculation › finishes a small tenant within the request
04must prove
Proposed
Recalculation traverses contacts before organizations in batches and resumes from its committed position after an interruption.
invariantservicetest
services-crm:modules/regions/tests/integration/services/region-assignment/region-assignment.integration.spec.js#a recalculation resumed in batches › continues from its cursor, never repeating a record
05must prove
Proposed
Recalculation reevaluates eligible records under current rules through the common assignment decision, regardless of their remembered deciding address.
origin: services-crm:docs/migrations/crm-regions/README.md#2026-10-08 — Final acceptance (decision 2026-10-08, Andrew: saving rules changes no record; staff press Recalculate)
calculationservicetest
services-crm:modules/regions/tests/integration/services/region-assignment/region-assignment.integration.spec.js#rule changes and the recalculation › moves a contact to its region under the new rules
06must prove
Proposed
Recalculation skips overrides, records without a deciding address that never had one and records locked against updates.
origin: services-crm:docs/migrations/crm-regions/README.md#Behaviour changes, Not changed (kept as Rhythm 1.0 did; accepted by Andrew 2026-10-08)
policyserviceobserved
07must prove
Proposed
Repeating recalculation under unchanged rules does not change placements.
invariantservicetest
services-crm:modules/regions/tests/integration/services/region-assignment/region-assignment.integration.spec.js#rule changes and the recalculation › changes nothing on a second run under the same rules
08must prove
Proposed
A record save concurrent with recalculation ultimately places the record according to its newest address.
invariantservicetest
services-crm:modules/regions/tests/integration/services/region-assignment/region-assignment.integration.spec.js#a save racing a recalculation › ends with the region of the newest address
09
Proposed
Policy changes during a run are visible to subsequent batches.
policyserviceobserved
10must prove
Proposed
The examined count includes every traversed record, including skipped records, while changed counts only placements set or cleared.
calculationservicetest
services-crm:modules/regions/tests/integration/services/persistence/region-recalculations.queries.integration.spec.js#the record a batch of the run answers › answers the whole record of the run the following batches finished, counting every record it walked
11
Proposed
Starting recalculation while assignment is disabled traverses records but changes no placements.
policyserviceinferred
12
Proposed
The console places Recalculate in the needed banner, the toolbar during processing or an undismissed failure, and the action menu otherwise; disabled assignment hides it and missing authority disables it with an explanation.
origin: services-crm:docs/migrations/crm-regions/README.md#2026-10-15 — Final acceptance (console follow-ups) (Andrew approved 2026-10-15: two tabs, Test an Address dialog, drawers, a read-only Assignment Rules tab with its own editor screen and the banner)
policyconsoletest
react-console:components/regions/__tests__/recalculation.test.tsx#where Recalculate belongs › is in the banner that says it is needed

Scenarios

IdGivenWhenThenProvenance
01New York coverage now points elsewhere, with one contact held in the old region.An administrator runs recalculation.Eligible contacts move while the held contact remains.test
02A recalculation is already running.Another user requests recalculation.The request returns the same run rather than creating another.test

Edge Cases

IdGivenWhenThenProvenance
03Processing stops after a committed contact batch.A worker resumes the run.It continues beyond the saved position and completes the traversal.test
services-crm:modules/regions/tests/integration/services/region-assignment/region-assignment.integration.spec.js#a recalculation resumed in batches › ends completed, with every record examined once

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.