collavre 0.22.0 → 0.24.0

data/app/models/concerns/collavre/indexed_json_columns.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Collavre
+  # Keeps denormalized real columns in lockstep with keys stored inside a JSON
+  # column, so database indexes can be defined over plain columns instead of
+  # JSON expressions.
+  #
+  # WHY: A JSON-expression index serializes per-adapter --
+  # `json_extract(config, '$.x')` on SQLite vs `config->>'x'` on PostgreSQL.
+  # Because schema.rb is dumped from the SQLite dev DB, it carries the
+  # `json_extract` form, which is not a PostgreSQL function, so
+  # `db:schema:load` crashes on the prod PostgreSQL database. Promote the JSON
+  # key to a real column (which indexes and dumps identically on both adapters)
+  # and keep it synced from the JSON column on every save. The JSON column
+  # stays the source of truth; the promoted columns are re-derived on each save.
+  #
+  # Usage:
+  #   include Collavre::IndexedJsonColumns
+  #
+  #   indexed_json_columns json: :config, columns: {
+  #     repo_full_name: "repo_full_name",
+  #     pr_number:      "pr_number",
+  #   }
+  #
+  # `json:` names the JSON attribute (source of truth). `columns:` maps each
+  # promoted column to the JSON key it mirrors. A before_save re-derives every
+  # promoted column from the JSON attribute so the plain-column indexes enforce
+  # the same guarantees the JSON-expression indexes did.
+  module IndexedJsonColumns
+    extend ActiveSupport::Concern
+
+    included do
+      class_attribute :indexed_json_source, instance_writer: false, default: nil
+      class_attribute :indexed_json_column_map, instance_writer: false, default: {}.freeze
+    end
+
+    class_methods do
+      def indexed_json_columns(json:, columns:)
+        self.indexed_json_source = json.to_sym
+        self.indexed_json_column_map =
+          columns.each_with_object({}) { |(col, key), m| m[col.to_s] = key.to_s }.freeze
+        before_save :sync_indexed_json_columns
+      end
+    end
+
+    private
+
+    # Re-derive each promoted column from its JSON key. Reads the JSON attribute
+    # (source of truth) and writes through `[]=` so subtype reader overrides are
+    # bypassed and only genuinely changed values dirty the record.
+    def sync_indexed_json_columns
+      json = public_send(indexed_json_source) || {}
+      indexed_json_column_map.each do |column, json_key|
+        self[column] = json[json_key]
+      end
+    end
+  end
+end

data/app/services/collavre/agent_type_classifier.rb

@@ -0,0 +1,23 @@
+module Collavre
+  # Classifies an AI user/agent into a coarse role type by scanning its
+  # system prompt. Shared by the orchestration and system-events context
+  # builders so the prompt-to-type mapping lives in exactly one place.
+  module AgentTypeClassifier
+    module_function
+
+    # Returns the agent type string ("developer", "pm", "qa", "researcher",
+    # "marketer", "planner") or "agent" as the default when nothing matches.
+    def classify(user)
+      prompt = user.system_prompt.to_s.downcase
+      case prompt
+      when /developer|개발/ then "developer"
+      when /pm|project.?manager|프로젝트/ then "pm"
+      when /qa|test|quality|테스트|품질/ then "qa"
+      when /research|조사|연구/ then "researcher"
+      when /market|마케팅/ then "marketer"
+      when /plan|기획/ then "planner"
+      else "agent"
+      end
+    end
+  end
+end

data/app/services/collavre/ai_agent/a2a_dispatcher.rb

@@ -15,6 +15,10 @@ module Collavre
       # Dispatch A2A events if the response mentions any AI agents
       def dispatch
         return unless @reply_comment&.content.present?
+        # An approval-action message (approve button / approved) is a human decision
+        # surface and must never reach an AI agent — not even via an @mention in
+        # another agent's reply. Same invariant as Comment#dispatch_to_orchestration.
+        return if @reply_comment.approval_action?
 
         mentioned_agents = find_mentioned_agents
         return if mentioned_agents.empty?

