---
title: Regions Design Examination
examined_at: '2026-10-23'
examiner: codex
source_sha:
  services-crm: a8d1364f1dd44b723bb5f9acba12f983e9ec8d69
  react-console: baf6dae382d6f41dce976c7f848667ccc37e076f
branch: agent/crm-regions-desi-exam-1
examination_status: complete
counts:
  design_artifacts: 30
  domain_objects: 4
  state_models: 4
  workflows: 5
  service_contracts: 1
  screen_contracts: 3
  decision_records: 13
  transitions: 28
  hops: 26
  operations: 32
  new_findings: 10
  inference_operations: 0
  domain_invariants: 33
  state_invariants: 19
evidence:
  planning: specs/crm/regions/
  missing_brief: briefs/design/crm-regions.brief.md
  health_dependency: >-
    services-crm:package-lock.json#@rhythmsoftware/macroservice-http 0.18.0; integrity-verified
    dist/health-route.js:healthRoute
  new_findings:
    - FND-CRM-REG-031
    - FND-CRM-REG-032
    - FND-CRM-REG-033
    - FND-CRM-REG-034
    - FND-CRM-REG-035
    - FND-CRM-REG-036
    - FND-CRM-REG-037
    - FND-CRM-REG-038
    - FND-CRM-REG-039
    - FND-CRM-REG-040
artifacts_examined:
  - id: SVC-CRM-REG-regions
    path: specs/crm/regions/design/contracts/SVC-CRM-REG-regions.md
  - id: ADR-CRM-REG-001
    path: specs/crm/regions/design/decisions/ADR-CRM-REG-001-regions-decides-placement-entities-stores-it.md
  - id: ADR-CRM-REG-002
    path: >-
      specs/crm/regions/design/decisions/ADR-CRM-REG-002-placement-follows-the-committed-address-asynchronously.md
  - id: ADR-CRM-REG-003
    path: specs/crm/regions/design/decisions/ADR-CRM-REG-003-policy-changes-move-no-record.md
  - id: ADR-CRM-REG-004
    path: specs/crm/regions/design/decisions/ADR-CRM-REG-004-recalculation-is-a-self-continuing-resumable-run.md
  - id: ADR-CRM-REG-005
    path: specs/crm/regions/design/decisions/ADR-CRM-REG-005-first-enabled-match-wins-with-the-fallback-last.md
  - id: ADR-CRM-REG-006
    path: specs/crm/regions/design/decisions/ADR-CRM-REG-006-the-policy-is-edited-whole-or-one-rule-at-a-time.md
  - id: ADR-CRM-REG-007
    path: specs/crm/regions/design/decisions/ADR-CRM-REG-007-regions-and-the-policy-carry-no-custom-fields.md
  - id: ADR-CRM-REG-008
    path: specs/crm/regions/design/decisions/ADR-CRM-REG-008-region-replacement-carries-the-complete-payload.md
  - id: ADR-CRM-REG-009
    path: specs/crm/regions/design/decisions/ADR-CRM-REG-009-changes-are-made-against-the-version-read.md
  - id: ADR-CRM-REG-010
    path: specs/crm/regions/design/decisions/ADR-CRM-REG-010-region-locks-need-dedicated-audited-actions.md
  - id: ADR-CRM-REG-011
    path: >-
      specs/crm/regions/design/decisions/ADR-CRM-REG-011-placement-advances-the-version-only-when-the-region-moves.md
  - id: ADR-CRM-REG-012
    path: specs/crm/regions/design/decisions/ADR-CRM-REG-012-no-regional-operation-is-published-to-submissions.md
  - id: ADR-CRM-REG-013
    path: >-
      specs/crm/regions/design/decisions/ADR-CRM-REG-013-every-regional-reference-stays-inside-its-workspace.md
  - id: DOM-CRM-REG-001
    path: specs/crm/regions/design/objects/DOM-CRM-REG-001-region.md
  - id: DOM-CRM-REG-002
    path: specs/crm/regions/design/objects/DOM-CRM-REG-002-assignment-policy.md
  - id: DOM-CRM-REG-003
    path: specs/crm/regions/design/objects/DOM-CRM-REG-003-regional-placement.md
  - id: DOM-CRM-REG-004
    path: specs/crm/regions/design/objects/DOM-CRM-REG-004-recalculation-run.md
  - id: SCR-CRM-REG-001
    path: specs/crm/regions/design/screens/SCR-CRM-REG-001-regions-catalogue.md
  - id: SCR-CRM-REG-002
    path: specs/crm/regions/design/screens/SCR-CRM-REG-002-assignment-rules-view.md
  - id: SCR-CRM-REG-003
    path: specs/crm/regions/design/screens/SCR-CRM-REG-003-assignment-rules-editor.md
  - id: STATE-CRM-REG-001
    path: specs/crm/regions/design/state-models/STATE-CRM-REG-001-region-availability.md
  - id: STATE-CRM-REG-002
    path: specs/crm/regions/design/state-models/STATE-CRM-REG-002-assignment-policy-currency.md
  - id: STATE-CRM-REG-003
    path: specs/crm/regions/design/state-models/STATE-CRM-REG-003-regional-placement.md
  - id: STATE-CRM-REG-004
    path: specs/crm/regions/design/state-models/STATE-CRM-REG-004-recalculation-run.md
  - id: WF-CRM-REG-001
    path: specs/crm/regions/design/workflows/WF-CRM-REG-001-place-a-record-after-its-deciding-address-changes.md
  - id: WF-CRM-REG-002
    path: >-
      specs/crm/regions/design/workflows/WF-CRM-REG-002-follow-an-organization-address-to-its-linked-contacts.md
  - id: WF-CRM-REG-003
    path: specs/crm/regions/design/workflows/WF-CRM-REG-003-recalculate-every-record-under-the-current-policy.md
  - id: WF-CRM-REG-004
    path: specs/crm/regions/design/workflows/WF-CRM-REG-004-record-a-policy-change-and-ask-for-recalculation.md
  - id: WF-CRM-REG-005
    path: specs/crm/regions/design/workflows/WF-CRM-REG-005-import-regions-from-a-file.md
