support_desk 0.3.0 → 0.4.0

data/lib/support_desk/models/ticket.rb

@@ -59,6 +59,7 @@ module SupportDesk
     # readonly record refuses to be destroyed. Deleting a ticket is the one
     # thing that takes its timeline with it, and it needs no callbacks.
     has_many :events, class_name: "SupportDesk::Event", inverse_of: :ticket, dependent: :delete_all
+    has_many :message_registrations, class_name: "SupportDesk::MessageRegistration", dependent: :delete_all
     has_many :messages, through: :conversation, source: :messages
 
     # The assistant surface — the turn, the policy gates, her two verbs and
@@ -191,6 +192,35 @@ module SupportDesk
         find_by(conversation_id: conversation.id)
       end
 
+      # The conversations behind +requester+'s own cases, while they still
+      # hold its seat: chats' participation and block rules (`inbox_for`),
+      # without the host's `inbox_scope`. Participation is what makes a
+      # conversation theirs to read; the inbox is only where it is listed.
+      # What chats adds to its lookup (SupportDesk::ConversationAccess) and
+      # what the ticket page reads from.
+      #
+      # A case and its conversation have to point at each other: a direct
+      # conversation whose subject IS one of this requester's cases, that very
+      # case's conversation. A ticket mislinked to a group, or to a
+      # conversation about something else, opens nothing.
+      def conversations_of(requester)
+        return Chats::Conversation.none unless requester.respond_to?(:support_tickets)
+
+        tickets = arel_table
+        conversations = Chats::Conversation.arel_table
+        own_cases = requester.support_tickets.where(tickets[:id].eq(conversations[:subject_id])).select(:conversation_id)
+        Chats::Conversation.inbox_for(requester).direct
+                           .where(subject_type: polymorphic_name)
+                           .where(id: own_cases)
+      end
+
+      # One of them, by id, or nil.
+      def requester_conversation(requester, id)
+        return nil if id.blank?
+
+        conversations_of(requester).find_by(id: id)
+      end
+
       # Open a ticket and post its first message. Usually called as
       # `requester.ask_support!(…)` — or, when the desk writes first, as
       # `agent.open_support_conversation_with!(…)`. This is the seam under
@@ -341,10 +371,14 @@ module SupportDesk
 
       # A loaded instance may predate revocation or deletion. Check the row,
       # just as requester eligibility does; this does not serialize revocation.
+      #
+      # Returns the FRESH record, so a caller that goes on to read a runtime
+      # flag off it (the assistant's `active?`, which the policy reads) is
+      # reading the row and not the copy it was handed (R9).
       def ensure_agent_record!(record) # :nodoc:
         if record.respond_to?(:persisted?) && record.persisted? && record.respond_to?(:support_agent?)
           current = record.class.uncached { record.class.find_by(id: record.id) }
-          return if current&.support_agent?
+          return current if current&.support_agent?
         end
 
         raise NotAnAgent, "#{record.class} is not a currently eligible, persisted support agent — " \
@@ -616,6 +650,7 @@ module SupportDesk
         ticket.send(:record_registration!, posted) if posted
         ticket.send(:stamp_assistant_action!) if by_support && SupportDesk.ai_actor?(by)
         pin_opening_lines!(ticket, notices, posted)
+        post_acknowledgement!(ticket, posted) if posted && !by_support
         ticket
       end
 
@@ -626,6 +661,30 @@ module SupportDesk
         ticket.conversation.post_system_message!(line)
       end
 