data/app/services/collavre/ai_agent/message_builder.rb

@@ -146,7 +146,7 @@ module Collavre
         history_chars = 0
         count = 0
 
-        Comment.public_only.where(creative_id: creative_id)
+        Comment.public_only.without_approval_action.where(creative_id: creative_id)
                .where(topic_id: topic_id)
                .where.not(user_id: nil)
                .includes(:user)

data/app/services/collavre/ai_agent/session_provisioner.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+module Collavre
+  module AiAgent
+    # Provisions the identities a Claude Code registration needs:
+    #   - one shared ai_user per (human, agent_name) — the Agent identity
+    #   - one Topic per (agent, session_id) — the Session identity
+    #
+    # Extracted from Api::V1::AgentsController#register so the action stays a
+    # thin orchestration of provisioning + inbox share. Behavior is identical to
+    # the inlined controller methods it replaces.
+    class SessionProvisioner
+      def initialize(user)
+        @user = user
+      end
+
+      # One ai_user per (user, agent_name) so a human's sessions share one Agent
+      # identity. Same agent_name re-registering reuses the existing row —
+      # idempotent retries (and every additional session) don't proliferate
+      # agents.
+      #
+      # Returns nil when a row with the deterministic email already exists but is
+      # owned by someone else or isn't a Claude Channel ai_user. The email format
+      # is human-derivable (user.id + slug + digest), so a foreign row could be
+      # planted by signup/import; silently reusing it would attach the caller's
+      # inbox feedback share to that foreign User and leave the plugin's
+      # AgentChannel subscription rejected on ownership mismatch. Caller renders
+      # 409 in that case.
+      def find_or_create_agent(agent_name)
+        email = session_agent_email(agent_name)
+
+        existing = User.find_by(email: email)
+        return verified_agent(existing) if existing
+
+        # routing_expression: nil so the new ai_user is not matchable until the
+        # client claims the per-agent stream via AgentChannel. See the comment on
+        # verified_agent.
+        User.create!(
+          email: email,
+          name: "Claude Channel (#{agent_name})",
+          password: SecureRandom.hex(32),
+          llm_vendor: "anthropic",
+          llm_model: "claude-code",
+          created_by_id: @user.id,
+          searchable: false,
+          routing_expression: nil
+        )
+      rescue ActiveRecord::RecordNotUnique
+        # A concurrent registration for the same (user, agent_name) won the
+        # users.email unique race. The desired row now exists — re-find and
+        # re-verify ownership instead of surfacing a 500 that aborts one of the
+        # two simultaneously launching plugin instances.
+        verified_agent(User.find_by(email: email))
+      end
+
+      # One Topic per (agent, session_id). On re-register (including --resume from
+      # the same cwd, which yields the same session_id) the existing topic is
+      # reused — even if archived — so the conversation persists instead of
+      # orphaning. A fresh session gets a new topic under the same shared agent,
+      # which is how one agent fans out to many sessions.
+      def find_or_create_topic(inbox, ai_user, session_id, session_label)
+        existing = inbox.topics.find_by(primary_agent_id: ai_user.id, session_id: session_id)
+        return existing if existing
+
+        label = session_label.to_s.strip.presence || session_id
+        inbox.topics.create!(
+          name: unique_topic_name(inbox, "Claude #{label}"),
+          user: @user,
+          primary_agent_id: ai_user.id,
+          session_id: session_id
+        )
+      end
+
+      private
+
+      # Deterministic, collision-free email key for a (user, agent_name) agent.
+      # The readable slug is lossy — "qa/bot", "qa bot" and "qa--bot" all squeeze
+      # to "qa-bot", and any all-symbol name collapses to "session" — so a short
+      # digest of the normalized raw name disambiguates distinct configured names
+      # that would otherwise alias onto ONE shared agent identity (ActionCable
+      # stream, routing state, tasks, creative shares). The slug stays for human
+      # readability; the digest decides identity. Same normalized name -> same
+      # key, so idempotent re-register/reuse is preserved. Normalization
+      # (strip+downcase) keeps case/whitespace-only differences folded, matching
+      # the prior behavior — only the lossy punctuation/spacing collapse is fixed.
+      def session_agent_email(agent_name)
+        normalized = agent_name.to_s.strip.downcase
+        slug = normalized.gsub(/[^a-z0-9-]+/, "-").squeeze("-").gsub(/\A-|-\z/, "")
+        slug = "session" if slug.blank?
+        digest = Digest::SHA256.hexdigest(normalized)[0, 10]
+        "claude-channel-#{@user.id}-#{slug}-#{digest}@agent.collavre.local"
+      end
+
+      # Returns the agent only when it is the current user's own Claude Channel
+      # agent; nil otherwise (the caller renders :conflict). Routing activation
+      # stays deferred to AgentChannel#subscribe_to_agent_stream so the agent
+      # becomes matchable only once a WebSocket subscriber exists for
+      # agent:user:<id> — otherwise comments matched between register returning
+      # and the client's subsequent cable subscribe would broadcast into an empty
+      # stream, stranding delegated tasks until stuck recovery.
+      def verified_agent(ai_user)
+        return nil unless ai_user &&
+                          ai_user.created_by_id == @user.id &&
+                          ai_user.ai_user? &&
+                          ai_user.claude_channel_agent?
+
+        ai_user
+      end
+
+      # Topics carry a UNIQUE (creative_id, name) index, so two sessions whose
+      # friendly labels collide (e.g. both rooted at a dir named "src") cannot
+      # share a name. Append the smallest numeric suffix that is free.
+      def unique_topic_name(inbox, desired)
+        return desired unless inbox.topics.exists?(name: desired)
+
+        n = 2
+        loop do
+          candidate = "#{desired} (#{n})"
+          return candidate unless inbox.topics.exists?(name: candidate)
+
+          n += 1
+        end
+      end
+    end
+  end
+end

