support_desk 0.2.0 → 0.3.2

data/lib/support_desk/models/ticket/assistance.rb

@@ -0,0 +1,899 @@
+# frozen_string_literal: true
+
+module SupportDesk
+  class Ticket
+    # Everything a case knows about its assistant: the turn, the policy
+    # gates, the two verbs that are hers alone (`respond!`, `draft!`), the
+    # two exits (`escalate!`, `request_human!`) and the human override
+    # (`pause_assistant!`).
+    #
+    # == The turn
+    #
+    # `assistant_revision` is an integer bumped by every registered message
+    # and every transition. `assistant_turn` is that integer, spelled as an
+    # opaque string, and EVERY assistant action requires it and consumes it:
+    #
+    #   turn = ticket.assistant_turn          # "t7-r12"
+    #   ticket.respond!(answer, by: rose, turn: turn)
+    #
+    # A model takes seconds to answer, and a customer can write again while
+    # it does. The turn is what makes that safe: the action is compared
+    # against the case's current revision under its row lock, and a late,
+    # retried or redelivered one raises SupportDesk::StaleTurn and writes
+    # nothing. It is also why there are no idempotency keys, claim rows or
+    # leases in this gem — one integer under the lock already answers "is
+    # this still the case you read?".
+    #
+    # == Gate the action, never the evidence
+    #
+    # Policy decides what she may PRODUCE. It never decides what a person can
+    # see: the transcript, the case, the queue and the door to a human are
+    # the same whatever the level, and a refusal is always a named reason on
+    # a record (an `assistant_withheld` event, a policy in a draft's
+    # metadata), never silence.
+    #
+    # == The locking protocol: TICKET, then CONVERSATION
+    #
+    # The turn is only as good as the reconciliation behind it, and
+    # reconciliation is a SELECT: on its own it cannot exclude a requester
+    # message that commits one millisecond later. The customer does not take
+    # the ticket lock — they press send, and chats writes a message.
+    #
+    # What chats DOES take is the conversation row. Every message insert
+    # updates `chats_conversations` inside its own transaction
+    # (`Chats::Message#register_on_conversation`, plus the `messages_count`
+    # counter cache), so that row is the serialization point for writes this
+    # gem does not own. Every speaking path therefore takes the ticket's row
+    # lock and then, before reconciling, the conversation's
+    # (`#lock_conversation!`):
+    #
+    # * a requester message already in flight holds that row, so we block
+    #   until it commits — and reconciliation then sees it, which makes the
+    #   turn stale, which is exactly what should happen;
+    # * a message that starts after we hold the row blocks until we commit,
+    #   so our answer is ordered before it and its own turn follows.
+    #
+    # THE ORDER IS ALWAYS TICKET → CONVERSATION. A requester write locks only
+    # the conversation; the after-commit subscriber's `register!` locks the
+    # ticket and then, through the system lines a hand-off posts, the
+    # conversation. Nothing takes them the other way round, and nothing new
+    # may.
+    #
+    # What it does NOT cover:
+    #
+    # * A message whose INSERT was already stamped when we win the row is
+    #   still stamped earlier than our answer, so a transcript can show a
+    #   question above an answer that did not address it. That is a genuinely
+    #   simultaneous send, and its registration raises a turn of its own.
+    #
+    # * SQLITE. All of the above is a `SELECT … FOR UPDATE` blocking a
+    #   concurrent writer, which is PostgreSQL and MySQL. SQLite has no row
+    #   locks: it serializes WRITES, and in WAL mode our reconciliation reads
+    #   the last committed snapshot straight through a requester's open write
+    #   transaction. So a message committing behind the SELECT is still
+    #   missed there, exactly as it was in 0.3.0 — the conversation row buys
+    #   nothing, because nothing waits on it. Run PostgreSQL or MySQL for a
+    #   production desk with an assistant; `doctor` warns about this.
+    module Assistance
+      extend ActiveSupport::Concern
+
+      included do
+        has_many :drafts, class_name: "SupportDesk::Draft", inverse_of: :ticket, dependent: :destroy
+        has_one :pending_draft, -> { pending }, class_name: "SupportDesk::Draft", inverse_of: :ticket
+
+        # --- Scopes -------------------------------------------------------------
+
+        scope :held_by_assistants, lambda {
+          where(assignee_type: SupportDesk::Assistant.polymorphic_name)
+        }
+        scope :held_by_humans, lambda {
+          assigned.where.not(assignee_type: SupportDesk::Assistant.polymorphic_name)
+        }
+        # The tab that exists so a case a machine could not finish is never
+        # the one nobody looks at.
+        scope :needs_human, -> { where.not(human_required_at: nil) }
+        scope :assistant_paused, -> { where.not(assistant_paused_at: nil) }
+        scope :assistant_capped, -> { where.not(assistant_cap: nil) }
+        scope :resolved_by_assistant, lambda {
+          closed.where(closed_by_type: SupportDesk::Assistant.polymorphic_name)
+        }
+        scope :with_pending_draft, -> { where(id: SupportDesk::Draft.pending.select(:ticket_id)) }
+        # Waiting on the desk since before +time+, with nothing from the
+        # assistant since the customer wrote: a harness that is down, or one
+        # that keeps deciding to do nothing.
+        scope :assistant_idle_since, lambda { |time|
+          awaiting_reply.where(last_requester_message_at: ..time)
+                        .where("assistant_acted_at IS NULL OR assistant_acted_at < last_requester_message_at")
+        }
+        # Cases whose conversation holds a requester message the gem never
+        # folded in. The registration runs after the message's commit, so it can
+        # be LOST — a killed worker, a dropped subscriber — and the clocks then
+        # describe a case that no longer exists: `awaiting_requester` on a case
+        # that is waiting for an answer, which no idle query can see. This one
+        # asks the messages instead of the clocks (R3).
+        #
+        # Built in Arel rather than as a string, because it compares two tables'
+        # columns to each other and there is no value to bind: it has to be
+        # readable as "no user input reaches this SQL" at a glance.
+        scope :with_unregistered_requester_messages, lambda {
+          tickets = arel_table
+          messages = Chats::Message.arel_table
+          receipts = MessageRegistration.arel_table
+          registered = MessageRegistration.select(Arel.sql("1"))
+                                          .where(receipts[:message_id].eq(messages[:id]))
+          unregistered = Chats::Message.select(Arel.sql("1"))
+                                       .where(kind: "text")
+                                       .where(messages[:conversation_id].eq(tickets[:conversation_id]))
+                                       .where(messages[:sender_type].eq(tickets[:requester_type]))
+                                       .where(messages[:sender_id].eq(tickets[:requester_id]))
+                                       .where(registered.arel.exists.not)
+          where(unregistered.arel.exists)
+        }
+      end
+
+      # --- Readers ------------------------------------------------------------------
+
+      # The assistant who works this case's desk, or nil.
+      def assistant = desk&.assistant
+
+      # What she may do here, right now, and why. See AssistantPolicy.
+      def assistant_policy(assistant = self.assistant, hand_back: false)
+        AssistantPolicy.for(self, assistant, hand_back: hand_back)
+      end
+
+      # The token every assistant action has to hold. Never nil: a case that
+      # has never been touched still has a turn, which is what makes "the
+      # turn you read" a complete answer rather than a special case.
+      def assistant_turn = "t#{id}-r#{assistant_revision.to_i}"
+
+      # Whether this case has anything to do with an assistant — configured
+      # on the desk now, or spoken in by one at any point. History counts:
+      # the door to a person must not vanish because somebody edited an
+      # initializer after she answered.
+      def assistant_in_play?
+        assistant.present? || assistant_turns_count.to_i.positive?
+      end
+
+      def held_by_assistant?
+        assigned? && assignee_type == SupportDesk::Assistant.polymorphic_name
+      end
+
+      # Whether a person has been asked for on this case — by the assistant,
+      # by the requester, or by the silent sweep.
+      def human_required? = human_required_at.present?
+
+      # Whether a human has switched her off on this case.
+      def assistant_paused? = assistant_paused_at.present?
+
+      # How many times she may still speak here; nil when unlimited.
+      def assistant_turns_left
+        max = assistant&.max_turns
+        return nil if max.nil?
+
+        [ max - assistant_turns_count.to_i, 0 ].max
+      end
+
+      # The conversation as ordered turns — the readable half of what a
+      # harness works from. `limit:` keeps the LAST n, which is the part
+      # still being answered. See SupportDesk::Transcript.
+      def transcript(limit: nil)
+        Transcript.new(self, limit: limit)
+      end
+
+      # Everything a machine needs to answer this case, as data: the desk,
+      # the policy, the case, the requester and the transcript.
+      # `include_internal: true` adds the desk's own notes and proposals —
+      # off by default, because it leaves the building. See
+      # SupportDesk::Brief.
+      def brief(include_internal: false, transcript_limit: 50)
+        Brief.new(self, include_internal: include_internal, transcript_limit: transcript_limit)
+      end
+
+      # Whether this message came from an assistant — by authorship when she
+      # signs, by the provenance stamp when she doesn't. Both shapes, because
+      # a host that changes disclosure mode must not rewrite old bubbles.
+      def assistant_message?(message)
+        return false if message.nil?
+
+        return true if message.author.is_a?(SupportDesk::Assistant)
+
+        stamp = message.try(:metadata)
+        stamp.is_a?(Hash) && stamp.dig("support_desk", "assistant").present?
+      end
+
+      # --- Her two verbs ------------------------------------------------------------
+
+      # Answer, and let policy decide what that means: sent to the requester,
+      # proposed as a draft for a person to send, or withheld. The ONE verb a
+      # harness needs — it never has to encode the rules it is working under.
+      #
+      # Returns a SupportDesk::Outcome. Raises StaleTurn when the case moved
+      # on, Locked when there is nobody to write to, NotAnAssistant when
+      # `by:` isn't this desk's assistant.
+      def respond!(body = nil, by:, turn:, files: [], confidence: nil, sources: [], metadata: {}, request: nil)
+        raise ArgumentError, "respond! needs something to say" if body.blank? && files.blank?
+
+        # Durable repair first, in a transaction of its own: what it folds in
+        # survives the StaleTurn that folding it in may cause (R3).
+        reconcile_and_commit!
+
+        with_lock(requires_new: true) do
+          assistant = resolve_assistant!(by)
+          lock_conversation!
+          reconcile_unregistered_messages!
+          ensure_current_turn!(turn)
+          ensure_writable!
+          policy = assistant_policy(assistant)
+          next withhold!(assistant, policy, :policy, request: request) unless policy.may_draft?
+          next withhold!(assistant, policy, :not_your_turn, request: request) unless awaiting_reply?
+
+          left = assistant_turns_left
+          if policy.may_reply? && (left.nil? || left.positive?)
+            message = speak!(body, assistant, policy: policy, turn: turn, files: files, confidence: confidence,
+                                              sources: sources, metadata: metadata, request: request)
+            Outcome.new(action: :sent, message: message, policy: policy, turn: assistant_turn)
+          else
+            draft = propose_draft!(body, assistant, policy: policy, files: files, confidence: confidence,
+                                                    sources: sources, metadata: metadata)
+            reason = nil
+            # Out of budget at a level that could otherwise have answered:
+            # the draft stays, and so does a person — a conversation that
+            # ran out of turns is one somebody has to finish.
+            if policy.may_reply? && left&.zero?
+              handed_off, from = flag_human_required!(actor: assistant, kind: :escalated, reason: "max_turns",
+                                                      summary: metadata[:summary] || metadata["summary"],
+                                                      line: :hand_off_line, request: request)
+              # A conversation that ran out of turns is a hand-off like any
+              # other, and it says so out loud: the host's "a person is
+              # needed here" notifier listens for this and nothing else (R7).
+              publish_escalation!(from: from, reason: :max_turns, by: assistant) if handed_off
+              reason = :max_turns
+            end
+            Outcome.new(action: :drafted, draft: draft, policy: policy, reason: reason, turn: assistant_turn)
+          end
+        end
+      end
+
+      # Propose a reply for a person to send, whatever the level allows.
+      # `respond!` is what a harness should call; this is for a host that has
+      # already decided it wants a draft. Returns the SupportDesk::Draft.
+      def draft!(body = nil, by:, turn:, files: [], confidence: nil, sources: [], metadata: {}, request: nil)
+        raise ArgumentError, "draft! needs something to say" if body.blank? && files.blank?
+
+        reconcile_and_commit!
+
+        with_lock(requires_new: true) do
+          assistant = resolve_assistant!(by)
+          lock_conversation!
+          reconcile_unregistered_messages!
+          ensure_current_turn!(turn)
+          ensure_writable!
+          policy = assistant_policy(assistant)
+          raise AssistantNotAllowed.new(policy, verb: :draft) unless policy.may_draft?
+
+          propose_draft!(body, assistant, policy: policy, files: files, confidence: confidence,
+                                          sources: sources, metadata: metadata)
+        end
+      end
+
+      # --- The two exits ------------------------------------------------------------
+
+      # Hand the case to a person: the assistant's own way out, and what the
+      # silent sweep calls as `:system`. Releases her seat, records the
+      # reason, raises the priority and tells the requester.
+      #
+      # `turn:` is required when `by:` is the assistant — escalating is an
+      # action like any other, and a stale one must not speak.
+      def escalate!(by: nil, reason:, summary: nil, turn: nil, request: nil)
+        actor = resolve_actor(by)
+        ensure_agent!(actor)
+        machine = SupportDesk.ai_actor?(actor)
+        raise ArgumentError, "escalate! needs a reason" if reason.blank?
+
+        assistant = nil
+        event = nil
+        from = nil
+        with_lock(requires_new: true) do
+          if machine
+            # Under the lock, from the row (R9).
+            assistant = resolve_assistant!(actor)
+            ensure_current_turn!(turn)
+            policy = assistant_policy(assistant)
+            raise AssistantNotAllowed.new(policy, verb: :escalate) unless policy.may_observe?
+          end
+
+          event, from = flag_human_required!(actor: actor, kind: :escalated, reason: reason, summary: summary,
+                                             line: :hand_off_line, request: request)
+        end
+        return self unless event
+
+        stamp_assistant_action! if assistant
+        publish_escalation!(from: from, reason: reason, by: actor)
+        self
+      end
+
+      # "Prefiero hablar con una persona." The requester's own door, and the
+      # one thing on this case they can always do: it reopens a closed case
+      # where the desk allows it, flags the case, and says so in the thread.
+      # Idempotent — pressing it twice writes once.
+      def request_human!(by: nil, request: nil)
+        actor = resolve_actor(by)
+        unless self.class.same_actor?(actor, requester)
+          raise NotAllowed,
+                "#{describe_actor(actor)} can't ask for a person on #{reference} — it isn't their case"
+        end
+
+        event = nil
+        with_lock(requires_new: true) do
+          reopen!(by: actor, request: request) if closed? && desk_config.closed_tickets == :reopen_on_reply
+          ensure_writable!
+          event, = flag_human_required!(actor: actor, kind: :human_requested, reason: "requester_request",
+                                        summary: nil, line: :human_requested_line, request: request)
+        end
+        return self unless event
+
+        SupportDesk.emit_after_commit(:human_requested, self, by: actor, reason: :requester_request)
+        self
+      end
+
+      # --- The human override -------------------------------------------------------
+
+      # Switch the assistant off on THIS case: a delicate conversation, a
+      # customer who has had enough, a thread somebody wants to handle
+      # themselves. Releases her seat, throws away her pending proposal, and
+      # floors her policy at :off until somebody resumes her.
+      def pause_assistant!(by: nil, reason: nil, request: nil)
+        actor = resolve_actor(by)
+        if actor.is_a?(Symbol) || SupportDesk.ai_actor?(actor)
+          raise NotAllowed, "only a person can pause the assistant on a case"
+        end
+        ensure_agent!(actor)
+
+        event = write_transition!(:assistant_paused, actor: actor, request: request) do
+          raise InvalidTransition, "can't pause the assistant on a closed case" if closed?
+          next false if assistant_paused?
+
+          release_assistant_seat!(reason: :released)
+          supersede_pending_drafts!
+          update!(assistant_paused_at: Time.current, assistant_paused_reason: reason.presence&.to_s)
+          { "reason" => reason.presence&.to_s }
+        end
+        return self unless event
+
+        SupportDesk.emit_after_commit(:assistant_paused, self, by: actor)
+        self
+      end
+
+      # Let her back in on this case. Clears the pause and NOTHING ELSE: a
+      # case cap and a request for a person are different decisions, made by
+      # different people, and only an explicit hand-back lifts those.
+      def resume_assistant!(by: nil, request: nil)
+        actor = resolve_actor(by)
+        if actor.is_a?(Symbol) || SupportDesk.ai_actor?(actor)
+          raise NotAllowed, "only a person can resume the assistant on a case"
+        end
+        ensure_agent!(actor)
+
+        event = write_transition!(:assistant_resumed, actor: actor, request: request) do
+          next false unless assistant_paused?
+
+          update!(assistant_paused_at: nil, assistant_paused_reason: nil)
+          {}
+        end
+        return self unless event
+
+        SupportDesk.emit_after_commit(:assistant_resumed, self, by: actor)
+        emit_assistant_turn if awaiting_reply?
+        self
+      end
+
+      # --- Internals ----------------------------------------------------------------
+
+      # The verbs the assistant may press on this case right now — the
+      # machine's half of `actions_for`, and the same decision the
+      # transitions make, so a harness reading `may` from a brief is reading
+      # the authorization and not a hint.
+      def assistant_actions_for(assistant) # :nodoc:
+        return [] unless assistant.is_a?(SupportDesk::Assistant)
+        return [] unless self.class.same_actor?(assistant, self.assistant)
+
+        verbs = assistant_policy(assistant).allowed_verbs.dup
+        verbs -= %i[escalate] if closed?
+        verbs -= %i[reply draft take] if requester_unavailable?
+        verbs -= %i[take] unless unassigned?
+        verbs -= %i[release] unless assigned_to?(assistant)
+        verbs -= %i[reply] unless awaiting_reply?
+        verbs -= %i[close] unless assigned_to?(assistant) && awaiting_requester? && !human_required?
+        verbs
+      end
+
+      # The silent sweep's own transition: hand this case to a person ONLY if
+      # it is still the case the sweep selected — open, still hers, still owing
+      # the next word, still past her promise, and with nobody asked for yet.
+      # Returns true when it moved. See SupportDesk.release_silent_assistants!.
+      #
+      # Every one of those predicates was true when the sweep SELECTED its
+      # candidates, and a person can answer, take the case or reset the clock
+      # between that query and this write. 0.3.0 rechecked only "closed" and
+      # "already asked for", so a case somebody had just answered was marked
+      # human-required anyway: its priority went up and the customer was told a
+      # person was coming, on a case that already had one (R5).
+      def escalate_if_still_silent!(assistant, window) # :nodoc:
+        event = nil
+        from = nil
+        with_lock(requires_new: true) do
+          next unless open?
+          next unless assigned_to?(assistant)
+          next unless awaiting_reply?
+          next if human_required?
+          next unless waiting_since.present? && waiting_since <= window.ago
+
+          event, from = flag_human_required!(
+            actor: :system, kind: :escalated, reason: "assistant_silent",
+            summary: "no answer in #{SupportDesk.humanize_duration(window)}",
+            line: :hand_off_line, request: nil
+          )
+        end
+        return false unless event
+
+        publish_escalation!(from: from, reason: "assistant_silent", by: :system)
+        true
+      end
+
+      # Give a stranded seat back to people: the assistant holding this case is
+      # switched off, no longer declared, or no longer allowed to hold it.
+      # Returns true when it moved. See SupportDesk.reclaim_assistant_seats!.
+      #
+      # This is INVALID-ASSIGNEE recovery, and it is deliberately not silence
+      # detection: it needs no `responds_within`, no overdue clock and no
+      # waiting side. `deactivate!` promises the seats come back, and in 0.3.0
+      # that promise was kept only for an assistant who had a promise of her
+      # own and a case that was already late (R6).
+      def reclaim_assistant_seat! # :nodoc:
+        event = nil
+        from = nil
+        escalated = false
+        with_lock(requires_new: true) do
+          next unless open?
+          next unless held_by_assistant?
+
+          from = assignee
+          next if assistant_may_keep_seat?(from)
+
+          if human_required?
+            # Somebody has already been asked for, and why is their business —
+            # the only thing left to give back is the seat.
+            event = write_transition!(:released, actor: :system) do
+              release_assistant_seat!(reason: :released)
+              { "from" => SupportDesk.actor_key(from), "reason" => "assistant_unavailable" }
+            end
+          else
+            escalated = true
+            event, = flag_human_required!(actor: :system, kind: :escalated, reason: "assistant_unavailable",
+                                          summary: nil, line: :hand_off_line, request: nil)
+          end
+        end
+        return false unless event
+
+        if escalated
+          publish_escalation!(from: from, reason: "assistant_unavailable", by: :system)
+        else
+          SupportDesk.emit_after_commit(:ticket_released, self, from: from, reason: :assistant_unavailable)
+        end
+        true
+      end
+
+      # The ONE place `:ticket_escalated` is published. Every hand-off that
+      # takes her off a case goes through it — her own `escalate!`, the budget
+      # branch of `respond!`, the silent sweep — so no path can write the
+      # transition and forget the signal (R7). A no-op writes no event and
+      # publishes nothing.
+      def publish_escalation!(from:, reason:, by:) # :nodoc:
+        SupportDesk.emit_after_commit(:ticket_escalated, self, from: from, reason: reason.to_sym, by: by)
+      end
+
+      # Bump the case's revision — the caller holds the lock. `update_columns`
+      # on purpose: inside the transaction, no callbacks, no validations, and
+      # the in-memory value moves with the row, so the turn a caller reads
+      # next is the one the database has.
+      def bump_assistant_revision! # :nodoc:
+        update_columns(assistant_revision: assistant_revision.to_i + 1)
+      end
+
+      # Fold in every requester message chats has committed but nobody has
+      # registered, in a transaction of ITS OWN, and commit it — whatever the
+      # answer that discovered it then decides. Returns how many it folded in.
+      #
+      # A registration lost after commit (a worker killed between the message's
+      # COMMIT and the subscriber that registers it) used to be unrepairable:
+      # reconciliation ran inside the candidate answer's savepoint, the bumped
+      # revision made that very answer stale, and the StaleTurn rolled the
+      # repair back with it. The next run read the same revision and did the
+      # same thing, for ever (R3).
+      #
+      # Durability is the caller's: at the top level (a job, the recovery task)
+      # this really commits, and the `:assistant_turn` it emits for what it
+      # registered is an ACTIONABLE turn. Inside a host's own transaction it is
+      # a savepoint like any other, and it commits when that does.
+      def reconcile_and_commit! # :nodoc:
+        folded = 0
+        with_lock(requires_new: true) do
+          lock_conversation!
+          folded = reconcile_unregistered_messages!
+        end
+        folded
+      end
+
+      # When the assistant last did anything here — what the idle-turn check
+      # and the redispatch task read to tell "she decided not to speak" from
+      # "nothing is running".
+      def stamp_assistant_action! # :nodoc:
+        update_columns(assistant_acted_at: Time.current)
+      end
+
+      private
+
+      # The actor, as this desk's assistant — or a refusal that names which
+      # of the three things went wrong. Every AI-kind actor comes through
+      # here: a host model declared `kind: :ai` is not an assistant, and
+      # another desk's assistant is not this desk's (I2).
+      def resolve_assistant!(actor)
+        unless actor.is_a?(SupportDesk::Assistant)
+          raise NotAnAssistant,
+                "#{describe_actor(actor)} is an AI agent but not a SupportDesk::Assistant — only the desk's " \
+                "configured assistant may act on a case"
+        end
+        unless self.class.same_actor?(actor, assistant)
+          raise NotAnAssistant,
+                "#{actor.key} is not desk #{desk.key}'s assistant"
+        end
+
+        # Fresh from the row: `active` is a cross-process kill switch, and a
+        # record loaded a minute ago is not evidence about now — nor is one
+        # loaded before this call waited for the case's lock. The FRESH
+        # record is what is handed back, because the policy reads `active?`
+        # off the record it is given (R9).
+        #
+        # Every caller resolves inside the lock. That still leaves the
+        # ordinary in-flight window — a switch that commits after this read
+        # and before our own commit wins nothing, and its next check stops
+        # the next call — which is documented rather than claimed away.
+        self.class.ensure_agent_record!(actor)
+      end
+
+      # The turn check, under the lock, from the revision the row holds.
+      def ensure_current_turn!(turn)
+        raise ArgumentError, "turn: is required for an assistant — pass the turn you read" if turn.nil?
+        return if turn.to_s == assistant_turn
+
+        raise StaleTurn,
+              "#{turn} is stale on #{reference}: the case has changed (now #{assistant_turn})"
+      end
+
+      # Fold in any requester message chats has committed but the gem hasn't
+      # folded in yet, under the lock, BEFORE the turn is checked (I5).
+      #
+      # The subscriber runs after commit and the assistant's job runs on
+      # another connection: without this, a message the customer sent a
+      # millisecond ago would be invisible to the turn, and she would answer
+      # around it. Folding it in here makes the turn stale instead, which is
+      # exactly what should happen.
+      def reconcile_unregistered_messages!
+        return 0 if conversation.nil?
+
+        folded = unregistered_requester_messages.oldest_first.to_a
+        folded.each { |message| record_registration!(message) }
+        folded.size
+      end
+
+      # Every committed requester message without a receipt, regardless of
+      # timestamp or UUID order. The clocks are not evidence of registration.
+      def unregistered_requester_messages
+        conversation.messages.where(kind: "text", sender_type: requester_type, sender_id: requester_id)
+                    .where.not(id: message_registrations.select(:message_id))
+      end
+
+      # A SELECT … FOR UPDATE on the conversation row, taken AFTER the ticket's
+      # and before any reconciliation. See the module comment: this row is what
+      # chats updates inside every message's own transaction, so it is the only
+      # seam that serializes a customer's write against ours without a write
+      # hook in chats (R1).
+      #
+      # Read through the id rather than the association: `lock!` refuses a
+      # record with unsaved changes, and nothing here wants the in-memory
+      # conversation reloaded.
+      def lock_conversation!
+        return if conversation_id.blank?
+
+        Chats::Conversation.lock.find_by(id: conversation_id)
+      end
+
+      # Whether the assistant sitting on this case may go on sitting on it: she
+      # is on duty, she is still declared, and her policy still lets her hold
+      # it. Read under the lock, from the reloaded assignee.
+      #
+      # A policy that RAISES — a desk pointing at an assistant nobody declares
+      # any more — is an answer too, and it is "no": a seat nothing can reason
+      # about belongs to a person.
+      def assistant_may_keep_seat?(holder)
+        return false unless holder.is_a?(SupportDesk::Assistant)
+        return false unless holder.active?
+        return false unless holder.configured?
+
+        assistant_policy(holder).may_hold?
+      rescue StandardError
+        false
+      end
+
+      # Nothing was written, and the reason is on the record: a policy that
+      # refused is evidence, not silence.
+      def withhold!(assistant, policy, reason, request: nil)
+        event = record_transition!(:assistant_withheld, actor: assistant) do
+          { "assistant" => assistant.key, "reason" => reason.to_s, "policy" => policy.to_h }
+        end
+        stamp_assistant_action!
+        publish_transition(event, :assistant_withheld, assistant, request)
+        SupportDesk.emit_after_commit(:assistant_withheld, self, assistant, reason: reason, policy: policy)
+        Outcome.new(action: :withheld, reason: reason, policy: policy, turn: assistant_turn)
+      end
+
+      # Say it to the requester. The caller holds the lock and has already
+      # decided she may.
+      def speak!(body, assistant, policy:, turn:, files:, confidence:, sources:, metadata:, request:)
+        notice = (post_disclosure_notice!(assistant) if assistant.notice? && !disclosure_posted?(assistant))
+        apply_reply_policy!(assistant, request: request)
+
+        stamped = assistant_message_metadata(assistant, policy: policy, turn: turn, confidence: confidence,
+                                                        sources: sources, host: metadata)
+
+        # `author: nil` in the nameless modes, so chats prints no signature
+        # and the requester sees the desk — while the metadata above still
+        # says exactly what wrote it, for staff, for export and for audit.
+        posted = post_agent_message!(body, files: files, by: (assistant if assistant.signs?), metadata: stamped)
+        pin_before!(notice, posted) if notice
+        record_registration!(posted)
+        update_columns(assistant_turns_count: assistant_turns_count.to_i + 1)
+        stamp_assistant_action!
+        posted
+      end
+
+      # What every machine-written message carries: who wrote it, under what
+      # disclosure, holding which turn, and the whole policy that allowed it.
+      #
+      # The host's own metadata is NESTED under "host" rather than merged:
+      # the "support_desk" key is the gem's evidence, and a host writing
+      # `policy` into it would be rewriting it.
+      def assistant_message_metadata(assistant, policy:, turn:, confidence: nil, sources: [], host: {})
+        stamped = { "support_desk" => {
+          "assistant" => assistant.key,
+          "kind" => "ai",
+          "name" => assistant.name,
+          "display_name" => assistant.disclosed_name,
+          "disclosure" => assistant.disclosure.to_s,
+          "signed" => assistant.signs?,
+          "turn" => turn.to_s,
+          "confidence" => confidence,
+          "sources" => sources.presence,
+          "policy" => policy.to_h
+        }.compact }
+        stamped["host"] = host if host.present?
+        stamped
+      end
+
+      # The desk's first word, when it is hers. Called from inside the
+      # transaction that created the case (see Ticket.post_opening!), where
+      # she is already seated and there is no earlier turn for anybody to
+      # have held — so the first turn is the one this message consumes.
+      def post_assistant_opening!(body, files:, assistant:)
+        policy = assistant_policy(assistant)
+        stamped = assistant_message_metadata(assistant, policy: policy, turn: assistant_turn)
+        posted = post_agent_message!(body, files: files, by: (assistant if assistant.signs?), metadata: stamped)
+        update_columns(assistant_turns_count: 1)
+        posted
+      end
+
+      # Write the proposal. Validated BEFORE the pending one is superseded:
+      # a draft that can't be saved must not take the previous one with it.
+      def propose_draft!(body, assistant, policy:, files: [], confidence: nil, sources: [], metadata: {})
+        candidate = drafts.new(author: assistant, proposed_turn: assistant_turn, body: body,
+                               confidence: confidence, sources: sources || [],
+                               metadata: { "policy" => policy.to_h, "host" => metadata.presence }.compact)
+        candidate.files = files if files.present? && candidate.respond_to?(:files=)
+        candidate.validate!
+
+        # One pending proposal per case. The row lock serialises this, so
+        # there is no unique-violation to rescue: supersede, then insert.
+        drafts.pending.each(&:supersede!)
+        bump_assistant_revision!
+        # The turn this proposal LEAVES the case at, not the one it answered
+        # — a proposal is itself a change, so stamping the turn it consumed
+        # would make every draft stale the moment it was written.
+        candidate.proposed_turn = assistant_turn
+        candidate.save!
+        reset_draft_associations!
+        stamp_assistant_action!
+        broadcast_change
+        SupportDesk.emit_after_commit(:draft_proposed, self, candidate)
+        candidate
+      end
+
+      # The notice a `:notice` mode opens with, posted once per disclosure
+      # MODE: a host that changes mode discloses again, and one that doesn't
+      # never repeats itself.
+      def post_disclosure_notice!(assistant)
+        line = assistant.config.line_for(:disclosure_line, self)
+        if line.blank?
+          raise ConfigurationError,
+                "assistant #{assistant.key} discloses with a notice but has no disclosure_line — " \
+                "an undisclosed autonomous message is never posted silently"
+        end
+
+        notice = conversation.post_system_message!(line)
+        disclosed = (metadata["assistant_disclosed"] || {}).merge(assistant.key.to_s => assistant.disclosure.to_s)
+        update!(metadata: metadata.merge("assistant_disclosed" => disclosed))
+        notice
+      end
+
+      def disclosure_posted?(assistant)
+        metadata.dig("assistant_disclosed", assistant.key.to_s) == assistant.disclosure.to_s
+      end
+
+      # chats orders a transcript by (created_at, id), and two inserts in one
+      # transaction can share a timestamp — so a notice is pinned one
+      # database tick before the message it introduces, exactly as the
+      # opening line is.
+      def pin_before!(notice, message)
+        return if notice.nil? || message.nil?
+
+        notice.update_columns(created_at: message.created_at - self.class.send(:ordering_tick))
+      end
+
+      # The one write behind both hand-offs: release her seat, record who
+      # asked and why, raise the priority, and say so in the thread.
+      # Returns [event, previous assignee] — nil event when it was a no-op.
+      def flag_human_required!(actor:, kind:, reason:, summary:, line:, request:)
+        from = nil
+        event = write_transition!(kind, actor: actor, request: request) do
+          raise InvalidTransition, "can't #{kind} a closed case — reopen it first" if closed?
+          next false if human_required?
+
+          from = assignee
+          release_assistant_seat!(reason: :escalated)
+          update!(human_required_at: Time.current, human_required_reason: reason.to_s,
+                  priority: [ priority.to_i, Topic::PRIORITIES[:high] ].max)
+          { "reason" => reason.to_s, "summary" => summary.presence,
+            "from" => SupportDesk.actor_key(from) }.compact
+        end
+        return [ nil, nil ] unless event
+
+        post_assistant_line!(line) unless requester_unavailable?
+        [ event, from ]
+      end
+
+      # Her seat, and only hers: a human who holds the case keeps it. A case
+      # that waited long enough for a person still gets one, seat or no seat.
+      def release_assistant_seat!(reason:)
+        return unless held_by_assistant?
+
+        assignments.open.each { |assignment| assignment.release!(reason: reason) }
+        update!(assignee: nil)
+      end
+
+      # One of the assistant's system lines, in the thread. A blank line
+      # posts nothing, and a rendering error is reported rather than raised:
+      # a missing translation must not roll back a hand-off.
+      def post_assistant_line!(setting)
+        assistant = self.assistant
+        return if assistant.nil? || conversation.nil?
+
+        line = assistant.config.line_for(setting, self)
+        return if line.blank?
+
+        conversation.post_system_message!(line)
+      rescue StandardError => e
+        SupportDesk.report_error(e, context: { hook: setting, ticket: id })
+      end
+
+      # The host's "somebody typed 'quiero hablar con una persona'" hook, run
+      # on every requester message under the registration lock.
+      #
+      # It FAILS CLOSED (v2 R28): true hands the case over, false and nil do
+      # nothing, and anything else — a String, a raise — is reported AND
+      # hands the case over. A hook nobody can read the answer of is a hook
+      # that has already failed, and the safe direction is a person.
+      def evaluate_hand_off_phrase!(message)
+        assistant = self.assistant
+        return if assistant.nil? || human_required? || !assistant_in_play?
+
+        block = assistant.config.hand_off_when
+        return if block.nil?
+
+        result = begin
+          block.call(self, message)
+        rescue StandardError => e
+          SupportDesk.report_error(e, context: { hook: :hand_off_when, ticket: id })
+          :error
+        end
+
+        case result
+        when true
+          flag_human_required!(actor: requester, kind: :human_requested, reason: "phrase", summary: nil,
+                               line: :human_requested_line, request: nil)
+          SupportDesk.emit_after_commit(:human_requested, self, by: requester, reason: :phrase)
+        when false, nil
+          nil
+        else
+          unless result == :error
+            SupportDesk.report_error(
+              ArgumentError.new("hand_off_when must return true, false or nil, got #{result.inspect}"),
+              context: { hook: :hand_off_when, ticket: id }
+            )
+          end
+          flag_human_required!(actor: requester, kind: :human_requested, reason: "hand_off_when_error",
+                               summary: nil, line: :human_requested_line, request: nil)
+          SupportDesk.emit_after_commit(:human_requested, self, by: requester, reason: :hand_off_when_error)
+        end
+      end
+
+      # "There is something to answer here." The only event a harness
+      # subscribes to, and the only place the gem asks anybody to do work.
+      #
+      # It carries the turn, so a job can check `ticket.assistant_turn ==
+      # turn` before spending money. A hook that raises is reported: a
+      # broken subscriber must not roll back the message that triggered it.
+      def emit_assistant_turn(message = nil)
+        return unless open? && awaiting_reply?
+
+        assistant = self.assistant
+        return if assistant.nil?
+        return unless assistant_policy(assistant).may_observe?
+
+        SupportDesk.emit_after_commit(:assistant_turn, self, assistant, message, turn: assistant_turn)
+      rescue StandardError => e
+        SupportDesk.report_error(e, context: { hook: :assistant_turn, ticket: id })
+      end
+
+      # A human transition that lowers the effective level below :reply while
+      # she holds the case takes her seat — a case she may no longer answer
+      # is not a case she can go on holding.
+      def release_assistant_if_unfit!
+        return false unless held_by_assistant?
+
+        holder = assignee
+        return false if assistant_policy(holder).may_reply?
+
+        assignments.open.each { |assignment| assignment.release!(reason: :released) }
+        update!(assignee: nil)
+        true
+      end
+
+      # Every pending proposal on this case is out of date. `except:` is the
+      # draft being sent right now, which is about to become "sent".
+      def supersede_pending_drafts!(except: nil)
+        scope = drafts.pending
+        scope = scope.where.not(id: except) if except.present?
+        scope.each(&:supersede!)
+        reset_draft_associations!
+      end
+
+      # A closed case has nothing pending. Returns how many it expired, for
+      # the close event's payload.
+      def expire_pending_drafts!
+        pending = drafts.pending.to_a
+        pending.each(&:expire!)
+        reset_draft_associations!
+        pending.size
+      end
+
+      # The proposals moved, so what this instance remembers about them is
+      # a lie. Everything that changes a draft's status calls this, so
+      # `ticket.pending_draft` and `actions_for` are right inside the SAME
+      # operation — a console that had to `reload` to see its own write is a
+      # console that renders a button nobody can press.
+      def reset_draft_associations!
+        association(:pending_draft).reset
+        association(:drafts).reset
+      end
+    end
+  end
+end