+      # The desk's acknowledgement, right under the requester's first message
+      # and in the same transaction, so "did that go through?" is answered by
+      # the very commit that made it so. Pinned one tick AFTER the message
+      # whenever the clock did not move between the two inserts (the same tie
+      # `pin_opening_lines!` breaks the other way), and it is then the
+      # conversation's last message: what a list row previews.
+      #
+      # It is the desk's receipt for words the requester has just written, so
+      # it is never news to them: their read horizon moves through it. Without
+      # that, a tick dated after the clock (a frozen or coarse one) would stay
+      # unread on a page that already shows it, chats' own thread included,
+      # which reads at "now".
+      def post_acknowledgement!(ticket, posted)
+        line = ticket.desk_config.acknowledgement_for(ticket)
+        return if line.blank?
+
+        notice = ticket.conversation.post_system_message!(line)
+        if notice.created_at <= posted.created_at
+          notice.update_columns(created_at: posted.created_at + ordering_tick)
+          ticket.conversation.recompute_last_message!
+        end
+        ticket.conversation.participant_for(ticket.requester)&.read!(at: notice.created_at)
+      end
+
       # chats orders a transcript by (created_at, id), and inserting one row
       # after another does NOT guarantee two different timestamps: frozen
       # time in a test, a coarse column, a clock that doesn't move between
@@ -670,12 +729,10 @@ module SupportDesk
       # running before any of it.
       def reply_into!(ticket, message, files:, by:, by_support:, request:, authorize_reuse:)
         if by_support
-          # `turn: :current` is for the assistant: reuse turns outreach into
-          # an ordinary reply, with her full rules — and the turn she has to
-          # hold is the one this lock reads, because there was never an
-          # earlier one to give her.
+          # Only this private outreach path supplies the current turn internally.
+          # Public replies must present the token their harness observed.
           ticket.send(:reply_under_lock!, message, by: by, files: files, request: request,
-                                                   authorize: authorize_reuse, turn: :current)
+                                                   authorize: authorize_reuse, outreach: true)
         else
           ticket.with_lock(requires_new: true) do
             authorize_reuse&.call(ticket)
@@ -721,7 +778,7 @@ module SupportDesk
     def chat_locked_notice
       return I18n.t("support_desk.thread.unavailable_notice") if requester_unavailable?
 
-      I18n.t("support_desk.thread.closed_notice")
+      I18n.t("support_desk.thread.closed_notice", **desk_config.line_interpolations(self))
     end
 
     # Whether the person this case belongs to can be written to at all right
@@ -863,6 +920,7 @@ module SupportDesk
     def reply!(body = nil, by: nil, files: [], request: nil, metadata: {}, turn: nil)
       actor = resolve_actor(by)
       ensure_agent!(actor)
+      reconcile_and_commit! if SupportDesk.ai_actor?(actor)
 
       reply_under_lock!(body, by: actor, files: files, request: request, metadata: metadata, turn: turn)
     end
@@ -872,11 +930,15 @@ module SupportDesk
     def note!(body, by: nil, request: nil, turn: nil)
       actor = resolve_actor(by)
       ensure_agent!(actor)
-      assistant = (resolve_assistant!(actor) if SupportDesk.ai_actor?(actor))
+      machine = SupportDesk.ai_actor?(actor)
       raise ArgumentError, "a note needs something to say" if body.blank?
 
+      assistant = nil
       event = write_transition!(:note, actor: actor, request: request) do
-        if assistant
+        if machine
+          # Under the lock, from the row: a kill switch that commits while
+          # this call waits for the case is a kill switch that stops it (R9).
+          assistant = resolve_assistant!(actor)
           ensure_current_turn!(turn)
           policy = assistant_policy(assistant)
           raise AssistantNotAllowed.new(policy, verb: :note) unless policy.may_observe?
@@ -891,10 +953,9 @@ module SupportDesk
     # Give the ticket to an agent. `assign!(to: lucia, by: lucia)` is
     # somebody taking it; `assign!(to: pedro, by: admin)` is somebody being
     # handed it. Repeating an assignment to the current holder does nothing.
-    def assign!(to:, by: nil, reason: nil, note: nil, request: nil)
+    def assign!(to:, by: nil, reason: nil, note: nil, request: nil, turn: nil)
       actor = resolve_actor(by)
       ensure_agent!(actor)
-      ensure_assistant_may_assign!(actor, to)
       ensure_assignable!(to)
 
       reason ||= to == actor ? :taken : :assigned
@@ -906,6 +967,13 @@ module SupportDesk
 
       event = write_transition!(:assigned, actor: actor, request: request) do
         raise InvalidTransition, "can't assign a closed ticket — reopen it first" if closed?
