woods 1.6.1 → 2.0.0.beta2

data/lib/woods/resilience/retryable_provider.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative '../embedding/provider'
+require_relative '../retry_after'
 require_relative 'circuit_breaker'
 
 module Woods
@@ -26,6 +27,17 @@ module Woods
     class RetryableProvider
       include Woods::Embedding::Provider::Interface
 
+      # @return [#embed, #embed_batch] the wrapped (raw) embedding provider.
+      #   Exposed so builders can reach the concrete class for tokenizer
+      #   calibration (see Builder#chars_per_token_for) without unwinding
+      #   the resilience stack by hand.
+      attr_reader :provider
+
+      # @return [CircuitBreaker, nil] the breaker guarding this provider's
+      #   calls, or nil when none was configured. Per-instance by design —
+      #   never share one breaker across unrelated components.
+      attr_reader :circuit_breaker
+
       # @param provider [#embed, #embed_batch, #dimensions, #model_name] The underlying embedding provider
       # @param max_retries [Integer] Maximum number of retry attempts
       # @param circuit_breaker [CircuitBreaker, nil] Optional circuit breaker instance
@@ -71,13 +83,20 @@ module Woods
 
       # Delegate the per-provider input cap. The retry wrapper does not
       # change the provider's budget, so just hand through whatever the
-      # inner provider reports. Without this, `respond_to?` returns true
-      # via Interface but the call raises NotImplementedError.
+      # inner provider reports. `respond_to?` alone is the wrong guard
+      # here: {Woods::Embedding::Provider::Interface} *defines*
+      # +max_input_tokens+ as a +NotImplementedError+ stub, so a provider
+      # that merely includes the interface without overriding it still
+      # answers +respond_to?+ with +true+ (B-108) and raises when called.
+      # A provider with no such method at all still needs the
+      # +respond_to?+ guard to avoid a bare +NoMethodError+.
       #
       # @return [Integer, nil]
       def max_input_tokens
-        return @provider.max_input_tokens if @provider.respond_to?(:max_input_tokens)
+        return nil unless @provider.respond_to?(:max_input_tokens)
 
+        @provider.max_input_tokens
+      rescue NotImplementedError
         nil
       end
 
@@ -90,18 +109,27 @@ module Woods
       # `BACKOFF_BASE * 2**attempt` with full jitter applied on top.
       BACKOFF_BASE = 0.1
 
+      # Upper bound honored for a server-supplied +Retry-After+. Bounds a
+      # hostile or misconfigured header (e.g. an HTTP-date hours away) so a
+      # single throttled call cannot stall the embed pipeline indefinitely;
+      # real rate-limit windows sit well under this.
+      MAX_RETRY_AFTER_SECONDS = 120.0
+
       private
 
       # Execute a block with retry logic, exponential backoff, and jitter.
       #
       # Argument errors surface immediately (non-retryable — they indicate
       # a programming mistake or invalid input, not a transient failure).
+      # Errors carrying a non-retryable HTTP status (see {#retryable_error?})
+      # also surface immediately — retrying a 401 only delays the real error.
       #
       # @yield The block to execute
       # @return [Object] The return value of the block
       # @raise [CircuitOpenError] immediately without retrying
       # @raise [ArgumentError] immediately without retrying
-      # @raise [StandardError] the last error if all retries are exhausted
+      # @raise [StandardError] the last error if all retries are exhausted,
+      #   or the first error when it is classified non-retryable
       def with_retries
         attempt = 0
         begin
@@ -110,13 +138,50 @@ module Woods
         rescue CircuitOpenError, ArgumentError
           raise
         rescue StandardError => e
-          raise e if attempt > @max_retries
+          raise e if attempt > @max_retries || !retryable_error?(e)
 
-          sleep(backoff_seconds(attempt))
+          sleep(retry_delay(e, attempt))
           retry
         end
       end
 
