davinci_pas_test_kit 0.14.1 → 0.15.0

data/lib/davinci_pas_test_kit/{pas_bundle_validation.rb → cross_suite/pas_bundle_validation.rb}

@@ -1,32 +1,95 @@
 # frozen_string_literal: true
 
+require_relative '../parameters_helper'
 require_relative 'validation_test'
+require_relative 'pas_constants'
 
 module DaVinciPASTestKit
   module PasBundleValidation
     include DaVinciPASTestKit::ValidationTest
+    include ParametersHelper
+
+    US_CORE_VERSION = '6.1.0'
+    US_CORE_PROFILE_BASE = 'http://hl7.org/fhir/us/core/StructureDefinition'
+    BASE_R4_PROFILE = :base_r4
+    CLAIM_ENCOUNTER_EXTENSION_URL = 'http://hl7.org/fhir/5.0/StructureDefinition/extension-Claim.encounter'
+    LOINC_SYSTEM = 'http://loinc.org'
+    TERMINOLOGY_CONDITION_CATEGORY_SYSTEM = 'http://terminology.hl7.org/CodeSystem/condition-category'
+    OBSERVATION_CATEGORY_SYSTEM = 'http://terminology.hl7.org/CodeSystem/observation-category'
+    DIAGNOSTIC_REPORT_CATEGORY_SYSTEM = 'http://terminology.hl7.org/CodeSystem/v2-0074'
+
+    US_CORE_SINGLE_PROFILE_IDS_BY_RESOURCE = {
+      'AllergyIntolerance' => 'us-core-allergyintolerance',
+      'CarePlan' => 'us-core-careplan',
+      'CareTeam' => 'us-core-careteam',
+      'Coverage' => 'us-core-coverage',
+      'Device' => 'us-core-implantable-device',
+      'DocumentReference' => 'us-core-documentreference',
+      'Encounter' => 'us-core-encounter',
+      'Goal' => 'us-core-goal',
+      'Immunization' => 'us-core-immunization',
+      'Location' => 'us-core-location',
+      'Medication' => 'us-core-medication',
+      'MedicationDispense' => 'us-core-medicationdispense',
+      'MedicationRequest' => 'us-core-medicationrequest',
+      'Organization' => 'us-core-organization',
+      'Patient' => 'us-core-patient',
+      'Practitioner' => 'us-core-practitioner',
+      'PractitionerRole' => 'us-core-practitionerrole',
+      'Procedure' => 'us-core-procedure',
+      'Provenance' => 'us-core-provenance',
+      'QuestionnaireResponse' => 'us-core-questionnaireresponse',
+      'RelatedPerson' => 'us-core-relatedperson',
+      'ServiceRequest' => 'us-core-servicerequest',
+      'Specimen' => 'us-core-specimen'
+    }.freeze
+
+    US_CORE_CONDITION_ENCOUNTER_DIAGNOSIS_PROFILE_ID = 'us-core-condition-encounter-diagnosis'
+    US_CORE_CONDITION_PROBLEMS_HEALTH_CONCERNS_PROFILE_ID = 'us-core-condition-problems-health-concerns'
+    US_CORE_DIAGNOSTIC_REPORT_LAB_PROFILE_ID = 'us-core-diagnosticreport-lab'
+    US_CORE_DIAGNOSTIC_REPORT_NOTE_PROFILE_ID = 'us-core-diagnosticreport-note'
+    US_CORE_OBSERVATION_CLINICAL_RESULT_PROFILE_ID = 'us-core-observation-clinical-result'
+    US_CORE_OBSERVATION_LAB_PROFILE_ID = 'us-core-observation-lab'
+    US_CORE_OBSERVATION_SCREENING_ASSESSMENT_PROFILE_ID = 'us-core-observation-screening-assessment'
+    US_CORE_SIMPLE_OBSERVATION_PROFILE_ID = 'us-core-simple-observation'
+    US_CORE_SMOKING_STATUS_PROFILE_ID = 'us-core-smokingstatus'
+    US_CORE_VITAL_SIGNS_PROFILE_ID = 'us-core-vital-signs'
+
+    US_CORE_OBSERVATION_CODE_PROFILE_IDS = {
+      '11341-5' => 'us-core-observation-occupation',
+      '86645-9' => 'us-core-observation-pregnancyintent',
+      '82810-3' => 'us-core-observation-pregnancystatus',
+      '76690-7' => 'us-core-observation-sexual-orientation',
+      '8289-1' => 'head-occipital-frontal-circumference-percentile',
+      '59576-9' => 'pediatric-bmi-for-age',
+      '77606-2' => 'pediatric-weight-for-height',
+      '85354-9' => 'us-core-blood-pressure',
+      '39156-5' => 'us-core-bmi',
+      '8302-2' => 'us-core-body-height',
+      '8310-5' => 'us-core-body-temperature',
+      '29463-7' => 'us-core-body-weight',
+      '9843-4' => 'us-core-head-circumference',
+      '8867-4' => 'us-core-heart-rate',
+      '59408-5' => 'us-core-pulse-oximetry',
+      '2708-6' => 'us-core-pulse-oximetry',
+      '9279-1' => 'us-core-respiratory-rate',
+      '72166-2' => 'us-core-smokingstatus'
+    }.freeze
 
