woods 2.0.0.beta1 → 2.0.0.beta3

data/lib/woods/mcp/initialization_guidance.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Woods
+  module MCP
+    # Short, client-neutral instructions for initialize and modern discovery.
+    # Only tool registration shapes the text: readiness and retrieval can
+    # change after startup, so clients must consult live status before use.
+    module InitializationGuidance
+      # Contract budget for all supported wiring combinations, tested at build.
+      MAX_BYTES = 2048
+
+      WORKFLOW = <<~TEXT
+        Start with woods_status: check index readiness, generation freshness and relevant type counts before relying on results.
+        For exact names, discover identifiers with search (prefer literal exact_prefix/exact_suffix), then inspect with lookup. For conceptual questions, use codebase_retrieve only when woods_status reports retrieval enabled. Otherwise use search and lookup.
+        Follow dependencies or dependents at depth 1 or 2; narrow types and via before paging. Respect partial results and limits: a missing match is not proof of absence, and a partial traversal does not establish every dependent or leaf.
+        Verify important conclusions against current source and tests. Recorded relationships and inferred downstream impact do not prove runtime execution or test coverage.
+        Registration does not authorize extraction, configuration changes, or live Console access. Use only the tools registered here and operate within the user's authorized scope.
+      TEXT
+
+      # @param tool_names [Array<String>] actual names after conditional registration
+      # @return [String] stable instructions, without index data or provider calls
+      def self.for(tool_names)
+        "#{WORKFLOW}Registered tools: #{tool_names.sort.join(', ')}"
+      end
+    end
+  end
+end

data/lib/woods/mcp/origin_guard.rb

@@ -62,15 +62,12 @@ module Woods
       # @param enabled [#call, nil] Optional request-time predicate. When it
       #   returns falsy the request passes through unguarded. Nil (the
       #   default) means always guard.
-      def initialize(app, allowed_origins: nil, path: nil, enabled: nil)
-        @app = app
-        @path = path
-        @enabled = enabled
-        if allowed_origins.respond_to?(:call)
-          @allowed_source = allowed_origins
-        else
-          build_allow_list(allowed_origins)
-        end
+      # Rails 6.0 forwards middleware options as a positional hash on Ruby 3.
+      # Delegate to explicit keywords to preserve required/unknown option checks.
+      def initialize(app, options = {}, **keywords)
+        raise TypeError, 'middleware options must be a Hash' unless options.is_a?(Hash)
+
+        initialize_options(app, **options, **keywords)
       end
 
       # Rack entry point. Out-of-scope requests (non-matching `path:` prefix
@@ -97,6 +94,17 @@ module Woods
 
       private
 
+      def initialize_options(app, allowed_origins: nil, path: nil, enabled: nil)
+        @app = app
+        @path = path
+        @enabled = enabled
+        if allowed_origins.respond_to?(:call)
+          @allowed_source = allowed_origins
+        else
+          build_allow_list(allowed_origins)
+        end
+      end
+
       # @param env [Hash] Rack environment
       # @return [Boolean] whether this request falls under the guard
       def guard?(env)