data/app/services/collavre/ai_agent/task_claim_service.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module Collavre
+  module AiAgent
+    # Atomically claims and finalizes a delegated task on behalf of a Claude
+    # Channel /reply. Extracted from Api::V1::AgentsController#reply so the
+    # controller only sequences: claim -> save comment -> finalize. Behavior is
+    # identical to the inlined controller methods it replaces.
+    class TaskClaimService
+      # Atomically claim a delegated task for completion. Two-step:
+      #   1. Find a candidate task in delegated state, scoped to this agent +
+      #      topic. With task_id supplied, exact match (required under topic
+      #      concurrency > 1 where multiple delegated tasks coexist; the client
+      #      echoes the dispatch's task_id). Without task_id (legacy clients),
+      #      oldest-first.
+      #   2. Inside a transaction: SELECT FOR UPDATE the row, re-check
+      #      status == 'delegated' under the lock, then update! to 'done'.
+      #      Concurrent claimers block on the lock; the loser sees the
+      #      already-flipped status post-lock and returns nil so the caller can
+      #      refuse the duplicate.
+      # update_all (NOT update!) is required to skip Task's after_update_commit
+      # callbacks at claim time. The callbacks fire check_trigger_loop_completion
+      # (which enqueues TriggerLoopCheckJob) and broadcast_stop_button_removal
+      # (which reads reply_comment). Both depend on the reply comment already
+      # existing — but reply() claims BEFORE comment.save to win the race against
+      # concurrent /reply calls. If update! fired the trigger-loop check here, the
+      # job could run (cooldown_seconds: 0) before comment.save commits, find no
+      # agent comment, and leave the loop stuck in "running". #finalize replays
+      # both callbacks after the comment is persisted via
+      # Task#fire_completion_callbacks_after_external_claim.
+      def claim(agent:, topic:, requested_task_id:)
+        scope = Task.where(agent_id: agent.id, topic_id: topic.id, status: "delegated")
+        candidate =
+          if requested_task_id.present?
+            scope.find_by(id: requested_task_id)
+          else
+            scope.order(:created_at).first
+          end
+        return nil unless candidate
+
+        claimed = nil
+        Task.transaction do
+          locked = Task.lock.find_by(id: candidate.id)
+          next unless locked && locked.status == "delegated"
+
+          Task.where(id: locked.id).update_all(status: "done", pending_tool_call: nil, updated_at: Time.current)
+          claimed = locked.reload
+        end
+        claimed
+      end
+
+      # Post-claim side effects, run only after the reply comment is saved. Links
+      # the comment to the claimed task, releases the ResourceTracker slot the
+      # AiAgentJob held under task.id, advances the parent workflow (if any), and
+      # drains the topic queue — mirroring AiAgentJob#perform's success path for
+      # non-delegated runs.
+      def finalize(agent:, task:, comment:)
+        comment.update_column(:task_id, task.id)
+
+        Orchestration::ResourceTracker.for(agent).release!(task.id)
+
+        if task.parent_task_id.present?
+          Collavre::Comments::WorkflowExecutor.new(task.parent_task).complete_subtask!(task)
+        end
+
+        Orchestration::AgentOrchestrator.dequeue_next_for_topic(task.topic_id, task.creative_id)
+
+        # Replay the after_update_commit callbacks that were bypassed by
+        # update_all in #claim — now that the reply comment is linked,
+        # TriggerLoopCheckJob can read it and decide whether to advance/await/
+        # complete the drop-trigger loop, and the stop-button broadcast has a
+        # comment to render.
+        task.fire_completion_callbacks_after_external_claim
+
+        # Clear the typing indicator immediately on reply. ClaudeChannelPresenceJob
+        # would also stop on its next beat (task no longer "delegated"), but that
+        # is up to HEARTBEAT_SECONDS away — broadcast idle now so the indicator
+        # drops the moment Claude's reply lands.
+        broadcast_claude_idle(agent, task, comment)
+      end
+
+      private
+
+      # Clear the chat typing indicator via the canonical status broadcaster (the
+      # same one AiAgentService uses for every other agent), so the Claude path
+      # emits an identical "idle" agent_status payload.
+      def broadcast_claude_idle(agent, task, comment)
+        creative = comment.creative&.effective_origin
+        return unless creative
+
+        AiAgent::AgentLifecycleManager.new(task: task, agent: agent, creative: creative)
+                                      .broadcast_status("idle")
+      end
+    end
+  end
+end

