Retire regions while preserving their references

Purpose

Staff retire a chapter or territory while retaining the regional references that existing records still need.

How It Works

Staff deactivate a region when its chapter or territory closes. Existing references remain available for ongoing record work. Deletion requires separate authority and fails while records or rules still depend on the region. An unused region can be removed permanently. The menu changes its activation action according to the region’s current state. Deactivating a target used by an enabled rule raises the recalculation signal, although matching continues assigning that inactive target. Product must settle that disagreement before retirement becomes a reliable workflow. Ordinary regional writes also accept locks, including a full lock that those writes cannot subsequently remove. The product should implement the recorded audited lock and unlock policy.

Relationships

Maintain the region catalogue supplies the regional catalogue used by the surrounding work.
Determine an address’s geographic region supplies the common geographic decision.
Identify placements that need recalculation identifies policy generations still needing application.

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: Referenced regions remain available and deletion refusals identify the dependency.Retirement retains current references.Unreferenced regions can be removed permanently.
Surfaces: consoleapi
Intent sources: services-crm:docs/migrations/crm-regions/README.md#Behaviour changes, item 3 (Andrew's requirement for the port: a region the workspace lacks is refused and a region in use cannot be deleted)services-crm:docs/migrations/crm-regions/README.md#2026-10-12 — Final acceptance (second pass), decision 2026-10-12: an inactive region is a gray Inactive pill, no Status columnservices-crm:docs/milestones/CRM-M3-crm-configuration.md#D-08

Controls

20 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-DAT-001 TC-DAT-003 TC-DAT-004 TC-LOG-001 TC-LOG-002 TC-LOG-003 TC-LOG-004 TC-LOG-005 TC-PI-001 TC-PI-003 TC-PI-005 TC-TEN-001 TC-TEN-002 TC-TEN-003

Permissions

Key	Checked at	Scope
`crm.regions.update`	api	tenant
`crm.regions.delete`	api	tenant
`crm.regions.delete`	console	tenant

Business Rules

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

Id	Rule	Kind	Enforced at	Provenance
`01`must prove Proposed	Deletion is rejected while a contact, organization or assignment rule references the region, with the dependency named and no changes committed. origin: services-crm:docs/migrations/crm-regions/README.md#Behaviour changes, item 3 (Andrew's requirement for the port: a region the workspace lacks is refused and a region in use cannot be deleted) no proof recorded yet	invariant	service, database	test services-crm:modules/regions/tests/integration/db/regions.table.integration.spec.js#references › refuses to delete a region a contact is in, naming what uses it
`02`must prove Proposed	Deleting an unreferenced region removes it permanently, and subsequent reads cannot find it. no proof recorded yet	lifecycle	service	test services-crm:modules/regions/tests/e2e/regions.e2e.spec.js#deletes a region nothing uses
`03`must prove Proposed	Deletion requires the administrator-tier delete permission, and the console withholds Delete from users who lack that permission. no proof recorded yet	permission	api, console	observed services-crm:tests/unit/regions-authorization.spec.ts#requires crm.regions.delete to delete a region; services-crm:modules/regions/aws/api/regions.routes.ts:regionsRoutes
`04`must prove Proposed	A delete lock prevents removal and a full lock also prevents editing; ordinary creates and replacements accept locks, and replacement without a delete lock clears that lock. no proof recorded yet	policy	service	observed services-crm:modules/regions/services/persistence/regions.ts:updateRegionRow, deleteRegionRow
`05`must prove Confirmed	The product should provide narrowly authorized, audited actions for setting and removing region locks independently of ordinary edits. origin: services-crm:docs/milestones/CRM-M3-crm-configuration.md#D-08 no proof recorded yet	permission	service	documented services-crm:docs/milestones/CRM-M3-crm-configuration.md#D-08
`06` Proposed	Deactivation preserves existing record and rule references, allowing staff to retire a region without removing it.	policy	service	test react-console:acceptance/crm/playwright/journeys/configuration/CRM-ACC-0361.spec.ts#CRM-ACC-0361
`07`must prove Proposed	Deactivating a region referenced by an enabled rule records a policy change for recalculation; deactivating an unreferenced region does not. no proof recorded yet	policy	service	observed services-crm:modules/regions/services/persistence/regions.ts:updateRegion; services-crm:modules/regions/services/persistence/region-assignment-settings.ts:noteRuleRegionDeactivated
`08`must prove Proposed	Enabled rules continue assigning an inactive target region because matching does not examine the target’s active state. no proof recorded yet	policy	service	test react-console:acceptance/crm/playwright/journeys/configuration/CRM-ACC-0361.spec.ts#CRM-ACC-0361
`09` Proposed	The console identifies inactive regions with a gray badge next to the name and omits a separate status column. origin: services-crm:docs/migrations/crm-regions/README.md#2026-10-12 — Final acceptance (second pass), decision 2026-10-12: an inactive region is a gray Inactive pill, no Status column	policy	console	test react-console:components/regions/__tests__/regions-screen.test.tsx#the regions table › marks an inactive region with the badge beside its name, and has no status column
`10` Proposed	An active region’s menu offers Deactivate, an inactive region’s menu offers Activate, and Delete appears last.	policy	console	test react-console:components/regions/__tests__/regions-row-menu.test.tsx#the Regions row menu › holds Deactivate for an active region and Delete last, and no Edit
`11` Proposed	The acceptance catalogue requires new-choice pickers to omit inactive regions while retaining and labelling an inactive region already selected on a record.	policy	console	documented react-console:acceptance/crm/journeys/configuration/CRM-ACC-0373.json

Scenarios

Id	Given	When	Then	Provenance
`01`	A retired chapter’s region remains referenced by contacts and a rule.	An administrator requests deletion.	References prevent deletion, leaving deactivation available instead.	test react-console:acceptance/crm/playwright/journeys/configuration/CRM-ACC-0361.spec.ts#CRM-ACC-0361
`02`	An accidentally created region has no references.	The administrator removes it.	The region is no longer readable.	test services-crm:modules/regions/tests/e2e/regions.e2e.spec.js#leaves nothing to read after the delete: a later GET answers 404

Edge Cases

Id	Given	When	Then	Provenance
`03`	An enabled rule targets a region just deactivated.	Staff inspect the Assignment Rules tab.	The tab requests recalculation even though matching still uses the inactive target.	test react-console:acceptance/crm/playwright/journeys/configuration/CRM-ACC-0361.spec.ts#CRM-ACC-0361

Planning

Retire regions while preserving their references ​

Purpose ​

How It Works ​

Relationships ​