woods 2.0.0.beta2 → 2.0.0.beta4

data/lib/woods/mcp/index_reader.rb

@@ -8,6 +8,10 @@ require 'pathname'
 require 'set'
 
 require_relative '../generation'
+require_relative '../source_inputs/status'
+require_relative 'search_results'
+require_relative '../retrieval/scope'
+require_relative 'traversal_evidence'
 
 module Woods
   module MCP
@@ -40,6 +44,15 @@ module Woods
 
       TYPE_TO_DIR = DIR_TO_TYPE.invert.freeze
 
+      # Most output directories contain one unit type. RailsSourceExtractor
+      # emits gem_source units in rails_source/, while GraphQL publishes four
+      # subtypes in graphql/. Directory-filtered search retains its historical
+      # family labels while artifact readers preserve the actual unit type.
+      UNIT_TYPES_BY_DIR = DIR_TO_TYPE.transform_values { |type| [type].freeze }
+                                     .merge('rails_source' => %w[rails_source gem_source].freeze,
+                                            'graphql' => %w[graphql_type graphql_mutation graphql_resolver graphql_query].freeze)
+                                     .freeze
+
       # Maximum number of loaded unit files to cache in memory.
       MAX_UNIT_CACHE = 50
 
@@ -47,11 +60,16 @@ module Woods
       # @param auto_refresh [Boolean] re-read the index when its published
       #   generation moves. On by default; specs that assert caching behaviour
       #   turn it off.
-      # @raise [ArgumentError] if directory doesn't exist or has no manifest.json
+      # @raise [ArgumentError] if directory doesn't exist or no published index resolves
       def initialize(index_dir, auto_refresh: true)
         @index_dir = Pathname.new(index_dir)
         raise ArgumentError, "Index directory does not exist: #{index_dir}" unless @index_dir.directory?
-        raise ArgumentError, "No manifest.json found in: #{index_dir}" unless manifest_present?
+        unless manifest_present?
+          raise ArgumentError, "Could not resolve a published Woods index in: #{@index_dir.expand_path}\n" \
+                               'Expected generation.json pointing to a payload manifest.json, or a legacy flat manifest.json. ' \
+                               'Point IndexReader at an existing index root. ' \
+                               'If no index exists, run `bundle exec rake woods:extract` in your Rails app.'
+        end
 
         @unit_cache = {}
         @unit_cache_signatures = {}
@@ -89,6 +107,13 @@ module Woods
       # @return [Integer, nil] nil until something has been read
       attr_reader :loaded_generation
 
+      # Cache identity includes the publish token: overlapping writers can
+      # legitimately publish the same number with a different immutable payload.
+      def generation_identity
+        ensure_fresh!
+        [@loaded_generation, @loaded_token, current_payload_dir.to_s].freeze
+      end
+
       # Drop caches if the index has been rewritten since they were populated.
       #
       # This is what makes the MCP `reload` tool an optimization rather than a
@@ -274,6 +299,7 @@ module Woods
         @raw_graph_data = nil
         @normalized_graph_edges = nil
         @graph_node_types = nil
+        @traversal_evidence_index = nil
         remove_instance_variable(:@multi_database_graph) if defined?(@multi_database_graph)
       end
 
@@ -295,6 +321,15 @@ module Woods
         current_payload_dir
       end
 
+      # Verify the immutable payload this reader is actually serving. Do not
+      # cache source results: an edit can occur without an index generation move.
+      def source_freshness(mode: 'quick')
+        with_pinned_generation do
+          SourceInputs::Status.new(output_dir: @index_dir, payload_dir: current_payload_dir,
+                                   generation: @payload_dir ? @loaded_generation : 0, mode: mode).call
+        end
+      end
+
       # @return [Hash] Parsed manifest.json
       def manifest
         ensure_fresh!
@@ -337,7 +372,19 @@ module Woods
       #
       # @param identifier [String] Unit identifier (e.g. "Post", "Api::V1::HealthController")
       # @return [Hash, nil] Full unit data or nil if not found
-      def find_unit(identifier)
+      def find_unit(identifier, type: nil)
+        if type
+          return with_pinned_generation do
+            dir = UNIT_TYPES_BY_DIR.find { |_, types| types.include?(type) }&.first
+            next nil unless dir
+            raise IOError, "symlink unit directory: #{dir}" if current_payload_dir.join(dir).symlink?
+
+            next nil unless search_index_entries(dir).any? { |entry| entry['identifier'] == identifier }
+
+            unit = read_published_unit(dir, identifier)
+            unit if unit['type'] == type
+          end
+        end
         ensure_fresh!
         location = identifier_map[identifier]
         return nil unless location