+      # Decide whether an error is worth retrying.
+      #
+      # Errors that expose an HTTP status (duck-typed on +#http_status+ —
+      # {Woods::Embedding::Provider::RequestError} is the canonical shape)
+      # are classified precisely: 429 (rate limit), 408 (request timeout),
+      # and 5xx are transient; every other 4xx is a request or credential
+      # problem no retry can fix, so burning the retry budget (and sleeping
+      # between attempts) only postpones the real error. Status-less errors
+      # — connection resets, socket timeouts, legacy Woods::Error strings —
+      # keep the historical retry-everything behavior.
+      #
+      # @param error [StandardError]
+      # @return [Boolean] true when the error should be retried
+      def retryable_error?(error)
+        status = error.respond_to?(:http_status) ? error.http_status : nil
+        return true unless status.is_a?(Integer)
+
+        status == 429 || status == 408 || status >= 500
+      end
+
+      # Seconds to sleep before the next retry. A server-supplied
+      # +Retry-After+ (parsed via {Woods::RetryAfter}, which handles both
+      # the delta-seconds and HTTP-date forms) takes precedence over the
+      # local backoff schedule, capped at {MAX_RETRY_AFTER_SECONDS};
+      # without one, full-jitter exponential backoff applies.
+      #
+      # @param error [StandardError] the error that triggered the retry
+      # @param attempt [Integer] 1-based attempt counter
+      # @return [Float] seconds to sleep before the next retry
+      def retry_delay(error, attempt)
+        fallback = backoff_seconds(attempt)
+        header = error.respond_to?(:retry_after) ? error.retry_after : nil
+        return fallback if header.nil?
+
+        RetryAfter.seconds(header, fallback: fallback, max: MAX_RETRY_AFTER_SECONDS)
+      end
+
       # Full-jitter exponential backoff with a hard cap. See "Exponential
       # Backoff and Jitter", AWS Architecture Blog (Marc Brooker, 2015):
       # a uniformly random delay in [0, base*2**attempt] de-correlates

data/lib/woods/resolved_config.rb

@@ -44,6 +44,9 @@ module Woods
     # @return [Hash] Store types — :vector_store, :metadata_store, :graph_store (Symbols)
     attr_reader :stores
 
+    # @return [Hash] Non-secret options required to reopen durable stores
+    attr_reader :store_options
+
     # Parse a +woods.json+ hash into a {ResolvedConfig}.
     #
     # @param raw [Hash] Parsed JSON hash (string or symbol keys)
@@ -58,7 +61,8 @@ module Woods
         gem_version: data[:gem_version].to_s,
         created_at: parse_time(data[:created_at]),
         embedding_provider: parse_provider(data[:embedding_provider] || {}),
-        stores: parse_stores(data[:stores] || {})
+        stores: parse_stores(data[:stores] || {}),
+        store_options: parse_store_options(data[:store_options] || {})
       )
     end
 
@@ -82,17 +86,18 @@ module Woods
     def self.from_configuration(config, gem_version: nil, provider: nil) # rubocop:disable Metrics/MethodLength,Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
       require_relative 'version'
 
-      opts = config.embedding_options || {}
-      declared_dim = opts[:dimension] || opts['dimension']
-      dim = declared_dim || (provider.respond_to?(:dimensions) ? provider.dimensions : nil)
+      opts = (config.embedding_options || {}).transform_keys(&:to_sym)
+      declared_dim = opts[:dimensions] || opts[:dimension] || opts[:dims]
+      dim = provider.respond_to?(:dimensions) ? provider.dimensions : declared_dim
+      model = provider.respond_to?(:model_name) ? provider.model_name : (opts[:model] || config.embedding_model)
 
       provider_hash = {
         class: resolve_provider_class(config.embedding_provider),
-        model: (opts[:model] || opts['model'] || config.embedding_model).to_s,
+        model: model.to_s,
         dimension: dim.to_i,
-        host: opts[:host] || opts['host'],
-        num_ctx: opts[:num_ctx] || opts['num_ctx'],
-        read_timeout: opts[:read_timeout] || opts['read_timeout']
+        host: opts[:host],
+        num_ctx: opts[:num_ctx],
+        read_timeout: opts[:read_timeout]
       }.compact
 
       new(
@@ -104,7 +109,8 @@ module Woods
           vector_store: config.vector_store,
           metadata_store: config.metadata_store,
           graph_store: config.graph_store
-        }
+        },
+        store_options: durable_store_options(config)
       )
     end
 