data/lib/woods/mcp/published_lexical_retriever.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require_relative 'index_reader'
+require_relative '../retriever'
+require_relative '../storage/metadata_store'
+require_relative '../storage_identity'
+
+module Woods
+  module MCP
+    # Loads only authoritative published extraction units. The reader pin spans
+    # snapshot construction AND the query, so a publication cannot mix units.
+    # No provider, vector adapter, host source read, or context cache is involved.
+    class PublishedLexicalRetriever
+      attr_reader :reader, :snapshot, :default_budget
+
+      def initialize(index_dir:, reader: nil, default_budget: 8000)
+        @default_budget = default_budget
+        @index_dir = Pathname.new(index_dir)
+        @reader = reader || IndexReader.new(index_dir)
+        @snapshot_mutex = Mutex.new
+        @snapshot = nil
+      end
+
+      def mode = :lexical
+      def vector_store = nil
+      def graph_store = nil
+      def metadata_store = @snapshot&.last&.metadata_store
+
+      # Server uses one reader for status, tool pinning and lexical retrieval.
+      # Called only during server construction, before request threads start.
+      def bind_reader(reader)
+        @reader = reader
+        @snapshot = nil
+        self
+      end
+
+      def warmup!
+        validate_publication!
+        reader.with_pinned_generation { snapshot_for_reader }
+        self
+      end
+
+      def retrieve(query, budget: @default_budget, **options)
+        validate_publication!
+        reader.with_pinned_generation do
+          retriever = snapshot_for_reader
+          options[:evidence_generation] = reader.loaded_generation if options[:evidence] && options[:evidence] != 'full'
+          result = retriever.retrieve(query, budget: budget, **options)
+          result.sources.each { |source| source[:generation] = reader.loaded_generation }
+          result
+        end
+      rescue Retriever::StoreError
+        raise
+      rescue StandardError => e
+        raise if e.is_a?(Woods::InvalidQueryError) || e.is_a?(ArgumentError)
+
+        raise Retriever::StoreError, "lexical index read failed: #{e.class}: #{e.message}"
+      end
+
+      # Explicit invalidation is used by reload after its candidate has been
+      # validated. Ordinary generation changes rebuild lazily under the pin.
+      def invalidate_snapshot!
+        @snapshot_mutex.synchronize { @snapshot = nil }
+      end
+
+      def install_snapshot!(snapshot)
+        @snapshot_mutex.synchronize { @snapshot = snapshot }
+      end
+
+      private
+
+      def validate_publication!
+        path = @index_dir.join(Generation::FILENAME)
+        unless path.exist?
+          raise IOError, 'published generation marker disappeared' if reader.loaded_generation
+
+          return
+        end
+        data = JSON.parse(AtomicFile.read(path))
+        unless data.is_a?(Hash) && data['number'].is_a?(Integer) && data['number'].positive?
+          raise IOError, 'invalid published generation marker'
+        end
+        return if data['payload'].nil?
+
+        payload = data['payload']
+        unless payload.is_a?(String) && !payload.empty? && !Pathname.new(payload).absolute?
+          raise IOError, 'invalid generation payload pointer'
+        end
+
+        directory = @index_dir.join(payload)
+        return if directory.directory? && directory.realpath.to_s.start_with?("#{@index_dir.realpath}/")
+
+        raise IOError, 'missing or escaping generation payload'
+      end
+
+      def snapshot_for_reader
+        @snapshot_mutex.synchronize do
+          key = reader.generation_identity
+          # Flat legacy indexes have no immutable generation identity. Rebuild
+          # each time instead of serving changed files from a permanent cache.
+          return @snapshot.last if key.first && @snapshot&.first == key
+
+          metadata = Storage::MetadataStore::InMemory.new
+          reader.each_unit do |unit|
+            metadata.store(StorageIdentity.key(unit.fetch('identifier'), unit.fetch('type')), unit)
+          end
+          candidate = Retriever.new(vector_store: nil, metadata_store: metadata, graph_store: nil,
+                                    embedding_provider: nil, mode: :lexical)
+          @snapshot = [key.freeze, candidate].freeze
+          candidate
+        end
+      end
+    end
+  end
+end

data/lib/woods/mcp/renderers/markdown_renderer.rb

@@ -60,7 +60,7 @@ module Woods
           lines = []
           lines << "## Search: \"#{query}\""
           lines << ''
-          lines << "#{count} result#{'s' unless count == 1} found."
+          lines << "#{count} result#{'s' unless count == 1} returned."
           lines << ''
 
           results.each do |r|
@@ -80,6 +80,8 @@ module Woods
             lines << "**note:** #{note}" if note
           end
 
+          lines.concat(search_completeness_lines(data))
+
           lines.join("\n").rstrip
         end
 
@@ -431,6 +433,11 @@ module Woods
             deps.each { |d| lines << "#{indent}  - #{d}" }
           end
 