@@ -361,6 +408,32 @@ module Woods
         dirs.flat_map { |dir| read_index(dir) }
       end
 
+      # Enumerate complete typed published units, holding one generation pin.
+      # Bulk consumers must fail closed on a corrupt/missing entry instead of
+      # silently constructing a partial retrieval index. Bare-name lookup cannot
+      # do this because multiple types can legitimately share an identifier.
+      def each_unit
+        return enum_for(__method__) unless block_given?
+
+        with_pinned_generation do
+          TYPE_DIRS.each do |dir|
+            directory = current_payload_dir.join(dir)
+            raise IOError, "symlink unit directory: #{dir}" if directory.symlink?
+
+            entries = published_unit_entries(dir)
+            seen = Set.new
+            entries.each do |entry|
+              id = entry.is_a?(Hash) && entry['identifier']
+              unless id.is_a?(String) && !id.empty? && seen.add?(id)
+                raise IOError, "invalid or duplicate unit identifier in #{dir}/_index.json"
+              end
+
+              yield read_published_unit(dir, id)
+            end
+          end
+        end
+      end
+
       # Default maximum number of unit files to load during phase-2 search.
       # Override with WOODS_SEARCH_MAX_SCAN env var.
       DEFAULT_SEARCH_MAX_SCAN = 500
@@ -400,23 +473,23 @@ module Woods
       # @param limit [Integer] Maximum results to return
       # @param exact_prefix [String, nil] Literal identifier prefix filter (case-insensitive)
       # @param exact_suffix [String, nil] Literal identifier suffix filter (case-insensitive)
-      # @return [Hash] { results: Array<Hash>, note: String|nil, partial: Boolean }
+      # @return [Hash] results, optional note/partial, and explicit completeness evidence
       # @raise [ArgumentError] when all of query, exact_prefix, and exact_suffix are blank
-      def search(query = nil, types: nil, fields: %w[identifier], limit: 20, exact_prefix: nil, exact_suffix: nil)
-        # Pinned, not merely checked-once. This walks the identifier map and
-        # then loads units for the hits; each nested `find_unit` re-checks
-        # freshness, so a publish landing mid-walk rebuilt the caches while the
-        # result list still held identifiers from the previous generation — one
-        # response describing two indexes.
+      def search(query = nil, types: nil, fields: %w[identifier], limit: 20, exact_prefix: nil, exact_suffix: nil,
+                 packages: nil, source_paths: nil)
+        # Keep summaries, typed deep reads and lookahead on one generation,
+        # including when publication advances after the result page fills.
         with_pinned_generation do
           search_within_pin(query, types: types, fields: fields, limit: limit,
-                                   exact_prefix: exact_prefix, exact_suffix: exact_suffix)
+                                   exact_prefix: exact_prefix, exact_suffix: exact_suffix,
+                                   packages: packages, source_paths: source_paths)
         end
       end
 
       # @api private
       def search_within_pin(query = nil, types: nil, fields: %w[identifier], limit: 20,
-                            exact_prefix: nil, exact_suffix: nil)
+                            exact_prefix: nil, exact_suffix: nil, packages: nil, source_paths: nil)
+        scope = search_scope(packages, source_paths, types)
         prefix = exact_prefix.blank? ? nil : exact_prefix.downcase
         suffix = exact_suffix.blank? ? nil : exact_suffix.downcase
         if query.blank? && !prefix && !suffix
@@ -430,114 +503,126 @@ module Woods
         max_scan = max_scan_env.empty? ? DEFAULT_SEARCH_MAX_SCAN : max_scan_env.to_i
         max_scan = DEFAULT_SEARCH_MAX_SCAN if max_scan <= 0
 
-        results = []
+        results = SearchResults.new(limit: limit)
         notes = []
         phase2_scanned = 0
-        partial = false
 
         begin