+        # Every mutable question about a seat is asked HERE, under the row
+        # lock, from the reloaded row: who holds the case, what her policy
+        # says, which turn she is on. Asked before the lock (0.3.0) they
+        # were answers about a case that has since moved, and a stale
+        # instance could take a seat a person had already been given (R2).
+        ensure_assistant_may_assign!(actor, to, turn: turn)
+        ensure_assistant_may_hold!(to)
         next false if assigned_to?(to)
 
         assignment = Assignment.open!(ticket: self, agent: to, by: actor, reason: reason, note: note)
@@ -946,6 +1014,7 @@ module SupportDesk
                                 "(#{assignee ? describe_actor(assignee) : "nobody"} does) — use assign! to override"
         end
         raise InvalidTransition, "can't hand off a closed ticket" if closed?
+        ensure_assistant_may_hold!(to)
         next false if assigned_to?(to)
 
         from = assignee
@@ -969,14 +1038,18 @@ module SupportDesk
     end
 
     # Put the ticket back in the unassigned pile.
-    def release!(by: nil, reason: :released, request: nil)
+    def release!(by: nil, reason: :released, request: nil, turn: nil)
       actor = resolve_actor(by)
       ensure_agent!(actor)
-      assistant = (resolve_assistant!(actor) if SupportDesk.ai_actor?(actor))
       from = nil
       event = write_transition!(:released, actor: actor, request: request) do
         raise InvalidTransition, "can't release a closed ticket" if closed?
+        assistant = (resolve_assistant!(actor) if SupportDesk.ai_actor?(actor))
         if assistant
+          # Giving a seat back is an action like any other, so it holds the
+          # turn it read: a run that finished after the case moved on must
+          # not release the seat a newer one took (R2).
+          ensure_current_turn!(turn)
           policy = assistant_policy(assistant)
           raise AssistantNotAllowed.new(policy, verb: :release) unless policy.may_observe?
           # Her own seat, and only hers: putting a PERSON's case back in the
@@ -1000,10 +1073,15 @@ module SupportDesk
     def close!(by: nil, request: nil, turn: nil)
       actor = resolve_actor(by)
       ensure_agent!(actor)
-      assistant = (resolve_assistant!(actor) if SupportDesk.ai_actor?(actor))
+      machine = SupportDesk.ai_actor?(actor)
+      reconcile_and_commit! if machine
 
       event = write_transition!(:closed, actor: actor, request: request) do
-        if assistant
+        if machine
+          # Resolved under the lock, so the kill switch is read after the
+          # wait rather than before it (R9).
+          assistant = resolve_assistant!(actor)
+          lock_conversation!
           reconcile_unregistered_messages!
           ensure_current_turn!(turn)
           policy = assistant_policy(assistant)
@@ -1327,22 +1405,30 @@ module SupportDesk
       end
 
       ensure_agent!(agent)
+    end
+
+    # "Could she hold this case once the human-side flags were lifted?" —
+    # the hand-back question, so the very flags a hand-back exists to clear
+    # are not what refuses it. Her autonomy, the topic and the host's cap
+    # block still decide.
+    #
+    # Asked UNDER THE LOCK (R2): a cap that lands while a take waits for the
+    # row is the cap that applies to it.
+    def ensure_assistant_may_hold!(agent)
       return unless SupportDesk.ai_actor?(agent)
 
-      # "Could she hold this case once the human-side flags were lifted?" —
-      # the hand-back question, so the very flags a hand-back exists to
-      # clear are not what refuses it. Her autonomy, the topic and the host's
-      # cap block still decide.
       policy = assistant_policy(agent, hand_back: true)
       raise AssistantNotAllowed.new(policy, verb: :take) unless policy.may_hold?
     end
 
     # An assistant may take a case, and that is all: only herself, only when
-    # nobody holds it, and only at a level that may answer.
-    def ensure_assistant_may_assign!(actor, to)
+    # nobody holds it, only at a level that may answer, and only holding the
+    # turn she read. Called under the row lock, from the reloaded row.
+    def ensure_assistant_may_assign!(actor, to, turn:)
       return unless SupportDesk.ai_actor?(actor)
 
       assistant = resolve_assistant!(actor)
