spree_cm_commissioner 2.7.1.pre.pre5 → 2.7.1.pre.pre7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 84d0265d3f929b863daa466604c59bce056eeefaf6a68b8835fe6f4090c46260
-  data.tar.gz: 4e7479e3a9625ac96dc232247e68ced8ad65b52942c6ad415c8f6504bbdee411
+  metadata.gz: 1d5c165b63ae28d6c85cc90a61791e4c358329c04ee7fc1d3e096c595a4998df
+  data.tar.gz: ac2ad57bca6d10b9fdab2de0cb4ed71fb642f566140f6fbde62e146bb6ece18d
 SHA512:
-  metadata.gz: bff8835ece695f1ab781c31eb0d3b279ca9417b5034509ba9070883b9ceb95a883465ca4bdfaa5dc2687d4c8a682744405edc2fcae30dbb83b39956f321440a8
-  data.tar.gz: 5adfe3d241415a2f6fd3a9537adb951882201bee5564741ccd2d7f767d6033f92f0211f1ac26901fe4821539551931381605fe240a55134e9e71783283d9a047
+  metadata.gz: 59c576a6399bb685a3c9af3df233ec99b58dadfc94abfccdfe1fd82c8adf635b78e7d1e682b65671ce66298bad1a3f76bb6c44186c1ef3f502ac614416f84e34
+  data.tar.gz: 154bcdb685ff2f61f50370b4dad38fba5a9f60914edecd5c55da28824c4f009e0563bf10e8f65632a758b2158558e77175a9a593c9bbc2158ed4407d210e6b33

data/.env.example

@@ -50,3 +50,15 @@ EXPORT_PRESIGNED_URL_EXPIRATION_MINUTES=15
 
 # import order batch size
 IMPORT_ORDERS_BATCH_SIZE=50
+
+# Inventory Hold System
+# See: app/services/spree_cm_commissioner/order_holds/hold.rb
+HOLD_DURATION_IN_MINUTES=8                  # How long a hold is active after checkout begins (address step)
+
+# See: app/services/spree_cm_commissioner/order_holds/lock_for_payment.rb
+PAYMENT_LOCK_MIN_DURATION_IN_MINUTES=5      # Minimum remaining hold time required when entering the payment step; hold is extended if below this threshold
+
+# See: app/services/spree_cm_commissioner/inventory_holds/validate_limits.rb
+MAX_ACTIVE_HOLDS_PER_USER=3                 # Max concurrent active holds allowed per user across all orders
+MAX_HOLDS_PER_IP_PER_HOUR=5                 # Max hold attempts per IP address within a rolling 1-hour window (abuse prevention)
+HOLD_COOLDOWN_AFTER_EXPIRY_IN_MINUTES=2     # Cooldown period before a user can re-acquire a hold after one expired on them

data/.gitignore

@@ -34,7 +34,3 @@ vendor/bundle/
 # Cursor
 .cursor
 dump.rdb
-# Added by code-review-graph
-.code-review-graph/
-.cursorrules
-.claude

data/Gemfile.lock

@@ -34,7 +34,7 @@ GIT
 PATH
   remote: .
   specs:
-    spree_cm_commissioner (2.7.1.pre.pre5)
+    spree_cm_commissioner (2.7.1.pre.pre7)
       activerecord-multi-tenant
       activerecord_json_validator (~> 2.1, >= 2.1.3)
       aws-sdk-cloudfront

data/app/controllers/concerns/spree_cm_commissioner/order_concern.rb

@@ -11,6 +11,7 @@ module SpreeCmCommissioner
         raise CanCan::AccessDenied
       end
 
+      @spree_current_order.last_ip_address = request.remote_ip
       @spree_current_order
     end
 

data/app/controllers/spree/admin/classifications_controller.rb

@@ -5,7 +5,7 @@ module Spree
 
       def recalculate_conversions
         if @taxon.parent.event?