-          dirs = if types
-                   types.filter_map { |t| TYPE_TO_DIR[t] }
-                 else
-                   TYPE_DIRS
-                 end
-
-          # Phase 2 candidates are collected per-dir and then scanned in
-          # round-robin across dirs. Exhausting the per-run scan cap linearly
-          # down TYPE_DIRS order would starve later types (`concerns` at pos
-          # 13, `test_mappings` at pos 31) on any codebase where the earlier
-          # dirs together exceed max_scan entries. Interleaving guarantees
-          # every type contributes to the scanned set.
+          dirs = scope || !types ? TYPE_DIRS : types.filter_map { |type| TYPE_TO_DIR[type] }.uniq
+          # Identifier matches retain priority. Deep candidates are interleaved
+          # across types so an early large directory cannot consume their budget.
           phase2_queues = {}
-
-          dirs.each do |dir|
-            type_name = DIR_TO_TYPE[dir]
-            entries = read_index(dir)
-
-            # Broad-match detection: warn when pattern matches >50% of dir entries
-            if entries.size > 1
-              matching_count = entries.count do |e|
-                identifier_passes_filters?(e['identifier'], pattern, prefix, suffix)
-              end
-              if matching_count > entries.size / 2.0
-                notes << "broad pattern matched #{matching_count}/#{entries.size} entries in #{dir}"
+          catch(:search_done) do
+            dirs.each do |dir|
+              type_name = DIR_TO_TYPE[dir]
+              entries = search_index_entries(dir)
+              entries = scoped_search_entries(entries, dir, scope) if scope
+              if entries.size > 1
+                matching_count = entries.count do |entry|
+                  identifier_passes_filters?(entry['identifier'], pattern, prefix, suffix)
+                end
+                if matching_count > entries.size / 2.0
+                  notes << "broad pattern matched #{matching_count}/#{entries.size} entries in #{dir}"
+                end
               end
-            end
 
-            entries.each do |entry|
-              id = entry['identifier']
-              next unless identifier_passes_prefix_suffix?(id, prefix, suffix)
-
-              # Phase 1: identifier matching (still in-order per dir)
-              if fields.include?('identifier') && pattern.match?(id)
-                next if results.size >= limit
+              entries.each do |entry|
+                type_name = entry.fetch('scope_type', DIR_TO_TYPE[dir])
+                id = entry['identifier']
+                next unless identifier_passes_prefix_suffix?(id, prefix, suffix)
 
-                results << { identifier: id, type: type_name, match_field: 'identifier' }
-                next
-              end
+                if fields.include?('identifier') && pattern.match?(id)
+                  results.add(identifier: id, type: type_name, match_field: 'identifier')
+                  throw :search_done if results.result_limit_reached?
 
-              # Phase 2 is only reached when the caller opted into deeper fields.
-              next unless fields.include?('metadata') || fields.include?('source_code')
+                  next
+                end
+                next unless fields.include?('metadata') || fields.include?('source_code')
 
-              (phase2_queues[dir] ||= []) << [type_name, id]
+                (phase2_queues[dir] ||= []) << [type_name, id]
+              end
             end
-          end
-
-          if results.size < limit && phase2_queues.any?
-            queues = phase2_queues.values.map(&:dup)
-            catch(:phase2_done) do
-              loop do
-                progressed = false
-                queues.each do |queue|
-                  next if queue.empty?
-
-                  throw :phase2_done if results.size >= limit
-
-                  if phase2_scanned >= max_scan
-                    partial = true
-                    throw :phase2_done
-                  end
-
-                  type_name, id = queue.shift
-                  progressed = true
 
-                  unit = find_unit(id)
-                  next unless unit
+            queues = phase2_queues.values
+            loop do
+              progressed = false
+              queues.each do |queue|
+                next if queue.empty?
 
-                  phase2_scanned += 1
-
-                  if fields.include?('source_code') && unit['source_code'] && pattern.match?(unit['source_code'])
-                    results << { identifier: id, type: type_name, match_field: 'source_code' }
-                  elsif fields.include?('metadata') && unit['metadata'] && pattern.match?(unit['metadata'].to_json)
-                    results << { identifier: id, type: type_name, match_field: 'metadata' }
-                  end
+                if phase2_scanned >= max_scan
+                  results.stop('scan_budget')
+                  throw :search_done
                 end
