woods 2.0.0.beta2 → 2.0.0.beta4

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
 
@@ -150,11 +152,11 @@ module Woods
             - **units_indexed** (manifest.json, `structure` tool) — total
               ExtractedUnits written by the extractor. Canonical count.
             - **graph_nodes** (`pagerank`, `dependencies`, `dependents`) —
-              units present in the dependency graph. Excludes orphans
-              that have no incoming or outgoing edges.
+              units present in the dependency graph, including isolated units
+              with no incoming or outgoing edges.
             - **searchable_entries** (`codebase_retrieve`) — retriever-store
-              entries, including per-chunk rows for units long enough to
-              be chunked. Always ≥ units_indexed.
+              entries. Semantic mode may include per-chunk rows; lexical mode
+              ranks published units. Coverage depends on the configured store.
           GLOSSARY
         end
 
@@ -175,7 +177,7 @@ module Woods
 
           GRAPH_ANALYSIS_SECTIONS.each do |section|
             items = fetch_key(data, section)
-            next unless items.is_a?(Array) && items.any?
+            next unless items.is_a?(Array) && (items.any? || fetch_key(data, "#{section}_total"))
 
             lines << "### #{section.tr('_', ' ').capitalize}"
             lines << ''
@@ -192,11 +194,11 @@ module Woods
             end
 
             total_key = "#{section}_total"
-            if data[total_key]
+            if fetch_key(data, total_key)
               lines << ''
               offset = fetch_key(data, "#{section}_offset", 0)
               position = offset.positive? ? " from offset #{offset}" : ''
-              lines << "_Showing #{items.size} of #{data[total_key]}#{position} (truncated)_"
+              lines << "_Showing #{items.size} of #{fetch_key(data, total_key)}#{position} (truncated)_"
             end
             lines << ''
           end
@@ -415,6 +417,8 @@ module Woods
             return lines.join("\n").rstrip
           end
 
+          lines.concat(traversal_coverage_lines(data))
+
           nodes.each do |id, info|
             depth = fetch_key(info, :depth) || 0
             deps = fetch_key(info, :deps, [])
@@ -431,7 +435,16 @@ module Woods
             deps.each { |d| lines << "#{indent}  - #{d}" }
           end
 
-          lines << '' << truncation_note(data, nodes.size) if fetch_key(data, :nodes_total)
+          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 (note = traversal_lower_bound_note(data, nodes.size))
+            lines << '' << "_#{note}_"
+          elsif fetch_key(data, :nodes_total)
+            lines << '' << truncation_note(data, nodes.size)
+          end
 
           lines.join("\n").rstrip
         end

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
@@ -125,9 +126,9 @@ module Woods
           lines << 'Denominators:'
           lines << '  units_indexed     (manifest, structure): total ExtractedUnits written.'
           lines << '  graph_nodes       (pagerank, dependencies, dependents): units in the graph'
-          lines << '                    (excludes orphans with no incoming/outgoing edges).'
-          lines << '  searchable_entries (codebase_retrieve): retriever-store entries including'
-          lines << '                    per-chunk rows. Always >= units_indexed.'
+          lines << '                    (includes isolated units with no incoming/outgoing edges).'
+          lines << '  searchable_entries (codebase_retrieve): retriever-store entries; semantic mode may include'
+          lines << '                    per-chunk rows; lexical mode ranks published units. Store coverage varies.'
 
           lines.join("\n").rstrip
         end
@@ -145,7 +146,7 @@ module Woods
 
           GRAPH_ANALYSIS_SECTIONS.each do |section|
             items = fetch_key(data, section)
-            next unless items.is_a?(Array) && items.any?
+            next unless items.is_a?(Array) && (items.any? || fetch_key(data, "#{section}_total"))
 
             lines << "#{section.tr('_', ' ').upcase}:"
             items.each do |item|
@@ -160,9 +161,9 @@ module Woods
 
             total_key = "#{section}_total"
             offset = fetch_key(data, "#{section}_offset", 0)
-            if data[total_key]
+            if fetch_key(data, total_key)
               position = offset.positive? ? " from offset #{offset}" : ''
-              lines << "  (showing #{items.size} of #{data[total_key]}#{position}; truncated)"
+              lines << "  (showing #{items.size} of #{fetch_key(data, total_key)}#{position}; truncated)"
             end
             lines << ''
           end
@@ -278,6 +279,8 @@ module Woods
             return lines.join("\n").rstrip
           end
 
+          lines.concat(traversal_coverage_lines(data))
+
           nodes.each do |id, info|
             depth = fetch_key(info, :depth) || 0
             deps = fetch_key(info, :deps, [])
@@ -288,7 +291,14 @@ module Woods
             deps.each { |d| lines << "#{indent}  -> #{d}" }
           end
 
-          if fetch_key(data, :nodes_total)
+          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 (note = traversal_lower_bound_note(data, nodes.size))
+            lines << note
+          elsif fetch_key(data, :nodes_total)
             offset = fetch_key(data, :nodes_offset, 0)
             position = offset.positive? ? " from offset #{offset}" : ''
             lines << "  (showing #{nodes.size} of #{fetch_key(data, :nodes_total)}#{position}; truncated)"

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