Fix OH renewability/refillability to require completed dispense (#27123)

* fix: require completed dispense for OH renewability gate 3

* fix: require completed dispense for OH refillability Gate 5

Apply the same entered-in-error fix to the refill helper that was applied
to the renewability helper. Gate 5 now checks for at least one completed
MedicationDispense, preventing prescriptions with only entered-in-error
dispenses from being marked as refillable.

Bug: An Oracle Health prescription whose only MedicationDispense had
status 'entered-in-error' was incorrectly marked is_refillable: true,
causing it to appear on the Ready to Refill page even though no initial
fill was ever processed.

Root cause: Gate 5 checked medication_dispenses(resource).empty? which
passes for any dispense regardless of status. entered-in-error dispenses
represent voided records, not actual fills.

Fix: Replace the empty? check with completed_dispense_exists? which
requires at least one dispense with status == 'completed'.

* Move completed_dispense_exists? to FhirHelpers to deduplicate

completed_dispense_exists? was defined identically in both
OracleHealthRefillHelper and OracleHealthRenewabilityHelper.
Since it operates on FHIR MedicationDispense data and both helpers
already depend on FhirHelpers, move it there as the single source
of truth.

most_recent_dispense_in_progress? stays in OracleHealthRefillHelper
since it's not duplicated (only used by refill helper and adapter).

* Address Copilot review: fix dependency docs and renewability test

- Fix refill helper dependency docs: replace stale extract_expiration_date
  with parse_expiration_date_utc and prescription_expired? (actual deps)
- Add completed_dispense_exists? and non_va_med? to renewability helper
  dependency docs
- Fix entered-in-error renewability test: change from refills:1/non-expired
  (which failed on Gate 6, not Gate 3) to refills:0/expired so the failure
  is attributable to Gate 3 (completed dispense required)

Author: acrollet

lib/unified_health_data/adapters/fhir_helpers.rb

@@ -81,6 +81,16 @@ def find_most_recent_medication_dispense(medication_request)
         end
       end
 
+      # Checks for at least one successfully completed dispense.
+      # Dispenses with status 'entered-in-error' represent voided records and
+      # do not count as evidence that the initial fill was processed.
+      #
+      # @param resource [Hash] FHIR MedicationRequest resource
+      # @return [Boolean] true when a completed MedicationDispense exists
+      def completed_dispense_exists?(resource)
+        medication_dispenses(resource).any? { |dispense| dispense['status'] == 'completed' }
+      end
+
       # Builds instruction text from FHIR dosageInstruction components
       #
       # @param instruction [Hash] FHIR dosageInstruction object

lib/unified_health_data/adapters/oracle_health_refill_helper.rb

@@ -8,15 +8,14 @@ module Adapters
     # This module is designed to be included in OracleHealthPrescriptionAdapter
     # and has dependencies on methods from the including class and other mixed-in modules:
     #
-    # Required methods from including class (OracleHealthPrescriptionAdapter):
-    # - extract_expiration_date(resource) - Extracts validityPeriod.end from resource
-    #
     # Required methods from other modules (via include):
     # - categorize_medication(resource) - From OracleHealthCategorizer
     # - non_va_med?(resource) - From OracleHealthCategorizer
     # - medication_dispenses(resource) - From FhirHelpers
+    # - completed_dispense_exists?(resource) - From FhirHelpers
     # - find_most_recent_medication_dispense(medication_request) - From FhirHelpers
-    # - log_invalid_expiration_date(resource, date) - From FhirHelpers
+    # - parse_expiration_date_utc(resource) - From FhirHelpers
+    # - prescription_expired?(resource) - From FhirHelpers
     module OracleHealthRefillHelper
       # Determines if a medication is refillable based on gate checks
       # A medication is refillable only if ALL gate conditions pass
@@ -25,7 +24,7 @@ module OracleHealthRefillHelper
       # Gate 2: MedicationRequest.status == 'active'
       # Gate 3: Prescription not expired
       # Gate 4: Refills remaining > 0
-      # Gate 5: At least one dispense exists
+      # Gate 5: At least one completed dispense exists
       # Gate 6: Most recent dispense is not in-progress
       # Gate 7: No pending refill request (refill_status != 'submitted')
       #
@@ -37,7 +36,7 @@ def refillable?(resource, refill_status)
         return false unless resource['status'] == 'active'
         return false unless prescription_not_expired?(resource)
         return false unless extract_refill_remaining(resource).positive?
-        return false if medication_dispenses(resource).empty?
+        return false unless completed_dispense_exists?(resource)
         return false if most_recent_dispense_in_progress?(resource)
         return false if refill_status == 'submitted'
 
@@ -75,7 +74,7 @@ def extract_refill_remaining(resource)
       # In-progress statuses: preparation, in-progress, on-hold
       #
       # @param resource [Hash] FHIR MedicationRequest resource
-      # @return [Boolean] True if most recent dispense is in-progress
+      # @return [Boolean] true if most recent dispense is in-progress
       def most_recent_dispense_in_progress?(resource)
         most_recent = find_most_recent_medication_dispense(resource)
         return false if most_recent.nil?

lib/unified_health_data/adapters/oracle_health_renewability_helper.rb

@@ -12,7 +12,9 @@ module Adapters
     #
     #   Requires these methods from other modules (via include):
     #   - categorize_medication(resource) - From OracleHealthCategorizer
+    #   - non_va_med?(resource) - From OracleHealthCategorizer
     #   - medication_dispenses(resource) - From FhirHelpers
+    #   - completed_dispense_exists?(resource) - From FhirHelpers
     #   - parse_expiration_date_utc(resource) - From FhirHelpers
     #   - prescription_expired?(resource) - From FhirHelpers
     module OracleHealthRenewabilityHelper
@@ -23,7 +25,7 @@ module OracleHealthRenewabilityHelper
       #
       # Gate 1: MedicationRequest.status == 'active'
       # Gate 2: Category must be VA Prescription
-      # Gate 3: At least one dispense exists
+      # Gate 3: At least one completed dispense exists
       # Gate 4: Validity period end date exists
       # Gate 5: Within 120 days of validity period end
       # Gate 6: Refills exhausted OR prescription expired
@@ -35,7 +37,7 @@ def renewable?(resource)
         return false if resource.nil? || !resource.is_a?(Hash)
         return false unless resource['status'] == 'active'
         return false if non_va_med?(resource)
-        return false if medication_dispenses(resource).empty?
+        return false unless completed_dispense_exists?(resource)
         return false unless validity_period_end_exists?(resource)
         return false unless within_renewal_window?(resource)
         return false unless refills_exhausted_or_expired?(resource)

spec/lib/unified_health_data/adapters/oracle_health_refill_helper_spec.rb

@@ -127,6 +127,42 @@
       end
     end
 
+    context 'when only an entered-in-error dispense exists' do
+      let(:entered_in_error_dispense) do
+        {
+          'resourceType' => 'MedicationDispense',
+          'status' => 'entered-in-error',
+          'whenHandedOver' => '2025-01-01T10:00:00Z'
+        }
+      end
+
+      let(:entered_in_error_resource) do
+        refillable_resource.merge('contained' => [entered_in_error_dispense])
+      end
+
+      it 'returns false' do
+        expect(subject.refillable?(entered_in_error_resource, nil)).to be false
+      end
+    end
+
+    context 'when entered-in-error and completed dispenses both exist' do
+      let(:entered_in_error_dispense) do
+        {
+          'resourceType' => 'MedicationDispense',
+          'status' => 'entered-in-error',
+          'whenHandedOver' => '2025-01-01T10:00:00Z'
+        }
+      end
+
+      let(:mixed_dispense_resource) do
+        refillable_resource.merge('contained' => [entered_in_error_dispense, completed_dispense])
+      end
+
+      it 'returns true' do
+        expect(subject.refillable?(mixed_dispense_resource, nil)).to be true
+      end
+    end
+
     context 'when most recent dispense is in progress' do
       let(:in_progress_dispense) do
         {

spec/lib/unified_health_data/adapters/oracle_health_renewability_helper_spec.rb

@@ -180,6 +180,42 @@
         expect(subject.send(:renewable?, resource)).to be false
       end
 
+      it 'returns false when only entered-in-error dispense exists for active expired prescription' do
+        resource = fhir_resource(
+          status: 'active',
+          refills: 0,
+          expiration: 30.days.ago,
+          source: 'VA'
+        ).merge(
+          'contained' => [
+            {
+              'resourceType' => 'MedicationDispense',
+              'id' => 'dispense-1',
+              'status' => 'entered-in-error'
+            }
+          ]
+        )
+        expect(subject.send(:renewable?, resource)).to be false
+      end
+
+      it 'returns false with entered-in-error dispense for active non-expired prescription with no repeats' do
+        resource = fhir_resource(
+          status: 'active',
+          refills: 0,
+          expiration: 30.days.from_now,
+          source: 'VA'
+        ).merge(
+          'contained' => [
+            {
+              'resourceType' => 'MedicationDispense',
+              'id' => 'dispense-1',
+              'status' => 'entered-in-error'
+            }
+          ]
+        )
+        expect(subject.send(:renewable?, resource)).to be false
+      end
+
       it 'returns true with one completed dispense' do
         resource = fhir_resource(
           status: 'active',