-                break unless progressed
+                type_name, id = queue.shift
+                progressed = true
+                phase2_scanned += 1
+                unit = scope ? scope.metadata_store.find(StorageIdentity.key(id, type_name)) : load_search_unit(type_name, id)
+                field = if fields.include?('source_code') && unit['source_code'] && pattern.match?(unit['source_code'])
+                          'source_code'
+                        elsif fields.include?('metadata') && unit['metadata'] && pattern.match?(unit['metadata'].to_json)
+                          'metadata'
+                        end
+                next unless field
+
+                results.add(identifier: id, type: type_name, match_field: field)
+                throw :search_done if results.result_limit_reached?
               end
+              break unless progressed
             end
           end
         rescue StandardError => e
           raise unless regexp_timeout_error?(e)
 
           notes << "search aborted: the pattern exceeded the #{SEARCH_PATTERN_TIMEOUT}s per-match limit"
-          partial = true
+          results.stop('regex_timeout')
         end
 
-        response = { results: results.first(limit) }
-        response[:note] = notes.join('; ') unless notes.empty?
-        response[:partial] = true if partial
+        response = results.finish.response(note: notes.join('; '))
+        response[:applied_scope] = scope.summary if scope
         response
       end
 
+      # Scope preparation reads the complete pinned unit snapshot. Search's
+      # deep-field scan budget still governs matching work after this read.
+      def search_scope(packages, source_paths, types)
+        return unless Retrieval::Scope.requested?(packages: packages, source_paths: source_paths)
+
+        metadata = Storage::MetadataStore::InMemory.new
+        each_unit { |unit| metadata.store(StorageIdentity.key(unit.fetch('identifier'), unit.fetch('type')), unit) }
+        Retrieval::Scope.new(metadata_store: metadata, packages: packages, source_paths: source_paths, types: types)
+      end
+      private :search_scope
+
+      def scoped_search_entries(entries, dir, scope)
+        entries.flat_map do |entry|
+          UNIT_TYPES_BY_DIR.fetch(dir).filter_map do |type|
+            key = StorageIdentity.key(entry['identifier'], type)
+            entry.merge('scope_type' => type) if scope.include?(key)
+          end
+        end
+      end
+      private :scoped_search_entries
+
       # BFS traversal of forward dependencies.
       #
       # @param identifier [String] Starting unit identifier
       # @param depth [Integer] Maximum traversal depth
       # @param types [Array<String>, nil] Filter to these singular type names
       # @param via [Array<String>, nil] Filter to these relationship types (e.g. ["link_to", "redirect_to"])
-      # @return [Hash] { root:, nodes: { id => { type:, depth:, deps: [] } } }
-      def traverse_dependencies(identifier, depth: 2, types: nil, via: nil)
-        traverse(identifier, depth: depth, types: types, via: via, direction: :forward)
+      # @param max_nodes [Integer] Distinct admitted nodes including root (default 1000; clamped to 1..10_000)
+      # @param max_edges [Integer] Edge checks before filters, including reverse via checks
+      #   (default 10_000; clamped to 1..100_000). Graph loading/cache preparation is not budgeted.
+      # @return [Hash] { root:, found:, nodes: { id => { type:, depth:, deps: [] } } };
+      #   incomplete walks add partial: true, partial_reason (node_budget or edge_budget),
+      #   and traversal_budget (max_nodes, max_edges, visited_nodes, visited_edges).
+      #   Already discovered rows remain; empty deps in a partial result need not mean a leaf.
+      def traverse_dependencies(identifier, depth: 2, types: nil, via: nil, max_nodes: 1000, max_edges: 10_000, explain: false)
+        if explain
+          return traverse_with_evidence(identifier, depth: depth, types: types, via: via, direction: :forward,
+                                                    max_nodes: max_nodes, max_edges: max_edges)
+        end
+
+        traverse(identifier, depth: depth, types: types, via: via, direction: :forward, max_nodes: max_nodes, max_edges: max_edges)
       end
 
       # BFS traversal of reverse dependencies (dependents).
@@ -546,9 +631,20 @@ module Woods
       # @param depth [Integer] Maximum traversal depth
       # @param types [Array<String>, nil] Filter to these singular type names
       # @param via [Array<String>, nil] Filter to these relationship types (e.g. ["link_to", "redirect_to"])