-          SpreeCmCommissioner::MaintenanceTasks::Event.pending.find_or_create_by(
+          SpreeCmCommissioner::MaintenanceTasks::Event.pending.create_or_find_by(
             maintainable_type: 'Spree::Taxon',
             maintainable_id: @taxon.parent.id
           ) do |task|

data/app/controllers/spree/admin/inventory_holds_controller.rb

@@ -0,0 +1,64 @@
+module Spree
+  module Admin
+    class InventoryHoldsController < BaseController
+      def index
+        authorize! :manage, SpreeCmCommissioner::InventoryHold
+
+        q = params.fetch(:q, {})
+        q = q.respond_to?(:to_unsafe_h) ? q.to_unsafe_h.deep_dup : q.deep_dup
+        q['s'] ||= 'created_at desc'
+        q['created_at_gt'] = parse_time_or_nil(q['created_at_gt'], :beginning_of_day) if q['created_at_gt'].present?
+        q['created_at_lt'] = parse_time_or_nil(q['created_at_lt'], :end_of_day) if q['created_at_lt'].present?
+
+        @search = scope.ransack(q)
+        result_scope = @search.result(distinct: true)
+
+        @holds = result_scope
+                 .includes(order: [:user, { line_items: { variant: { product: :vendor } } }])
+                 .page(params[:page])
+                 .per(params[:per_page] || Spree::Backend::Config[:admin_orders_per_page])
+
+        @status_counts = result_scope.reorder(nil).group(:status).count
+      end
+
+      def release
+        authorize! :manage, SpreeCmCommissioner::InventoryHold
+
+        hold = SpreeCmCommissioner::InventoryHold.find(params[:id])
+
+        if hold.finalized?
+          flash[:error] = "Hold ##{hold.id} is already #{hold.status} and cannot be released."
+          return redirect_to admin_inventory_holds_path(back_params)
+        end
+
+        result = SpreeCmCommissioner::InventoryHolds::Release.call(hold: hold, reason: :user_canceled)
+
+        if result.success?
+          flash[:success] = "Hold ##{hold.id} for order #{hold.order.number} has been released."
+        else
+          flash[:error] = "Failed to release hold ##{hold.id}: #{result.error}"
+        end
+
+        redirect_to admin_inventory_holds_path(back_params)
+      end
+
+      private
+
+      def back_params
+        raw_params = params[:back_params].presence || params
+        ActionController::Parameters.new(raw_params).permit(:page, :per_page, q: {})
+      end
+
+      def scope
+        SpreeCmCommissioner::InventoryHold
+          .accessible_by(current_ability, :manage)
+      end
+
+      def parse_time_or_nil(value, boundary)
+        Time.zone.parse(value).public_send(boundary)
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end

data/app/controllers/spree/admin/inventory_monitorings_controller.rb

@@ -5,19 +5,20 @@ module Spree
         authorize! :manage, SpreeCmCommissioner::InventoryItem
 
         @time_range = params[:time_range] || 7
-        @filter_type = params[:filter_type] || 'all'
+        @product_type = params[:product_type].presence
         @vendor_id = params[:vendor_id]
 
         finder = SpreeCmCommissioner::InventoryItems::RecentlyChangedFinder.new(
           time_range: @time_range.to_i.days.ago,
           limit: 1000,
           vendor_id: @vendor_id,
-          filter_type: @filter_type
+          product_type: @product_type
         )
 
         @inventory_items = finder.execute
         @total_count = @inventory_items.size
         @out_of_sync_count = @inventory_items.count { |item| item[:out_of_sync] }
+        @on_hold_out_of_sync_count = @inventory_items.count { |item| item[:on_hold_out_of_sync] }
       end
 
       def reset
@@ -32,7 +33,10 @@ module Spree
           flash[:error] = "Failed to reset inventory: #{result.message}"
         end
 
-        redirect_to action: :index, time_range: params[:time_range], filter_type: params[:filter_type]
+        redirect_to action: :index,
+                    time_range: params[:time_range],
+                    product_type: params[:product_type],
+                    vendor_id: params[:vendor_id]
       end
     end
   end

data/app/controllers/spree/admin/stock_managements_controller.rb

@@ -5,7 +5,7 @@ module Spree
 
       before_action :load_parent
 
-      helper_method :inventory_item_message
+      helper_method :inventory_item_message, :inventory_item_hold_message
 
       def load_parent
         @product = Spree::Product.find_by(slug: params[:product_id])
@@ -75,6 +75,15 @@ module Spree
         end
       end
 
+      def inventory_item_hold_message(inventory_item, cached_inventory_item)
+        synced = inventory_item.quantity_on_hold == cached_inventory_item.quantity_on_hold
+        if synced
+          "Synced: Quantity on hold matches in both DB and Redis (#{cached_inventory_item.quantity_on_hold})."
+        else
+          "Out of sync: Redis shows #{cached_inventory_item.quantity_on_hold} on hold, which doesn't match the database."
+        end
+      end
+
       private
 
       def load_inventories

data/app/controllers/spree/api/v2/operator/recalculate_tickets_controller.rb

@@ -7,7 +7,7 @@ module Spree
           before_action :load_taxon, only: :create
 
           def create
-            SpreeCmCommissioner::MaintenanceTasks::Event.pending.find_or_create_by(
+            SpreeCmCommissioner::MaintenanceTasks::Event.pending.create_or_find_by(
               maintainable: @taxon
             ).async_execute
 

data/app/controllers/spree/api/v2/storefront/pricing_previews_controller.rb

@@ -0,0 +1,50 @@
+module Spree
+  module Api
+    module V2
+      module Storefront
+        class PricingPreviewsController < ::Spree::Api::V2::BaseController
+          # GET /api/v2/tenant/pricing_previews
+          def index
+            permitted_preview_params = params.permit(SpreeCmCommissioner::PricingModels::OrderContext::PREVIEW_PERMITTED_PARAMS)
+            order_context = SpreeCmCommissioner::PricingModels::OrderContext.load!(permitted_preview_params[:order_context])
+            pricing_models_updated_at = SpreeCmCommissioner::PricingModel.joins(:vendor)
+                                                                         .where(spree_vendors: { tenant_id: nil })
+                                                                         .maximum(:updated_at)
+            cache_key = 'pricing:preview:v2:' \
+                        "#{Digest::SHA256.hexdigest(permitted_preview_params.to_json)}:" \
+                        "#{pricing_models_updated_at.to_i}"
+
+            cached_result = Rails.cache.fetch(cache_key, expires_in: 60.seconds) do
+              result = SpreeCmCommissioner::PricingModels::Preview.call(order_context: order_context)
+              if result.success?
+                {
+                  success: true,
+                  payload: serialize_resource(result.value[:pricing_preview]).as_json
+                }
+              else
+                {
+                  success: false,
+                  error: result.error.to_s
+                }
+              end
+            end
+
+            if cached_result[:success]
+              render_serialized_payload { cached_result[:payload] }
+            else
+              render_error_payload(cached_result[:error], 422)
+            end
+          rescue ArgumentError => e
+            render_error_payload(e.message, 422)
+          end
+
+          private
+
+          def resource_serializer
+            SpreeCmCommissioner::V2::Storefront::PricingPreviewSerializer
+          end
+        end
+      end
+    end
+  end
+end

data/app/controllers/spree/api/v2/tenant/base_controller.rb

@@ -16,10 +16,6 @@ module Spree
             set_current_tenant(@tenant)
           end
 
-          def current_vendor
-            @current_vendor ||= @tenant.active_vendor
-          end
-
           def render_serialized_payload(status = 200)
             render json: yield, status: status, content_type: content_type
           end

data/app/controllers/spree/api/v2/tenant/intercity_taxi/draft_orders_controller.rb

@@ -29,6 +29,7 @@ module Spree
               result = SpreeCmCommissioner::IntercityTaxiOrder::Update.call(
                 order: spree_current_order,
                 remark: params[:remark],
+                passenger_count: params[:passenger_count],
                 pickup_map_place_attributes: params[:pickup_map_place_attributes]&.permit(
                   :place_name,
                   :lat,

data/app/controllers/spree/api/v2/tenant/pricing_previews_controller.rb

@@ -0,0 +1,54 @@
+module Spree
+  module Api
+    module V2
+      module Tenant
+        class PricingPreviewsController < BaseController
+          # GET /api/v2/tenant/pricing_previews
+          def index
+            permitted_preview_params = params.permit(SpreeCmCommissioner::PricingModels::OrderContext::PREVIEW_PERMITTED_PARAMS)
+            order_context = SpreeCmCommissioner::PricingModels::OrderContext.load!(
+              permitted_preview_params[:order_context],
+              tenant_id: current_tenant.id
+            )
+
+            pricing_models_updated_at = SpreeCmCommissioner::PricingModel.joins(:vendor)
+                                                                         .where(spree_vendors: { tenant_id: current_tenant.id })
+                                                                         .maximum(:updated_at)
+            cache_key = 'pricing:preview:v2:' \
+                        "#{Digest::SHA256.hexdigest(permitted_preview_params.to_json)}:" \
+                        "#{pricing_models_updated_at.to_i}"
+
+            cached_result = Rails.cache.fetch(cache_key, expires_in: 60.seconds) do
+              result = SpreeCmCommissioner::PricingModels::Preview.call(order_context: order_context)
+              if result.success?
+                {
+                  success: true,
+                  payload: serialize_resource(result.value[:pricing_preview]).as_json
+                }
+              else
+                {
+                  success: false,
+                  error: result.error.to_s
+                }
+              end
+            end
+
+            if cached_result[:success]
+              render_serialized_payload { cached_result[:payload] }
+            else
+              render_error_payload(cached_result[:error], 422)
+            end
+          rescue ArgumentError => e
+            render_error_payload(e.message, 422)
+          end
+
+          private
+
+          def resource_serializer
+            Spree::V2::Tenant::PricingPreviewSerializer
+          end
+        end
+      end
+    end
+  end
+end

data/app/factory/spree_cm_commissioner/order_telegram_message_factory.rb

@@ -48,6 +48,8 @@ module SpreeCmCommissioner
     end
 
     def line_item_content(line_item)
+      return intercity_taxi_line_item_content(line_item) if intercity_taxi?(line_item)
+
       text = []
 
       text << bold(line_item.product.name.to_s)
@@ -82,6 +84,8 @@ module SpreeCmCommissioner
       text << "Email: #{inline_code(order.email)}" if order.email.present?
       text << "Delivery Address: #{formatted_shipping_address.presence || 'N/A'}" if order.delivery_required?
 
+      append_intercity_taxi_footer(text) if intercity_taxi_order?
+
       if show_details_link && order.guests.any?
         text << ''
         text << 'View Tickets:'
@@ -125,5 +129,89 @@ module SpreeCmCommissioner
 
       formatted_rows
     end
+
+    private
+
+    def intercity_taxi?(line_item)
+      trip_for(line_item)&.intercity_taxi?
+    end
+
+    def intercity_taxi_order?
+      selected_line_items.any? { |li| intercity_taxi?(li) }
+    end
+
+    def trip_for(line_item)
+      return nil unless line_item.respond_to?(:trip_id) && line_item.trip_id.present?
+
+      @trip_cache ||= {}
+      @trip_cache[line_item.trip_id] ||= SpreeCmCommissioner::Trip.find_by(id: line_item.trip_id)
+    end
+
+    def intercity_taxi_line_item_content(line_item)
+      text = []
+      route_text = taxi_route_text(line_item)
+      departure_text = taxi_departure_text(line_item)
+      text << bold('🚗 Trip Details')
+      text << "Route: #{route_text}" if route_text.present?
+      text << "Passengers: #{line_item.passenger_count || line_item.quantity}"
+      text << "Departure: #{departure_text}" if departure_text.present?
+
+      text.compact.join("\n")
+    end
+
+    def taxi_route_text(line_item)
+      trip = trip_for(line_item)
+      return line_item.product.name if trip.blank?
+
+      origin = trip.origin_place&.name
+      destination = trip.destination_place&.name
+      vehicle = trip.vehicle_type&.name
+
+      parts = [origin, destination].compact_blank.join(' → ')
+      vehicle.present? ? "#{parts} (#{vehicle})" : parts
+    end
+
+    def taxi_departure_text(line_item)
+      return nil unless line_item.date_present?
+
+      line_item.from_date.strftime('%b %d, %Y · %H:%M')
+    end
+
+    def nationality_text
+      values = order.saved_guests.map { |sg| sg.nationality&.name.presence || sg.nationality_group&.humanize }.compact.uniq
+      return nil if values.empty?
+
+      values.join(', ')
+    end
+
+    def append_intercity_taxi_footer(text)
+      text << "Nationality: #{nationality_text}" if nationality_text.present?
+
+      pickup = selected_line_items.filter_map(&:pickup_map_place).first
+      dropoff = selected_line_items.filter_map(&:dropoff_map_place).first
+
+      append_map_place(text, '📍 Pick-up Location', pickup) if pickup
+      append_map_place(text, '📍 Drop-off Location', dropoff) if dropoff
+
+      remark = selected_line_items.filter_map { |li| li.remark.presence }.first
+      return if remark.blank?
+
+      text << ''
+      text << bold('🗒️ Notes to Driver')
+      text << ERB::Util.html_escape(remark)
+    end
+
+    def append_map_place(text, title, map_place)
+      text << ''
+      text << bold(title)
+      text << "Address: #{ERB::Util.html_escape(map_place.place_name)}" if map_place.place_name.present?
+      text << "Google Maps: #{ERB::Util.html_escape(google_maps_link(map_place))}" if google_maps_link(map_place).present?
+    end
+
+    def google_maps_link(map_place)
+      return nil if map_place.lat.blank? || map_place.lng.blank?
+
+      "https://www.google.com/maps/search/?api=1&query=#{map_place.lat},#{map_place.lng}"
+    end
   end
 end

data/app/finders/spree_cm_commissioner/accommodations/find.rb

@@ -13,11 +13,11 @@ module SpreeCmCommissioner
       def execute
         scope
           .where(default_state_id: state_id)
-          .where(inventory_items: { inventory_date: stay_dates })
-          .where('CAST(spree_variants.public_metadata->\'cm_options\'->>\'number-of-adults\' AS INTEGER) +
-                  CAST(spree_variants.public_metadata->\'cm_options\'->>\'number-of-kids\' AS INTEGER) >= ?', number_of_guests
+          .where('spree_variants.track_inventory = FALSE OR cm_inventory_items.inventory_date BETWEEN ? AND ?', from_date, to_date)
+          .where('spree_variants.track_inventory = FALSE OR cm_inventory_items.quantity_available > 0')
+          .where('COALESCE(CAST(spree_variants.public_metadata->\'cm_options\'->>\'number-of-adults\' AS INTEGER), 0) +
+                  COALESCE(CAST(spree_variants.public_metadata->\'cm_options\'->>\'number-of-kids\' AS INTEGER), 0) >= ?', number_of_guests
           )
-          .where('inventory_items.quantity_available > 0')
           .distinct
       end
 
@@ -25,7 +25,8 @@ module SpreeCmCommissioner
 
       def scope
         Spree::Vendor
-          .joins(variants: :inventory_items)
+          .joins(products: :variants)
+          .joins('LEFT OUTER JOIN cm_inventory_items ON cm_inventory_items.variant_id = spree_variants.id')
           .where(primary_product_type: :accommodation, state: :active)
       end
 

data/app/finders/spree_cm_commissioner/inventory_items/recently_changed_finder.rb

@@ -1,11 +1,11 @@
 module SpreeCmCommissioner
   module InventoryItems
     class RecentlyChangedFinder
-      def initialize(time_range: 7.days.ago, limit: 1000, vendor_id: nil, filter_type: 'all')
+      def initialize(time_range: 7.days.ago, limit: 1000, vendor_id: nil, product_type: nil)
         @time_range = time_range
         @limit = limit
         @vendor_id = vendor_id
-        @filter_type = filter_type
+        @product_type = product_type
       end
 
       # Finds recently changed items with Redis comparison
@@ -22,13 +22,15 @@ module SpreeCmCommissioner
 
       def fetch_recent_items
         query = SpreeCmCommissioner::InventoryItem.active
-                                                  .where('cm_inventory_items.updated_at > ?', @time_range)
                                                   .joins(variant: :product)
+                                                  .where(spree_variants: { track_inventory: true })
+                                                  .where('cm_inventory_items.updated_at > ?', @time_range)
                                                   .select(
                                                     'cm_inventory_items.id',
                                                     'cm_inventory_items.variant_id',
                                                     'cm_inventory_items.inventory_date',
                                                     'cm_inventory_items.quantity_available',
+                                                    'cm_inventory_items.quantity_on_hold',
                                                     'cm_inventory_items.updated_at',
                                                     'cm_inventory_items.product_type',
                                                     'spree_variants.sku',
@@ -36,16 +38,7 @@ module SpreeCmCommissioner
                                                     'spree_products.slug as product_slug'
                                                   )
 
-        # Apply filter_type at query level
-        query = case @filter_type
-                when 'permanent'
-                  query.where(cm_inventory_items: { inventory_date: nil })
-                when 'non_permanent'
-                  query.where.not(cm_inventory_items: { inventory_date: nil })
-                else
-                  query
-                end
-
+        query = query.where(cm_inventory_items: { product_type: @product_type }) if @product_type.present?
         query = query.where(spree_variants: { vendor_id: @vendor_id }) if @vendor_id.present?
 
         query.limit(@limit).order('cm_inventory_items.updated_at DESC')
@@ -55,34 +48,51 @@ module SpreeCmCommissioner
       def fetch_quantity_in_redis_batch(items)
         return [] if items.empty?
 
-        keys = items.map { |item| "inventory:#{item.id}" }
+        stock_keys = items.map(&:redis_key)
+        hold_keys = items.map(&:redis_hold_key)
+        all_keys = stock_keys + hold_keys
 
         # Use mget for efficient batch Redis fetch
-        quantity_in_redis_array = SpreeCmCommissioner.inventory_redis_pool.with do |redis|
-          redis.mget(*keys)
+        all_values = SpreeCmCommissioner.inventory_redis_pool.with do |redis|
+          redis.mget(*all_keys)
         end
 
+        quantity_in_redis_array = all_values.first(items.length)
+        on_hold_in_redis_array = all_values.last(items.length)
+
         # Combine with DB data
         items.each_with_index.map do |item, index|
-          quantity_in_redis = quantity_in_redis_array[index]&.to_i
-          quantity_available = item.quantity_available
-
-          {
-            inventory_item_id: item.id,
-            variant_id: item.variant_id,
-            product_name: item.product_name,
-            product_slug: item.product_slug,
-            sku: item.sku,
-            inventory_date: item.inventory_date,
-            quantity_available: quantity_available,
-            quantity_in_redis: quantity_in_redis,
-            difference: quantity_in_redis ? (quantity_in_redis - quantity_available) : nil,
-            out_of_sync: quantity_in_redis.nil? || quantity_in_redis != quantity_available,
-            last_updated: item.updated_at,
-            product_type: item.product_type
-          }
+          build_item_hash(item, index, quantity_in_redis_array, on_hold_in_redis_array)
         end
       end
+
+      def build_item_hash(item, index, quantity_in_redis_array, on_hold_in_redis_array)
+        quantity_in_redis = quantity_in_redis_array[index]&.to_i
+        quantity_available = item.quantity_available
+        on_hold_in_redis = on_hold_in_redis_array[index]&.to_i
+        quantity_on_hold = item.quantity_on_hold
+
+        # for :out_of_sync, :on_hold_out_of_sync => nil quantity does mean no data on redis,
+        # but does not necessarily mean it's out of sync
+        {
+          inventory_item_id: item.id,
+          variant_id: item.variant_id,
+          product_name: item.product_name,
+          product_slug: item.product_slug,
+          sku: item.sku,
+          inventory_date: item.inventory_date,
+          quantity_available: quantity_available,
+          quantity_in_redis: quantity_in_redis,
+          difference: quantity_in_redis ? (quantity_in_redis - quantity_available) : nil,
+          out_of_sync: !quantity_in_redis.nil? && quantity_in_redis != quantity_available,
+          quantity_on_hold: quantity_on_hold,
+          on_hold_in_redis: on_hold_in_redis,
+          on_hold_difference: on_hold_in_redis ? (on_hold_in_redis - quantity_on_hold) : nil,
+          on_hold_out_of_sync: !on_hold_in_redis.nil? && on_hold_in_redis != quantity_on_hold,
+          last_updated: item.updated_at,
+          product_type: item.product_type
+        }
+      end
     end
   end
 end

data/app/helpers/spree_cm_commissioner/admin/homepage_segment_helper.rb

@@ -15,8 +15,6 @@ module SpreeCmCommissioner
           'badge badge-success text-uppercase'
         when :football
           'badge badge-dark text-uppercase'
-        when :show
-          'badge badge-danger text-uppercase'
         else
           'badge'
         end

data/app/jobs/spree_cm_commissioner/inventory_holds/bulk_release_stale_job.rb

@@ -0,0 +1,11 @@
+module SpreeCmCommissioner
+  module InventoryHolds
+    class BulkReleaseStaleJob < SpreeCmCommissioner::ApplicationJob
+      queue_as :inventory_hold
+
+      def perform
+        SpreeCmCommissioner::InventoryHolds::BulkReleaseStale.call!
+      end
+    end
+  end
+end

data/app/jobs/spree_cm_commissioner/inventory_holds/bulk_release_stale_payment_locked_job.rb

@@ -0,0 +1,11 @@
+module SpreeCmCommissioner
+  module InventoryHolds
+    class BulkReleaseStalePaymentLockedJob < SpreeCmCommissioner::ApplicationJob
+      queue_as :inventory_hold
+
+      def perform
+        SpreeCmCommissioner::InventoryHolds::BulkReleaseStalePaymentLocked.call!
+      end
+    end
+  end
+end

data/app/jobs/spree_cm_commissioner/inventory_holds/release_job.rb

@@ -0,0 +1,29 @@
+module SpreeCmCommissioner
+  module InventoryHolds
+    # Primary release for :active holds. Scheduled at hold creation (wait_until: expires_at).
+    # Safety net: BulkReleaseStaleJob catches any active holds this job misses.
+    class ReleaseJob < SpreeCmCommissioner::ApplicationJob
+      queue_as :inventory_hold
+
+      def perform(options = {})
+        hold = SpreeCmCommissioner::InventoryHold.find(options[:hold_id])
+
+        # Skip if already finalized (e.g. delayed or retried jobs).
+        # The release service also enforces idempotency.
+        return if hold.finalized?
+
+        # When LockForPayment runs (triggered on payment creation), the hold transitions
+        # to :payment_locked status. ReleaseJob must not touch those holds —
+        # BulkReleaseStalePaymentLockedJob (cron) is the sole cleanup mechanism for them,
+        # allowing future custom logic (e.g. extend instead of release when payments exist).
+        return if hold.payment_locked?
+
+        SpreeCmCommissioner::InventoryHolds::Release.call!(
+          hold: hold,
+          reason: :hold_expired,
+          scheduled_release: true
+        )
+      end
+    end
+  end
+end