+      ensure_current_turn!(turn)
       policy = assistant_policy(assistant)
       unless self.class.same_actor?(actor, to)
         raise AssistantNotAllowed.new(policy, verb: :assign,
@@ -1402,12 +1488,16 @@ module SupportDesk
     # `authorize:` is the console's hook (see Ticket.open_or_reply!): it runs
     # under this lock, before any policy side effect, and a raise there rolls
     # the whole thing back.
-    def reply_under_lock!(body, by:, files:, request:, authorize: nil, metadata: {}, turn: nil)
+    def reply_under_lock!(body, by:, files:, request:, authorize: nil, metadata: {}, turn: nil, outreach: false)
       with_lock(requires_new: true) do
         authorize&.call(self)
         next assistant_reply_under_lock!(body, assistant: by, files: files, request: request,
-                                               metadata: metadata, turn: turn) if SupportDesk.ai_actor?(by)
+                                               metadata: metadata, turn: turn, outreach: outreach) if SupportDesk.ai_actor?(by)
 
+        # Fold committed inputs before a human answer too. A delayed callback
+        # must not later turn an already-answered question back into work.
+        lock_conversation!
+        reconcile_unregistered_messages!
         ensure_writable!
         apply_reply_policy!(by, request: request)
         posted = post_agent_message!(body, files: files, by: by, metadata: metadata)
@@ -1423,13 +1513,13 @@ module SupportDesk
     # `reply!` by the assistant: her full rules, under the lock the caller
     # already holds. Everything here is also what `respond!` runs — this is
     # the path for a host that decided to answer rather than ask policy.
-    def assistant_reply_under_lock!(body, assistant:, files:, request:, metadata:, turn:)
+    def assistant_reply_under_lock!(body, assistant:, files:, request:, metadata:, turn:, outreach: false)
       assistant = resolve_assistant!(assistant)
-      # `:current` means "the turn as this lock sees it" — the one place the
-      # gem supplies a turn itself, because an outreach reply into an
-      # existing case has no earlier turn for anybody to have held.
-      turn = assistant_turn if turn == :current
+      # Private outreach supplies a token only after acquiring both locks;
+      # public replies compare the caller's actual observed token.
+      lock_conversation!
       reconcile_unregistered_messages!
+      turn = assistant_turn if outreach
       ensure_current_turn!(turn)
       ensure_writable!
 
@@ -1458,14 +1548,16 @@ module SupportDesk
                             "take it first"
         end
 
-        assign!(to: actor, by: actor, request: request)
+        # This private path already validated the reply while holding the lock.
+        # Seat-taking consumes the real current token, not a public sentinel.
+        assign!(to: actor, by: actor, request: request, turn: assistant_turn)
       elsif !assigned_to?(actor)
         # Humans outrank assistants, under EVERY reply policy (I8). A person
         # answering a case a machine is holding takes it over: there is
         # nothing to ask about "who owns this" when one of the two can't
         # want it, and leaving her seated would keep her answering next.
         if held_by_assistant? && !SupportDesk.ai_actor?(actor)
-          return assign!(to: actor, by: actor, reason: :drop_in_takeover, request: request)
+          return assign!(to: actor, by: actor, reason: :drop_in_takeover, request: request, turn: assistant_turn)
         end
         # Belt: the `held_by_human` floor already turned this into a draft,
         # so an assistant reaching here is a bug, not a policy question.
@@ -1476,7 +1568,7 @@ module SupportDesk
           raise NotAllowed, "ticket #{reference} is held by #{describe_actor(assignee)} and this desk only " \
                             "lets the assignee reply"
         when :take_over
-          assign!(to: actor, by: actor, reason: :drop_in_takeover, request: request)
+          assign!(to: actor, by: actor, reason: :drop_in_takeover, request: request, turn: assistant_turn)
         else
           write_transition!(:drop_in, actor: actor, request: request) do
             { "assignee" => SupportDesk.actor_key(assignee) }
