woods 1.6.1 → 2.0.0.beta2

data/lib/woods/retriever.rb

@@ -12,6 +12,15 @@ require_relative 'embedding/token_counter'
 require_relative 'token_utils'
 
 module Woods
+  # Raised by {Retriever#retrieve} when +query+ fails the validation
+  # boundary at the top of the pipeline: nil, blank, non-String, or over
+  # {Retriever::MAX_QUERY_BYTES}. One shared boundary for every strategy
+  # (keyword/vector/graph/hybrid) — pre-fix, a blank query surfaced as a
+  # raw provider ArgumentError, and only on the vector path; the other
+  # strategies tolerated it silently, and an oversized query went to the
+  # provider verbatim to fail as an opaque 400.
+  class InvalidQueryError < Error; end
+
   # Retriever orchestrates the full retrieval pipeline: classify, execute,
   # rank, and assemble context from a natural language query.
   #
@@ -50,8 +59,14 @@ module Woods
     ).freeze
 
     # Diagnostic trace for retrieval quality analysis.
+    #
+    # +skipped_missing_metadata+ carries {Retrieval::ContextAssembler}'s count
+    # of candidates dropped because the metadata store had no record for
+    # their identifier (a stale vector). See +RetrievalResult+'s docstring
+    # for how callers should read it alongside +sources+.
     RetrievalTrace = Struct.new(:classification, :strategy, :candidate_count,
                                 :ranked_count, :tokens_used, :elapsed_ms,
+                                :skipped_missing_metadata,
                                 keyword_init: true)
 
     # The result of a retrieval operation.
@@ -85,18 +100,107 @@ module Woods
     RetrievalResult = Struct.new(:context, :sources, :classification, :strategy, :tokens_used, :budget, :trace,
                                  :type_rank_context, keyword_init: true)
 
+    # Raised when a metadata-store access fails during retrieval (M8). One
+    # shared typed error for every store call site: the retriever used to
+    # swallow these into misleading answers — +types:+ queries reported
+    # +:absent+, the rank-within-type fallback short-circuited to empty, and
+    # exclusion filtering silently no-op'd, each presenting a broken store as
+    # a clean empty result. Raising here lets the MCP server map the failure
+    # to tool-visible degraded metadata instead.
+    class StoreError < Error
+      # @return [String] which store failed (e.g. +"metadata"+)
+      attr_reader :store
+
+      # @param message [String] includes the underlying error class and message
+      # @param store [Symbol, String] the failing store component
+      def initialize(message, store: :metadata)
+        super(message)
+        @store = store.to_s
+      end
+    end
+
+    # Store adapter wrapper that turns ANY failure of a store call into the
+    # shared typed {StoreError}, naming the store that failed.
+    #
+    # M8 wrapped the three lookups the Retriever performs itself, but the
+    # store reads carrying most of the query traffic happen INSIDE the
+    # pipeline components — the ranker's and assembler's +find_batch+, and
+    # every executor store call. Those escaped raw: the SDK reported
+    # "Internal error calling tool codebase_retrieve", or {MCP::ToolContract}
+    # saw an IO-flavored cause and relabeled it +corrupt_artifact+ ("An Index
+    # artifact is unavailable or malformed") — the wrong diagnosis for, say, a
+    # SQLite metadata DB deleted mid-serve (MCP-6).
+    #
+    # Only the pipeline COMPONENTS get facades. The Pipeline struct's store
+    # members and the public +vector_store+ / +metadata_store+ / +graph_store+
+    # readers keep the raw adapters, so the reload transaction's capability
+    # and store-type checks ({MCP::Bootstrapper.refreshable_stores?},
+    # +implements_own?+) still see the real objects.
+    class TranslatedStore
+      # @param store [Object] the wrapped adapter
+      # @param name [Symbol] store component name (+:vector+, +:metadata+, +:graph+)
+      def initialize(store, name)
+        @store = store
+        @name = name
+      end
+
+      # @return [Object] the wrapped adapter, for callers that need identity
+      attr_reader :store
+
+      def respond_to_missing?(name, include_private = false)
+        @store.respond_to?(name, include_private) || super
+      end
+
+      def method_missing(name, ...)
+        return super unless @store.respond_to?(name)
+
+        @store.public_send(name, ...)
+      rescue StoreError
+        raise
+      rescue StandardError => e
+        raise StoreError.new("#{@name} store call #{name} failed: #{e.class}: #{e.message}", store: @name)
+      end
+    end
+
     # Unit types queried for the structural context overview.
     STRUCTURAL_TYPES = %w[model controller service job mailer component graphql].freeze
 