-      # @return [Hash] { root:, nodes: { id => { type:, depth:, deps: [] } } }
-      def traverse_dependents(identifier, depth: 2, types: nil, via: nil)
-        traverse(identifier, depth: depth, types: types, via: via, direction: :reverse)
+      # @param max_nodes [Integer] Distinct admitted nodes including root (default 1000; clamped to 1..10_000)
+      # @param max_edges [Integer] Edge checks before filters, including reverse via checks
+      #   (default 10_000; clamped to 1..100_000). Graph loading/cache preparation is not budgeted.
+      # @return [Hash] { root:, found:, nodes: { id => { type:, depth:, deps: [] } } };
+      #   incomplete walks add partial: true, partial_reason (node_budget or edge_budget),
+      #   and traversal_budget (max_nodes, max_edges, visited_nodes, visited_edges).
+      #   Already discovered rows remain; empty deps in a partial result need not mean a leaf.
+      def traverse_dependents(identifier, depth: 2, types: nil, via: nil, max_nodes: 1000, max_edges: 10_000, explain: false)
+        if explain
+          return traverse_with_evidence(identifier, depth: depth, types: types, via: via, direction: :reverse,
+                                                    max_nodes: max_nodes, max_edges: max_edges)
+        end
+
+        traverse(identifier, depth: depth, types: types, via: via, direction: :reverse, max_nodes: max_nodes, max_edges: max_edges)
       end
 
       # Search rails_source units by concept keyword.
@@ -578,7 +674,7 @@ module Woods
           break if results.size >= limit
 
           id = entry['identifier']
-          unit = find_unit(id)
+          unit = load_search_unit('rails_source', id)
           next unless unit
 
           metadata_json = unit['metadata']&.to_json
@@ -627,7 +723,7 @@ module Woods
           entries = read_index(dir)
           entries.each do |entry|
             id = entry['identifier']
-            unit = find_unit(id)
+            unit = load_search_unit(DIR_TO_TYPE.fetch(dir), id)
             next unless unit
 
             last_modified = unit.dig('metadata', 'git', 'last_modified')
@@ -872,6 +968,10 @@ module Woods
 
         marker = Woods::Generation.new(output_dir: @index_dir).current
         resolve_payload_dir(marker).join('manifest.json').file?
+      rescue TypeError, NoMethodError
+        # Match Bootstrapper's startup preflight for malformed marker shapes.
+        # Keep this local: errors during later generation refresh still surface.
+        false
       end
 
       # The loaded generation's payload directory, without a freshness check.
@@ -1102,15 +1202,80 @@ module Woods
           entries = read_index(dir)
           entries.each do |entry|
             id = entry['identifier']
-            base = id.gsub('::', '__').gsub(/[^a-zA-Z0-9_-]/, '_')
-            digest = Digest::SHA256.hexdigest(id)[0, 8]
-            filename = "#{base}_#{digest}.json"
-            map[id] = { type_dir: dir, filename: filename }
+            map[id] = { type_dir: dir, filename: unit_filename(id) }
           end
         end
         map
       end
 
+      # Read the selected type bucket, never the identifier-only lookup map.
+      # Keep the existing per-file signature checks and LRU cache for deep reads.
+      def load_search_unit(type, identifier)
+        data = load_unit(TYPE_TO_DIR.fetch(type), unit_filename(identifier))
+        unless valid_published_unit?(data, TYPE_TO_DIR.fetch(type), identifier)
+          raise IOError, "typed unit identity mismatch: #{type}:#{identifier}"
+        end
+
+        data
+      end
+
+      def unit_filename(identifier)
+        base = identifier.gsub('::', '__').gsub(/[^a-zA-Z0-9_-]/, '_')
+        "#{base}_#{Digest::SHA256.hexdigest(identifier)[0, 8]}.json"
+      end
+
+      def search_index_entries(dir)
+        entries = published_unit_entries(dir)
+        seen = Set.new
+        entries.each do |entry|
+          id = entry.is_a?(Hash) && entry['identifier']
+          unless id.is_a?(String) && !id.empty? && seen.add?(id)
+            raise IOError, "invalid or duplicate unit identifier in #{dir}/_index.json"
+          end
+        end
+        entries
+      end
+
+      def published_unit_entries(dir)
+        index_path = current_payload_dir.join(dir, '_index.json')
+        raise IOError, "symlink unit index: #{dir}" if index_path.symlink?
+
+        expected = manifest.dig('counts', dir)
+        raise IOError, "missing unit index: #{dir}/_index.json" if !index_path.file? && expected.to_i.positive?
+
+        entries = read_index(dir)
+        raise IOError, "invalid unit index: #{dir}" unless entries.is_a?(Array)
+        if expected.is_a?(Integer) && entries.size != expected
+          raise IOError, "unit count mismatch in #{dir}: expected #{expected}, found #{entries.size}"
+        end
+
+        entries
+      end
+
+      def read_published_unit(dir, identifier)
+        base = identifier.gsub('::', '__').gsub(/[^a-zA-Z0-9_-]/, '_')
+        filename = "#{base}_#{Digest::SHA256.hexdigest(identifier)[0, 8]}.json"
+        path = current_payload_dir.join(dir, filename)
+        raise IOError, "symlink unit file: #{dir}/#{filename}" if path.symlink?
+
+        raise IOError, "non-regular unit file: #{dir}/#{filename}" unless path.lstat.file?
+
+        data = File.open(path, File::RDONLY | File::NOFOLLOW | File::NONBLOCK) do |file|
+          raise IOError, "non-regular unit file: #{dir}/#{filename}" unless file.stat.file?
+
+          JSON.parse(file.read)
+        end
+        unless valid_published_unit?(data, dir, identifier)
+          raise IOError, "typed unit identity mismatch: #{dir}/#{filename}"
+        end
+
+        data
+      end
+
+      def valid_published_unit?(data, dir, identifier)
+        data.is_a?(Hash) && data['identifier'] == identifier && UNIT_TYPES_BY_DIR.fetch(dir).include?(data['type'])
+      end
+
       # Read and cache an _index.json file for a type directory.
       def read_index(dir)
         @index_cache ||= {}