-    CLAIM_PROFILE = 'http://hl7.org/fhir/us/davinci-pas/StructureDefinition/profile-claim-update'
-    CLAIM_RESPONSE_PROFILE = 'http://hl7.org/fhir/us/davinci-pas/StructureDefinition/profile-claimresponse'
-    CLAIM_INQUIRY_PROFILE = 'http://hl7.org/fhir/us/davinci-pas/StructureDefinition/profile-claim-inquiry'
-    CLAIM_INQUIRY_RESPONSE_PROFILE = 'http://hl7.org/fhir/us/davinci-pas/StructureDefinition/profile-claiminquiryresponse'
-
-    def all_scratch_resources
-      scratch_resources[:all] ||= []
+    def validation_error_messages
+      @validation_error_messages ||= []
     end
 
-    def save_bundles_and_entries_to_scratch(bundles)
-      bundles.each do |bundle|
-        all_scratch_resources << bundle
-        all_scratch_resources.concat(bundle.entry.map(&:resource))
-        all_scratch_resources.uniq!
+    def perform_bundle_validation(bundle, operation, type, ig_version)
+      target_profile = PASConstants.bundle_profile_url_for_operation_and_type(operation, type)
+      request_type = "#{operation}_#{type}"
+      if type == 'request'
+        perform_request_validation(bundle, target_profile, ig_version.delete_prefix('v'), request_type)
+      else
+        perform_response_validation(bundle, target_profile, ig_version.delete_prefix('v'), request_type)
       end
     end
 
-    def validation_error_messages
-      @validation_error_messages ||= []
-    end
-
     def perform_request_validation(bundle, profile_url, version, request_type)
       validate_pa_request_payload_structure(bundle, request_type)
       validate_resources_conformance_against_profile(bundle, profile_url, version, request_type)
@@ -39,20 +102,44 @@ module DaVinciPASTestKit
 
     def validate_pas_bundle_json(json, profile_url, version, request_type, bundle_type, skips: false, message: '')
       assert_valid_json(json)
-      bundle = FHIR.from_contents(json)
-      assert bundle.present?, 'Not a FHIR resource'
-      assert_resource_type(:bundle, resource: bundle)
+      resource = FHIR.from_contents(json)
+      assert resource.present?, 'Not a FHIR resource'
 
-      if bundle_type == 'request_bundle'
-        perform_request_validation(bundle, profile_url, version, request_type)
+      # For v2.2.1 inquire responses, expect Parameters resource
+      if version == '2.2.1' && request_type == 'inquire' && bundle_type == 'response_bundle'
+        if resource.resourceType == 'Parameters'
+          # Extract and validate each Bundle in the Parameters
+          bundles = extract_bundles_from_pas_inquiry_response_parameters(resource)
+
+          bundles.each do |bundle|
+            perform_response_validation(bundle, profile_url, version, request_type)
+          end
+        elsif resource.is_a?(FHIR::Bundle)
+          # Bundle received instead of Parameters - validate it but log an error
+          validation_error_messages << 'Expected Parameters resource for v2.2.1 inquire response, but received ' \
+                                       'Bundle. The response Bundle should be wrapped in a ' \
+                                       'Parameters resource with a return parameter.'
+          perform_response_validation(resource, profile_url, version, request_type)
+        else
+          assert false,
+                 "Expected Parameters resource for v2.2.1 inquire response, but received #{resource.resourceType}"
+        end
       else
