--- id: CON-CRM-REG-004 name: Recalculation Run feature: FEAT-CRM-REG-04 product_area: crm module: regions revision: 2 status: draft product_intent: proposed implementation_evidence: partially-observed source_sha: services-crm: a8d1364f1dd44b723bb5f9acba12f983e9ec8d69 react-console: baf6dae382d6f41dce976c7f848667ccc37e076f definition: >- A recalculation run records an explicit request to reevaluate existing contacts and organizations against the workspace’s regional policy. owned_by: MOD-CRM-REG synonyms: - workspace placement recalculation not_to_be_confused_with: - Event-driven assignment of one record - Policy replacement - Bulk import processing facets: - name: Processing status meaning: 'A run reports running, completed or failed.' used_for: Distinguishing unfinished work from final outcomes. - name: Traversal position meaning: The phase and saved progress locate the run within contacts and organizations. used_for: Monitoring processing and resuming committed progress. - name: Work counts meaning: Examined counts traversal and changed counts actual placement changes. used_for: Understanding how much regional work occurred. - name: Redacted failure meaning: A database failure retains its error kind and code without record values. used_for: Explaining processing failure without exposing input data. - name: Workspace exclusivity meaning: Only one run can remain running in the workspace. used_for: Returning the existing run when another start is requested. - name: Outstanding policy changes meaning: The need signal compares the current policy generation with successful runs. used_for: Prompting staff to apply policy changes explicitly. relationships: - to: CON-CRM-REG-002 statement: Each processing batch applies the policy it reads. provenance: observed source: 'services-crm:modules/regions/services/region-assignment/region-recalculation.ts:recalculateBatch' - to: CON-CRM-REG-003 statement: Recalculation preserves overrides and update locks while reevaluating eligible records. provenance: test source: >- services-crm:modules/regions/tests/integration/services/region-assignment/region-assignment.integration.spec.js#rule changes and the recalculation › leaves a contact that overrides automatic assignment lifecycle: - state: running meaning: Processing traverses contacts followed by organizations. how_it_changes: Traversal completes or a final delivery fails. - state: completed meaning: The traversal finished its record phases. how_it_changes: The run remains historical and a new request creates another run. - state: failed meaning: Final delivery failed and retains a redacted explanation. how_it_changes: Recovery requires starting a new run. acted_on_by: - CAP-CRM-REG-010 - CAP-CRM-REG-011 - CAP-CRM-REG-012 visible_to: - 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/services/region-assignment/region-recalculation.ts' - >- services-crm:modules/regions/tests/integration/services/region-assignment/region-assignment.integration.spec.js supersedes: [] --- # Recalculation Run ## What It Is A recalculation run records an administrator’s request to bring existing CRM placements into line with regional policy. It represents a piece of processing with its own identity, progress and outcome. Saving settings or rules does not start this work automatically. The administrator chooses when the new coverage should be applied to the workspace’s contacts and organizations. The run traverses contacts before organizations. Small amounts of work can finish during the request that starts it, while remaining batches continue in the background. Progress remains stored between batches, so processing resumes beyond committed work after an interruption. A completed run provides evidence that traversal finished, while its generation identifies the policy state under which the run began. ## What It Is Not Recalculation is separate from assignment following one record’s address change. Both share the same decision process, but a run revisits existing records even when their remembered deciding inputs have not changed. It is also separate from a regional file-import job and does not offer the import engine’s cancellation or control actions. A completed run does not guarantee that every record changed or that every record is eligible for assignment. Overrides, update locks and the absence of a past or present deciding address can preserve existing values. Rules changed during processing can also leave another recalculation needed after this run completes. ## How It Is Used Administrators see a need banner when the current policy generation lacks a successful run. They start processing from the available recalculation action and inspect its progress. Readers can inspect run records without starting work. The console refreshes active processing and can find a run already underway when the page opens. Only one run remains running in a workspace. Another start request returns that run and may process additional batches during its own budget. Workers coordinate committed progress rather than repeating the traversal. The run uses the policy read by each batch, so it does not freeze coverage at the moment it starts. Staff should consider the outstanding-policy signal alongside completion when deciding whether more processing is necessary. ## Its Facets **Processing status.** Running identifies unfinished work, completed identifies a finished traversal and failed identifies a final unsuccessful delivery. **Traversal position.** The current phase and saved position allow a worker to resume contact or organization processing without replaying committed batches. **Work counts.** Examined counts every traversed record, including records assignment skips. Changed counts actual regional values set or cleared. **Redacted failure.** A failed database batch records the error kind and database code rather than bound values or the statement. Successful progress clears the earlier reason. **Workspace exclusivity.** A second running run cannot be created for the same workspace. Completed or failed history does not prevent a new request. **Outstanding policy changes.** The settings compare their generation with successful runs. This detects policy changes even when their timestamps coincide with a run’s start. ## How It Relates The policy supplies current coverage and regional placement supplies the values being reevaluated. Contact and organization persistence retains ownership of record updates. Shared change-event delivery provides continuation and retry rather than a regional queue or schedule of its own. ## What It Could Become The product should decide whether cancellation or explicit recovery controls are needed beyond starting another run after final failure. It should also consider whether examined is clear enough when it includes skipped records. Policy snapshotting would change the present per-batch behavior and needs an explicit design decision.