verification_changes:
  - artifact: SVC-CRM-REG-regions
    field: operations.0.provenance
    before: null
    after: observed
  - artifact: SVC-CRM-REG-regions
    field: operations.0.source
    before: null
    after: >-
      services-crm:modules/regions/aws/api/regions.routes.ts:regionsModuleRoutes (healthRoute);
      services-crm:package-lock.json#@rhythmsoftware/macroservice-http 0.18.0 (integrity-verified package
      dist/health-route.js:healthRoute)
  - artifact: SVC-CRM-REG-regions
    field: operations.1.provenance
    before: null
    after: observed
  - artifact: SVC-CRM-REG-regions
    field: operations.1.source
    before: null
    after: 'services-crm:modules/regions/aws/api/regions.routes.ts:createRegion'
  - artifact: SVC-CRM-REG-regions
    field: operations.2.provenance
    before: null
    after: observed
  - artifact: SVC-CRM-REG-regions
    field: operations.2.source
    before: null
    after: 'services-crm:modules/regions/aws/api/regions.routes.ts:listRegions'
  - artifact: SVC-CRM-REG-regions
    field: operations.3.provenance
    before: null
    after: observed
  - artifact: SVC-CRM-REG-regions
    field: operations.3.source
    before: null
    after: 'services-crm:modules/regions/aws/api/regions.routes.ts:getRegion'
  - artifact: SVC-CRM-REG-regions
    field: operations.4.provenance
    before: null
    after: observed
  - artifact: SVC-CRM-REG-regions
    field: operations.4.source
    before: null
    after: 'services-crm:modules/regions/aws/api/regions.routes.ts:updateRegion'
  - artifact: SVC-CRM-REG-regions
    field: operations.5.provenance
    before: null
    after: observed
  - artifact: SVC-CRM-REG-regions
    field: operations.5.source
    before: null
    after: 'services-crm:modules/regions/aws/api/regions.routes.ts:patchRegion'
  - artifact: SVC-CRM-REG-regions
    field: operations.6.provenance
    before: null
    after: observed
  - artifact: SVC-CRM-REG-regions
    field: operations.6.source
    before: null
    after: 'services-crm:modules/regions/aws/api/regions.routes.ts:deleteRegion'
  - artifact: SVC-CRM-REG-regions
    field: operations.7.provenance
    before: null
    after: observed
  - artifact: SVC-CRM-REG-regions
    field: operations.7.source
    before: null
    after: 'services-crm:modules/regions/aws/api/regions.routes.ts:getRegionAssignmentSettings'
  - artifact: SVC-CRM-REG-regions
    field: operations.8.provenance
    before: null
    after: observed
  - artifact: SVC-CRM-REG-regions
    field: operations.8.source
    before: null
    after: 'services-crm:modules/regions/aws/api/regions.routes.ts:updateRegionAssignmentSettings'
  - artifact: SVC-CRM-REG-regions
    field: operations.9.provenance
    before: null
    after: observed
  - artifact: SVC-CRM-REG-regions
    field: operations.9.source
    before: null
    after: 'services-crm:modules/regions/aws/api/regions.routes.ts:listRegionAssignmentRules'
  - artifact: SVC-CRM-REG-regions
    field: operations.10.provenance
    before: null
    after: observed
  - artifact: SVC-CRM-REG-regions
    field: operations.10.source
    before: null
    after: 'services-crm:modules/regions/aws/api/regions.routes.ts:createRegionAssignmentRule'
  - artifact: SVC-CRM-REG-regions
    field: operations.11.provenance
    before: null
    after: observed
  - artifact: SVC-CRM-REG-regions
    field: operations.11.source
    before: null
    after: 'services-crm:modules/regions/aws/api/regions.routes.ts:reorderRegionAssignmentRules'
  - artifact: SVC-CRM-REG-regions
    field: operations.12.provenance
    before: null
    after: observed
  - artifact: SVC-CRM-REG-regions
    field: operations.12.source
    before: null
    after: 'services-crm:modules/regions/aws/api/regions.routes.ts:previewRegionAssignment'
  - artifact: SVC-CRM-REG-regions
    field: operations.13.provenance
    before: null
    after: observed
  - artifact: SVC-CRM-REG-regions
    field: operations.13.source
    before: null
    after: 'services-crm:modules/regions/aws/api/regions.routes.ts:getRegionAssignmentRule'
  - artifact: SVC-CRM-REG-regions
    field: operations.14.provenance
    before: null
    after: observed
  - artifact: SVC-CRM-REG-regions
    field: operations.14.source
    before: null
    after: 'services-crm:modules/regions/aws/api/regions.routes.ts:updateRegionAssignmentRule'
  - artifact: SVC-CRM-REG-regions
    field: operations.15.provenance
    before: null
    after: observed
  - artifact: SVC-CRM-REG-regions
    field: operations.15.source
    before: null
    after: 'services-crm:modules/regions/aws/api/regions.routes.ts:patchRegionAssignmentRule'
  - artifact: SVC-CRM-REG-regions
    field: operations.16.provenance
    before: null
    after: observed
  - artifact: SVC-CRM-REG-regions
    field: operations.16.source
    before: null
    after: 'services-crm:modules/regions/aws/api/regions.routes.ts:deleteRegionAssignmentRule'
  - artifact: SVC-CRM-REG-regions
    field: operations.17.provenance
    before: null
    after: observed
  - artifact: SVC-CRM-REG-regions
    field: operations.17.source
    before: null
    after: 'services-crm:modules/regions/aws/api/regions.routes.ts:recalculateRegionAssignments'
  - artifact: SVC-CRM-REG-regions
    field: operations.18.provenance
    before: null
    after: observed
  - artifact: SVC-CRM-REG-regions
    field: operations.18.source
    before: null
    after: 'services-crm:modules/regions/aws/api/regions.routes.ts:listRegionRecalculations'
  - artifact: SVC-CRM-REG-regions
    field: operations.19.provenance
    before: null
    after: observed
  - artifact: SVC-CRM-REG-regions
    field: operations.19.source
    before: null
    after: 'services-crm:modules/regions/aws/api/regions.routes.ts:getRegionRecalculation'
  - artifact: SVC-CRM-REG-regions
    field: operations.20.provenance
    before: null
    after: observed
  - artifact: SVC-CRM-REG-regions
    field: operations.20.source
    before: null
    after: >-
      services-crm:modules/data-jobs/aws/api/bulk-data-jobs.routes.ts:configurationDataJobRoutes,
      BULK_SUBMISSIONS
  - artifact: SVC-CRM-REG-regions
    field: operations.21.provenance
    before: null
    after: observed
  - artifact: SVC-CRM-REG-regions
    field: operations.21.source
    before: null
    after: >-
      services-crm:modules/data-jobs/aws/api/bulk-data-jobs.routes.ts:configurationDataJobRoutes,
      BULK_SUBMISSIONS
  - artifact: SVC-CRM-REG-regions
    field: operations.22.provenance
    before: null
    after: observed
  - artifact: SVC-CRM-REG-regions
    field: operations.22.source
    before: null
    after: >-
      services-crm:modules/data-jobs/aws/api/bulk-data-jobs.routes.ts:configurationDataJobRoutes,
      BULK_SUBMISSIONS
  - artifact: SVC-CRM-REG-regions
    field: operations.23.provenance
    before: null
    after: observed
  - artifact: SVC-CRM-REG-regions
    field: operations.23.source
    before: null
    after: >-
      services-crm:modules/data-jobs/aws/api/bulk-data-jobs.routes.ts:configurationDataJobRoutes,
      BULK_SUBMISSIONS
  - artifact: SVC-CRM-REG-regions
    field: operations.24.provenance
    before: null
    after: observed
  - artifact: SVC-CRM-REG-regions
    field: operations.24.source
    before: null
    after: >-
      services-crm:modules/data-jobs/aws/api/bulk-data-jobs.routes.ts:configurationDataJobRoutes,
      BULK_SUBMISSIONS
  - artifact: SVC-CRM-REG-regions
    field: operations.25.provenance
    before: null
    after: observed
  - artifact: SVC-CRM-REG-regions
    field: operations.25.source
    before: null
    after: >-
      services-crm:modules/data-jobs/aws/api/bulk-data-jobs.routes.ts:configurationDataJobRoutes,
      BULK_SUBMISSIONS
  - artifact: SVC-CRM-REG-regions
    field: operations.26.provenance
    before: null
    after: observed
  - artifact: SVC-CRM-REG-regions
    field: operations.26.source
    before: null
    after: >-
      services-crm:modules/data-jobs/aws/api/bulk-data-jobs.routes.ts:configurationDataJobRoutes,
      BULK_SUBMISSIONS
  - artifact: SVC-CRM-REG-regions
    field: operations.27.provenance
    before: null
    after: observed
  - artifact: SVC-CRM-REG-regions
    field: operations.27.source
    before: null
    after: >-
      services-crm:modules/data-jobs/aws/api/bulk-data-jobs.routes.ts:configurationDataJobRoutes,
      BULK_SUBMISSIONS
  - artifact: SVC-CRM-REG-regions
    field: operations.28.provenance
    before: null
    after: observed
  - artifact: SVC-CRM-REG-regions
    field: operations.28.source
    before: null
    after: >-
      services-crm:modules/data-jobs/aws/api/bulk-data-jobs.routes.ts:configurationDataJobRoutes,
      BULK_SUBMISSIONS
  - artifact: SVC-CRM-REG-regions
    field: operations.29.provenance
    before: null
    after: observed
  - artifact: SVC-CRM-REG-regions
    field: operations.29.source
    before: null
    after: >-
      services-crm:modules/data-jobs/aws/api/bulk-data-jobs.routes.ts:configurationDataJobRoutes,
      BULK_SUBMISSIONS
  - artifact: SVC-CRM-REG-regions
    field: operations.30.provenance
    before: null
    after: observed
  - artifact: SVC-CRM-REG-regions
    field: operations.30.source
    before: null
    after: >-
      services-crm:modules/data-jobs/aws/api/bulk-data-jobs.routes.ts:configurationDataJobRoutes,
      BULK_SUBMISSIONS
  - artifact: SVC-CRM-REG-regions
    field: operations.31.provenance
    before: null
    after: observed
  - artifact: SVC-CRM-REG-regions
    field: operations.31.source
    before: null
    after: >-
      services-crm:modules/data-jobs/aws/api/bulk-data-jobs.routes.ts:configurationDataJobRoutes,
      BULK_SUBMISSIONS
  - artifact: ADR-CRM-REG-001
    field: origin
    before: null
    after: >-
      Observed module boundary: services-crm:modules/regions/services/region-assignment/region-assignment.ts;
      no separate product approval record.
  - artifact: ADR-CRM-REG-009
    field: design_intent
    before: confirmed
    after: proposed
  - artifact: DOM-CRM-REG-001
    field: invariants.0.provenance
    before: test
    after: observed
  - artifact: DOM-CRM-REG-001
    field: invariants.0.source
    before: >-
      services-crm:modules/regions/tests/integration/db/regions.table.integration.spec.js#regions table
      (integration) › constraints › keys a region by tenant and id: the same id in two tenants
    after: >-
      services-crm:modules/regions/tests/integration/db/regions.table.integration.spec.js#regions table
      (integration) › constraints › keys a region by tenant and id: the same id in two tenants;
      services-crm:modules/regions/db/regions.table.ts:REGION_ID_PATTERN
  - artifact: DOM-CRM-REG-001
    field: invariants.2.provenance
    before: test
    after: observed
  - artifact: DOM-CRM-REG-001
    field: invariants.2.source
    before: >-
      services-crm:modules/regions/tests/integration/db/regions.table.integration.spec.js#regions table
      (integration) › references › refuses to delete a region an assignment rule names
    after: >-
      services-crm:modules/regions/tests/integration/db/regions.table.integration.spec.js#regions table
      (integration) › references › refuses to delete a region an assignment rule names;
      services-crm:modules/regions/services/persistence/regions.ts:REGION_REFERENCES, regionRefusal
  - artifact: DOM-CRM-REG-001
    field: invariants.3.provenance
    before: test
    after: observed
  - artifact: DOM-CRM-REG-001
    field: invariants.3.source
    before: >-
      services-crm:modules/regions/tests/integration/db/regions.table.integration.spec.js#regions table
      (integration) › references › refuses a contact naming a region its tenant does not have
    after: >-
      services-crm:modules/regions/tests/integration/db/regions.table.integration.spec.js#regions table
      (integration) › references › refuses a contact naming a region its tenant does not have;
      services-crm:db/migrations/0019_regions.sql (contacts_region_fk and organizations_region_fk NOT VALID)
  - artifact: DOM-CRM-REG-001
    field: invariants.7.enforced_at
    before:
      - api
      - service
    after:
      - api
  - artifact: DOM-CRM-REG-001
    field: invariants.7.provenance
    before: documented
    after: observed
  - artifact: DOM-CRM-REG-001
    field: invariants.7.source
    before: 'services-crm:docs/debt/region-custom-fields.md#Custom-field values of a region'
    after: >-
      services-crm:docs/debt/region-custom-fields.md#Custom-field values of a region;
      services-crm:modules/regions/aws/api/regions.schemas.ts:regionRequestSchema;
      services-crm:modules/regions/metadata/regions.object.ts:regionsObject
  - artifact: DOM-CRM-REG-002
    field: invariants.0.provenance
    before: test
    after: observed
  - artifact: DOM-CRM-REG-002
    field: invariants.0.source
    before: >-
      services-crm:modules/regions/tests/integration/db/region-assignment-settings.table.integration.spec.js#region
      assignment settings tables (integration) › settings constraints › holds one settings row per tenant
    after: >-
      services-crm:modules/regions/tests/integration/db/region-assignment-settings.table.integration.spec.js#region
      assignment settings tables (integration) › settings constraints › holds one settings row per tenant;
      services-crm:modules/regions/services/persistence/region-assignment-settings.ts:DEFAULT_REGION_ASSIGNMENT_SETTINGS
  - artifact: DOM-CRM-REG-002
    field: invariants.1.provenance
    before: test
    after: observed
  - artifact: DOM-CRM-REG-002
    field: invariants.1.source
    before: >-
      services-crm:modules/regions/tests/integration/db/region-assignment-settings.table.integration.spec.js#region
      assignment settings tables (integration) › settings constraints › refuses deciding by a type with no
      address type named
    after: >-
      services-crm:modules/regions/tests/integration/db/region-assignment-settings.table.integration.spec.js#region
      assignment settings tables (integration) › settings constraints › refuses deciding by a type with no
      address type named;
      services-crm:modules/regions/db/region-assignment-settings.table.ts:regionAssignmentSettings
  - artifact: DOM-CRM-REG-002
    field: invariants.3.source
    before: >-
      services-crm:modules/regions/db/region-assignment-settings.table.ts:regionAssignmentRules (states,
      countries and country checks)
    after: >-
      services-crm:modules/regions/db/region-assignment-settings.table.ts:regionAssignmentRules (states,
      countries and country checks);
      services-crm:modules/regions/services/persistence/region-assignment-settings.ts:normalizeRegionAssignmentRule,
      regionAssignmentRuleProblems
  - artifact: DOM-CRM-REG-002
    field: invariants.7.provenance
    before: test
    after: observed
  - artifact: DOM-CRM-REG-002
    field: invariants.7.source
    before: >-
      services-crm:modules/regions/tests/integration/services/region-assignment/region-assignment-rules.integration.spec.js#region
      assignment rules and slots (integration) › whether a recalculation is needed › says one is needed again
      as soon as a rule is added
    after: >-
      services-crm:modules/regions/tests/integration/services/region-assignment/region-assignment-rules.integration.spec.js#region
      assignment rules and slots (integration) › whether a recalculation is needed › says one is needed again
      as soon as a rule is added;
      services-crm:modules/regions/services/persistence/region-assignment-settings.ts:saveRegionAssignmentSettings,
      stampRulesChanged, noteRuleRegionDeactivated
  - artifact: DOM-CRM-REG-003
    field: invariants.0.provenance
    before: test
    after: observed
  - artifact: DOM-CRM-REG-003
    field: invariants.0.source
    before: >-
      services-crm:modules/regions/tests/integration/services/region-assignment/region-assignment-delivery.integration.spec.js#region
      assignment deliveries (integration) › two messages delivered out of order › ends in the region of the
      address the contact has now, not of the one the older message described
    after: >-
      services-crm:modules/regions/tests/integration/services/region-assignment/region-assignment-delivery.integration.spec.js#region
      assignment deliveries (integration) › two messages delivered out of order › ends in the region of the
      address the contact has now, not of the one the older message described;
      services-crm:modules/regions/services/region-assignment/region-assignment.ts:reconcileRegionAssignments;
      services-crm:modules/regions/services/persistence/region-assignment-settings.ts:readRegionAssignmentSettings
  - artifact: DOM-CRM-REG-003
    field: invariants.2.provenance
    before: test
    after: observed
  - artifact: DOM-CRM-REG-003
    field: invariants.2.source
    before: >-
      services-crm:modules/regions/tests/integration/services/region-assignment/region-assignment.integration.spec.js#region
      assignment (integration) › moving › clears the region when the deciding address is removed
    after: >-
      services-crm:modules/regions/tests/integration/services/region-assignment/region-assignment.integration.spec.js#region
      assignment (integration) › moving › clears the region when the deciding address is removed;
      services-crm:modules/regions/services/region-assignment/region-assignment.ts:reconcileRegionAssignments
  - artifact: DOM-CRM-REG-003
    field: invariants.5.source
    before: 'services-crm:modules/entities/services/persistence/contacts.ts:lockContactRegionTargets'
    after: >-
      services-crm:modules/entities/services/persistence/contacts.ts:lockContactRegionTargets;
      services-crm:modules/entities/services/persistence/organizations.ts:lockOrganizationRegionTargets
  - artifact: DOM-CRM-REG-003
    field: invariants.6.provenance
    before: test
    after: observed
  - artifact: DOM-CRM-REG-003
    field: invariants.6.source
    before: >-
      services-crm:modules/regions/tests/integration/services/region-assignment/region-assignment.integration.spec.js#region
      assignment (integration) › refusals › refuses a contact naming a region the tenant does not have
    after: >-
      services-crm:modules/regions/tests/integration/services/region-assignment/region-assignment.integration.spec.js#region
      assignment (integration) › refusals › refuses a contact naming a region the tenant does not have;
      services-crm:db/migrations/0019_regions.sql
  - artifact: DOM-CRM-REG-003
    field: invariants.7.provenance
    before: documented
    after: observed
  - artifact: DOM-CRM-REG-003
    field: invariants.7.source
    before: 'react-console:acceptance/crm/inventory/business-rules.json#RUL-CRM-ORG-042'
    after: >-
      react-console:acceptance/crm/inventory/business-rules.json#RUL-CRM-ORG-042;
      services-crm:modules/entities/services/persistence/organizations.ts:readOrganizationRegionAddresses
  - artifact: DOM-CRM-REG-004
    field: invariants.0.provenance
    before: test
    after: observed
  - artifact: DOM-CRM-REG-004
    field: invariants.0.source
    before: >-
      services-crm:modules/regions/tests/integration/services/persistence/region-recalculations.integration.spec.js#region
      recalculations table (integration) › refuses a second running run for the tenant
    after: >-
      services-crm:modules/regions/tests/integration/services/persistence/region-recalculations.integration.spec.js#region
      recalculations table (integration) › refuses a second running run for the tenant;
      services-crm:modules/regions/services/region-assignment/region-recalculation.ts:startRegionRecalculation
  - artifact: DOM-CRM-REG-004
    field: invariants.5.provenance
    before: test
    after: observed
  - artifact: DOM-CRM-REG-004
    field: invariants.5.source
    before: >-
      services-crm:modules/regions/tests/integration/services/region-assignment/region-recalculation-errors.integration.spec.js#a
      region recalculation that fails (integration) › the last delivery of a run’s event › fails the run,
      because nothing will deliver its event again
    after: >-
      services-crm:modules/regions/tests/integration/services/region-assignment/region-recalculation-errors.integration.spec.js#a
      region recalculation that fails (integration) › the last delivery of a run’s event › fails the run,
      because nothing will deliver its event again;
      services-crm:modules/regions/services/region-assignment/region-recalculation.ts:recordFailure
  - artifact: SCR-CRM-REG-001
    field: actions.4.permission
    before: crm.regions.delete
    after: crm.regions.delete and the console settings-management alias
  - artifact: STATE-CRM-REG-001
    field: transitions.0.provenance
    before: test
    after: observed
  - artifact: STATE-CRM-REG-001
    field: transitions.0.source
    before: >-
      services-crm:modules/regions/tests/integration/services/persistence/regions.integration.spec.js#creates
      a region active by default
    after: >-
      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
  - artifact: STATE-CRM-REG-001
    field: transitions.4.provenance
    before: test
    after: observed
  - artifact: STATE-CRM-REG-001
    field: transitions.4.source
    before: >-
      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
    after: >-
      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
  - artifact: STATE-CRM-REG-002
    field: transitions.3.provenance
    before: test
    after: observed
  - artifact: STATE-CRM-REG-002
    field: transitions.3.source
    before: >-
      services-crm:modules/regions/tests/integration/services/region-assignment/region-assignment-rules.integration.spec.js#region
      assignment rules and slots (integration) › whether a recalculation is needed › says one is needed again
      as soon as a rule is added
    after: >-
      services-crm:modules/regions/tests/integration/services/region-assignment/region-assignment-rules.integration.spec.js#region
      assignment rules and slots (integration) › whether a recalculation is needed › says one is needed again
      as soon as a rule is added;
      services-crm:modules/regions/services/persistence/region-assignment-settings.ts:saveRegionAssignmentSettings,
      stampRulesChanged, noteRuleRegionDeactivated
  - artifact: STATE-CRM-REG-004
    field: transitions.0.provenance
    before: test
    after: observed
  - artifact: STATE-CRM-REG-004
    field: transitions.0.source
    before: >-
      services-crm:modules/regions/tests/integration/services/persistence/region-recalculations.integration.spec.js#region
      recalculations table (integration) › refuses a second running run for the tenant
    after: >-
      services-crm:modules/regions/tests/integration/services/persistence/region-recalculations.integration.spec.js#region
      recalculations table (integration) › refuses a second running run for the tenant;
      services-crm:modules/regions/services/region-assignment/region-recalculation.ts:startRegionRecalculation;
      services-crm:modules/regions/aws/api/regions.routes.ts:recalculateRegionAssignments
  - artifact: STATE-CRM-REG-004
    field: transitions.3.provenance
    before: test
    after: observed
  - artifact: STATE-CRM-REG-004
    field: transitions.3.source
    before: >-
      services-crm:modules/regions/tests/integration/services/region-assignment/region-recalculation-errors.integration.spec.js#a
      region recalculation that fails (integration) › the last delivery of a run’s event › fails the run,
      because nothing will deliver its event again
    after: >-
      services-crm:modules/regions/tests/integration/services/region-assignment/region-recalculation-errors.integration.spec.js#a
      region recalculation that fails (integration) › the last delivery of a run’s event › fails the run,
      because nothing will deliver its event again;
      services-crm:modules/regions/services/region-assignment/region-recalculation.ts:recordFailure;
      services-crm:docs/change-events.md#7. Failures and recovery
  - artifact: WF-CRM-REG-001
    field: hops.0.provenance
    before: test
    after: observed
  - artifact: WF-CRM-REG-001
    field: hops.0.source
    before: >-
      services-crm:modules/regions/tests/integration/services/region-assignment/region-assignment.integration.spec.js#region
      assignment (integration) › initial assignment › answers no region from the create itself, because the
      assignment is a reaction to the committed save
    after: >-
      services-crm:modules/regions/tests/integration/services/region-assignment/region-assignment.integration.spec.js#region
      assignment (integration) › initial assignment › answers no region from the create itself, because the
      assignment is a reaction to the committed save;
      services-crm:modules/entities/db/region-fingerprint.ts:withoutRegionFingerprint;
      services-crm:docs/change-events.md#2. Capture
  - artifact: WF-CRM-REG-001
    field: hops.4.anchor
    before: 'services-crm:modules/entities/services/persistence/contacts.ts:setContactRegionAssignments'
    after: >-
      services-crm:modules/entities/services/persistence/contacts.ts:setContactRegionAssignments;
      services-crm:modules/entities/services/persistence/organizations.ts:setOrganizationRegionAssignments
  - artifact: WF-CRM-REG-001
    field: hops.5.provenance
    before: test
    after: documented
  - artifact: WF-CRM-REG-001
    field: hops.5.source
    before: >-
      services-crm:modules/regions/tests/integration/services/region-assignment/region-assignment-delivery.integration.spec.js#region
      assignment deliveries (integration) › a delivery that fails and is made again › assigns the region on
      the next delivery of the same message
    after: >-
      services-crm:modules/regions/tests/integration/services/region-assignment/region-assignment-delivery.integration.spec.js#region
      assignment deliveries (integration) › a delivery that fails and is made again › assigns the region on
      the next delivery of the same message; services-crm:docs/change-events.md#7. Failures and recovery
  - artifact: WF-CRM-REG-003
    field: hops.1.provenance
    before: test
    after: observed
  - artifact: WF-CRM-REG-003
    field: hops.1.source
    before: >-
      services-crm:modules/regions/tests/integration/services/persistence/region-recalculations.integration.spec.js#region
      recalculations table (integration) › refuses a second running run for the tenant
    after: >-
      services-crm:modules/regions/tests/integration/services/persistence/region-recalculations.integration.spec.js#region
      recalculations table (integration) › refuses a second running run for the tenant;
      services-crm:modules/regions/services/region-assignment/region-recalculation.ts:startRegionRecalculation;
      services-crm:modules/regions/aws/api/regions.routes.ts:recalculateRegionAssignments
  - artifact: WF-CRM-REG-003
    field: hops.4.provenance
    before: test
    after: observed
  - artifact: WF-CRM-REG-003
    field: hops.4.source
    before: >-
      services-crm:modules/regions/tests/integration/services/region-assignment/region-recalculation-errors.integration.spec.js#a
      region recalculation that fails (integration) › the last delivery of a run’s event › fails the run,
      because nothing will deliver its event again
    after: >-
      services-crm:modules/regions/tests/integration/services/region-assignment/region-recalculation-errors.integration.spec.js#a
      region recalculation that fails (integration) › the last delivery of a run’s event › fails the run,
      because nothing will deliver its event again;
      services-crm:modules/regions/services/region-assignment/region-recalculation.ts:recordFailure
  - artifact: WF-CRM-REG-005
    field: hops.1.source
    before: 'services-crm:modules/data-jobs/services/operations/configuration-imports.ts:regionImports'
    after: >-
      services-crm:modules/data-jobs/services/operations/configuration-imports.ts:regionImports;
      services-crm:modules/data-jobs/services/operations/configuration-import.ts:configurationImportOperation