@@ -113,12 +119,13 @@ module Woods
     # @param created_at [Time]
     # @param embedding_provider [Hash]
     # @param stores [Hash]
-    def initialize(schema_version:, gem_version:, created_at:, embedding_provider:, stores:)
+    def initialize(schema_version:, gem_version:, created_at:, embedding_provider:, stores:, store_options: {}) # rubocop:disable Metrics/ParameterLists
       @schema_version = schema_version
       @gem_version = gem_version.to_s.freeze
       @created_at = created_at
       @embedding_provider = deep_freeze(embedding_provider)
       @stores = deep_freeze(stores)
+      @store_options = deep_freeze(store_options)
       freeze
     end
 
@@ -127,6 +134,20 @@ module Woods
       embedding_provider[:dimension].to_i
     end
 
+    # Model recorded in +embedding_provider[:model]+.
+    #
+    # {Storage::Snapshotter::Vector.dump} guards its call with
+    # +resolved_config.respond_to?(:model_name)+ before writing the WVF1
+    # header's model field — that guard passed for every {ResolvedConfig}
+    # even with no +#model_name+ defined, so the header's model was always
+    # +''+ and no dump could say which model produced it.
+    #
+    # @return [String, nil] the model name, or nil when absent
+    def model_name
+      model = embedding_provider[:model].to_s
+      model.empty? ? nil : model
+    end
+
     # Short string identifying this provider configuration, useful for log
     # messages and {ConfigMismatch} error text.
     #
@@ -175,7 +196,8 @@ module Woods
         'gem_version' => gem_version,
         'created_at' => created_at.iso8601,
         'embedding_provider' => embedding_provider.transform_keys(&:to_s),
-        'stores' => stores.transform_keys(&:to_s).transform_values(&:to_s)
+        'stores' => stores.transform_keys(&:to_s).transform_values(&:to_s),
+        'store_options' => stringify_nested_keys(store_options)
       }
     end
 
@@ -186,6 +208,13 @@ module Woods
 
     private
 
+    def stringify_nested_keys(value)
+      return value.transform_keys(&:to_s).transform_values { |item| stringify_nested_keys(item) } if value.is_a?(Hash)
+      return value.map { |item| stringify_nested_keys(item) } if value.is_a?(Array)
+
+      value
+    end
+
     # Recursively freeze a Hash and every Hash/Array/String it transitively
     # holds. The previous shallow `.freeze` left nested Hash values mutable
     # — a caller reaching `config.embedding_provider[:options][:foo] = …`
@@ -279,6 +308,20 @@ module Woods
         }
       end
 
+      DURABLE_VECTOR_OPTION_KEYS = %i[collection dimensions distance allow_private_hosts table schema].freeze
+      private_constant :DURABLE_VECTOR_OPTION_KEYS
+
+      def durable_store_options(config)
+        vector = normalize_keys(config.vector_store_options || {}).slice(*DURABLE_VECTOR_OPTION_KEYS)
+        vector.empty? ? {} : { vector_store: vector }
+      end
+
+      def parse_store_options(raw)
+        data = normalize_keys(raw)
+        vector = normalize_keys(data[:vector_store] || {}).slice(*DURABLE_VECTOR_OPTION_KEYS)
+        vector.empty? ? {} : { vector_store: vector }
+      end
+
       def parse_time(value)
         value ? Time.parse(value.to_s) : Time.now.utc
       end
@@ -291,6 +334,7 @@ module Woods
         case provider
         when :openai then 'Woods::Embedding::Provider::OpenAI'
         when :ollama then 'Woods::Embedding::Provider::Ollama'
+        when :fake   then 'Woods::Embedding::Provider::Fake'
         when String  then provider
         when Class   then provider.name
         when nil     then ''

