Rhythm 2.0 Specifications

Appearance

CAP-CRM-REG-012Monitor recalculation and recover from failure

Markdown

CAP-CRM-REG-012

Monitor recalculation and recover from failure

Markdown
  • DocumentDraft
  • Product intentProposed
  • ImplementationPartially observed

Planning

Feature
FEAT-CRM-REG-04
Key concepts
CON-CRM-REG-004
Actors
ACT-CRM-003, ACT-CRM-002, ACT-CRM-005
Journeys
JNY-CRM-REG-002
Depends on
CAP-CRM-REG-011
Related
CAP-CRM-REG-011
Proved by
ATS-CRM-REG-012

KindCapabilityProduct areaCRMModuleRegionsRevision2

Read atservices-crm a8d1364freact-console baf6dae3

Monitor recalculation and recover from failure ​

Purpose ​

Staff inspect a recalculation’s progress and identify whether more processing or a new run is needed.

How It Works ​

Staff inspect recent recalculations or a particular run. The record identifies its status, processing phase and examined and changed counts. The console polls active work and can resume watching a run found when the page opens. A failing batch stores a redacted database reason while leaving the run eligible for later delivery. Successful progress clears the reason. Only a failing final delivery marks the run failed. The console reports the failure and the work completed beforehand. There is no cancellation operation. Recovery from a failed final run requires a new recalculation rather than restarting that record.

Relationships ​

  • Apply the current policy across existing records applies policy changes to existing records.

The Formal Contract

The narrative above explains; the sections below are authoritative — the rules, scenarios and tests this document binds.

Outcomes
Run status and accumulated counts remain inspectable.Database failures reveal a redacted explanation.Later queue delivery can recover unfinished work.
Surfaces
consoleapijob
Intent sources
services-crm:docs/migrations/crm-regions/README.md#Assignment and recalculation triggers in Rolodex 2.0 (Andrew, 2026-10-10: the failure reason is redacted)

Controls

24 controls apply, from the corpus control catalogue.

TC-AVL-004 TC-AZ-001 TC-AZ-002 TC-AZ-003 TC-AZ-004 TC-AZ-006 TC-DAT-001 TC-DAT-002 TC-DAT-003 TC-IAM-001 TC-IAM-005 TC-IAM-006 TC-LOG-004 TC-LOG-005 TC-MON-001 TC-MON-002 TC-PI-001 TC-PI-004 TC-PI-005 TC-PRV-001 TC-PRV-002 TC-TEN-001 TC-TEN-002 TC-TEN-003

Permissions

KeyChecked atScope
crm.regions.readapitenant

Business Rules

9 rules, 6 to be proved before approval. A rule's product intent is derived from its origin: 0 confirmed by a product decision, the rest inheriting this capability's proposed.

IdRuleKindEnforced atProvenance
01must prove
Proposed
Staff can list recent workspace recalculations newest first, with a default limit of twenty-five and maximum of one hundred, and inspect their status, phase, counts and failure reason.
no proof recorded yet
policyapi, servicetest
services-crm:modules/regions/tests/integration/services/persistence/region-recalculations.queries.integration.spec.js#listRegionRecalculations › answers the whole record of every run of the tenant, the newest first
02must prove
Proposed
Runs have running, completed or failed status; completion requires both record phases to finish, and changed never exceeds examined.
no proof recorded yet
invariantdatabasetest
services-crm:modules/regions/tests/integration/services/persistence/region-recalculations.integration.spec.js#refuses completed before the run is done
03must prove
Proposed
A failed database batch records only the redacted error kind and database code, then resumes from its committed position on another delivery.
origin: services-crm:docs/migrations/crm-regions/README.md#Assignment and recalculation triggers in Rolodex 2.0 (Andrew, 2026-10-10: the failure reason is redacted)
no proof recorded yet
policyservicetest
services-crm:modules/regions/tests/integration/services/region-assignment/region-recalculation-errors.integration.spec.js#the reason it records › records no value of the batch that failed: not the contact, the tenant, the statement or its parameters
04must prove
Proposed
A failed final delivery marks the run failed, while earlier failures leave it running.
origin: services-crm:docs/migrations/crm-regions/README.md#Assignment and recalculation triggers in Rolodex 2.0 (Andrew, 2026-10-10: the failure reason is redacted)
no proof recorded yet
lifecycleservicetest
services-crm:modules/regions/tests/integration/services/region-assignment/region-recalculation-errors.integration.spec.js#the last delivery of a run’s event › fails the run, because nothing will deliver its event again
05must prove
Proposed
Successful progress clears an earlier failure reason, leaving a completed run without that reason.
no proof recorded yet
lifecycleservicetest
services-crm:modules/regions/tests/integration/services/region-assignment/region-recalculation-errors.integration.spec.js#a run that gets past what stopped it › answers the whole record of the completed run, with no reason left on it
06must prove
Proposed
Recalculation reads remain workspace-specific and return not found for unknown runs.
no proof recorded yet
invariantapi, servicetest
services-crm:modules/regions/tests/integration/services/persistence/region-recalculations.queries.integration.spec.js#getRegionRecalculation › answers undefined in another tenant for the first tenant's run
07
Proposed
The API provides no cancellation action for a running recalculation.
policyapiobserved
services-crm:modules/regions/aws/api/regions.routes.ts:regionsRoutes
08
Proposed
A failed recalculation does not restart automatically; an authorized user must request a new run.
lifecycleserviceobserved
services-crm:modules/regions/services/region-assignment/region-recalculation.ts:startRegionRecalculation
09
Proposed
The console polls an active run every one and a half seconds, adopts an existing running run on page load, replaces the needed banner with progress and shows failure with the accumulated counts.
origin: services-crm:docs/migrations/crm-regions/README.md#2026-10-15 — Final acceptance (console follow-ups) (Andrew approved 2026-10-15: two tabs, Test an Address dialog, drawers, a read-only Assignment Rules tab with its own editor screen and the banner)
policyconsoleobserved
react-console:components/regions/__tests__/recalculation.test.tsx#the banner › reports a failure, with what it got through before it stopped; react-console:components/regions/recalculation.tsx:useRecalculation

Scenarios

IdGivenWhenThenProvenance
01A transient database error interrupts the next batch.Staff inspect the run and processing is delivered again.The run retains a redacted reason while running, then clears it after successful progress.test
services-crm:modules/regions/tests/integration/services/region-assignment/region-recalculation-errors.integration.spec.js#a run that gets past what stopped it › answers the whole record of the completed run, with no reason left on it

Edge Cases

IdGivenWhenThenProvenance
02All deliveries fail to process the unfinished batch.The queue makes its final delivery.The run becomes failed with its reason and staff can request a new run.test
services-crm:modules/regions/tests/integration/services/region-assignment/region-recalculation-errors.integration.spec.js#the last delivery of a run’s event › fails the run, because nothing will deliver its event again

The Markdown files under specs/ in rhythmsoftware/rhythm-v2-docs are the canonical source of truth. This reader is a generated, read-only projection of them.

Rhythm Software