---
# Regions Design Examination

## Scope and Method

I examined all thirty design artifacts and the Regions responsibility boundary against the pinned backend and console. The examination opened the cited sources and anchors, compared route declarations, schemas, persistence, table constraints, registered handlers and screen components, and read the cited tests as evidence of their actual assertions. Every design artifact received an OpenAI rewrite in its own commit after verification; the responsibility text was also rewritten.

The supplied planning corpus remains unchanged. It records draft or proposed intent rather than the approval described by the job, and the requested design brief is absent. Those gaps are findings, so this examination does not confer product approval or resolve planning decisions.

## Coverage

| Boundary | Examined coverage | Qualification |
| --- | --- | --- |
| Operations | All 32 declared operations have one service contract: one health route, nineteen regional business routes and twelve hosted import routes. | Access and permission keys were checked against declarations. Every operation is unpublished to Submissions; no scoped binding was found. |
| Tables | All six regional tables are mapped by the four domain objects. | Placement also maps the regional facets of the two Entities record tables; Entities retains aggregate ownership. |
| Objects | Four objects, their attributes and relationships, and all 33 invariants were examined. | Database enforcement is distinguished from service validation, and legacy reference exceptions remain explicit. Neither catalogue nor policy opts into custom fields. |
| States | Four models and all 28 transition rows were examined. | Placement outcomes are explanatory states rather than a persisted manual-versus-calculated discriminator. |
| Workflows | Five workflows and all 26 hops were examined. | Coverage includes six regional handler registrations across contact, organization and recalculation streams, the shared delivery queue and scheduled dispatch, and the delegated file-processing state machine and queue. Shared-engine internals remain a boundary qualification. |
| Screens | Three contracts cover the catalogue and the rules view and editor. | Actual component patterns, controls, validation, regional permission gates and operation mappings were checked against the console. |
| Decisions and ownership | Thirteen decisions and the Regions responsibility row were examined. | Existing product records are cited; composite regional proposals are not elevated to confirmed intent by code observation. |
| Inference | All nine service, workflow and screen contracts retain an inference declaration. | No regional model-call task was found in the scoped code, so no inference operation was created. The existing planning declaration gap remains open. |