@@ -1551,11 +1643,15 @@ module SupportDesk
     # caller is not always the lock holder it thinks it is.
     def record_registration!(message) # :nodoc:
       return self if role_of(message) == :system
+      unless message.persisted? && message.conversation_id == conversation_id
+        raise ArgumentError, "message must belong to this ticket's conversation"
+      end
       # Re-check under the lock: the same message can reach us twice (a
       # redelivered event, a hand-written replay), and an SLA clock that
       # moves twice for one message is a lie.
       return self if registered?(message)
 
+      message_registrations.create!(message_id: message.id)
       role = role_of(message)
       opening = opening_message?
       reopened = false
@@ -1565,10 +1661,10 @@ module SupportDesk
       closed_by_assistant = false
       case role
       when :requester
-        attributes[:last_requester_message_at] = message.created_at
+        attributes[:last_requester_message_at] = [ last_requester_message_at, message.created_at ].compact.max
         # The pointer the turn's reconciliation reads: which requester
         # message the clocks are standing on, by id and not only by time.
-        attributes[:last_requester_message_id] = message.id
+        attributes[:last_requester_message_id] = message.id if after_requester_watermark?(message)
         if closed? && message.created_at > closed_at && desk_config.closed_tickets == :reopen_on_reply
           # Read before the merge below clears it — see #reopen!.
           closed_by_assistant = closed_by_type == SupportDesk::Assistant.polymorphic_name
@@ -1577,7 +1673,7 @@ module SupportDesk
           reopened = true
         end
       when :agent
-        attributes[:last_agent_message_at] = message.created_at
+        attributes[:last_agent_message_at] = [ last_agent_message_at, message.created_at ].compact.max
         # A first REPLY answers something. An agent message with no earlier
         # requester message is the desk opening the conversation, or a word
         # into an empty case — neither is a reply, and a requester clock that
@@ -1592,7 +1688,13 @@ module SupportDesk
       end
 
       assign_attributes(attributes)
-      self.awaiting = closed? ? "none" : awaiting_from_clocks
+      self.awaiting = if closed?
+        "none"
+      elsif role == :requester
+        "agent"
+      else
+        awaiting_from_clocks
+      end
       self.waiting_since = waiting_since_from_clocks
       save!
       # Every registered message moves the case on, so every one of them
@@ -1609,48 +1711,51 @@ module SupportDesk
 
       # After the bump, and after any reopen: the hook decides about a case
       # in the state this message left it in.
-      evaluate_hand_off_phrase!(message) if role == :requester
+      evaluate_hand_off_phrase!(message) if role == :requester && !closed?
 
       publish_transition(reopen_event, :reopened, requester, nil) if reopen_event
       announce_registration(message, role: role, opening: opening, reopened: reopened)
       self
     end
 
-    # Whether this message is already folded in. The last-id check catches
-    # the common redelivery; the clock check catches the rest, because a
-    # REPLAY can arrive in any order and an older message must never rewind
-    # `awaiting`, restart an SLA clock, or reopen a case that was closed
-    # after it.
-    #
-    # The comparison is `<=`, so a message whose timestamp already sits on
-    # the clock counts as folded in: idempotency is the documented promise,
-    # and the cost of the rare tie is one clock that doesn't advance until
-    # the next message.
+    # Receipt identity, not transcript order, decides whether a callback is a
+    # replay. A later commit may have an earlier timestamp or a smaller UUID.
     def registered?(message)