-        perform_response_validation(bundle, profile_url, version, request_type)
+        # For v2.0.1 or non-inquire operations, expect Bundle resource
+        assert_resource_type(:bundle, resource: resource)
+        bundle = resource
+
+        if bundle_type == 'request_bundle'
+          perform_request_validation(bundle, profile_url, version, request_type)
+        else
+          perform_response_validation(bundle, profile_url, version, request_type)
+        end
       end
 
       validation_error_messages.each do |msg|
         messages << { type: 'error', message: msg }
       end
-      msg = 'Bundle response returned and/or entry resources are not conformant. Check messages for issues found.'
+      msg = 'Bundle and/or entry resources are not conformant. Check messages for issues found.'
       assert validation_error_messages.blank?, msg
     rescue Inferno::Exceptions::AssertionException => e
       msg = "#{message} #{e.message}".strip
@@ -127,7 +214,7 @@ module DaVinciPASTestKit
     # a given combination of content. Resources echoed back from the request are validated
     # to ensure the same fullUrl and resource identifiers as in the
     # request are used.
-    def validate_pa_response_body_structure(pa_response_bundle, pa_request_bundle)
+    def validate_pa_response_body_structure(pa_response_bundle, _pa_request_bundle)
       first_entry = pa_response_bundle.entry.first.resource
       unless first_entry.is_a?(FHIR::ClaimResponse)
         validation_error_messages <<
@@ -166,6 +253,7 @@ module DaVinciPASTestKit
     # The request/response bundle and includes resources are validated against their
     # respective profile.
     def validate_resources_conformance_against_profile(bundle, profile_url, version, request_type)
+      reset_bundle_profile_inference_state
       add_resource_target_profile_to_map('bundle', bundle, profile_url)
 
       bundle_entry = bundle.entry
@@ -175,12 +263,18 @@ module DaVinciPASTestKit
       end
 
       if root_entry.present?
-        root_resource_profile_url = find_profile_url(request_type)[root_entry.resource.resourceType]
+        root_resource_profile_url = if %w[submit submit_request].include?(request_type) &&
+                                       root_entry.resource.resourceType == 'Claim'
+                                      determine_claim_submit_profile_url(version, root_entry.resource)
+                                    else
+                                      find_profile_url(request_type)[root_entry.resource.resourceType]
+                                    end
 
         add_resource_target_profile_to_map(root_entry.fullUrl, root_entry.resource, root_resource_profile_url)
         extract_profiles_to_validate_each_entry(bundle_entry, root_entry, root_resource_profile_url, version)
       end
 
+      add_us_core_profiles_to_unprofiled_entries(bundle_entry, version)
       validate_bundle_entries_against_profiles(version)
     end
 
@@ -209,18 +303,176 @@ module DaVinciPASTestKit
     # and collects error messages for non-conformant entries. Asserts that there are no validation errors.
     # @param version [String] The version of the IG.
     def validate_bundle_entries_against_profiles(version)
-      bundle_resources_target_profile_map.each_value do |item|
+      bundle_resources_target_profile_map.each do |key, item|
         resource = item[:resource]
         base_profile = FHIR::Definitions.resource_definition(resource.resourceType).url
+
         success_profile = item[:profile_urls].find do |url|
-          profile_to_validate = url == base_profile ? url : "#{url}|#{version}"
-          resource_is_valid?(resource:, profile_url: profile_to_validate)
+          if key == 'bundle'
+            profile_to_validate = profile_url_for_validation(url, base_profile, version)
+            bundle_profile_valid?(resource, profile_to_validate)
+          elsif url == BASE_R4_PROFILE
+            resource_is_valid?(resource:)
+          else
+            profile_to_validate = profile_url_for_validation(url, base_profile, version)
+            resource_is_valid?(resource:, profile_url: profile_to_validate)
+          end
         end
 
         validation_error_messages << generate_non_conformance_message(item) unless success_profile
       end
     end
 