data/app/services/collavre/ai_client.rb

@@ -10,13 +10,61 @@ module Collavre
 
     attr_reader :last_input_tokens, :last_output_tokens
 
-    def initialize(vendor:, model:, system_prompt:, llm_api_key: nil, gateway_url: nil, context: {})
+    # Vendor <select> options for AI-agent config. Core ships only its built-in
+    # (stateless) providers; vendor engines append their own through
+    # register_vendor_option, so core never names a vendor engine.
+    BASE_VENDOR_OPTIONS = [
+      [ "Google (Gemini)", "google" ],
+      [ "OpenAI", "openai" ],
+      [ "Anthropic", "anthropic" ]
+    ].freeze
+
+    class << self
+      def registered_vendor_options
+        @registered_vendor_options ||= []
+      end
+
+      # Append a vendor <select> option ([label, value]). Idempotent by value.
+      def register_vendor_option(label, value)
+        value = value.to_s
+        return if BASE_VENDOR_OPTIONS.any? { |_l, v| v == value }
+        return if registered_vendor_options.any? { |_l, v| v == value }
+
+        registered_vendor_options << [ label, value ]
+      end
+
+      def vendor_options
+        BASE_VENDOR_OPTIONS + registered_vendor_options
+      end
+
+      # Vendors that use stateful/incremental sessions. Base providers are
+      # stateless; vendor engines that add session support register here so core
+      # never string-matches a vendor name to decide session behavior.
+      def session_vendors
+        @session_vendors ||= Set.new
+      end
+
+      def register_session_vendor(vendor)
+        session_vendors << vendor.to_s.downcase
+      end
+
+      def vendor_supports_session?(vendor)
+        session_vendors.include?(vendor.to_s.downcase)
+      end
+    end
+
+    # log_interactions: persist each call to ActivityLog. Default true. Pass false
+    # for ephemeral, high-frequency calls on text the user has not submitted (e.g.
+    # inline typo correction on debounced typing) so private drafts are never
+    # written to server-side activity logs.
+    def initialize(vendor:, model:, system_prompt:, llm_api_key: nil, gateway_url: nil, context: {}, log_interactions: true)
       @vendor = vendor
       @model = model
       @system_prompt = system_prompt
       @llm_api_key = llm_api_key
       @gateway_url = gateway_url
       @context = context