## Changes by Artifact

All prose and explanatory fields in the following artifacts were rewritten. The metadata ledger in this report records verification changes to provenance, sources, enforcement and intent separately from prose changes.

| Artifact | Verification result and final treatment |
| --- | --- |
| Region object | Qualified legacy references, separated enforcement layers and replaced overly broad test attribution with implementation evidence. |
| Assignment policy object | Made the unsaved version optional, distinguished dense ordering from database checks, and qualified unlocked reads and first-write races. |
| Regional placement object | Clarified Entities ownership, deciding-address behavior, locked-record handling and legacy references. |
| Recalculation run object | Distinguished admission constraints from best-effort failure settlement and checked persisted counters, cursor and phases. |
| Region availability model | Corrected creation and deletion evidence, immediate reference checks and inactive creation in the diagram. |
| Assignment policy currency model | Qualified concurrency and initialization; policy currency does not promise that stored placements have caught up. |
| Regional placement model | Removed an invented persisted distinction, corrected clearing after an unmatched address, and described asynchronous override release. |
| Recalculation model | Distinguished the request boundary from persisted states and made exhausted failure settlement an explicit recovery gap. |
| Address-change workflow | Checked capture and reconciliation anchors, organization locking, delivery retries, production-only alarms and redrive; removed a completion-time guarantee. |
| Linked-contact workflow | Checked organization-address propagation, record locking, traversal and retry behavior. |
| Recalculation workflow | Qualified final failure settlement and batch progress; documented polling and failure-display limitations. |
| Policy-change workflow | Distinguished schema and service validation and qualified policy initialization and snapshot consistency. |
| File-import workflow | Corrected insert, update and upsert distinctions and configured reject-versus-overwrite behavior; retained uncertainty at the shared-engine boundary. |
| Regions service contract | Sourced every operation to its route, proved public health access through the integrity-verified pinned dependency, and checked capabilities, permissions and publication status. |
| Catalogue screen | Corrected control labels and combined manage/delete gating; checked replacement payload behavior. |
| Rules-view screen | Removed an unrendered change-time claim and documented missing historical-failure restoration, running-error display and read-error handling. |
| Rules-editor screen | Identified the actual drawer and page patterns and made cancellation confirmation conditional on changes. |
| Placement-ownership decision | Sourced the implementation boundary and distinguished automatic decisions from authorized staff selections. |
| Asynchronous-placement decision | Reworded the committed-event boundary and recovery qualifications against the registered handlers. |
| Policy-change decision | Preserved the separation between saving coverage and requesting recalculation. |
| Resumable-recalculation decision | Reworded batching, continuation and failure behavior without promising unconditional final settlement. |
| First-match decision | Reworded ordering, enabled-rule matching and fallback behavior against the matching service. |
| Whole-or-individual-policy decision | Reworded shared policy mutation and version-reset behavior without resolving the existing open choice. |
| No-custom-fields decision | Checked the absence of an opt-in and retained the proposed product decision. |
| Complete-replacement decision | Preserved observed replacement behavior and its disagreement with the preferred product contract. |
| Version-read decision | Downgraded the composite decision to proposed because the cited product record does not approve its regional exceptions. |
| Audited-lock-actions decision | Preserved the cited product direction while distinguishing ordinary regional lock writes from dedicated audited actions. |
| Placement-version decision | Checked that only a changed stored region advances the record version. |
| Submissions-publication decision | Checked the publication boundary against the cited architecture decision and available bindings. |
| Workspace-reference decision | Distinguished current composite references from tolerated legacy references and shared outbox storage. |
| Regions responsibilities | Reconciled ownership and the 32-operation boundary, then rewrote event descriptions and prose with the implementation qualifications. |