+    def profile_url_for_validation(url, base_profile, version)
+      url = url.to_s
+      return url if url.include?('|') || profile_url_without_version(url) == base_profile
+      return "#{url}|#{US_CORE_VERSION}" if us_core_profile_url?(url)
+
+      "#{url}|#{version}"
+    end
+
+    def reset_bundle_profile_inference_state
+      bundle_resources_target_profile_map.clear
+      @bundle_entry_map = nil
+    end
+
+    def add_us_core_profiles_to_unprofiled_entries(bundle_entry, version)
+      return unless us_core_profile_fallback_enabled?(version)
+
+      bundle_entry.each do |entry|
+        resource = entry.resource
+        next if resource.blank?
+
+        resource_full_url = resource_full_url_for_entry(entry)
+        next if bundle_resources_target_profile_map[resource_full_url]&.dig(:profile_urls).present?
+
+        profile_urls = us_core_profile_urls_for_resource(resource)
+        profile_urls = [BASE_R4_PROFILE] if profile_urls.blank?
+
+        profile_urls.each do |profile_url|
+          add_resource_target_profile_to_map(resource_full_url, resource, profile_url)
+        end
+      end
+    end
+
+    def resource_full_url_for_entry(entry)
+      resource = entry.resource
+
+      entry.fullUrl.presence || "#{resource.resourceType}/#{resource.id}"
+    end
+
+    def us_core_profile_fallback_enabled?(version)
+      version.to_s.delete_prefix('v').match?(/\A2\.2(\.|\z)/)
+    end
+
+    def us_core_profile_urls_for_resource(resource)
+      profile_ids =
+        case resource.resourceType
+        when 'Condition'
+          us_core_condition_profile_ids(resource)
+        when 'DiagnosticReport'
+          us_core_diagnostic_report_profile_ids(resource)
+        when 'Observation'
+          us_core_observation_profile_ids(resource)
+        else
+          Array(US_CORE_SINGLE_PROFILE_IDS_BY_RESOURCE[resource.resourceType])
+        end
+
+      us_core_profile_urls(profile_ids)
+    end
+
+    def us_core_condition_profile_ids(resource)
+      if category_code_present?(resource, 'encounter-diagnosis', system: TERMINOLOGY_CONDITION_CATEGORY_SYSTEM)
+        [US_CORE_CONDITION_ENCOUNTER_DIAGNOSIS_PROFILE_ID]
+      else
+        [US_CORE_CONDITION_PROBLEMS_HEALTH_CONCERNS_PROFILE_ID]
+      end
+    end
+
+    def us_core_diagnostic_report_profile_ids(resource)
+      if category_code_present?(resource, 'LAB', system: DIAGNOSTIC_REPORT_CATEGORY_SYSTEM)
+        [US_CORE_DIAGNOSTIC_REPORT_LAB_PROFILE_ID]
+      else
+        [US_CORE_DIAGNOSTIC_REPORT_NOTE_PROFILE_ID]
+      end
+    end
+
+    def us_core_observation_profile_ids(resource)
+      code_profile_id = US_CORE_OBSERVATION_CODE_PROFILE_IDS.find do |code, _profile_id|
+        codeable_concept_has_code?(resource.code, code, system: LOINC_SYSTEM)
+      end&.last
+      return [code_profile_id] if code_profile_id.present?
+
+      profile_ids = []
+      profile_ids << US_CORE_SMOKING_STATUS_PROFILE_ID if category_code_present?(resource, 'social-history',
+                                                                                 system: OBSERVATION_CATEGORY_SYSTEM)
+      profile_ids << US_CORE_VITAL_SIGNS_PROFILE_ID if category_code_present?(resource, 'vital-signs',
+                                                                              system: OBSERVATION_CATEGORY_SYSTEM)
+      if category_code_present?(resource, 'survey', system: OBSERVATION_CATEGORY_SYSTEM)
+        profile_ids << US_CORE_OBSERVATION_SCREENING_ASSESSMENT_PROFILE_ID
+      end
+      # Keep candidate profiles most-specific first because validation stops at the first conformant profile.
+      profile_ids << if category_code_present?(resource, 'laboratory', system: OBSERVATION_CATEGORY_SYSTEM)
+                       US_CORE_OBSERVATION_LAB_PROFILE_ID
+                     else
+                       US_CORE_OBSERVATION_CLINICAL_RESULT_PROFILE_ID
+                     end
+      profile_ids << US_CORE_SIMPLE_OBSERVATION_PROFILE_ID
+      profile_ids.uniq
+    end
+
+    def us_core_profile_urls(profile_ids)
+      Array(profile_ids).map { |profile_id| "#{US_CORE_PROFILE_BASE}/#{profile_id}|#{US_CORE_VERSION}" }
+    end
+
+    def profile_url_without_version(url)
+      url.to_s.split('|', 2).first
+    end
+
+    def us_core_profile_url?(url)
+      profile_url_without_version(url).start_with?("#{US_CORE_PROFILE_BASE}/")
+    end
+
+    def category_code_present?(resource, code, system:)
+      codeable_concept_has_code?(resource.category, code, system:)
+    end
+
+    def codeable_concept_has_code?(codeable_concepts, code, system:)
+      systems = Array(system).compact
+      Array(codeable_concepts).compact.any? do |codeable_concept|
+        Array(codeable_concept&.coding).compact.any? do |coding|
+          coding.code == code && systems.include?(coding.system)
+        end
+      end
+    end
+
+    # Validates a Bundle resource against a profile, filtering out entry-resource-level issues
+    # that are covered by individual resource validation to avoid duplicate messages.
+    # @param bundle [FHIR::Bundle] The Bundle resource to validate.
+    # @param profile_url [String] The profile URL (with version) to validate against.
+    # @return [Boolean] true if no unfiltered errors remain after removing entry-resource issues.
+    def bundle_profile_valid?(bundle, profile_url)
+      response_details = []
+      resource_is_valid?(resource: bundle, profile_url:,
+                         add_messages_to_runnable: false,
+                         validator_response_details: response_details)
+      bundle_level_issues = reject_entry_resource_issues(response_details)
+      bundle_level_issues.each { |issue| messages << { type: issue.severity, message: issue.message } }
+      bundle_level_issues.none? { |issue| issue.severity == 'error' }
+    end
+
+    # Rejects validator issues that are already filtered or are located at/below
+    # Bundle.entry[N].resource, since those are validated individually per resource.
+    # @param issues [Array<ValidatorIssue>] Raw issues from the validator.
+    # @return [Array<ValidatorIssue>] Issues relevant only to the Bundle structure itself.
+    #
+    # Entry resources that receive direct PAS or US Core target profiles are validated individually after this filter.
+    def reject_entry_resource_issues(issues)
+      issues.reject do |issue|
+        issue.filtered || issue.location&.match?(/\ABundle\.entry\[\d+\]\.resource/)
+      end
+    end
+
     def generate_non_conformance_message(item)
       "#{item[:resource].resourceType}/#{item[:resource].id} is not conformant to any of the " \
         "target profiles: #{item[:profile_urls]}."