+          lines.concat(TraversalEvidenceText.lines(fetch_key(data, :explanation)))
+
+          if fetch_key(data, :partial)
+            lines << "Partial traversal (#{fetch_key(data, :partial_reason)}); narrow depth/types/via or increase max_nodes/max_edges."
+          end
           lines << '' << truncation_note(data, nodes.size) if fetch_key(data, :nodes_total)
 
           lines.join("\n").rstrip

data/lib/woods/mcp/renderers/plain_renderer.rb

@@ -63,7 +63,7 @@ module Woods
           results = fetch_key(data, :results, [])
 
           lines = []
-          lines << "Search: \"#{query}\" (#{count} results)"
+          lines << "Search: \"#{query}\" (#{count} result#{'s' unless count == 1} returned)"
           lines << DIVIDER
 
           results.each do |r|
@@ -79,6 +79,7 @@ module Woods
           partial = fetch_key(data, :partial, false)
           lines << 'partial: true' if partial
           lines << "note: #{note}" if note
+          lines.concat(search_completeness_lines(data))
 
           lines.join("\n").rstrip
         end
@@ -288,6 +289,11 @@ module Woods
             deps.each { |d| lines << "#{indent}  -> #{d}" }
           end
 
+          lines.concat(TraversalEvidenceText.lines(fetch_key(data, :explanation)))
+
+          if fetch_key(data, :partial)
+            lines << "Partial traversal (#{fetch_key(data, :partial_reason)}); narrow depth/types/via or increase max_nodes/max_edges."
+          end
           if fetch_key(data, :nodes_total)
             offset = fetch_key(data, :nodes_offset, 0)
             position = offset.positive? ? " from offset #{offset}" : ''

data/lib/woods/mcp/search_results.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require 'set'
+
+module Woods
+  module MCP
+    # Accumulates a bounded search prefix and evidence about its completeness.
+    # A full page is not evidence of truncation: only an additional distinct
+    # typed match establishes that more results exist. Budget/timeout cutoffs
+    # leave both the total and the existence of another match unknown.
+    class SearchResults
+      NARROWING_HINT = 'Narrow types, literal exact_prefix/exact_suffix filters, or the requested deep fields.'
+
+      def self.unavailable
+        { status: 'unknown', reason: 'unreadable_or_corrupt_source', has_more: nil,
+          total_matches: nil, matched_lower_bound: nil }
+      end
+
+      def initialize(limit:)
+        @limit = limit
+        @matches = []
+        @seen = Set.new
+        @reason = nil
+      end
+
+      # Admit at most one lookahead match beyond the returned page.
+      # @return [self]
+      def add(identifier:, type:, match_field:)
+        return self if result_limit_reached?
+        return self unless @seen.add?([type, identifier])
+
+        @matches << { identifier: identifier, type: type, match_field: match_field }
+        @reason = 'result_limit' if @matches.size > @limit
+        self
+      end
+
+      def result_limit_reached?
+        @reason == 'result_limit'
+      end
+
+      # Stop because the remaining search domain could not be examined.
+      def stop(reason)
+        @reason = reason
+      end
+
+      # The caller must establish exhaustion rather than infer it from page size.
+      def finish
+        @reason ||= 'exhausted'
+        self
+      end
+
+      # @param note [String, nil] existing advisory/timeout guidance
+      # @return [Hash] returned rows plus additive completeness metadata
+      def response(note: nil)
+        raise ArgumentError, 'Search has not finished' unless @reason
+
+        complete = @reason == 'exhausted'
+        result = {
+          results: @matches.first(@limit),
+          completeness: {
+            status: complete ? 'complete' : 'partial', reason: @reason,
+            has_more: complete ? false : (true if result_limit_reached?),
+            total_matches: complete ? @matches.size : nil,
+            matched_lower_bound: @matches.size
+          }
+        }
+        result[:partial] = true unless complete
+        result[:hint] = NARROWING_HINT unless complete
+        result[:note] = note unless note.nil? || note.empty?
+        result
+      end
+    end
+  end
+end