data/lib/woods/retrieval/context_assembler.rb

@@ -8,14 +8,12 @@ module Woods
     # Transforms ranked search candidates into a token-budgeted context string
     # for LLM consumption.
     #
-    # Allocates a fixed token budget across four sections:
-    # - Structural (10%): Always-included codebase overview
-    # - Primary (50%): Direct query results
-    # - Supporting (25%): Dependencies and related context
-    # - Framework (15%): Rails/gem source when query has framework context
-    #
-    # When framework context is not needed, primary and supporting sections
-    # receive the framework allocation proportionally.
+    # Allocates a fixed token budget in two passes:
+    # - Structural (10% of the total budget): Always-included codebase overview
+    # - Everything else splits what's LEFT after structural is carved out
+    #   ({#compute_section_budgets}), not the total budget directly:
+    #   - Framework context active: Primary 55%, Supporting 25%, Framework 20%
+    #   - Framework context inactive: Primary 65%, Supporting 35%, Framework 0%
     #
     # @example
     #   assembler = ContextAssembler.new(metadata_store: store)
@@ -27,11 +25,30 @@ module Woods
     class ContextAssembler
       DEFAULT_BUDGET = 8000 # tokens
 
+      # Only +:structural+ is read directly ({#add_structural_section}) — it
+      # is a fraction of the TOTAL budget. The other sections split what
+      # remains after structural is carved out and have two different
+      # fraction sets depending on +classification.framework_context+, which
+      # a single flat hash can't express; see {FRAMEWORK_ACTIVE_ALLOCATION}
+      # and {FRAMEWORK_INACTIVE_ALLOCATION}.
       BUDGET_ALLOCATION = {
-        structural: 0.10,
-        primary: 0.50,
+        structural: 0.10
+      }.freeze
+
+      # Fractions of the REMAINING (post-structural) budget when the query
+      # has framework context. Read by {#compute_section_budgets}.
+      FRAMEWORK_ACTIVE_ALLOCATION = {
+        primary: 0.55,
         supporting: 0.25,
-        framework: 0.15
+        framework: 0.20
+      }.freeze
+
+      # Fractions of the REMAINING (post-structural) budget when the query
+      # has no framework context — the framework section gets nothing, and
+      # its share isn't proportionally added to primary/supporting.
+      FRAMEWORK_INACTIVE_ALLOCATION = {
+        primary: 0.65,
+        supporting: 0.35
       }.freeze
 
       # Minimum token count for a section to be worth including.
@@ -91,6 +108,7 @@ module Woods
         sections = []
         sources = []
         tokens_used = 0
+        @skipped_missing_metadata = 0
 
         # Collapse +User#chunk_0+, +User#chunk_1+, … back to their base unit
         # BEFORE metadata lookup and section assembly. Chunk IDs are an
@@ -109,16 +127,9 @@ module Woods
         budgets = compute_section_budgets(effective_budget - tokens_used, classification)
 
         # 3. Primary, supporting, and framework sections
-        add_candidate_section(sections, sources, :primary,
-                              candidates.reject { |c| c.source == :graph_expansion }, budgets[:primary])
-        add_candidate_section(sections, sources, :supporting,
-                              candidates.select { |c| c.source == :graph_expansion }, budgets[:supporting])
-        if budgets[:framework].positive?
-          add_candidate_section(sections, sources, :framework,
-                                candidates.select { |c| framework_candidate?(c) }, budgets[:framework])
-        end
+        add_result_sections(sections, sources, candidates, budgets)
 
-        build_result(sections, sources, effective_budget)
+        build_result(sections, sources, effective_budget, @skipped_missing_metadata)
       end
 
       private
@@ -159,7 +170,8 @@ module Woods
           identifier: new_identifier,
           score: candidate.score,
           source: candidate.source,
-          metadata: candidate.metadata
+          metadata: candidate.metadata,
+          matched_fields: candidate.matched_fields
         )
       end
 
@@ -175,6 +187,54 @@ module Woods
         tokens_used + estimate_tokens(text)
       end
 
