spree_cm_commissioner 2.10.0 → 2.10.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6d59a44e1e25ec19ab8c634622f91006ea28bec265ea877dad8565cffa54bad3
-  data.tar.gz: 43415e8984f459f0387e110707963f4685c92251f589a2301342f82783c4e714
+  metadata.gz: 34524289f2fc489da23a30fcaca4bfcdac167a60b0efd382368efda96433e4d9
+  data.tar.gz: 47cd7bcb029126c27c0dd1c7081f26b8a217e740be768662f59a208a0e440ad6
 SHA512:
-  metadata.gz: 1fbfc67d4bc18eb071d854b643ef3bfbaf1312b75f5c241020d58b09855ee234a58064ce08a104ee856b48dec25ce8547ad9c442cbd2648c83ad350c04fec3e1
-  data.tar.gz: 53317e748ac053ed6b60ec7e9accdd915266aa6b3e547692865191868d6051693dcad05dee73bed5e196b027fc27436e72fba2c62e05b3b33f806a7558618cf9
+  metadata.gz: 134f803e39f5fce95401a2404cf6f559baf6997651440578767022cc9c7c4ddf1368da4b16ec12b096753569794593a03a8ace0ac1522fab107a0ae57b09db04
+  data.tar.gz: d8401ff0a245a5429919380ffc56412e2a09614fe82a78bef24f2e90ff54d88feb885ea0bb78993d2f45e9e7cc6a294958642290e53f8ea41650fc3ca4652759

data/Gemfile.lock

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

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

@@ -5,10 +5,17 @@ module Spree
         base.before_action :build_logo, only: %i[create update]
         base.before_action :build_payment_qrcode, only: %i[create update]
         base.before_action :contruct_nearby_place, only: %i[create update]
+        base.before_action :compact_sellable_product_types, only: %i[create update]
       end
 
       private
 
+      def compact_sellable_product_types
+        return unless permitted_resource_params.key?(:sellable_product_types)
+
+        permitted_resource_params[:sellable_product_types] = permitted_resource_params[:sellable_product_types].compact_blank
+      end
+
       def contruct_nearby_place
         return unless permitted_resource_params.key?(:nearby_places_attributes)
 

data/app/errors/spree_cm_commissioner/reserved_blocks/locked_by_operator_error.rb

@@ -0,0 +1,25 @@
+module SpreeCmCommissioner
+  module ReservedBlocks
+    # Raised when a customer tries to hold or reserve a seat an operator has taken off sale.
+    #
+    # The customer-facing message deliberately says only "not available" — it must not leak the
+    # operator's reason (e.g. "held for staff"), which lives in private_metadata.
+    class LockedByOperatorError < StandardError
+      attr_reader :block_label
+
+      def initialize(block_label = nil)
+        @block_label = block_label
+        super()
+      end
+
+      # override
+      def message
+        if block_label.present?
+          I18n.t('line_item.validation.blocks_are_locked_by_operator_with_label', label: block_label)
+        else
+          I18n.t('line_item.validation.blocks_are_locked_by_operator')
+        end
+      end
+    end
+  end
+end

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

@@ -15,8 +15,8 @@ module SpreeCmCommissioner
           .joins(:inventory_items)
           .where(vendor_id: vendor_id)
           .where(inventory_items: { inventory_date: stay_dates })