The module registry now names the actual regional console boundary and records design examination. Permanent identifiers were retained, and ten new finding identifiers were allocated before their rows were written. The design verification commits precede the separate final-text commits; no planning rule was changed to make the implementation appear compliant.

## Open Disagreements

The new findings cover the missing brief and unrecorded planning approval; inconsistent policy read snapshots and concurrent initialization; recalculation monitoring and best-effort failure settlement; inaccurate display and component assumptions; evidence narrower than compound claims; partial database enforcement and tolerated legacy references; and configurable import overwrites. These remain open rather than receiving an invented product resolution.

Existing disagreements about retirement, replacement, lock actions, history, individual-rule versions and delegated infrastructure evidence remain open. The documented product direction on complete replacement and audited lock actions is cited rather than re-decided. Andrew must establish which planning records are approved and resolve the regional proposals before implementation preparation relies on them.

## Validation and Limits

The final acceptance run completed dependency installation, corpus conformance with zero errors, and all four corpus test cases. Conformance also passed after every design rewrite commit. The changed-file audit confines work to the authorized design, finding, registry, responsibility, module-row and report surfaces; the planning artifacts are unchanged.

Backend integration and browser suites were not executed. Their existing source assertions were examined, so this report provides a pinned-source examination and corpus validation rather than fresh runtime proof. Shared execution details that cannot be established within the permitted evidence boundary remain findings or explicit qualifications.

## Verdict for Andrew

The rewritten design is a faithful, qualified account of the regional implementation at the pinned commits, but the supplied planning corpus does not establish approved product intent. Its weakest areas are policy concurrency, recalculation recovery and monitoring, and evidence for delegated execution guarantees. Before implementation preparation begins, confirm the planning authority and decide the outstanding replacement, locking, versioning and recovery requirements.