--- id: STATE-CRM-REG-001 title: Region availability object: DOM-CRM-REG-001 product_area: crm module: regions revision: 2 status: draft design_intent: proposed implementation_evidence: observed source_sha: services-crm: a8d1364f1dd44b723bb5f9acba12f983e9ec8d69 react-console: baf6dae382d6f41dce976c7f848667ccc37e076f states: - name: active meaning: The definition is active and available as a geographic target. - name: inactive meaning: >- Retirement preserves references; enabled coverage continues matching this target, although new-choice controls should omit it. - name: deleted meaning: The definition has been removed after dependency and lock checks. transitions: - from: active to: active trigger: Create a definition or save an active definition with active retained. guard: >- Creation needs create authority and valid data; later saves need update authority, a current version and no full lock. side_effects: - Accepted updates increment the version even without a business change. - Submitted integration and customer-lock values are persisted. who: 'A user with regional create or update authority, or a regional import' provenance: observed source: >- services-crm:modules/regions/tests/integration/services/persistence/regions.integration.spec.js#creates a region active by default; services-crm:modules/regions/services/persistence/regions.ts:insertRegion, updateRegionRow; services-crm:modules/regions/aws/api/regions.routes.ts - from: active to: inactive trigger: Save the active flag as false. guard: 'Update authority, a matching version and an editable definition are required.' side_effects: - An enabled referencing rule causes generation and change-time updates within the same transaction. - Existing references remain unchanged. who: 'A user with regional update authority, or a regional import' provenance: observed source: 'services-crm:modules/regions/services/persistence/regions.ts:updateRegion' - from: inactive to: active trigger: Save the retired definition with active restored. guard: 'The caller must have update authority, the current version and no blocking full lock.' side_effects: - Reactivation leaves the policy generation unchanged. who: 'A user with regional update authority, or a regional import' provenance: observed source: 'services-crm:modules/regions/services/persistence/regions.ts:updateRegion' - from: inactive to: inactive trigger: Save other fields while the definition remains retired. guard: 'The caller must satisfy update permission, version and lock checks.' side_effects: - An accepted save increments the definition’s version. who: 'A user with regional update authority, or a regional import' provenance: observed source: 'services-crm:modules/regions/services/persistence/regions.ts:updateRegionRow' - from: active to: deleted trigger: Request removal of an active definition. guard: Delete authority is required; neither lock kind nor any record or rule dependency may remain. side_effects: - Successful removal has no placement update; a blocked removal reports its dependency category. who: A user with administrator-tier regional delete authority provenance: observed source: >- services-crm:modules/regions/tests/integration/db/regions.table.integration.spec.js#regions table (integration) › references › refuses to delete a region a contact is in, naming what uses it; services-crm:modules/regions/services/persistence/regions.ts:deleteRegionRow; services-crm:modules/regions/aws/api/regions.routes.ts:deleteRegion - from: inactive to: deleted trigger: Request removal of an unused retired definition. guard: Deletion requires the delete key and a definition with no lock or dependency. side_effects: - The unused definition is removed without changing placements. who: A user with administrator-tier regional delete authority provenance: observed source: 'services-crm:modules/regions/services/persistence/regions.ts:deleteRegion' invalid: - from: deleted to: active why: Removal has no restore operation; reusing the identifier creates another definition. - from: active to: deleted why: Dependencies or either lock kind prevent this transition. - from: inactive to: active why: A full lock prevents reactivation through the ordinary update operation. concurrency: >- Edits lock the definition and compare the caller’s version, allowing only one successful edit from a shared version. Deletion locks without a version check. Immediate reference checks coordinate competing removal and reference writes so new dangling references cannot commit. invariants: - INV-DOM-CRM-REG-001-03 - INV-DOM-CRM-REG-001-05 - INV-DOM-CRM-REG-001-06 - INV-DOM-CRM-REG-001-07 evidence: - >- services-crm at a8d1364f: modules/regions/services/persistence/regions.ts; db/regions.table.ts; aws/api/regions.routes.ts; tests/integration/db/regions.table.integration.spec.js. - 'react-console at baf6dae3: components/regions/regions-table.tsx (Deactivate, Activate and Delete actions).' --- # Region availability ## The Lifecycle ```mermaid stateDiagram-v2 [*] --> active: create active [*] --> inactive: create retired active --> active: edit inactive --> inactive: edit active --> inactive: retire inactive --> active: reactivate active --> deleted: remove unused unlocked definition inactive --> deleted: remove unused unlocked definition deleted --> [*] ``` ## Transitions Explained Creation normally produces an active definition, but the caller can create it retired. Retirement preserves references. An enabled rule targeting the retired definition causes a policy-change stamp, although the matcher continues assigning that target. Reactivation does not advance the policy generation. Removal requires an unused, unlocked definition. ## What Cannot Happen Dependencies prevent deletion, and a full lock prevents ordinary editing, including availability changes. Removal supplies no restoration action. These restrictions do not establish that retirement removes a region from geographic coverage. ## Concurrency and Timing Update versions protect against conflicting edits. Deletion is unversioned and can remove a definition edited since the caller last read it. Database reference checks preserve integrity during a competing reference write.