+      # Partition candidates into the primary/supporting/framework sections
+      # and append each section's content.
+      #
+      # The three sections are a strict PARTITION, not overlapping selects.
+      # When the framework budget is active, framework-source candidates
+      # (rails_source / gem_source) are formatted ONLY in the framework
+      # section — previously a vector-sourced rails_source hit landed in
+      # primary AND framework, spending both budgets on the same source
+      # text (#186 / B-074). When the framework budget is zero (no
+      # framework context), framework candidates stay in their natural
+      # primary/supporting bucket, preserving the pre-fix behaviour.
+      #
+      # @param sections [Array<Hash>] Section accumulator (mutated)
+      # @param sources [Array<Hash>] Source-attribution accumulator (mutated)
+      # @param candidates [Array<Candidate>] Ranked, chunk-collapsed candidates
+      # @param budgets [Hash<Symbol, Integer>] Per-section token budgets
+      # @return [void]
+      def add_result_sections(sections, sources, candidates, budgets)
+        framework_active = budgets[:framework].positive?
+        framework, local = if framework_active
+                             candidates.partition { |c| framework_candidate?(c) }
+                           else
+                             [[], candidates]
+                           end
+
+        supporting_candidates, primary_candidates = local.partition { |c| c.source == :graph_expansion }
+        budgets = reclaim_empty_supporting_budget(budgets, supporting_candidates)
+
+        add_candidate_section(sections, sources, :primary, primary_candidates, budgets[:primary])
+        add_candidate_section(sections, sources, :supporting, supporting_candidates, budgets[:supporting])
+        add_candidate_section(sections, sources, :framework, framework, budgets[:framework]) if framework_active
+      end
+
+      # The supporting section only ever holds :graph_expansion candidates
+      # ({#add_result_sections}), so a query where no graph expansion ran
+      # reserves a supporting budget it can never spend. Rolling that
+      # reservation into primary before assembly recovers it instead of
+      # stranding it.
+      #
+      # @param budgets [Hash<Symbol, Integer>]
+      # @param supporting_candidates [Array<Candidate>]
+      # @return [Hash<Symbol, Integer>]
+      def reclaim_empty_supporting_budget(budgets, supporting_candidates)
+        return budgets unless supporting_candidates.empty?
+
+        budgets.merge(primary: budgets[:primary] + budgets[:supporting], supporting: 0)
+      end
+
       # Add a candidate-based section if candidates produce content.
       #
       # @return [void]
@@ -188,24 +248,18 @@ module Woods
         sources.concat(section_sources)
       end
 
-      # Compute token budgets for primary/supporting/framework sections.
+      # Compute token budgets for primary/supporting/framework sections from
+      # {FRAMEWORK_ACTIVE_ALLOCATION} / {FRAMEWORK_INACTIVE_ALLOCATION}.
       #
       # @param remaining [Integer] Tokens available after structural
       # @param classification [QueryClassifier::Classification]
       # @return [Hash<Symbol, Integer>]
       def compute_section_budgets(remaining, classification)
         if classification.framework_context
-          {
-            primary: (remaining * 0.55).to_i,
-            supporting: (remaining * 0.25).to_i,
-            framework: (remaining * 0.20).to_i
-          }
+          FRAMEWORK_ACTIVE_ALLOCATION.transform_values { |fraction| (remaining * fraction).to_i }
         else
-          {
-            primary: (remaining * 0.65).to_i,
-            supporting: (remaining * 0.35).to_i,
-            framework: 0
-          }
+          FRAMEWORK_INACTIVE_ALLOCATION.transform_values { |fraction| (remaining * fraction).to_i }
+                                       .merge(framework: 0)
         end
       end
 
@@ -230,7 +284,14 @@ module Woods
       # Append a single candidate to the section. Returns updated tokens_used, or nil to stop.
       def append_candidate(parts, sources, candidate, budget, tokens_used)
         unit = @unit_cache[candidate.identifier]