-      return true if last_registered_message_id.present? && last_registered_message_id.to_s == message.id.to_s
-
-      role = role_of(message)
-      clock = case role
-      when :requester then last_requester_message_at
-      when :agent then last_agent_message_at
-      end
-      return false if clock.blank?
-      return true if message.created_at < clock
-      return false unless message.created_at == clock
-
-      # Equal timestamps are NOT the same message. A coarse column, a frozen
-      # clock in a test, or two very fast inserts can put two different
-      # messages on one instant, and a `<=` here folded the second one in
-      # without moving anything — so the assistant answered a question the
-      # case had never registered. The only equal-timestamp message that
-      # counts as folded in is the one the clock was set FROM.
-      case role
-      when :requester then last_requester_message_id.present? &&
-                           last_requester_message_id.to_s == message.id.to_s
-      else false
+      message_registrations.exists?(message_id: message.id)
+    end
+
+    # Advance the requester clock pointer only in transcript order. Receipt
+    # identity decides registration separately, so late arrivals cannot rewind
+    # clocks or be discarded as replays.
+    def after_requester_watermark?(message)
+      watermark = last_requester_message_at
+      return true if watermark.blank?
+      return true if message.created_at > watermark
+      return false if message.created_at < watermark
+      # A tie with no pointer to break it (a 0.2 row whose backfill found
+      # nothing) is new: the alternative silently drops it.
+      return true if last_requester_message_id.blank?
+
+      compare_message_ids(message.id, last_requester_message_id).positive?
+    end
+
+    # Order two chats message ids the way the DATABASE orders that column,
+    # because the reconciliation query compares them in SQL and this one
+    # compares them in Ruby. Integers compare numerically (10 is after 9);
+    # anything else — a uuid, a ULID — compares as a string, which is how
+    # every adapter orders those columns too.
+    def compare_message_ids(one, other)
+      if one.is_a?(Integer) && other.is_a?(Integer)
+        one <=> other
+      elsif integerish?(one) && integerish?(other)
+        one.to_i <=> other.to_i
+      else
+        one.to_s <=> other.to_s
       end
     end
 
+    def integerish?(value) = value.to_s.match?(/\A-?\d+\z/)
+
     def opening_message?
       last_registered_message_id.blank? && last_requester_message_at.nil? && last_agent_message_at.nil?
     end

data/lib/support_desk/transcript.rb

@@ -29,14 +29,10 @@ module SupportDesk
   #
   # == Names survive renames
   #
-  # An assistant's name is read from the message's own provenance stamp
-  # first (`metadata["support_desk"]["assistant"]`, the KEY), resolved
-  # through the configuration when she is still declared, and only then
-  # falls back to the `display_name` the message was written with. So a
-  # transcript reads "Rose" while Rose is configured, keeps saying what the
-  # customer was actually shown for an assistant nobody declares any more,
-  # and never invents a name for a message written under a nameless
-  # disclosure mode.
+  # The assistant's original name is stored on new messages. Older assistant
+  # messages fall back to their stored display name, then to configuration or
+  # the author record only when there is no message snapshot. Exported turns
+  # retain AI provenance even when their requester-facing mode is nameless.
   #
   # == Deleted messages are turns too
   #
@@ -204,12 +200,13 @@ module SupportDesk
       end
     end
 
-    # The key the message was stamped with, resolved to the name that key
-    # has NOW — and the stored display name when nothing declares her any
-    # more. A message written by the record rather than by `speak!` (an
-    # import, a host that posts its own) has neither, so the record answers.
+    # Message snapshots survive configuration changes. Imports without a
+    # snapshot use the configured key or author as a legacy fallback.
     def assistant_name(message)
       stamp = provenance(message)
+      return stamp["name"] if stamp["name"].is_a?(String) && stamp["name"].present?
+      return stamp["display_name"] if stamp["display_name"].is_a?(String) && stamp["display_name"].present?
+
       key = stamp["assistant"]
       if key.present? && SupportDesk.config.assistant?(key)
         return SupportDesk.config.assistant(key).name

data/lib/support_desk/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SupportDesk
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
 end

data/lib/support_desk/wizard.rb

@@ -179,11 +179,7 @@ module SupportDesk
     # The promise shown next to the composer ("we usually reply in under a
     # day"), built from `config.reply_within` — one setting, one truth: the
     # same number the SLA breaches on.
-    def promise
-      return nil if promise_within.nil?
-
-      I18n.t("support_desk.thread.promise", time: self.class.humanize_duration(promise_within))
-    end
+    def promise = target_desk.config.reply_promise
 
     # The promise as a Duration, for hosts that want to phrase it themselves.
     def promise_within = target_desk.config.reply_within