+      @log_interactions = log_interactions
       @last_input_tokens = 0
       @last_output_tokens = 0
     end
@@ -36,8 +84,16 @@ module Collavre
       add_messages(@conversation, contents)
 
       response = @conversation.complete do |chunk|
-        delta = extract_chunk_content(chunk)
-        next if delta.blank?
+        delta = extract_chunk_content(chunk).to_s
+        # Deliberately NOT `blank?`. A delta of exactly "\n\n" — the paragraph
+        # break, which providers routinely emit as a token of its own — is
+        # blank? == true, so skipping blanks deletes it. And the deleted delta is
+        # never yielded, so it is gone from the caller's stream too: AiAgentService
+        # persists ResponseStreamer#content, which is built only from the yielded
+        # deltas, and the reply lands in the database with its paragraphs glued
+        # together. Only truly empty deltas (role-only / tool-call chunks carry no
+        # content) are skippable.
+        next if delta.empty?
 
         response_content << delta
         yield delta if block_given?
@@ -64,7 +120,13 @@ module Collavre
       raise # Re-raise cancellation errors without catching them
     rescue StandardError => e
       error_message = "[#{e.class.name}] #{e.message}"
-      Rails.logger.error "AI Client error: #{error_message}"
+      # When log_interactions is false (inline typo correction runs on the user's
+      # *unsubmitted* draft), the LLM error message can echo the request text. Log
+      # only the error class to app logs so private drafts never leak — matching the
+      # no-log guarantee already enforced on the parse path (TypoCorrector) and the
+      # ActivityLog gate below. error_message stays intact for the gated ensure log
+      # and the streamed yield (which goes back to the same user).
+      Rails.logger.error "AI Client error: #{@log_interactions ? error_message : "[#{e.class.name}]"}"
       Rails.logger.error "Partial response length: #{response_content.length} chars" if response_content.present?
       Rails.logger.debug e.backtrace.join("\n")
       yield "\n\n⚠️ AI Error: #{error_message}" if block_given?
@@ -72,14 +134,16 @@ module Collavre
     ensure
       @last_input_tokens = input_tokens || 0
       @last_output_tokens = output_tokens || 0
-      log_interaction(
-        messages: @conversation&.messages&.to_a || Array(contents),
-        tools: @conversation&.tools&.to_a || [],
-        response_content: response_content.presence,
-        error_message: error_message,
-        input_tokens: input_tokens,
-        output_tokens: output_tokens
-      )
+      if @log_interactions
+        log_interaction(
+          messages: @conversation&.messages&.to_a || Array(contents),
+          tools: @conversation&.tools&.to_a || [],
+          response_content: response_content.presence,
+          error_message: error_message,
+          input_tokens: input_tokens,
+          output_tokens: output_tokens
+        )
+      end
     end
 
     # Ask a follow-up question using the existing conversation context.
@@ -115,6 +179,11 @@ module Collavre
       when "openai"
         api_key = @llm_api_key.presence || IntegrationSettings.fetch(:openai_api_key)
         base_url = @gateway_url.presence
+        # A custom OpenAI-compatible gateway (local Ollama / LM Studio, etc.) needs
+        # no real OpenAI key, but RubyLLM raises ConfigurationError before sending
+        # if openai_api_key is blank. Supply a placeholder so keyless local gateways
+        # work; hosted OpenAI (no gateway) still requires a real key.
+        api_key = "local-gateway" if api_key.blank? && base_url
         proc do |config|
           config.openai_api_key = api_key
           config.openai_api_base = base_url if base_url

data/app/services/collavre/auto_theme_generator.rb

@@ -57,7 +57,20 @@ module Collavre
     end
 
     def generate(prompt)
-      system_prompt = <<~PROMPT
+      parse_response(request_theme(prompt))
+    end
+
+    private
+
+    def request_theme(prompt)
+      @client.chat([
+        { role: :system, parts: [ { text: system_prompt } ] },
+        { role: :user, parts: [ { text: "Create a theme description: #{prompt}" } ] }
+      ])
+    end
+
+    def system_prompt
+      <<~PROMPT
         You are a color theme designer for a workspace app.
         Generate a JSON with ONLY these keys: #{REQUIRED_VARIABLES.join(', ')}.
 
@@ -181,21 +194,12 @@ module Collavre
              For dark/accent themes, h1 can use a subtle darker surface. Must not clash with text.
            - For playful themes, vary heading colors. For minimal themes, keep sizes uniform.
       PROMPT
-
-      response = @client.chat([
-        { role: :system, parts: [ { text: system_prompt } ] },
-        { role: :user, parts: [ { text: "Create a theme description: #{prompt}" } ] }
-      ])
-
-      parse_response(response)
     end
 
-    private
-
     def default_client
       AiClient.new(
         vendor: "google",
-        model: "gemini-3-flash-preview",
+        model: "gemini-3.1-flash-lite",
         system_prompt: nil
       )
     end

data/app/services/collavre/creatives/children_index.rb

@@ -0,0 +1,86 @@
+module Collavre
+module Creatives
+  # Per-level batch answer to "which children does this node show?" for the
+  # browse tree, replacing a per-node `children_with_permission` call.
+  #
+  # Presence (`has_children?`) is resolved for every node in a level with one
+  # plucked scan plus one batched PermissionFilter; the full child rows are
+  # materialized only for the nodes that actually render them (expanded, or a
+  # filter forcing the subtree open). Presence and content are derived from the
+  # same candidate set, so an expand toggle can never open an empty branch or
+  # hide a reachable subtree — a drift that would also leak the existence of
+  # children the user cannot see.
+  #
+  # Children of a linked shell live under its effective origin, so every lookup
+  # resolves the shell to its origin first. Preload `:origin` on the level before
+  # indexing it, or that resolution costs a query per shell.
+  class ChildrenIndex
+    def initialize(user:, show_archived:, allowed_creative_ids: nil)
+      @user = user
+      @show_archived = show_archived
+      @allowed_creative_ids = allowed_creative_ids
+      @child_ids_by_creative = {}
+      @rows_by_child_id = {}
+    end
+
+    # Scans a level. Only creatives not seen before cost anything, so the
+    # recursive descent pays two queries per level, not per node.
+    def index(creatives)
+      pending = creatives.reject { |c| @child_ids_by_creative.key?(c.id) }
+      return if pending.empty?
+
+      origin_id_by_id = pending.to_h { |c| [ c.id, c.effective_origin.id ] }
+
+      candidates = Creative.where(parent_id: origin_id_by_id.values.uniq)
+      candidates = candidates.where(archived_at: nil) unless show_archived
+      rows = candidates.order(:sequence).pluck(:id, :parent_id)
+
+      visible_by_origin = visible_child_ids_by_origin(rows)
+      pending.each do |creative|
+        @child_ids_by_creative[creative.id] = visible_by_origin[origin_id_by_id[creative.id]] || []
+      end
+    end
+
+    def has_children?(creative)
+      child_ids(creative).any?
+    end
+
+    # Materializes the child rows of `creatives` in a single query. Called only
+    # for the nodes whose children actually render.
+    def load(creatives)
+      wanted = creatives.flat_map { |c| child_ids(c) }.uniq - @rows_by_child_id.keys
+      return if wanted.empty?
+
+      Creative.where(id: wanted).each { |child| @rows_by_child_id[child.id] = child }
+    end
+
+    # Sequence-ordered, permission- and archive-filtered children. Empty unless
+    # `load` has materialized them.
+    def children_for(creative)
+      child_ids(creative).filter_map { |id| @rows_by_child_id[id] }
+    end
+
+    private
+
+    attr_reader :user, :show_archived, :allowed_creative_ids
+
+    # `rows` arrive in sequence order, so the per-origin lists inherit it.
+    def visible_child_ids_by_origin(rows)
+      return {} if rows.empty?
+
+      readable = PermissionFilter.new(user: user).readable_ids(rows.map(&:first)).to_set
+
+      rows.each_with_object({}) do |(child_id, origin_id), acc|
+        next unless readable.include?(child_id)
+        next if allowed_creative_ids && !allowed_creative_ids.include?(child_id.to_s)
+
+        (acc[origin_id] ||= []) << child_id
+      end
+    end
+
+    def child_ids(creative)
+      @child_ids_by_creative.fetch(creative.id, [])
+    end
+  end
+end
+end

data/app/services/collavre/creatives/comment_badge_index.rb

@@ -0,0 +1,73 @@
+module Collavre
+module Creatives
+  # Batches the browse tree's comment badge. Per node this was two queries — a
+  # read-pointer lookup and an unread COUNT — which is what made the badge cost
+  # scale with the size of the rendered tree.
+  #
+  # Keyed by *origin*: a linked shell shows its origin's comments.
+  class CommentBadgeIndex
+    def initialize(user:)
+      @user = user
+      @unread_by_origin_id = {}
+    end
+
+    def index(origins)
+      pending = origins.uniq(&:id).reject { |o| @unread_by_origin_id.key?(o.id) }
+      return if pending.empty?
+
+      watermarks = read_watermarks(pending.map(&:id))
+
+      # No read pointer means nothing has been read yet, so every comment counts
+      # as unread — including private ones, matching the counter cache.
+      pending.each do |origin|
+        @unread_by_origin_id[origin.id] = origin.comments_count unless watermarks.key?(origin.id)
+      end
+
+      counts = unread_counts(watermarks)
+      watermarks.each_key { |origin_id| @unread_by_origin_id[origin_id] = counts.fetch(origin_id, 0) }
+    end
+
+    # nil when the origin was never indexed, which tells the caller to fall back
+    # to the single-creative path rather than silently render a zero badge.
+    def unread_count_for(origin)
+      @unread_by_origin_id[origin.id]
+    end
+
+    private
+
+    attr_reader :user
+
+    # `user_id: nil` for an anonymous visitor is the lookup the un-batched path
+    # made too, so the two agree on which pointer (if any) applies.
+    def read_watermarks(origin_ids)
+      return {} if origin_ids.empty?
+
+      CommentReadPointer
+        .where(user_id: user&.id, creative_id: origin_ids)
+        .where.not(last_read_comment_id: nil)
+        .pluck(:creative_id, :last_read_comment_id)
+        .to_h
+    end
+
+    # One grouped COUNT for the whole level. Each origin carries its own read
+    # watermark, so the thresholds are OR-ed together rather than shared. Built
+    # from relations rather than a SQL fragment: a hand-built string here would
+    # be safe (literal template, bound values) but unprovably so to a scanner.
+    def unread_counts(watermarks)
+      return {} if watermarks.empty?
+
+      newer_than_watermark = watermarks
+        .map { |origin_id, last_read_id| unread_scope(origin_id, last_read_id) }
+        .reduce { |combined, scope| combined.or(scope) }
+
+      Comment.where(private: false).merge(newer_than_watermark).group(:creative_id).count
+    end
+
+    def unread_scope(origin_id, last_read_id)
+      Comment
+        .where(creative_id: origin_id)
+        .where(Comment.arel_table[:id].gt(last_read_id))
+    end
+  end
+end
+end