@@ -236,14 +488,18 @@ module DaVinciPASTestKit
       return if current_entry.blank?
 
       # NOTE: the IG does not have the metadata for us-core profiles.
-      metadata = metadata_map("v#{version}")[current_entry_profile_url]
+      metadata = metadata_map("v#{version}")[profile_url_without_version(current_entry_profile_url)]
       return if metadata.blank?
 
       bundle_map = bundle_entry_map(bundle_entry)
-      reference_elements = metadata.references
+      reference_elements = metadata.references.dup
 
       # Special handling for Claim submit profile
-      if current_entry_profile_url == CLAIM_PROFILE
+      claim_submit_profile_urls = [
+        PASConstants::CLAIM_PROFILE,
+        PASConstants::CLAIM_PROFILE_FIRST_SUBMIT
+      ]
+      if claim_submit_profile_urls.include?(current_entry_profile_url)
         handle_claim_profile(reference_elements,
                              current_entry_profile_url)
       end
@@ -259,7 +515,11 @@ module DaVinciPASTestKit
     # @param reference_elements [Array] The array of reference elements to be updated.
     # @param current_entry_profile_url [String] The profile URL of the current entry being processed.
     def handle_claim_profile(reference_elements, current_entry_profile_url)
-      return unless current_entry_profile_url == CLAIM_PROFILE
+      claim_submit_profile_urls = [
+        PASConstants::CLAIM_PROFILE,
+        PASConstants::CLAIM_PROFILE_FIRST_SUBMIT
+      ]
+      return unless claim_submit_profile_urls.include?(current_entry_profile_url)
 
       claim_ref_element = {
         path: 'Claim.item.extension.value',
@@ -271,7 +531,16 @@ module DaVinciPASTestKit
         ]
       }
 