-          .where('CAST(public_metadata->\'cm_options\'->>\'number-of-adults\' AS INTEGER) +
-                  CAST(public_metadata->\'cm_options\'->>\'number-of-kids\' AS INTEGER) >= ?', number_of_guests
+          .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('inventory_items.quantity_available > 0')
           .distinct

data/app/jobs/spree_cm_commissioner/async_operation_job.rb

@@ -0,0 +1,27 @@
+module SpreeCmCommissioner
+  # Runs any AsyncOperation subclass. Same shape as ExportJob: load the record, call the one method the
+  # subclass implements.
+  #
+  # ApplicationJob, not ApplicationUniqueJob: `unique :until_executed` keys on the job arguments, and
+  # those carry a per-record id, so uniqueness could never collide -- it would buy a Redis lock for
+  # nothing. The in_progress? guard below is what actually makes a duplicate enqueue a no-op.
+  class AsyncOperationJob < ApplicationJob
+    queue_as :default
+
+    def perform(options = {})
+      operation = SpreeCmCommissioner::AsyncOperation.find_by(id: options[:async_operation_id])
+      return if operation.blank?
+
+      # Guard on `done` only, not on "not in progress". An exception below marks the operation failed and
+      # re-raises so Sidekiq retries -- guarding on in_progress? would make every one of those retries
+      # return here immediately, which is the opposite of retrying. Completed work is the thing that must
+      # never run twice; a failed operation is exactly what a retry is for.
+      return if operation.done?
+
+      operation.process!
+    rescue StandardError => e
+      operation&.fail!(e.message)
+      raise # ApplicationJob logs it; Sidekiq retries; Sentry captures.
+    end
+  end
+end

data/app/jobs/spree_cm_commissioner/ticket_transfers/expire_job.rb

@@ -0,0 +1,29 @@
+module SpreeCmCommissioner
+  module TicketTransfers
+    class ExpireJob < ApplicationJob
+      # Same window as OrderHolds::LockForPayment — gives an in-flight gateway
+      # redirect/webhook (e.g. PayWay, ACLEDA) room to resolve before we retry.
+      RETRY_DELAY = ENV.fetch('PAYMENT_LOCK_MIN_DURATION_IN_MINUTES', '5').to_i.minutes
+      MAX_RETRIES = 1
+      UNRESOLVED_PAYMENT_STATES = %w[checkout pending processing].freeze
+
+      def perform(transfer_id, attempt = 0)
+        ticket_transfer = SpreeCmCommissioner::TicketTransfer.find_by(id: transfer_id)
+        return unless ticket_transfer
+
+        if payment_in_progress?(ticket_transfer) && attempt < MAX_RETRIES
+          self.class.set(wait: RETRY_DELAY).perform_later(transfer_id, attempt + 1)
+          return
+        end
+
+        SpreeCmCommissioner::TicketTransfers::Expire.call(ticket_transfer: ticket_transfer)
+      end
+
+      private
+
+      def payment_in_progress?(ticket_transfer)
+        ticket_transfer.order&.payments&.where(state: UNRESOLVED_PAYMENT_STATES)&.exists? || false
+      end
+    end
+  end
+end

data/app/jobs/spree_cm_commissioner/voting_session_auto_close_job.rb

@@ -0,0 +1,22 @@
+module SpreeCmCommissioner
+  # Flips the Firestore `state` to closed once a manually-started vote window elapses.
+  #
+  # Enqueued by VotingSessionTimingConcern#start_vote! with wait_until: vote_close_at. Vote
+  # rejection does not depend on this job — can_vote? already gates on the persisted
+  # vote_close_at — so a missed run costs a stale label in the app, never an accepted late vote.
+  class VotingSessionAutoCloseJob < ApplicationJob
+    queue_as :default
+
+    def perform(voting_session_id)
+      voting_session = SpreeCmCommissioner::VotingSession.find_by(id: voting_session_id)
+      return if voting_session.nil?
+
+      # vote_close_at may have moved since this was scheduled (a restart, or the organizer
+      # pressing Stop Vote and starting a new window). Only publish once the window has genuinely
+      # elapsed; otherwise the run that matches the new vote_close_at will handle it.
+      return if voting_session.vote_close_at.present? && Time.current < voting_session.vote_close_at
+
+      SpreeCmCommissioner::VotingSessions::PublishToFirestore.call(voting_session: voting_session)
+    end
+  end
+end

data/app/jobs/spree_cm_commissioner/voting_session_firestore_publish_job.rb

@@ -0,0 +1,18 @@
+module SpreeCmCommissioner
+  # Pushes a voting session's live state to Firestore off the request cycle, so an organizer
+  # pressing "Start Vote" never waits on a Firestore round-trip.
+  #
+  # Takes an id rather than the record so a retry publishes the state as it is *now*, not as it
+  # was when the job was enqueued — a rapid start/pause/stop sequence must not have a stale
+  # retry overwrite the current state.
+  class VotingSessionFirestorePublishJob < ApplicationJob
+    queue_as :default
+
+    def perform(voting_session_id)
+      voting_session = SpreeCmCommissioner::VotingSession.find_by(id: voting_session_id)
+      return if voting_session.nil?
+
+      SpreeCmCommissioner::VotingSessions::PublishToFirestore.call(voting_session: voting_session)
+    end
+  end
+end

data/app/models/concerns/spree_cm_commissioner/firestore_connection.rb

@@ -0,0 +1,27 @@
+require 'google/cloud/firestore'
+
+module SpreeCmCommissioner
+  # Shared Cloud Firestore client construction.
+  #
+  # The waiting-room services each inline this same pair (see WaitingGuestsCaller#firestore);
+  # this concern is the extracted version for new writers, plus a #firestore_available? guard so
+  # environments without the credential (dev, test, CI) no-op instead of raising on connect.
+  module FirestoreConnection
+    extend ActiveSupport::Concern
+
+    def firestore_available?
+      service_account.present?
+    end
+
+    def firestore
+      @firestore ||= Google::Cloud::Firestore.new(
+        project_id: service_account[:project_id],
+        credentials: service_account
+      )
+    end
+
+    def service_account
+      @service_account ||= Rails.application.credentials.cloud_firestore_service_account
+    end
+  end
+end

data/app/models/concerns/spree_cm_commissioner/ticket_transferable.rb

@@ -11,5 +11,16 @@ module SpreeCmCommissioner
     def ticket_transfer?
       channel == SpreeCmCommissioner::OrderDecorator::TICKET_TRANSFER_CHANNEL
     end
+
+    # Completes an accepted ticket transfer for this order. Called from
+    # Spree::Payment#after_completed, so the buyer's payment is already captured.
+    def complete_ticket_transfer_if_ready
+      return unless ticket_transfer?
+
+      transfer = ticket_transfer
+      return if transfer.blank? || !transfer.accepted?
+
+      SpreeCmCommissioner::TicketTransfers::Complete.call(ticket_transfer: transfer)
+    end
   end
 end

data/app/models/concerns/spree_cm_commissioner/voting_session_config_concern.rb

@@ -0,0 +1,87 @@
+module SpreeCmCommissioner
+  # The fraud_config/voting_config JSON stores and their derived, show-inheriting accessors.
+  # Extracted purely to keep VotingSession under RuboCop's Metrics/ClassLength — no behavior
+  # here depends on anything else in the concern split (unlike VotingSessionTimingConcern, whose
+  # enum/predicate ordering matters).
+  module VotingSessionConfigConcern
+    extend ActiveSupport::Concern
+
+    included do
+      store_accessor :fraud_config,
+                     :max_votes_per_minute_per_user,
+                     :max_votes_per_minute_per_ip,
+                     :max_accounts_per_device,
+                     :block_vpn,
+                     :max_votes_per_contestant_per_user
+
+      store_accessor :voting_config,
+                     :free_vote_limit,
+                     :free_vote_limit_type,
+                     :allow_user_to_get_free_vote,
+                     :paid_vote_enabled,
+                     :max_paid_votes_per_session,
+                     :sms_vote_enabled,
+                     :sms_vote_cost_usd,
+                     :operator_vote_enabled,
+                     :votes_weight,
+                     :voters_weight,
+                     :suggestion_top_n,
+                     :pre_vote_weight
+
+      validate :weights_present_for_weighted_sum
+    end
+
+    DEFAULT_SUGGESTION_TOP_N = 1
+
+    def effective_suggestion_top_n
+      suggestion_top_n&.to_i&.positive? ? suggestion_top_n.to_i : DEFAULT_SUGGESTION_TOP_N
+    end
+
+    def effective_voting_config
+      return {} unless show
+
+      config = parse_json_config(voting_config)
+      show_config = show.effective_voting_config
+      config.reverse_merge(show_config || {})
+    end
+
+    def effective_fraud_config
+      return {} unless show
+
+      config = parse_json_config(fraud_config)
+      show_config = show.effective_fraud_config
+      config.reverse_merge(show_config || {})
+    end
+
+    def max_votes_per_user
+      effective_voting_config['max_votes_per_user'] || 10
+    end
+
+    def rate_limit_window
+      effective_voting_config['rate_limit_window'] || 60
+    end
+
+    def rate_limit_max_votes
+      effective_voting_config['rate_limit_max_votes'] || 5
+    end
+
+    private
+
+    def weights_present_for_weighted_sum
+      return unless weighted_sum?
+
+      config = effective_voting_config
+      errors.add(:votes_weight, :blank) if config['votes_weight'].blank?
+      errors.add(:voters_weight, :blank) if config['voters_weight'].blank?
+    end
+
+    def parse_json_config(value)
+      return {} if value.nil? || value == ''
+      return value if value.is_a?(Hash)
+
+      JSON.parse(value)
+    rescue JSON::ParserError
+      {}
+    end
+  end
+end

data/app/models/concerns/spree_cm_commissioner/voting_session_timing_concern.rb

@@ -0,0 +1,137 @@
+module SpreeCmCommissioner
+  # How a voting session's vote window (vote_open_at/vote_close_at) gets its values, kept
+  # deliberately separate from opens_at/closes_at — the show's own time slot within its episode
+  # (an episode can span many voting sessions, e.g. one per day of a week-long run), which has
+  # nothing to do with when voting is actually open.
+  #
+  # There is no mode flag: the presence of vote_open_at/vote_close_at is the signal.
+  #
+  #   Pre-set at creation  — auto-activates: once #activate flips status to enabled, can_vote?
+  #                          just compares Time.current against the already-real timestamps.
+  #   Left blank           — #start_vote! rewrites them to now / now + vote_duration_seconds the
+  #                          moment the organizer presses it, live during the broadcast.
+  #
+  # Both paths start at status: archived and reach enabled through one of two routes:
+  #
+  #   archived --(check "Visible")--> on_air --#start_vote!--> enabled  (progressive reveal, then vote)
+  #   archived ------------------------------#start_vote!--> enabled     (reveal and vote in one click)
+  #
+  # There is no separate "reveal" action: setting visible: true while archived (from the organizer
+  # dashboard's edit form) *is* the reveal — see #promote_from_archived_when_made_visible, which
+  # auto-transitions status to on_air in the same write rather than rejecting the attempt. on_air
+  # exists specifically so a session can show its contestants one by one — in sync with a live
+  # performance — before voting opens; it is visible but never votable (status isn't enabled, so
+  # can_vote? is false regardless of vote_open_at).
+  module VotingSessionTimingConcern
+    extend ActiveSupport::Concern
+
+    included do
+      validates :vote_duration_seconds, numericality: { greater_than: 0 }, allow_nil: true
+      validate :vote_closes_after_vote_opens
+
+      # before_update, not before_save: the `visible` column defaults to true at the DB level, so
+      # a brand-new record saved with the default status: archived (see
+      # ParamsConcern#force_archived_status_on_create, which explicitly sets visible: false too)
+      # must never auto-promote itself on its first save just because it hasn't touched `visible`
+      # yet — "reveal" is something an organizer does to an *existing* archived session.
+      before_update :promote_from_archived_when_made_visible
+      after_commit :publish_live_state_to_firestore, on: %i[create update], if: :live_state_changed?
+
+      scope :visible, -> { where(visible: true) }
+    end
+
+    # Columns the show screen renders. `display` is included because hiding a session should
+    # disappear from the app as promptly as opening one appears.
+    LIVE_STATE_COLUMNS = %w[status opens_at closes_at vote_open_at vote_close_at display visible].freeze
+
+    # Opens the vote window *now* rather than at a pre-set time, overriding whatever vote_open_at
+    # already held (a live show running early is exactly when this gets pressed). visible: true is
+    # set explicitly so this also works when called directly from archived — revealing and opening
+    # voting in one click, without going through on_air first.
+    def start_vote!
+      now = Time.current
+      update!(
+        vote_open_at: now,
+        vote_close_at: now + vote_duration_seconds.to_i.seconds,
+        status: :enabled,
+        visible: true
+      )
+
+      SpreeCmCommissioner::VotingSessionAutoCloseJob.set(wait_until: vote_close_at).perform_later(id)
+    end
+
+    # Ends the vote window immediately and moves to closed. status: closed (not just a rewritten
+    # vote_close_at) matters for two reasons: votes are rejected the instant this runs, since
+    # can_vote? short-circuits on enabled? before ever comparing timestamps — no dependency on the
+    # inclusive Time#between? boundary at vote_close_at; and it's what triggers
+    # schedule_counter_reconciliation (only fires on saved_change_to_status?(enabled -> closed)),
+    # which would otherwise only run via the separate "Close" action, never on a manual stop.
+    #
+    # vote_close_at clamped to vote_open_at + 1s: an organizer who starts and immediately stops
+    # would otherwise produce vote_close_at == vote_open_at, which the closes-after-opens
+    # validation rejects — a validation error on what is a legitimate "cancel that" action.
+    def stop_vote!
+      opened_at = vote_open_at || Time.current
+      update!(status: :closed, vote_close_at: [Time.current, opened_at + 1.second].max)
+    end
+
+    # True when voting hasn't opened yet — either vote_open_at was never set, it's set but its
+    # time hasn't arrived, or status is on_air. The on_air check matters on its own: on_air can be
+    # revisited after a prior round already closed (an organizer reverting status by hand to
+    # re-reveal), in which case vote_open_at/vote_close_at are still populated from that earlier
+    # round and both in the past — without this, the timestamp check alone would say the window
+    # isn't pending, and Firestore's state_for would wrongly report 'closed' for a session that's
+    # actually on_air right now. Covers "never started," "pre-scheduled but not live yet," and
+    # "on_air again after a previous round" identically, since none of them is votable nor has a
+    # real countdown to show.
+    def vote_window_pending?
+      on_air? || vote_open_at.blank? || Time.current < vote_open_at
+    end
+
+    # Shifts vote_close_at by `seconds` (organizer-chosen at the moment, not necessarily
+    # vote_duration_seconds) without touching vote_open_at — distinct from #start_vote!, which
+    # would discard the time already elapsed by resetting the window to start now.
+    #
+    # Extends from max(vote_close_at, Time.current), not from the raw stored value: the
+    # controller also offers this once a window has already lapsed (status still enabled, nothing
+    # auto-flipped it to closed yet) specifically to reopen it. Adding straight to a stale
+    # vote_close_at sitting hours in the past would land the new value in the past too — "+10
+    # minutes" on a session that closed last night must mean 10 minutes from now, not 10 minutes
+    # from when it closed.
+    #
+    # `seconds` may be negative to cut a currently-open window short without a full Stop Vote;
+    # going negative enough to land at or before vote_open_at raises via the closes-after-opens
+    # validation.
+    def extend_vote!(seconds)
+      update!(vote_close_at: [vote_close_at, Time.current].max + seconds.to_i.seconds)
+
+      SpreeCmCommissioner::VotingSessionAutoCloseJob.set(wait_until: vote_close_at).perform_later(id)
+    end
+
+    private
+
+    # archived sessions are prepped privately by default (visible starts false), but the organizer
+    # controls visibility directly from the edit form — checking "Visible to Viewers" while
+    # archived is the reveal action, not a separate button. Rather than rejecting that write, treat
+    # it as intent: promote status to on_air in the same save, so the session actually becomes
+    # reachable via the `current` scope (which never includes plain `archived`, regardless of
+    # `visible`). Setting visible: false while archived is a no-op — status simply stays archived.
+    def promote_from_archived_when_made_visible
+      self.status = 'on_air' if archived? && visible?
+    end
+
+    def vote_closes_after_vote_opens
+      return unless vote_open_at && vote_close_at
+
+      errors.add(:vote_close_at, :must_be_after_vote_opens_at) if vote_close_at <= vote_open_at
+    end
+
+    def live_state_changed?
+      LIVE_STATE_COLUMNS.any? { |column| saved_change_to_attribute?(column) }
+    end
+
+    def publish_live_state_to_firestore
+      SpreeCmCommissioner::VotingSessionFirestorePublishJob.perform_later(id)
+    end
+  end
+end

data/app/models/spree_cm_commissioner/async_operation.rb

@@ -0,0 +1,73 @@
+module SpreeCmCommissioner
+  # A long-running operation a human started and is waiting on the result of, with a status an admin
+  # screen can poll: queue -> progress -> done | failed.
+  #
+  # SCOPE RULE: operations a person initiated and is watching. Not webhook deliveries, not per-order
+  # background work, not general job logging.
+  #
+  # That rule is what keeps this table small enough to need no retention policy -- admin actions are rare,
+  # and the rows are a few hundred bytes of jsonb. cm_exports, the table this is modelled on, has grown
+  # unpruned while storing actual files. If a future subclass ever puts high-volume work here, add a
+  # purge alongside cleanup_integration_sync_sessions in config/schedule.yml; the
+  # [type, status, created_at] index exists to serve exactly that query.
+  #
+  # Subclasses supply their own payload/result keys via store_*_metadata and implement #process!.
+  # See AsyncOperations::SeatLock.
+  class AsyncOperation < Base
+    include SpreeCmCommissioner::StoreMetadata
+
+    belongs_to :operable, polymorphic: true, optional: true
+    belongs_to :user, optional: true, class_name: 'Spree::User'
+
+    enum status: { queue: 0, progress: 1, done: 2, failed: 3 }
+
+    # :text, not :string. StoreMetadata attaches `length: { maximum: 255 }` to every :string key, so a
+    # long exception message would fail validation inside the failure handler and bury the real error.
+    store_private_metadata :error, :text
+
+    ERROR_LIMIT = 1000
+
+    # after_create_commit, not after_create: Sidekiq can dequeue faster than the enclosing transaction
+    # commits, and the job would then find no row and silently drop the operation.
+    after_create_commit :enqueue
+
+    # Subclasses may override to pick a different queue or a dedicated job.
+    def enqueue
+      SpreeCmCommissioner::AsyncOperationJob.perform_later(async_operation_id: id)
+    end
+
+    def in_progress?
+      queue? || progress?
+    end
+
+    # Heartbeat, not wall clock. A running operation touches the row as it accumulates results, so real
+    # work never looks stale while a killed worker does. Without this the admin panel spins forever.
+    def stale?
+      in_progress? && updated_at < timeout.ago
+    end
+
+    def timeout
+      20.minutes
+    end
+
+    def start!
+      update!(status: :progress, started_at: Time.current)
+    end
+
+    def finish!
+      update!(status: :done, finished_at: Time.current)
+    end
+
+    # save(validate: false), not update!: this runs from a rescue block, so a subclass validation failing
+    # here would raise a second exception and bury the original. Recording a failure must not be able to
+    # fail.
+    def fail!(message)
+      assign_attributes(status: :failed, finished_at: Time.current, error: message.to_s.truncate(ERROR_LIMIT))
+      save(validate: false)
+    end
+
+    def process!
+      raise NotImplementedError, 'Subclasses must implement #process!'
+    end
+  end
+end

data/app/models/spree_cm_commissioner/async_operations/seat_lock.rb

@@ -0,0 +1,76 @@
+module SpreeCmCommissioner
+  module AsyncOperations
+    # One operator submission of the "Lock Seats" drawer.
+    #
+    # Stores the DESIRED state (which seats should end up locked across which dates), not a diff. The diff
+    # against what is currently locked is computed by Seats::ApplyLocks at perform time, so it works from
+    # fresh data rather than a snapshot taken when the drawer was rendered.
+    class SeatLock < SpreeCmCommissioner::AsyncOperation
+      # Everything private: why a seat is off sale is operator-internal, same rule as ReservedBlock.
+      store_private_metadata :block_ids, :array, default: []
+      store_private_metadata :selections, :array, default: [] # ["512:2026-08-08", ...]
+      store_private_metadata :lock_reason, :string
+      store_private_metadata :lock_note, :text
+
+      store_private_metadata :locked_count, :integer, default: 0
+      store_private_metadata :unlocked_count, :integer, default: 0
+      store_private_metadata :skipped_summary, :hash, default: {} # { reason => count }
+      store_private_metadata :skipped_samples, :array, default: [] # [{ date:, block_label:, reason: }]
+
+      # Skips are summarised rather than listed. each_block_date emits a :no_inventory skip for every pair
+      # with no inventory item, so an ordinary action -- 31 dates selected where only 10 have inventory,
+      # 40 seats -- produces 840 entries. A reason->count hash plus a small sample is both a row that
+      # stays small and the only version an operator can actually read.
+      SKIPPED_SAMPLE_LIMIT = 20
+
+      alias_attribute :trip, :operable
+
+      def process!
+        SpreeCmCommissioner::Seats::ApplyLocks.call!(operation: self)
+      end
+
+      def skipped_count
+        skipped_summary.values.sum(&:to_i)
+      end
+
+      def any_skips?
+        skipped_count.positive?
+      end
+
+      # One UPDATE per service call rather than per seat-date. Doubles as the stale? heartbeat, so a long
+      # run never looks like a dead worker.
+      #
+      # Reassigns every jsonb-backed value: ActiveRecord::Store does not dirty-track in-place mutation,
+      # so `skipped_samples << x` would be silently lost on save.
+      def track!(locked: 0, unlocked: 0, skips: [])
+        # Stringify once, on the way in. The services hand over symbol-keyed hashes but jsonb round-trips
+        # them to string keys, so without this the same record reads differently before and after a
+        # reload -- and every consumer would have to check both.
+        entries = skips.map { |skip| skip.transform_keys(&:to_s) }
+
+        self.locked_count = locked_count + locked
+        self.unlocked_count = unlocked_count + unlocked
+        self.skipped_summary = merge_skipped_summary(entries)
+        self.skipped_samples = (skipped_samples + sample_room(entries)).first(SKIPPED_SAMPLE_LIMIT)
+
+        save!
+      end
+
+      private
+
+      def merge_skipped_summary(entries)
+        entries.each_with_object(skipped_summary.dup) do |skip, acc|
+          reason = skip['reason'].to_s
+          acc[reason] = acc[reason].to_i + 1
+        end
+      end
+
+      def sample_room(entries)
+        room = SKIPPED_SAMPLE_LIMIT - skipped_samples.size
+        return [] if room <= 0
+
+        entries.first(room)
+      end
+    end
+  end
+end

data/app/models/spree_cm_commissioner/block.rb

@@ -28,6 +28,10 @@ module SpreeCmCommissioner
     validate :cannot_unassign_variant_with_active_blocks
 
     before_validation :assign_layout_from_section, if: -> { seat_layout.nil? && seat_section.present? }
+    # `prepend: true` is essential. `has_many :all_reserved_blocks, dependent: :destroy` registers its
+    # own before_destroy at association-declaration time, which is above this line — so without
+    # prepending, the reserved blocks are destroyed first and this guard finds nothing left to object to.
+    before_destroy :cannot_destroy_with_locked_blocks, prepend: true
 
     def label_required?
       sellable? || %w[other text].include?(block_type.to_s)
@@ -55,18 +59,44 @@ module SpreeCmCommissioner
 
     private
 
+    # Deleting a seat would cascade into its locked rows, dropping the deduction without giving the
+    # quantity back. Unlock first.
+    #
+    # Only `locked` needs this: reserved/on_hold rows have a guest, and the cm_guests -> cm_blocks
+    # foreign key already refuses. Locked rows have no guest, so nothing below the model stops them.
+    #
+    # `throw :abort` because errors.add alone does not halt a destroy.
+    def cannot_destroy_with_locked_blocks
+      count = all_reserved_blocks.locked.count
+      return if count.zero?
+
+      errors.add(
+        :base,
+        "cannot be deleted because #{count} #{count == 1 ? 'seat is' : 'seats are'} locked by the operator"
+      )
+      throw :abort
+    end
+
     def cannot_unassign_variant_with_active_blocks
       return if variant_id_was.blank? || variant_id.present?
 
-      active_blocks = all_reserved_blocks.reserved_or_on_hold
+      # `unavailable` rather than `reserved_or_on_hold` so a variant carrying operator-locked seats
+      # cannot be unassigned either.
+      active_blocks = all_reserved_blocks.unavailable
       return unless active_blocks.exists?
 
       block_count = active_blocks.count
       block_statuses = active_blocks.pluck(:status).uniq.map { |s| s.humanize.downcase }
 
+      # "by guests" only when every blocker actually has one. `unavailable` includes `locked` rows,
+      # which belong to no guest, so keeping the suffix unconditionally would misdescribe the reason
+      # whenever an operator lock is among the blockers (on_hold/reserved still get "by guests").
+      by_guests = active_blocks.where.not(guest_id: nil).count == block_count
+
       errors.add(
         :variant,
-        "cannot be unassigned because #{block_count} #{block_count == 1 ? 'block is' : 'blocks are'} #{block_statuses.join(' and ')} by guests"
+        "cannot be unassigned because #{block_count} #{block_count == 1 ? 'block is' : 'blocks are'} " \
+        "#{block_statuses.join(' and ')}#{' by guests' if by_guests}"
       )
     end
   end