--- id: CON-CRM-REG-003 name: Regional Placement feature: FEAT-CRM-REG-03 product_area: crm module: regions revision: 2 status: draft product_intent: proposed implementation_evidence: observed source_sha: services-crm: a8d1364f1dd44b723bb5f9acba12f983e9ec8d69 react-console: baf6dae382d6f41dce976c7f848667ccc37e076f definition: >- A regional placement is a contact’s or organization’s current region, maintained from its deciding address or selected as a staff exception. owned_by: MOD-CRM-REG synonyms: - current record region - regional assignment not_to_be_confused_with: - The referenced regional definition - The geographic policy - The underlying address detail facets: - name: Stored region meaning: The record references one current region or has none. used_for: Grouping people and organizations for regional work. - name: Current deciding input meaning: 'The policy selects an address, including details resolved through an organizational link.' used_for: Providing the address used for assignment. - name: Remembered deciding input meaning: The record remembers the source and address used by its preceding decision. used_for: Avoiding repeat work and recognizing removal of a previously available address. - name: Automatic-assignment override meaning: The record can exclude itself from automatic placement. used_for: Preserving a deliberate regional exception. - name: Manual selection without override meaning: Staff can select a region without excluding future automatic decisions. used_for: Making a temporary choice that changed input can replace. - name: Version consequence meaning: Placement changes advance the record version while an unchanged region does not. used_for: Protecting edits without invalidating reads solely for bookkeeping. relationships: - to: CON-CRM-REG-001 statement: Placement can identify a single regional definition. provenance: observed source: 'services-crm:modules/regions/db/regions.table.ts' - to: CON-CRM-REG-002 statement: Automatic processing applies the policy to eligible records. provenance: observed source: 'services-crm:modules/regions/services/region-assignment/region-assignment.ts:reconcileRegionAssignments' - to: CON-CRM-REG-004 statement: Recalculation reevaluates eligible placements under current coverage. provenance: test source: >- 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 - to: CON-CRM-ENT-001 statement: The contact retains its regional reference and address details. provenance: observed source: 'services-crm:modules/entities/services/persistence/contacts.ts:setContactRegionAssignments' - to: CON-CRM-ENT-002 statement: The organization retains its regional reference and address details. provenance: observed source: 'services-crm:modules/entities/services/persistence/organizations.ts:setOrganizationRegionAssignments' - to: CON-CRM-ENT-003 statement: A linked deciding address resolves through an effective affiliation. provenance: inferred source: 'services-crm:modules/entities/services/persistence/contacts.ts:readContactRegionAddresses' note: >- The region-address reader filters organizational links through effective affiliations before returning address input. lifecycle: - state: unplaced meaning: The record has no regional reference. how_it_changes: Staff select a region or eligible processing supplies one. - state: placed by the rules meaning: Placement reflects a policy decision for the deciding address. how_it_changes: An input changes or staff apply revised policy through recalculation. - state: set by hand meaning: Staff chose the current region directly. how_it_changes: A deciding-address change can replace it unless the override protects it. - state: held meaning: The override protects the current regional choice. how_it_changes: Staff release the override to permit reconciliation. acted_on_by: - CAP-CRM-REG-006 - CAP-CRM-REG-008 - CAP-CRM-REG-009 - CAP-CRM-REG-011 visible_to: - ACT-CRM-001 - ACT-CRM-002 - ACT-CRM-003 - ACT-CRM-005 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:modules/regions/db/regions.table.ts' - 'services-crm:modules/regions/services/region-assignment/region-assignment.ts' - >- services-crm:modules/regions/tests/integration/services/region-assignment/region-assignment.integration.spec.js - 'services-crm:modules/entities/services/persistence/contacts.ts' - 'services-crm:modules/entities/services/persistence/organizations.ts' supersedes: [] --- # Regional Placement ## What It Is A regional placement is the region currently stored on a contact or organization. It may result from geographic matching, a direct staff choice or a deliberate exception protected by the automatic-assignment override. A record can also have no region. That absence can mean it lacks a deciding address, falls outside coverage or belongs to a record kind the policy does not assign. Placement lives with the contact or organization rather than in a separate staff-maintained list of assignments. Regions processing updates it after an address save commits. A record therefore can be saved successfully before its new geographic placement appears. Processing uses the currently committed address and policy rather than the historical address described by a queued event. ## What It Is Not The placement is separate from the regional definition and from its geographic policy. A record can retain a placement while administrators change either of those. It is also separate from the underlying address. Linked contact details can resolve from an organization without copying that organization’s address into the contact, while the contact still stores its own region. A manual choice alone does not create a lasting exception. Staff use the override when they intend to preserve a choice through later deciding-address changes and recalculation. Product language should make that distinction clear so a coordinator does not mistake temporary selection for a protected chapter assignment. ## How It Is Used Coordinators see placement as part of maintaining member and company records. Routine address changes can move an eligible record between geographic groups after processing. A coordinator can instead hold a member in a chapter that serves them despite a different home address. Releasing that hold restores reconciliation against the current deciding input. Administrators can apply changed coverage to existing records through recalculation. Both ordinary processing and recalculation respect overrides and update locks. Repeated event delivery reads current state and uses remembered input to avoid unnecessary writes. The implementation distinguishes a removed deciding address from a record that never had one, preserving manual placement in the latter case. ## Its Facets **Stored region.** The reference identifies one regional definition or remains empty. The owning record retains that value for regional work. **Current deciding input.** The policy identifies the preferred or typed address. An effective organizational affiliation can supply linked address details. **Remembered deciding input.** Processing remembers the address and its source. That comparison limits repeat work and identifies removal of previously used input. **Automatic-assignment override.** This record-level choice preserves the current region despite geographic changes and explicit recalculation. **Manual selection without override.** Staff can temporarily choose a region while retaining eligibility for subsequent automatic decisions. **Version consequence.** Changing the region advances the owning record’s version. Remembering an address that produces the same region leaves that version alone. ## How It Relates The regional catalogue supplies valid targets and the policy supplies geographic decisions. Recalculation revisits eligible placements under saved coverage. Contacts own their placements and affiliations; organizations own the addresses that linked contacts may resolve. An organization address change can reconcile those contacts without writing their address rows. ## What It Could Become The product should decide whether affiliation expiry should trigger reconciliation, since expiry alone currently leaves the stored region unchanged. A later organization address event can clear placement when the expired link no longer resolves. The product should also improve regional display and choice behavior where the acceptance tests record contact-screen defects.