+      # This temporary traversal handling may be replaced later by shared metadata-driven navigation logic.
+      claim_encounter_ref_element = {
+        path: "Claim.extension.where(url = '#{CLAIM_ENCOUNTER_EXTENSION_URL}').value",
+        profiles: [
+          'http://hl7.org/fhir/us/davinci-pas/StructureDefinition/profile-encounter'
+        ]
+      }
+
       reference_elements << claim_ref_element
+      reference_elements << claim_encounter_ref_element
     end
 
     # Processes a given reference element definition from a FHIR bundle entry.
@@ -311,7 +580,7 @@ module DaVinciPASTestKit
 
       reference_element[:profiles].each do |profile_url|
         # NOTE: the IG does not have the metadata for us-core profiles.
-        target_metadata = metadata_map("v#{version}")[profile_url]
+        target_metadata = metadata_map("v#{version}")[profile_url_without_version(profile_url)]
         resource_type = instance.resource.resourceType
         next unless target_metadata&.resource == resource_type || profile_url.include?(resource_type)
 
@@ -356,10 +625,12 @@ module DaVinciPASTestKit
 
     # Mapping profile url to metadata
     def metadata_map(version)
-      @metadata ||= YAML.load_file(File.join(__dir__, "generated/#{version}/metadata.yml"),
-                                   aliases: true)
-      @metadata_map ||= @metadata[:groups].to_h do |group|
-        [group[:profile_url], Generator::GroupMetadata.new(group)]
+      @metadata ||= {}
+      @metadata[version] ||= YAML.load_file(File.join(__dir__, "generated/#{version}/metadata.yml"),
+                                            aliases: true)
+      @metadata_map ||= {}
+      @metadata_map[version] ||= @metadata[version][:profiles].to_h do |profile_metadata|
+        [profile_metadata[:profile_url], Generator::ProfileMetadata.new(profile_metadata)]
       end
     end
 
@@ -407,11 +678,39 @@ module DaVinciPASTestKit
     # Resource Types to validate in request/ response bundle
     def find_profile_url(request_type)
       {
-        'Claim' => request_type == 'submit' ? CLAIM_PROFILE : CLAIM_INQUIRY_PROFILE,
-        'ClaimResponse' => request_type == 'submit' ? CLAIM_RESPONSE_PROFILE : CLAIM_INQUIRY_RESPONSE_PROFILE
+        'Claim' => if request_type.start_with?('submit')
+                     PASConstants::CLAIM_PROFILE
+                   else
+                     PASConstants::CLAIM_INQUIRY_PROFILE
+                   end,
+        'ClaimResponse' => if %w[submit submit_response].include?(request_type)
+                             PASConstants::CLAIM_RESPONSE_PROFILE
+                           else
+                             PASConstants::CLAIM_INQUIRY_RESPONSE_PROFILE
+                           end
       }
     end
 
