---
id: ADR-CRM-REG-004
title: 'Recalculation Is a Self-Continuing, Resumable Run'
product_area: crm
module: regions
revision: 2
status: proposed
design_intent: confirmed
source_sha:
  services-crm: a8d1364f1dd44b723bb5f9acba12f983e9ec8d69
  react-console: baf6dae382d6f41dce976c7f848667ccc37e076f
decision: >-
  Recalculation persists transactional batch progress, continues through captured events and delegates retry
  to the queue while attempting redacted terminal failure settlement on final delivery.
constrains:
  - DOM-CRM-REG-004
  - STATE-CRM-REG-004
  - WF-CRM-REG-003
  - SVC-CRM-REG-regions
origin: >-
  Andrew, 2026-10-10 (the failure reason is redacted), cited in
  services-crm:docs/migrations/crm-regions/README.md#Assignment and recalculation triggers in Rolodex 2.0; the
  queued-work standard §3, cited in
  services-crm:modules/regions/services/region-assignment/region-recalculation.ts
alternatives:
  - option: Complete the entire traversal in the start request.
    why_not: >-
      Request time limits make this unsuitable for large workspaces, and one transaction would retain no
      intermediate progress.
  - option: Add a dedicated scheduler or state-machine execution.
    why_not: >-
      The current design uses captured continuation events and queue retry; a new engine would need a separate
      scheduling and recovery contract.
  - option: Track retry attempts inside the regional handler.
    why_not: >-
      The cited queue convention assigns attempts and redelivery to the queue rather than regional
      persistence.
consequences:
  - Small traversals can complete during the start request.
  - 'Committed batches survive interruption, while an interrupted transaction rolls back its batch.'
  - Successfully failed runs stay historical; another run begins traversal again.
  - 'There is no cancellation route, and failed terminal settlement needs recovery outside regional operations.'
supersedes: []
evidence:
  - >-
    services-crm at a8d1364f: modules/regions/services/region-assignment/region-recalculation.ts;
    services/persistence/region-recalculations.ts; db/region-recalculations.table.ts.
---

# Recalculation Is a Self-Continuing, Resumable Run

## Context

Large workspaces need progress that survives request and worker budgets. Existing change delivery supplies the continuation seam.

## Decision

Initial insertion reaches the runner, and a continuation increment requests another worker. Each batch locks the run and commits placement with progress. Failure settlement is separate and best effort; final delivery can leave a running row if settlement fails.

## Alternatives Considered

Complete the entire traversal in the start request. Request time limits make this unsuitable for large workspaces, and one transaction would retain no intermediate progress.

Add a dedicated scheduler or state-machine execution. The current design uses captured continuation events and queue retry; a new engine would need a separate scheduling and recovery contract.

Track retry attempts inside the regional handler. The cited queue convention assigns attempts and redelivery to the queue rather than regional persistence.

## Consequences

Small traversals can complete during the start request. Committed batches survive interruption, while an interrupted transaction rolls back its batch. Successfully failed runs stay historical; another run begins traversal again. There is no cancellation route, and failed terminal settlement needs recovery outside regional operations.