-        return tokens_used unless unit
+        unless unit
+          # Vector search matched an identifier the metadata store no longer
+          # has (a stale vector for a deleted/renamed unit). Counted so
+          # callers can distinguish "nothing matched" from "matches existed
+          # but the index is stale" instead of a silent empty section.
+          @skipped_missing_metadata += 1
+          return tokens_used
+        end
 
         text = format_unit(unit, candidate)
         tokens = estimate_tokens(text)
@@ -271,7 +332,7 @@ module Woods
       # @return [Hash]
       def build_source_attribution(candidate, unit, truncated: false)
         attribution = {
-          identifier: candidate.identifier,
+          identifier: unit_field(unit, :identifier) || candidate.identifier,
           type: unit_field(unit, :type),
           score: candidate.score,
           file_path: unit_field(unit, :file_path)
@@ -291,14 +352,36 @@ module Woods
 
       # Check if a candidate is framework source.
       #
+      # Reads +candidate.metadata+ first, then falls back to the assembled
+      # +@unit_cache+ entry. A real graph-expansion candidate always carries
+      # +metadata: {}+ (see {SearchExecutor#execute_graph}), so relying on
+      # +candidate.metadata+ alone silently misses every graph-expanded
+      # framework unit — they'd never partition out of primary/supporting
+      # into the framework section.
+      #
       # @param candidate [Candidate]
       # @return [Boolean]
       def framework_candidate?(candidate)
+        type = type_from_candidate_metadata(candidate) || type_from_unit_cache(candidate)
+        %w[rails_source gem_source].include?(type.to_s)
+      end
+
+      # @param candidate [Candidate]
+      # @return [String, Symbol, nil]
+      def type_from_candidate_metadata(candidate)
         metadata = candidate.metadata
-        return false unless metadata
+        return nil unless metadata
 
-        type = metadata[:type] || metadata['type']
-        %w[rails_source gem_source].include?(type.to_s)
+        metadata[:type] || metadata['type']
+      end
+
+      # @param candidate [Candidate]
+      # @return [String, Symbol, nil]
+      def type_from_unit_cache(candidate)
+        unit = @unit_cache[candidate.identifier]
+        return nil unless unit
+
+        unit_field(unit, :type)
       end
 
       # Truncate text to fit within a token budget.
@@ -349,20 +432,29 @@ module Woods
       # @param sections [Array<Hash>] Assembled sections
       # @param sources [Array<Hash>] Source attributions
       # @param effective_budget [Integer] The budget actually used for assembly
+      # @param skipped_missing_metadata [Integer] Candidates dropped because the
+      #   metadata store had no record for their identifier (stale vector)
       # @return [AssembledContext]
-      def build_result(sections, sources, effective_budget)
+      def build_result(sections, sources, effective_budget, skipped_missing_metadata)
         context = sections.map { |s| s[:content] }.join("\n\n---\n\n")
         AssembledContext.new(
           context: context,
           tokens_used: estimate_tokens(context),
           budget: effective_budget,
           sources: sources.uniq,
-          sections: sections.map { |s| s[:section] }
+          sections: sections.map { |s| s[:section] },
+          skipped_missing_metadata: skipped_missing_metadata
         )
       end
     end
 
     # Result of context assembly.
-    AssembledContext = Struct.new(:context, :tokens_used, :budget, :sources, :sections, keyword_init: true)
+    #
+    # +skipped_missing_metadata+ counts candidates whose identifier had no
+    # entry in the metadata store — a stale vector left behind by a deleted
+    # or renamed unit. A nonzero count alongside empty +sources+ means the
+    # index needs re-embedding, not that the query had no matches.
+    AssembledContext = Struct.new(:context, :tokens_used, :budget, :sources, :sections,
+                                  :skipped_missing_metadata, keyword_init: true)
   end
 end

data/lib/woods/retrieval/query_classifier.rb

@@ -25,14 +25,17 @@ module Woods
 
       # Intent patterns — order matters (first match wins)
       INTENT_PATTERNS = {
-        locate: /\b(where|find|which file|locate|look for|search for)\b/i,
+        # :trace is checked BEFORE :locate: a query like "find who calls X"
+        # matches both patterns ("find" vs "who calls"), and the tracing
+        # intent is the one the agent means. :locate first misrouted these
+        # to keyword/direct location handling, skipping graph-based tracing.
         trace: /\b(trace|follow|track|call(s|ed by)|depends on|used by|who calls|what calls)\b/i,
+        locate: /\b(where|find|which file|locate|look for|search for)\b/i,
         debug: /\b(bug|error|fix|broken|failing|wrong|issue|problem|crash|exception)\b/i,
         implement: /\b(implement|add|create|build|write|make|generate)\b/i,
         compare: /\b(compare|difference|vs|versus|between|contrast)\b/i,
-        # rubocop:disable Layout/LineLength
+        # rubocop:disable-next Layout/LineLength
         framework: /\b(how does rails|what does rails|rails .+ work|work.+\brails\b|in rails\b|activerecord|actioncontroller|activejob|actionmailer|actioncable|actiontext|activestorage|solid_queue|solid_cache|solid_cable|kamal|propshaft|importmap|hotwire|turbo|stimulus|zeitwerk)\b/i,
-        # rubocop:enable Layout/LineLength
         reference: /\b(show me|what is|what are|list|options for|api|interface|signature)\b/i,
         understand: /\b(how|why|explain|understand|what happens|describe|overview)\b/i
       }.freeze
@@ -44,16 +47,31 @@ module Woods
         exploratory: /\b(related|around|near|similar|like|associated)\b/i
       }.freeze
 