+    # Determines the target profile URL for a Claim resource in a submit request bundle.
+    #
+    # In v2.2.1, profile-pas-request-bundle permits either profile-claim or profile-claim-update.
+    # The structural discriminator is Claim.related: profile-claim-update requires it (must-support)
+    # while profile-claim disallows it (max: 0). For all other versions, profile-claim-update is
+    # used unconditionally.
+    #
+    # @param version [String] The IG version (e.g. '2.2.1').
+    # @param claim [FHIR::Claim] The Claim resource to inspect.
+    # @return [String] The profile URL to validate against.
+    def determine_claim_submit_profile_url(version, claim)
+      return PASConstants::CLAIM_PROFILE unless version == '2.2.1'
+
+      if claim.related.blank?
+        PASConstants::CLAIM_PROFILE_FIRST_SUBMIT
+      else
+        PASConstants::CLAIM_PROFILE
+      end
+    end
+
     # Checks the following requirement:
     # The Claim.supportingInfo.sequence for each entry SHALL be unique within the Claim.
     #
@@ -456,13 +755,17 @@ module DaVinciPASTestKit
     # @param target_resource [FHIR::Model] The FHIR resource to traverse and validate.
     # @param base_url [String] The server base url.
     # @param resources_to_match [Array<FHIR:Bundle:Entry] The list of FHIR bundle entries to match references against.
-    def check_presence_of_referenced_resources(target_resource, base_url, resources_to_match)
+    # @param skip_claim_related [Boolean] When true, a Claim's `related` element is not traversed. This is set
+    #   for any Claim reached by following a reference (i.e. a non-primary Claim in a Claim Update chain), whose
+    #   own Claim.related.claim (the grandparent) is deliberately omitted from the Bundle per spec-65/66. The
+    #   primary Claim passed in by the caller keeps `skip_claim_related: false`, so its parent reference - and the
+    #   parent's own referenced resources - are still checked.
+    def check_presence_of_referenced_resources(target_resource, base_url, resources_to_match,
+                                               skip_claim_related: false)
       return if target_resource.blank?
 
       if target_resource.is_a?(FHIR::Reference) && target_resource.reference.present?
         ref = target_resource.reference
-        return if ref.blank?
-
         absolute_ref = absolute_url(ref, base_url)
         matching_resources = resources_to_match.find_all { |res| res.fullUrl == absolute_ref }
 
@@ -472,20 +775,49 @@ module DaVinciPASTestKit
         end
 
         if matching_resources.length.positive?
-          check_presence_of_referenced_resources(matching_resources.first, base_url, resources_to_match)
+          # A resource reached by following a reference is an included resource, not the primary Claim
+          # being validated; if it is itself a Claim Update, its referenced grandparent Claim is omitted.
+          check_presence_of_referenced_resources(matching_resources.first.resource, base_url, resources_to_match,
+                                                 skip_claim_related: true)
         end
       else
         target_resource.source_hash.each_key do |attr|
+          next if claim_response_request_attr?(target_resource, attr)
+          next if skip_claim_related && claim_related_attr?(target_resource, attr)
+
           value = target_resource.send(attr.to_sym)
           if value.is_a?(FHIR::Model)
-            check_presence_of_referenced_resources(value, base_url, resources_to_match)
+            check_presence_of_referenced_resources(value, base_url, resources_to_match, skip_claim_related:)
           elsif value.is_a?(Array) && value.all?(FHIR::Model)
-            value.each { |elmt| check_presence_of_referenced_resources(elmt, base_url, resources_to_match) }
+            value.each do |elmt|
+              check_presence_of_referenced_resources(elmt, base_url, resources_to_match, skip_claim_related:)
+            end
           end
         end
       end
     end
 
+    # ClaimResponse.request is a back-reference to the submitted Claim. The PAS IG response bundle
+    # profile (profile-pas-response-bundle) has no required Claim entry slice, so the Claim need
+    # not be present in the response bundle. Skipping here matches the identical guard in
+    # ResponseGenerator#referenced_entities, which also skips ClaimResponse.request when
+    # building mock response bundles.
+    def claim_response_request_attr?(resource, attr)
+      attr.to_s == 'request' &&
+        resource.respond_to?(:resourceType) &&
+        resource.resourceType == 'ClaimResponse'
+    end
+
+    # Claim.related.claim points to the Claim being updated. For a non-primary Claim in a Claim Update
+    # chain (one reached by following a reference), that prior Claim is the grandparent, which spec-65/66
+    # require to be omitted from the Bundle. Used with the `skip_claim_related` flag so the generic
+    # reference-presence check does not flag the deliberately-omitted grandparent as missing.
+    def claim_related_attr?(resource, attr)
+      attr.to_s == 'related' &&
+        resource.respond_to?(:resourceType) &&
+        resource.resourceType == 'Claim'
+    end
+
     # Extracts resources from a bundle while following "next" links.
     #
     # @param bundle [FHIR::Bundle] The initial FHIR bundle to extract resources from.