-    # Direct handles to the injected stores. The sub-components
-    # ({Retrieval::SearchExecutor}, {Retrieval::Ranker},
-    # {Retrieval::ContextAssembler}) hold their own references too, but those
-    # are implementation details — callers that want to mutate store contents
-    # (e.g. the MCP +reload+ tool) read through these accessors. All three
-    # refer to the same Ruby objects the sub-components were initialised with,
-    # so in-place +#clear!+ + +#bulk_load+ propagates through the entire
-    # pipeline without re-instantiating sub-components.
-    attr_reader :vector_store, :metadata_store, :graph_store
+    # Immutable retrieval pipeline captured per store bundle. Every component
+    # that references a store lives here, so swapping the bundle is ONE
+    # assignment: {#swap_stores!} replaces +@pipeline+ and every query
+    # resolves the pipeline once at the top of {#retrieve}. An in-flight query
+    # keeps the struct it resolved and finishes entirely against the old
+    # stores; a new query sees only the complete new bundle (M7 — build-then-
+    # swap, never clear!+bulk_load on live stores).
+    Pipeline = Struct.new(:executor, :ranker, :assembler,
+                          :vector_store, :metadata_store, :graph_store,
+                          keyword_init: true)
+    private_constant :Pipeline
+
+    # The live store handles. These delegate to the current pipeline —
+    # callers that want store contents read through these accessors, exactly
+    # as before; the difference is that a swap retires the old store objects
+    # instead of mutating them in place.
+    def vector_store   = @pipeline.vector_store
+    def metadata_store = @pipeline.metadata_store
+    def graph_store    = @pipeline.graph_store
+
+    # Read-only view of the current store bundle and the components wired to
+    # it (executor, ranker, assembler). Diagnostics/specs used to poke
+    # +@executor+/-style ivars directly; this is the supported equivalent.
+    # The reload transaction swaps the whole struct via {#swap_stores!}.
+    #
+    # @return [Pipeline]
+    attr_reader :pipeline
+
+    # Optional callback invoked with the pipeline struct the moment
+    # {#retrieve} resolves it, before any pipeline work runs. Nil in
+    # production. Observability seam for the reload transaction's old-or-new
+    # guarantee (M7): a test can block an in-flight query AFTER it captured
+    # the old bundle but BEFORE the swap lands, deterministically.
+    #
+    # @return [Proc, nil]
+    attr_accessor :pipeline_observer
 
     # @param vector_store [Storage::VectorStore::Interface] Vector store adapter
     # @param metadata_store [Storage::MetadataStore::Interface] Metadata store adapter
@@ -104,30 +208,75 @@ module Woods
     # @param embedding_provider [Embedding::Provider::Interface] Embedding provider
     # @param formatter [#call, nil] Optional callable to post-process the context string
     def initialize(vector_store:, metadata_store:, graph_store:, embedding_provider:, formatter: nil)
-      @vector_store = vector_store
-      @metadata_store = metadata_store
-      @graph_store = graph_store
+      @embedding_provider = embedding_provider
       @formatter = formatter
-
       @classifier = Retrieval::QueryClassifier.new