@@ -1229,6 +1394,16 @@ module Woods
         end
       end
 
+      # Ownership/type preparation is cached once per retained generation, like
+      # graph_node_types. It never flattens adjacency; the per-query walker charges
+      # every candidate edge, including legacy reverse evidence recovery.
+      def traverse_with_evidence(identifier, **options)
+        with_pinned_generation do
+          @traversal_evidence_index ||= TraversalEvidenceIndex.new(raw_graph_data)
+          TraversalEvidence.new(@traversal_evidence_index).call(identifier, **options)
+        end
+      end
+
       # BFS traversal in either direction.
       #
       # Edges may be stored as bare strings (old format) or as
@@ -1241,70 +1416,89 @@ module Woods
       # @param via [Array<String>, nil] Filter to these relationship types
       # @param direction [:forward, :reverse] Traversal direction
       # @return [Hash]
-      def traverse(identifier, depth:, types:, via:, direction:)
+      def traverse(identifier, depth:, types:, via:, direction:, max_nodes:, max_edges:)
         graph_data = raw_graph_data
         nodes_data = graph_data['nodes'] || {}
-
         return { root: identifier, found: false, nodes: {} } unless nodes_data.key?(identifier)
 
-        # Normalize edges once per graph load — memoized alongside raw_graph_data
-        normalized_edges = normalized_graph_edges
-
+        budget = {
+          max_nodes: max_nodes.to_i.clamp(1, 10_000),
+          max_edges: max_edges.to_i.clamp(1, 100_000),
+          visited_nodes: 1, visited_edges: 0
+        }
         type_set = types&.to_set
         via_set = via&.to_set
         visited = Set.new([identifier])
         queue = [[identifier, 0]]
         result_nodes = {}
+        cursor = 0
+        partial_reason = nil
 
-        while queue.any?
-          current, current_depth = queue.shift
-
-          neighbors = if direction == :forward
-                        resolve_forward_neighbors(normalized_edges, current, via_set)
-                      else
-                        resolve_reverse_neighbors(graph_data, normalized_edges, current, via_set)
-                      end
-
-          # Filter by node type if requested. An identifier naming units of
-          # several types matches when any of them does — excluding it because
-          # the type that happens to sort first is not the requested one would
-          # hide a unit the filter asked for.
-          filtered = if type_set
-                       neighbors.select { |n| graph_node_types[n]&.any? { |t| type_set.include?(t) } }
-                     else
-                       neighbors
-                     end
-
-          # At max depth, record the node with empty deps so the renderer
-          # doesn't emit an extra level of unexpanded neighbors. The parent
-          # node's deps list already shows this node as a child.
-          will_expand = current_depth < depth
+        while cursor < queue.size
+          current, current_depth = queue[cursor]
+          cursor += 1
           node_meta = nodes_data[current]