-      # Target type patterns
+      # Target type patterns.
+      #
+      # Deliberately conservative (#184): +target_type+ is a heuristic that
+      # feeds the Ranker's soft +type_match+ signal, so every word here
+      # nudges the ranking of any query that contains it. Ordinary
+      # conversational words — bare HTTP verbs (get/post/put/patch/delete),
+      # "query", "type", "field", "email", "perform" — are not type signals
+      # on their own; they only count with disambiguating context (an
+      # uppercase HTTP verb, "notification email", "perform_later"). Add
+      # new words only when they are genuinely discriminative.
       TARGET_PATTERNS = {
         model: /\b(model|activerecord|association|schema|table|column|scope|validation)\b/i,
         controller: /\b(controller|action|route|endpoint|api|request|response|filter|callback)\b/i,
         service: /\b(service|interactor|operation|command|use.?case|business.?logic)\b/i,
-        job: /\b(job|worker|background|async|sidekiq|queue|perform)\b/i,
-        mailer: /\b(mailer|email|notification|send.?mail)\b/i,
-        graphql: /\b(graphql|mutation|query|type|resolver|field|argument|schema)\b/i,
+        job: /\b(job|worker|background|async|sidekiq|queue|perform.?(later|now|async))\b/i,
+        # rubocop:disable-next Layout/LineLength
+        mailer: /\b(mailer|mail|send.?mail|deliver.?(later|now)|notification\s+email|email\s+(template|notification|deliver\w*)|send\w*\s+(an\s+)?email)\b/i,
+        graphql: /\b(graphql|mutation|resolver)\b/i,
         concern: /\b(concern|mixin|module|included|extend)\b/i,
-        route: /\b(route|path|url|endpoint|uri|http|get|post|put|patch|delete)\b/i,
+        # Lowercase get/post/put/patch/delete are ordinary verbs ("how do we
+        # get the current user?") — only the unambiguous uppercase HTTP form
+        # counts. Verb-plus-context phrases ("GET request", "delete
+        # endpoint") already classify :controller via that pattern's
+        # request/endpoint/route words, which run first.
+        route: Regexp.union(/\b(route|path|url|uri|http)\b/i, /\b(GET|POST|PUT|PATCH|DELETE)\b/),
         middleware: /\b(middleware|rack|request.?pipeline|before.?action)\b/i,
         i18n: /\b(i18n|translation|locale|internationalization|t\(|translate)\b/i,
         pundit_policy: /\b(pundit|authorize|policy|allowed|permitted)\b/i,