-      @executor = Retrieval::SearchExecutor.new(
+      @pipeline = build_pipeline(vector_store: vector_store,
+                                 metadata_store: metadata_store,
+                                 graph_store: graph_store)
+    end
+
+    # Replace the store bundle atomically (M7).
+    #
+    # Builds a complete new pipeline from +stores+ (fresh executor, ranker and
+    # assembler — a fresh ranker also carries no memoized PageRank from the
+    # retired graph) and swaps it in with a single assignment. Queries already
+    # running resolved the old pipeline and finish against the old stores;
+    # queries started afterwards resolve the new bundle. No query can observe
+    # an empty or half-swapped store set, because no store is ever mutated in
+    # place.
+    #
+    # Called by the MCP reload transaction AFTER its candidate stores passed
+    # the generation recheck, under the exclusive swap lock.
+    #
+    # @param vector_store [Storage::VectorStore::Interface]
+    # @param metadata_store [Storage::MetadataStore::Interface]
+    # @param graph_store [Storage::GraphStore::Interface]
+    # @return [self]
+    def swap_stores!(vector_store:, metadata_store:, graph_store:)
+      @pipeline = build_pipeline(vector_store: vector_store,
+                                 metadata_store: metadata_store,
+                                 graph_store: graph_store)
+      self
+    end
+
+    # Build one immutable pipeline around a store bundle.
+    #
+    # Components read through {TranslatedStore} facades so every store call
+    # they make raises the typed {StoreError} instead of a raw adapter error
+    # (MCP-6); the struct keeps the raw adapters for identity and capability
+    # checks.
+    def build_pipeline(vector_store:, metadata_store:, graph_store:)
+      translated_vector = translate_store(vector_store, :vector)
+      translated_metadata = translate_store(metadata_store, :metadata)
+      translated_graph = translate_store(graph_store, :graph)
+
+      Pipeline.new(
+        executor: Retrieval::SearchExecutor.new(
+          vector_store: translated_vector,
+          metadata_store: translated_metadata,
+          graph_store: translated_graph,
+          embedding_provider: @embedding_provider
+        ),
+        ranker: Retrieval::Ranker.new(metadata_store: translated_metadata, graph_store: translated_graph),
+        assembler: Retrieval::ContextAssembler.new(
+          metadata_store: translated_metadata,
+          chars_per_token: infer_chars_per_token(@embedding_provider),
+          token_counter: infer_token_counter(@embedding_provider)
+        ),
         vector_store: vector_store,
         metadata_store: metadata_store,
-        graph_store: graph_store,
-        embedding_provider: embedding_provider
-      )
-      @ranker = Retrieval::Ranker.new(metadata_store: metadata_store, graph_store: graph_store)
-      # Match truncation sizing to the embedding provider's tokenizer so
-      # Ollama-indexed corpora (ratio ~1.5) don't get over-truncated by
-      # an OpenAI-sized default (4.0). Unknown/missing providers fall
-      # back to the OpenAI-friendly default.
-      chars_per_token = infer_chars_per_token(embedding_provider)
-      @assembler = Retrieval::ContextAssembler.new(
-        metadata_store: metadata_store,
-        chars_per_token: chars_per_token,
-        token_counter: infer_token_counter(embedding_provider)
+        graph_store: graph_store
       )
     end
+    private :build_pipeline
+
+    # Wrap one store adapter for the pipeline components. Nil stays nil — a
+    # nil graph store is a supported bundle shape.
+    def translate_store(store, name)
+      store && TranslatedStore.new(store, name)
+    end
+    private :translate_store
 
     # Infer the chars-per-token ratio from an embedding provider's model.
     # Ollama WordPiece-style tokenizers (nomic-embed-text, bge-*,
@@ -183,6 +332,16 @@ module Woods
     CHUNK_SUFFIX_PATTERN = /#chunk_\d+\z/
     private_constant :CHUNK_SUFFIX_PATTERN
 
+    # Maximum query size accepted by {#retrieve}, in bytes.
+    #
+    # Configuration/ResolvedConfig have no existing query-length knob
+    # (checked both) — +max_context_tokens+ bounds assembled OUTPUT
+    # context, not the input query. ~8KB comfortably covers any
+    # legitimate natural-language query and fails fast, in-process,
+    # instead of round-tripping an oversized string to an embedding or
+    # metadata provider just to get a 400 back.
+    MAX_QUERY_BYTES = 8 * 1024
+
     # Execute the full retrieval pipeline for a natural language query.
     #
     # Pipeline: classify -> execute -> rank -> filter -> (fallback within-type
@@ -200,18 +359,25 @@ module Woods
     #   exclude. Applied on top of DEFAULT_EXCLUDE_TYPES unless +types:+ is set.
     # @return [RetrievalResult] Complete retrieval result
     def retrieve(query, budget: 8000, types: nil, exclude_types: nil)
+      validate_query!(query)
       start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      # One atomic read of the bundle reference: everything this query does
+      # from here on — execution, ranking, filtering, assembly — stays on the
+      # SAME store set even if a reload swaps the pipeline mid-flight (M7).
+      pipeline = @pipeline
+      @pipeline_observer&.call(pipeline)
       classification = @classifier.classify(query)
-      execution_result = @executor.execute(query: query, classification: classification)
-      ranked = @ranker.rank(execution_result.candidates, classification: classification)
+      execution_result = pipeline.executor.execute(query: query, classification: classification)
+      ranked = pipeline.ranker.rank(execution_result.candidates, classification: classification)
 
       type_list = normalize_type_list(types)
-      filtered, fallback_ran = apply_type_filter(
-        ranked, query, classification, types: types, type_list: type_list, exclude_types: exclude_types
-      )
-      type_rank_context = type_list ? build_type_rank_context(ranked, type_list, fallback_ran: fallback_ran) : nil
+      filtered, fallback_ran = apply_type_filter(pipeline, ranked, query, classification,
+                                                 types: types, type_list: type_list,
+                                                 exclude_types: exclude_types)
+      type_rank_context = build_type_rank_context_for(ranked, pipeline, type_list, filtered,
+                                                      fallback_ran: fallback_ran)
 
-      assembled = assemble_context(filtered, classification, budget)
+      assembled = assemble_context(pipeline, filtered, classification, budget)
       trace = build_trace(classification, execution_result, filtered, assembled, start_time)
 
       build_result(
@@ -222,6 +388,19 @@ module Woods
 
     private
 
+    # Validate +query+ before any classify/execute/rank work happens.
+    #
+    # @param query [Object] The caller-supplied query
+    # @raise [InvalidQueryError] nil, non-String, blank, or over {MAX_QUERY_BYTES}
+    # @return [void]
+    def validate_query!(query)
+      raise InvalidQueryError, "query must be a String, got #{query.class}" unless query.is_a?(String)
+      raise InvalidQueryError, 'query cannot be blank' if query.strip.empty?
+      return unless query.bytesize > MAX_QUERY_BYTES
+
+      raise InvalidQueryError, "query exceeds max size of #{MAX_QUERY_BYTES} bytes (got #{query.bytesize})"
+    end
+
     # Filter ranked candidates by type, using an include-list when +types+
     # is set and an exclude-list otherwise (default: +DEFAULT_EXCLUDE_TYPES+,
     # extended by any +exclude_types+ the caller adds).
@@ -231,18 +410,20 @@ module Woods
     # filter still works on graph-expansion candidates that carry no
     # vector-store metadata.
     #
+    # @param pipeline [Pipeline] the store bundle this query resolved (M7:
+    #   every store access in the query flows from this snapshot)
     # @param candidates [Array<Candidate>]
     # @param types [Array<String, Symbol>, nil]
     # @param exclude_types [Array<String, Symbol>, nil]
     # @return [Array<Candidate>]
-    def filter_by_type(candidates, types:, exclude_types:)
+    def filter_by_type(pipeline, candidates, types:, exclude_types:)
       allowed = normalize_type_list(types)
-      return candidates.select { |c| allowed.include?(candidate_type(c)) } if allowed
+      return candidates.select { |c| allowed.include?(candidate_type(pipeline, c)) } if allowed
 
+      # DEFAULT_EXCLUDE_TYPES is always non-empty, so `excluded` here can
+      # never be empty — no early-return-candidates-unchanged branch exists.
       excluded = (normalize_type_list(exclude_types) || Set.new) | DEFAULT_EXCLUDE_TYPES.to_set
-      return candidates if excluded.empty?
-
-      candidates.reject { |c| excluded.include?(candidate_type(c)) }
+      candidates.reject { |c| excluded.include?(candidate_type(pipeline, c)) }
     end
 
     def normalize_type_list(list)
@@ -251,7 +432,7 @@ module Woods
       list.to_set(&:to_s)
     end
 
-    def candidate_type(candidate)
+    def candidate_type(pipeline, candidate)
       inline = type_from_hash(candidate.metadata)
       return inline if inline
 
@@ -262,9 +443,12 @@ module Woods
       # missed lookup would let the candidate past the default-exclude
       # (type resolves to '', which +excluded+ never contains).
       lookup_id = candidate.identifier.to_s.sub(CHUNK_SUFFIX_PATTERN, '')
-      type_from_hash(@metadata_store.find(lookup_id)) || ''
-    rescue StandardError
-      ''
+      type_from_hash(pipeline.metadata_store.find(lookup_id)) || ''
+    rescue StandardError => e
+      # M8: a failed lookup must not read as "type is ''" — that silently
+      # disables exclusion filtering. Raise the shared typed store error.
+      raise StoreError,
+            "metadata store lookup failed while resolving a candidate type: #{e.class}: #{e.message}"
     end
 
     def type_from_hash(hash)
@@ -276,14 +460,15 @@ module Woods
 
     # Assemble token-budgeted context from ranked candidates.
     #
+    # @param pipeline [Pipeline] the resolved store bundle
     # @param ranked [Array<Candidate>] Ranked search candidates
     # @param classification [QueryClassifier::Classification] Query classification
     # @return [AssembledContext]
-    def assemble_context(ranked, classification, budget)
-      @assembler.assemble(
+    def assemble_context(pipeline, ranked, classification, budget)
+      pipeline.assembler.assemble(
         candidates: ranked,
         classification: classification,
-        structural_context: build_structural_context,
+        structural_context: build_structural_context(pipeline.metadata_store),
         budget: budget
       )
     end
@@ -315,11 +500,11 @@ module Woods
     # passed a type filter and the global top-K had no candidate of the
     # requested type(s). Returns +[filtered, fallback_ran]+ — the second
     # element drives the :source field on type_rank_context.
-    def apply_type_filter(ranked, query, classification, types:, type_list:, exclude_types:)
-      filtered = filter_by_type(ranked, types: types, exclude_types: exclude_types)
+    def apply_type_filter(pipeline, ranked, query, classification, types:, type_list:, exclude_types:)
+      filtered = filter_by_type(pipeline, ranked, types: types, exclude_types: exclude_types)
       return [filtered, false] unless type_list && filtered.empty?
 
-      [within_type_fallback(query, classification, type_list, exclude_types), true]
+      [within_type_fallback(pipeline, query, classification, type_list, exclude_types), true]
     end
 
     # Rank-within-type fallback query. Pushes the explicit type filter
@@ -337,16 +522,16 @@ module Woods
     # Short-circuits to an empty Array when every requested type has
     # zero units in the index — there is nothing for the fallback to
     # find, so we skip the extra vector search.
-    def within_type_fallback(query, classification, type_list, exclude_types)
+    def within_type_fallback(pipeline, query, classification, type_list, exclude_types)
       type_array = type_list.to_a
-      return [] if type_array.all? { |t| total_of_type(t).to_i.zero? }
+      return [] if type_array.all? { |t| total_of_type(pipeline.metadata_store, t).to_i.zero? }
 
-      fallback = @executor.execute(
+      fallback = pipeline.executor.execute(
         query: query, classification: classification,
         type_filter: type_array, strategy: :vector
       )
-      ranked = @ranker.rank(fallback.candidates, classification: classification)
-      filter_by_type(ranked, types: type_array, exclude_types: exclude_types)
+      ranked = pipeline.ranker.rank(fallback.candidates, classification: classification)
+      filter_by_type(pipeline, ranked, types: type_array, exclude_types: exclude_types)
     end
 
     def build_trace(classification, execution_result, filtered, assembled, start_time)
@@ -357,10 +542,26 @@ module Woods
         candidate_count: execution_result.candidates.size,
         ranked_count: filtered.size,
         tokens_used: assembled.tokens_used,
-        elapsed_ms: elapsed_ms
+        elapsed_ms: elapsed_ms,
+        skipped_missing_metadata: assembled.skipped_missing_metadata.to_i
       )
     end
 
+    # Per-type rank metadata for +types:+ queries; nil on unfiltered queries.
+    #
+    # @param ranked [Array<Candidate>]
+    # @param pipeline [Pipeline] the resolved store bundle (M7)
+    # @param type_list [Set<String>, nil]
+    # @param filtered [Array<Candidate>] The post-fallback candidate list
+    # @param fallback_ran [Boolean] Whether rank-within-type fallback ran
+    # @return [Hash{String => Hash}, nil]
+    def build_type_rank_context_for(ranked, pipeline, type_list, filtered, fallback_ran:)
+      return nil unless type_list
+
+      build_type_rank_context(ranked, pipeline.metadata_store, type_list, filtered,
+                              fallback_ran: fallback_ran)
+    end
+
     # Build per-type rank metadata from the unfiltered global ranked list.
     #
     # +top_of_type_global_rank+ is the 1-based position of the first
@@ -372,19 +573,25 @@ module Woods
     # see the RetrievalResult docstring for the four-value enum.
     #
     # @param ranked [Array<Candidate>]
+    # @param metadata_store [Storage::MetadataStore::Interface] the resolved
+    #   bundle's metadata store (M7)
     # @param type_list [Set<String>]
+    # @param filtered [Array<Candidate>] The post-fallback candidate list
+    #   {#retrieve} is about to assemble — used to confirm the fallback
+    #   actually surfaced a candidate OF this specific type, not just that
+    #   fallback ran.
     # @param fallback_ran [Boolean] Whether rank-within-type fallback ran
     # @return [Hash{String => Hash}]
-    def build_type_rank_context(ranked, type_list, fallback_ran:)
+    def build_type_rank_context(ranked, metadata_store, type_list, filtered, fallback_ran:)
       global_k = ranked.size
       type_list.to_h do |type|
-        match_index = ranked.index { |c| candidate_type(c) == type }
+        match_index = ranked.index { |c| candidate_type_from(metadata_store, c) == type }
         top_rank = match_index ? match_index + 1 : nil
-        total = total_of_type(type)
+        total = total_of_type(metadata_store, type)
         [
           type,
           {
-            source: type_source(top_rank, total, fallback_ran: fallback_ran),
+            source: type_source(top_rank, total, metadata_store, filtered, type, fallback_ran: fallback_ran),
             top_of_type_global_rank: top_rank,
             global_k: global_k,
             total_of_type: total
@@ -395,18 +602,44 @@ module Woods
 
     # Pick the :source enum value for a single type based on where its
     # candidate ended up. See RetrievalResult's docstring for the enum.
-    def type_source(top_rank, total, fallback_ran:)
+    #
+    # +:within_type_fallback+ requires the fallback to have actually
+    # returned a candidate of THIS type — a multi-type fallback (e.g.
+    # +types: %w[service mailer]+) can run and surface candidates for only
+    # some of the requested types, and the type(s) it missed are
+    # +:outside_top_k+, not falsely reported as a weak fallback match.
+    def type_source(top_rank, total, metadata_store, filtered, type, fallback_ran:)
       return :in_top_k if top_rank
       return :absent if total.to_i.zero?
-      return :within_type_fallback if fallback_ran
+      return :within_type_fallback if fallback_ran && filtered.any? do |c|
+        candidate_type_from(metadata_store, c) == type
+      end
 
       :outside_top_k
     end
 
-    def total_of_type(type)
-      @metadata_store.find_by_type(type).size
-    rescue StandardError
-      nil
+    def total_of_type(metadata_store, type)
+      metadata_store.find_by_type(type).size
+    rescue StandardError => e
+      # M8: a failed count must not read as zero — that reports :absent for
+      # a type that may exist and short-circuits the within-type fallback.
+      raise StoreError,
+            "metadata store count failed for type #{type.inspect}: #{e.class}: #{e.message}"
+    end
+
+    # Chunk-suffix-stripping candidate-type probe against an explicit
+    # metadata store. Same lookup rules as {#candidate_type}; takes the
+    # store as an argument so a caller holding a resolved bundle snapshot
+    # (M7) probes the generation it started on.
+    def candidate_type_from(metadata_store, candidate)
+      inline = type_from_hash(candidate.metadata)
+      return inline if inline
+
+      lookup_id = candidate.identifier.to_s.sub(CHUNK_SUFFIX_PATTERN, '')
+      type_from_hash(metadata_store.find(lookup_id)) || ''
+    rescue StandardError => e
+      raise StoreError,
+            "metadata store lookup failed while resolving a candidate type: #{e.class}: #{e.message}"
     end
 
     # Append a compact markdown summary of +type_rank_context+ to the
@@ -439,20 +672,33 @@ module Woods
     # spot the searchable-entries vs unit-count discrepancy know which
     # tool carries the canonical unit totals (issue #105).
     #
-    # @return [String, nil] Overview string, or nil if the store is empty or on error
-    def build_structural_context
-      total = @metadata_store.count
+    # @param metadata_store [Storage::MetadataStore::Interface] the resolved
+    #   bundle's metadata store (M7)
+    # @return [String, nil] Overview string, or nil if the store is empty
+    # @raise [StoreError] the metadata store failed
+    def build_structural_context(metadata_store)
+      total = metadata_store.count
       return nil if total.zero?
 
       type_counts = STRUCTURAL_TYPES.filter_map do |type|
-        count = @metadata_store.find_by_type(type).size
+        count = metadata_store.find_by_type(type).size
         "#{count} #{type} entries" if count.positive?
       end
 
       "Codebase: #{total} searchable entries (#{type_counts.join(', ')}). " \
         'Entries include per-chunk rows for chunked units; see `structure` for canonical unit counts.'
-    rescue StandardError
-      nil
+    rescue StoreError
+      raise
+    rescue StandardError => e
+      # MCP-6: this used to rescue to nil — the last swallow-to-empty on the
+      # query path. A broken metadata store dropped the banner and every
+      # answer looked like a healthy codebase with nothing to say about
+      # itself. It is a metadata read like any other; raise the shared typed
+      # store error so the MCP boundary can report degraded_index.
+      raise StoreError.new(
+        "metadata store failed while building the structural overview: #{e.class}: #{e.message}",
+        store: :metadata
+      )
     end
   end
 end

data/lib/woods/retry_after.rb

@@ -12,13 +12,33 @@ module Woods
   # back off. This helper handles both forms and falls back to a caller-supplied
   # value when the header is absent or unparseable.
   module RetryAfter
+    # Ceiling on an honoured +Retry-After+, in seconds.
+    #
+    # The header is server-controlled, and nothing stops it saying `86400` or
+    # naming a date next week. A client that sleeps for exactly as long as it
+    # is told hands a buggy or hostile server the ability to park a sync
+    # indefinitely — an export run would sit in `sleep` for days with no
+    # output. Capping keeps the back-off honest without ignoring the server's
+    # intent: past this point, retrying later is the operator's call, not the
+    # process's.
+    #
+    # 120s matches the embedding providers' cap (#188).
+    MAX_SECONDS = 120.0
+
     module_function
 
     # @param header [String, nil] the raw +Retry-After+ header value
     # @param fallback [Numeric] seconds to use when the header is missing or unparseable
     # @param now [Time] reference time for the HTTP-date form (injectable for tests)
-    # @return [Float] non-negative seconds to wait
-    def seconds(header, fallback:, now: Time.now)
+    # @param max [Numeric] ceiling on the returned wait. Pass +Float::INFINITY+
+    #   to honour the header no matter how large.
+    # @return [Float] non-negative seconds to wait, never more than +max+
+    def seconds(header, fallback:, now: Time.now, max: MAX_SECONDS)
+      [raw_seconds(header, fallback: fallback, now: now), max.to_f].min
+    end
+
+    # The header's own value, uncapped.
+    def raw_seconds(header, fallback:, now: Time.now)
       value = header.to_s.strip
       return fallback.to_f if value.empty?
 

data/lib/woods/ruby_analyzer/class_analyzer.rb

@@ -33,28 +33,28 @@ module Woods
       def analyze(source:, file_path:)
         root = @parser.parse(source)
         units = []
-        extract_definitions(root, source, file_path, [], units)
+        extract_definitions(root, source, file_path, [], units, [])
         units
       end
 
       private
 
-      def extract_definitions(node, source, file_path, namespace_stack, units)
+      def extract_definitions(node, source, file_path, namespace_stack, units, scopes)
         return unless node.is_a?(Ast::Node)
 
         case node.type
         when :class
-          process_definition(node, :ruby_class, source, file_path, namespace_stack, units)
+          process_definition(node, :ruby_class, source, file_path, namespace_stack, units, scopes)
         when :module
-          process_definition(node, :ruby_module, source, file_path, namespace_stack, units)
+          process_definition(node, :ruby_module, source, file_path, namespace_stack, units, scopes)
         else
           (node.children || []).each do |child|
-            extract_definitions(child, source, file_path, namespace_stack, units)
+            extract_definitions(child, source, file_path, namespace_stack, units, scopes)
           end
         end
       end
 
-      def process_definition(node, type, source, file_path, namespace_stack, units)
+      def process_definition(node, type, source, file_path, namespace_stack, units, scopes)
         name = node.method_name
         fqn = build_fqn(name, namespace_stack)
         namespace = build_namespace(name, namespace_stack)
@@ -70,6 +70,7 @@ module Woods
         unit.namespace = namespace
         unit.source_code = extract_source(node, source)
         unit.metadata = {
+          lexical_scopes: [fqn] + scopes,
           superclass: superclass,
           includes: includes,
           extends: extends,
@@ -80,24 +81,19 @@ module Woods
         units << unit
 
         # Recurse into body for nested definitions
-        inner_ns = namespace_stack + fqn_parts(name)
+        inner_ns = fqn.split('::')
         children.each do |child|
-          extract_definitions(child, source, file_path, inner_ns, units)
+          extract_definitions(child, source, file_path, inner_ns, units, [fqn] + scopes)
         end
       end
 
       # Build namespace string (everything except the leaf name).
       def build_namespace(name, namespace_stack)
-        parts = namespace_stack + fqn_parts(name)
+        parts = build_fqn(name, namespace_stack).split('::')
         parts.pop # Remove leaf
         parts.empty? ? nil : parts.join('::')
       end
 
-      # Split a name that may contain :: into parts.
-      def fqn_parts(name)
-        name.to_s.split('::')
-      end
-
       # Extract superclass name from a class node.
       # Children[0] is name, children[1] is superclass (or nil).
       def extract_superclass(class_node)