@@ -527,10 +859,7 @@ module DaVinciPASTestKit
     # This method generates an error message when a referenced resource appears more than once
     # in a FHIR bundle, which is not allowed.
     def resource_shall_appear_once_message(absolute_ref, total_matches)
-      "
-        The referenced #{absolute_ref} resource
-        SHALL appear exactly once in the Bundle, but found #{total_matches}.
-      "
+      " The referenced #{absolute_ref} resource SHALL appear exactly once in the Bundle, but found #{total_matches}."
     end
 
     # Generates a message for a resource present in both the PA request and response bundles.
@@ -540,10 +869,8 @@ module DaVinciPASTestKit
     # This method generates an error message when a resource appears in both the PA request
     # and response bundles but does not have the same fullUrl or identifiers.
     def resource_present_in_pa_request_and_response_msg(resource)
-      "
-        Resource #{resource.resourceType}/#{resource.id} is an entry in both the PA Request Bundle
-        and the Response Bundle, but they do not have the same fullUrl or identifiers
-      "
+      "Resource #{resource.resourceType}/#{resource.id} is an entry in both the PA Request Bundle and the Response " \
+        'Bundle, but they do not have the same fullUrl or identifiers'
     end
   end
 end

data/lib/davinci_pas_test_kit/cross_suite/pas_constants.rb

@@ -0,0 +1,31 @@
+module DaVinciPASTestKit
+  module PASConstants
+    CLAIM_PROFILE = 'http://hl7.org/fhir/us/davinci-pas/StructureDefinition/profile-claim-update'.freeze
+    CLAIM_PROFILE_FIRST_SUBMIT = 'http://hl7.org/fhir/us/davinci-pas/StructureDefinition/profile-claim'.freeze
+    CLAIM_RESPONSE_PROFILE = 'http://hl7.org/fhir/us/davinci-pas/StructureDefinition/profile-claimresponse'.freeze
+    CLAIM_INQUIRY_PROFILE = 'http://hl7.org/fhir/us/davinci-pas/StructureDefinition/profile-claim-inquiry'.freeze
+    CLAIM_INQUIRY_RESPONSE_PROFILE = 'http://hl7.org/fhir/us/davinci-pas/StructureDefinition/profile-claiminquiryresponse'.freeze
+
+    BUNDLE_PROFILES_FOR_OPERATION_TYPE = {
+      submit_request: 'http://hl7.org/fhir/us/davinci-pas/StructureDefinition/profile-pas-request-bundle',
+      submit_response: 'http://hl7.org/fhir/us/davinci-pas/StructureDefinition/profile-pas-response-bundle',
+      inquire_request: 'http://hl7.org/fhir/us/davinci-pas/StructureDefinition/profile-pas-inquiry-request-bundle',
+      inquire_response: 'http://hl7.org/fhir/us/davinci-pas/StructureDefinition/profile-pas-inquiry-response-bundle'
+    }.freeze
+
+    def self.bundle_profile_url_for_operation_and_type(operation, type)
+      BUNDLE_PROFILES_FOR_OPERATION_TYPE[:"#{operation}_#{type}"]
+    end
+
+    def self.bundle_profile_name_for_operation_and_type(operation, type)
+      url = bundle_profile_url_for_operation_and_type(operation, type)
+      url.split('/profile-').last.titleize.gsub('Pas', 'PAS')
+    end
+
+    X12_ADJUDICATION_CODES = {
+      approval: 'A1',
+      denial: 'A3',
+      pended: 'A4'
+    }.freeze
+  end
+end