--- id: CAP-CRM-REG-002 title: Retire regions while preserving their references feature: FEAT-CRM-REG-01 product_area: crm module: regions revision: 2 status: draft product_intent: proposed implementation_evidence: inconsistent supersedes: - CAP-CRM-CFG-015 source_sha: services-crm: a8d1364f1dd44b723bb5f9acba12f983e9ec8d69 react-console: baf6dae382d6f41dce976c7f848667ccc37e076f 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 column - 'services-crm:docs/milestones/CRM-M3-crm-configuration.md#D-08' purpose: >- Staff retire a chapter or territory while retaining the regional references that existing records still need. outcomes: - Referenced regions remain available and deletion refusals identify the dependency. - Retirement retains current references. - Unreferenced regions can be removed permanently. concepts: - CON-CRM-REG-001 - CON-CRM-REG-002 actors: - ACT-CRM-003 surfaces: - console - api preconditions: [] postconditions: [] permissions: - key: crm.regions.update where_checked: api scope: tenant - key: crm.regions.delete where_checked: api scope: tenant - key: crm.regions.delete where_checked: console scope: tenant rules: - id: BR-CAP-CRM-REG-002-01 statement: >- Deletion is rejected while a contact, organization or assignment rule references the region, with the dependency named and no changes committed. kind: invariant enforced_at: - service - database must_prove: true provenance: test source: >- 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 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) - id: BR-CAP-CRM-REG-002-02 statement: 'Deleting an unreferenced region removes it permanently, and subsequent reads cannot find it.' kind: lifecycle enforced_at: - service must_prove: true provenance: test source: 'services-crm:modules/regions/tests/e2e/regions.e2e.spec.js#deletes a region nothing uses' origin: none - id: BR-CAP-CRM-REG-002-03 statement: >- Deletion requires the administrator-tier delete permission, and the console withholds Delete from users who lack that permission. kind: permission enforced_at: - api - console must_prove: true provenance: observed source: >- 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 origin: none - id: BR-CAP-CRM-REG-002-04 statement: >- 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. kind: policy enforced_at: - service must_prove: true provenance: observed source: 'services-crm:modules/regions/services/persistence/regions.ts:updateRegionRow, deleteRegionRow' origin: none - id: BR-CAP-CRM-REG-002-05 statement: >- The product should provide narrowly authorized, audited actions for setting and removing region locks independently of ordinary edits. kind: permission enforced_at: - service must_prove: true provenance: documented source: 'services-crm:docs/milestones/CRM-M3-crm-configuration.md#D-08' origin: 'services-crm:docs/milestones/CRM-M3-crm-configuration.md#D-08' - id: BR-CAP-CRM-REG-002-06 statement: >- Deactivation preserves existing record and rule references, allowing staff to retire a region without removing it. kind: policy enforced_at: - service must_prove: false provenance: test source: 'react-console:acceptance/crm/playwright/journeys/configuration/CRM-ACC-0361.spec.ts#CRM-ACC-0361' origin: none - id: BR-CAP-CRM-REG-002-07 statement: >- Deactivating a region referenced by an enabled rule records a policy change for recalculation; deactivating an unreferenced region does not. kind: policy enforced_at: - service must_prove: true provenance: observed source: >- services-crm:modules/regions/services/persistence/regions.ts:updateRegion; services-crm:modules/regions/services/persistence/region-assignment-settings.ts:noteRuleRegionDeactivated origin: none - id: BR-CAP-CRM-REG-002-08 statement: >- Enabled rules continue assigning an inactive target region because matching does not examine the target’s active state. kind: policy enforced_at: - service must_prove: true provenance: test source: 'react-console:acceptance/crm/playwright/journeys/configuration/CRM-ACC-0361.spec.ts#CRM-ACC-0361' origin: none - id: BR-CAP-CRM-REG-002-09 statement: >- The console identifies inactive regions with a gray badge next to the name and omits a separate status column. kind: policy enforced_at: - console must_prove: false provenance: test source: >- 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 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 - id: BR-CAP-CRM-REG-002-10 statement: >- An active region’s menu offers Deactivate, an inactive region’s menu offers Activate, and Delete appears last. kind: policy enforced_at: - console must_prove: false provenance: test source: >- 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 origin: none - id: BR-CAP-CRM-REG-002-11 statement: >- The acceptance catalogue requires new-choice pickers to omit inactive regions while retaining and labelling an inactive region already selected on a record. kind: policy enforced_at: - console must_prove: false provenance: documented source: 'react-console:acceptance/crm/journeys/configuration/CRM-ACC-0373.json' origin: none scenarios: - id: SC-CAP-CRM-REG-002-01 given: A retired chapter’s region remains referenced by contacts and a rule. when: An administrator requests deletion. then: 'References prevent deletion, leaving deactivation available instead.' provenance: test source: 'react-console:acceptance/crm/playwright/journeys/configuration/CRM-ACC-0361.spec.ts#CRM-ACC-0361' - id: SC-CAP-CRM-REG-002-02 given: An accidentally created region has no references. when: The administrator removes it. then: The region is no longer readable. provenance: test source: >- 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: SC-CAP-CRM-REG-002-03 given: An enabled rule targets a region just deactivated. when: Staff inspect the Assignment Rules tab. then: The tab requests recalculation even though matching still uses the inactive target. provenance: test source: 'react-console:acceptance/crm/playwright/journeys/configuration/CRM-ACC-0361.spec.ts#CRM-ACC-0361' constraints: [] depends_on: - CAP-CRM-REG-001 related: - CAP-CRM-REG-001 - CAP-CRM-REG-006 - CAP-CRM-REG-010 journeys: - JNY-CRM-REG-004 open_questions: - OQ-CRM-REG-001 evidence: - >- services-crm: Examined the pinned regional implementation, its declared constraints and the supporting records. - 'react-console: Examined the pinned regional configuration surfaces and their available test evidence.' - 'services-crm:docs/migrations/crm-regions/README.md' - 'services-crm:docs/milestones/CRM-M3-crm-configuration.md' - 'services-crm:modules/regions/tests/integration/db/regions.table.integration.spec.js' - 'services-crm:modules/regions/tests/e2e/regions.e2e.spec.js' - 'services-crm:tests/unit/regions-authorization.spec.ts' - 'services-crm:modules/regions/aws/api/regions.routes.ts' - 'services-crm:modules/regions/services/persistence/regions.ts' - 'react-console:acceptance/crm/playwright/journeys/configuration/CRM-ACC-0361.spec.ts' - 'services-crm:modules/regions/services/persistence/region-assignment-settings.ts' - 'react-console:components/regions/__tests__/regions-screen.test.tsx' - 'react-console:components/regions/__tests__/regions-row-menu.test.tsx' - 'react-console:acceptance/crm/journeys/configuration/CRM-ACC-0373.json' controls: [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] --- # 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.