-          entry = {
-            type: node_meta&.dig('type'),
-            depth: current_depth,
-            deps: will_expand ? filtered : []
-          }
-          # Only when the identifier is genuinely ambiguous, so the shape is
-          # unchanged for every node in an index with no shared identifiers.
+          entry = { type: node_meta&.dig('type'), depth: current_depth, deps: [] }
           node_types = graph_node_types[current] || []
           entry[:types] = node_types if node_types.size > 1
-          # Likewise: a single-database app learns nothing from a column that
-          # answers the same thing on every row (B-183).
           entry[:database] = node_meta&.dig('database') if multi_database_graph?
           result_nodes[current] = entry
+          next if partial_reason || current_depth >= depth
+
+          # Keep every discovered row, even after expansion stops. No dangling
+          # deps are introduced by the budget, and paging stays independent.
+          partial_reason = catch(:traversal_budget) do
+            each_traversal_neighbor(graph_data, current, direction, via_set, budget) do |neighbor|
+              next if type_set && !graph_node_types[neighbor]&.any? { |type| type_set.include?(type) }
+
+              unless visited.include?(neighbor)
+                throw :traversal_budget, 'node_budget' if visited.size >= budget[:max_nodes]
+
+                visited.add(neighbor)
+                budget[:visited_nodes] += 1
+                queue << [neighbor, current_depth + 1]
+              end
+              entry[:deps] << neighbor
+            end
+            nil
+          end
+        end
 
-          next unless will_expand
+        result = { root: identifier, found: true, nodes: result_nodes }
+        result.merge!(partial: true, partial_reason: partial_reason, traversal_budget: budget) if partial_reason
+        result
+      end
 
-          filtered.each do |neighbor|
-            unless visited.include?(neighbor)
-              visited.add(neighbor)
-              queue.push([neighbor, current_depth + 1])
+      # Walk stored adjacency order lazily. In reverse traversal a via filter
+      # must inspect forward edges too; those checks consume the same budget.
+      # Whole-generation JSON loading is deliberately outside the walk budget.
+      def each_traversal_neighbor(graph_data, identifier, direction, via_set, budget)
+        edges = normalized_graph_edges
+        if direction == :forward
+          (edges[identifier] || []).each do |edge|
+            consume_traversal_edge(budget)
+            edge = { 'target' => edge } unless edge.is_a?(Hash)
+            yield edge['target'] unless via_set && !via_set.include?(edge['via'])
+          end
+        else
+          ((graph_data['reverse'] || {})[identifier] || []).each do |dependent|
+            consume_traversal_edge(budget)
+            if via_set
+              matches = (edges[dependent] || []).any? do |edge|
+                consume_traversal_edge(budget)
+                edge.is_a?(Hash) && edge['target'] == identifier && via_set.include?(edge['via'])
+              end
+              next unless matches
             end
+            yield dependent
           end
         end
+      end
+
+      def consume_traversal_edge(budget)
+        throw :traversal_budget, 'edge_budget' if budget[:visited_edges] >= budget[:max_edges]
 
-        { root: identifier, found: true, nodes: result_nodes }
+        budget[:visited_edges] += 1
       end
 
       # Normalize all edge arrays once, converting bare strings to hashes.
@@ -1321,28 +1515,6 @@ module Woods
           entries.map { |e| e.is_a?(Hash) ? e : { 'target' => e } }
         end
       end
-
-      # Extract forward neighbor identifiers, optionally filtered by via type.
-      # Expects pre-normalized edges (all entries are hashes).
-      def resolve_forward_neighbors(normalized_edges, identifier, via_set)
-        edges = normalized_edges[identifier] || []
-        edges = edges.select { |e| via_set.include?(e['via']) } if via_set
-        edges.map { |e| e['target'] }
-      end
-
-      # Extract reverse neighbor identifiers, optionally filtered by via type.
-      # Reverse edges are stored as bare identifier arrays. When via filtering
-      # is requested, checks each dependent's pre-normalized forward edges to
-      # find those pointing at +identifier+ with a matching via type.
-      def resolve_reverse_neighbors(graph_data, normalized_edges, identifier, via_set)
-        dependents = (graph_data['reverse'] || {})[identifier] || []
-        return dependents unless via_set
-
-        dependents.select do |dep|
-          forward = normalized_edges[dep] || []
-          forward.any? { |e| e['target'] == identifier && via_set.include?(e['via']) }
-        end
-      end
     end
   end
 end