woods 2.0.0.beta1 → 2.0.0.beta3

data/lib/woods/resilience/index_validator/graph_checks.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Woods
+  module Resilience
+    class IndexValidator
+      # Reuse the published reader's retention pin but inspect raw graph and
+      # unit artifacts independently, without normalizing away bad records.
+      module GraphChecks
+        private
+
+        def with_validation_payload
+          root = Pathname.new(@index_dir)
+          if root.join('manifest.json').exist? || root.join('generation.json').exist?
+            Woods::PublishedIndex::GenerationCatalog.pointer(root)
+            reader = Woods::MCP::IndexReader.new(root)
+            reader.with_pinned_generation do
+              @validation_payload = reader.payload_dir.to_s
+              @validation_manifest = reader.manifest
+              yield
+            end
+          else
+            @validation_payload = @index_dir
+            yield
+          end
+        ensure
+          @validation_payload = nil
+          @validation_manifest = nil
+          @graph_index_entries = nil
+        end
+
+        def static_source_map?
+          manifest = @validation_manifest
+          manifest.is_a?(Hash) && manifest['provenance'].is_a?(Hash) &&
+            manifest['provenance']['mode'] == 'woods_static_ruby_source'
+        end
+
+        def validation_index_entries(path, errors)
+          entries = JSON.parse(Woods::AtomicFile.read(path))
+          unless entries.is_a?(Array)
+            errors << "#{path}: expected an array"
+            return []
+          end
+          entries.select do |entry|
+            valid = entry.is_a?(Hash) && entry['identifier'].is_a?(String) && !entry['identifier'].empty?
+            errors << "#{path}: entry requires a nonempty identifier" unless valid
+            valid
+          end
+        end
+
+        def collect_graph_index_entry(type_dir, entry, data, errors)
+          directory = File.basename(type_dir)
+          types = Woods::MCP::IndexReader::UNIT_TYPES_BY_DIR.fetch(directory)
+          typed_entry = graph_index_entry(entry, data, types)
+          @graph_index_entries << typed_entry
+          return unless data
+
+          file = find_unit_file(type_dir, entry['identifier'])
+          unless data['identifier'] == entry['identifier'] && types.include?(data['type'])
+            errors << "#{file}: expected typed unit #{typed_entry['type']}:#{entry['identifier']}"
+            return
+          end
+          validate_graph_unit_path(file, entry, data, errors)
+        end
+
+        def graph_index_entry(entry, data, types)
+          type = data && types.include?(data['type']) ? data['type'] : types.first
+          result = entry.merge('type' => type)
+          result['file_path'] = data['file_path'] if data&.key?('file_path') && !entry.key?('file_path')
+          result
+        end
+
+        def validate_graph_unit_path(file, entry, data, errors)
+          return unless entry.key?('file_path') && data.key?('file_path') && entry['file_path'] != data['file_path']
+
+          errors << "#{file}: file_path differs from #{File.dirname(file)}/_index.json for #{entry['identifier']}"
+        end
+      end
+    end
+  end
+end

data/lib/woods/resilience/index_validator.rb

@@ -2,10 +2,16 @@
 
 require 'json'
 require 'set'
+require 'rubygems/version'
+require_relative '../version'
 require_relative '../filename_utils'
 require_relative '../atomic_file'
 
 require_relative '../generation'
+require_relative '../published_index'
+require_relative 'graph_invariant_validator'
+require_relative 'index_validator/graph_checks'
+require_relative '../source_inputs/manifest'
 
 module Woods
   module Resilience
@@ -16,6 +22,8 @@ module Woods
     # - All files referenced in the index exist on disk
     # - Content hashes (source_hash) match the actual source_code
     # - No stale unit files exist that aren't listed in the index
+    # - Typed graph identities and reverse/file/type memberships agree
+    # All checks share one pinned generation; the validator never repairs it.
     #
     # **This class knows nothing about vectors or embedding dimensions.** Six
     # documents used to credit it with detecting dimension mismatches; it never
@@ -23,10 +31,8 @@ module Woods
     # `Tasks.verify_store_dimensions!` before a durable embed run and by
     # {Woods::Storage::Snapshotter::Vector} at MCP boot.
     #
-    # Consumed by `spec/integration/multi_worktree_spec.rb` as a per-worktree
-    # integrity oracle. The `woods:validate` rake task performs an overlapping
-    # check inline rather than calling this — deliberate duplication left alone
-    # for now, since the task's output format is user-facing.
+    # Shared by the `woods:validate` rake task and worktree integration checks.
+    # Writer-version mismatches are advisory; structural errors still fail.
     #
     # @example
     #   validator = IndexValidator.new(index_dir: "tmp/woods")
@@ -34,6 +40,7 @@ module Woods
     #   puts report.errors if !report.valid?
     class IndexValidator # rubocop:disable Metrics/ClassLength
       include Woods::FilenameUtils
+      include GraphChecks
 
       # Report produced by {#validate}.
       #
@@ -84,13 +91,19 @@ module Woods
           return ValidationReport.new(valid?: false, warnings: warnings, errors: errors)
         end
 
-        payload_type_dirs(errors).each do |type_dir|
-          validate_type_directory(type_dir, warnings, errors)
+        with_validation_payload do
+          @graph_index_entries = []
+          payload_type_dirs(errors).each do |type_dir|
+            validate_type_directory(type_dir, warnings, errors)
+          end
+          validate_flow_artifacts(errors)
+          validate_against_manifest(warnings, errors)
         end
-        validate_flow_artifacts(errors)
-        validate_against_manifest(warnings, errors)
 
         ValidationReport.new(valid?: errors.empty?, warnings: warnings, errors: errors)
+      rescue IOError, SystemCallError, ArgumentError, JSON::ParserError, Woods::PublishedIndex::CorruptPointerError => e
+        errors << "Cannot read published index: #{e.class}: #{e.message}"
+        ValidationReport.new(valid?: false, warnings: warnings, errors: errors)
       end
 
       # The checks `woods:validate` used to carry inline: manifest counts
@@ -107,19 +120,72 @@ module Woods
         manifest_path = File.join(payload, 'manifest.json')
         return unless File.exist?(manifest_path)
 
-        manifest = JSON.parse(Woods::AtomicFile.read(manifest_path))
+        manifest = read_validation_manifest(manifest_path, errors)
+        return unless manifest
+
+        validate_writer_version(manifest['woods_version'], warnings)
         unresolvable = Hash.new { |hash, key| hash[key] = [] }
 
-        (manifest['counts'] || {}).each do |type, expected_count|
+        manifest.fetch('counts', {}).each do |type, expected_count|
           validate_manifest_type(payload, type, expected_count, unresolvable, warnings, errors)
         end
 
         warn_unresolvable_paths(warnings, unresolvable)
         validate_dependency_graph(payload, errors)
+        validate_source_inputs(payload, errors)
+      end
+
+      # Optional for old generations; malformed new provenance is an artifact
+      # integrity error. Source drift itself is advisory and belongs to status.
+      def validate_source_inputs(payload, errors)
+        path = File.join(payload, SourceInputs::Manifest::FILE_NAME)
+        return unless File.exist?(path)
+
+        File.open(path, File::RDONLY | File::NONBLOCK) do |file|
+          raise SourceInputs::Manifest::Invalid unless file.stat.file?
+
+          SourceInputs::Manifest.parse(file.read(SourceInputs::Manifest::MAX_BYTES + 1))
+        end
+      rescue SourceInputs::Manifest::Invalid, SystemCallError, IOError
+        errors << 'Invalid source_inputs.json provenance artifact'
+      end
+
+      def read_validation_manifest(path, errors)
+        manifest = JSON.parse(Woods::AtomicFile.read(path))
+        unless manifest.is_a?(Hash)
+          errors << 'manifest.json: expected an object'
+          return
+        end
+        unless manifest.fetch('counts', {}).is_a?(Hash)
+          errors << 'manifest.json counts: expected an object'
+          return
+        end
+
+        manifest
+      end
+
+      # The version records the last publisher, not the producer of every
+      # retained unit. Missing provenance is normal for older indexes.
+      def validate_writer_version(value, warnings)
+        return if value.nil?
+
+        unless value.is_a?(String) && !value.strip.empty?
+          warnings << 'Invalid manifest woods_version; writer provenance is unknown. Run a full woods:extract.'
+          return
+        end
+
+        writer = Gem::Version.new(value)
+        reader = Gem::Version.new(Woods::VERSION)
+        return if writer.segments.first == reader.segments.first
+
+        warnings << "Index last published by Woods #{value}; reader is Woods #{Woods::VERSION}. " \
+                    'Major versions differ. Run a full woods:extract before relying on compatibility.'
+      rescue ArgumentError
+        warnings << 'Invalid manifest woods_version; writer provenance is unknown. Run a full woods:extract.'
       end
 
-      # Split each type's unresolvable units into app-tree paths and gem-owned
-      # paths, since only the first has a remedy the operator can act on.
+      # Split unresolvable app-tree paths from gem-owned paths so each warning
+      # can distinguish a different filesystem environment from a changed bundle.
       #
       # @param warnings [Array<String>]
       # @param unresolvable [Hash{String => Array<Array(String, Boolean)>}]
@@ -143,15 +209,16 @@ module Woods
 
       # Absolute paths outside the app root belong to a gem — an engine model,
       # a framework source — and resolve only where that gem is installed at
-      # the extracting path. Re-running extraction here cannot change that,
-      # so the remedy is not offered.
+      # the extracting path. A changed bundle requires fresh extraction; a
+      # reader on another filesystem instead needs the original gem paths.
       def warn_unresolvable_gem_paths(warnings, type, identifiers)
         return if identifiers.empty?
 
         warnings << "#{type}: #{identifiers.size} unit(s) whose file_path lies outside the app root " \
                     "and is absent here (e.g. #{identifiers.first(3).join(', ')}). Gem-owned units " \
                     '(engine models, framework sources) resolve only where that gem is installed at ' \
-                    'the extracting path.'
+                    'the extracting path. After a bundle update, run woods:extract in a fresh process ' \
+                    'with the updated bundle, then woods:validate.'
       end
 
       # rubocop:disable-next Metrics/ParameterLists
@@ -175,6 +242,10 @@ module Woods
       # @param errors [Array<String>]
       def validate_unit_file(file, type, unresolvable, errors)
         data = JSON.parse(Woods::AtomicFile.read(file))
+        unless data.is_a?(Hash)
+          errors << "#{file}: expected a unit object"
+          return
+        end
         errors << "#{file}: missing identifier" unless data['identifier']
         errors << "#{file}: missing source_code" unless data['source_code']
         file_path = data['file_path']
@@ -211,13 +282,14 @@ module Woods
           return
         end
 
-        JSON.parse(Woods::AtomicFile.read(graph_path))
+        graph = JSON.parse(Woods::AtomicFile.read(graph_path))
+        errors.concat(GraphInvariantValidator.new(graph: graph, index_entries: @graph_index_entries).validate)
       rescue JSON::ParserError
         errors << 'dependency_graph.json: invalid JSON'
       end
 
       def payload_dir
-        Woods::Generation.new(output_dir: @index_dir).payload_dir.to_s
+        @validation_payload || Woods::Generation.new(output_dir: @index_dir).payload_dir.to_s
       end
 
       private
@@ -292,12 +364,18 @@ module Woods
       # failure RAISES: {#payload_type_dirs} converts it to a validation
       # error rather than degrading to a silently empty allowlist.
       #
+      # The explicit Woods static-map provenance additionally admits the
+      # GemMapper's own type families; arbitrary directories stay excluded.
       # `flows/` is deliberately absent: it holds `flow_index.json` and
       # per-flow documents, which {#validate_flow_artifacts} owns.
       #
       # @return [Array<String>]
       def type_directory_allowlist
-        @type_directory_allowlist ||= self.class.unit_type_directories
+        directories = self.class.unit_type_directories
+        return directories unless static_source_map?
+
+        require_relative '../gem_mapper'
+        directories | Woods::GemMapper::TYPE_DIRECTORIES.values
       end
 
       # Validate the flows/ artifact family (G-2): `flow_index.json` parses,
@@ -361,13 +439,12 @@ module Woods
           return
         end
 
-        index_entries = JSON.parse(Woods::AtomicFile.read(index_path))
         indexed_identifiers = Set.new
-
-        index_entries.each do |entry|
+        validation_index_entries(index_path, errors).each do |entry|
           identifier = entry['identifier']
           indexed_identifiers << identifier
-          validate_index_entry(type_dir, type_name, identifier, errors)
+          data = validate_index_entry(type_dir, type_name, identifier, errors)
+          collect_graph_index_entry(type_dir, entry, data, errors)
         end
 
         check_stale_files(type_dir, type_name, indexed_identifiers, warnings)
@@ -413,11 +490,23 @@ module Woods
       # @param errors [Array<String>] Accumulated errors
       def validate_content_hash(unit_file, identifier, errors)
         data = JSON.parse(Woods::AtomicFile.read(unit_file))
+        unless data.is_a?(Hash)
+          errors << "#{unit_file}: expected a unit object"
+          return
+        end
+        check_content_hash(data, identifier, errors)
+        data
+      end
+
+      def check_content_hash(data, identifier, errors)
         source_code = data['source_code']
         stored_hash = data['source_hash']
-
         return unless source_code && stored_hash
 
+        unless source_code.is_a?(String) && stored_hash.is_a?(String)
+          errors << "#{identifier}: source_code and source_hash must be strings"
+          return
+        end
         expected_hash = Digest::SHA256.hexdigest(source_code)
         return if stored_hash == expected_hash
 

data/lib/woods/retrieval/context_assembler.rb

@@ -2,6 +2,7 @@
 
 require_relative 'search_executor'
 require_relative '../token_utils'
+require_relative 'source_evidence'
 
 module Woods
   module Retrieval
@@ -103,7 +104,18 @@ module Woods
       # @param structural_context [String, nil] Optional codebase overview text
       # @param budget [Integer, nil] Override token budget; falls back to @budget
       # @return [AssembledContext] Token-budgeted context with source attribution
-      def assemble(candidates:, classification:, structural_context: nil, budget: nil)
+      def assemble(**options)
+        # Pipeline assemblers are shared by concurrent Ruby/HTTP callers. Keep
+        # per-request metadata, query, mode and generation on a private worker.
+        dup.send(:assemble_request, **options)
+      end
+
+      def assemble_request(candidates:, classification:, structural_context: nil, budget: nil,
+                           evidence: 'full', query: nil, generation: nil)
+        SourceEvidence.validate_mode!(evidence)
+        @evidence_mode = evidence
+        @evidence_query = query
+        @evidence_generation = generation
         effective_budget = budget || @budget
         sections = []
         sources = []
@@ -132,6 +144,22 @@ module Woods
         build_result(sections, sources, effective_budget, @skipped_missing_metadata)
       end
 
+      private :assemble_request
+
+      # Estimate token count. Prefers the injected {TokenCounter} — which
+      # loads the provider's real tokenizer and returns exact counts — and
+      # falls back to the configured chars-per-token ratio when no counter
+      # is wired.
+      #
+      # @param text [String]
+      # @return [Integer]
+      def estimate_tokens(text)
+        return 0 if text.nil? || text.empty?
+        return @token_counter.count(text) if @token_counter
+
+        (text.length / @chars_per_token).ceil
+      end
+
       private
 
       # Suffix the Indexer appends when a single unit is split into multiple
@@ -293,6 +321,10 @@ module Woods
           return tokens_used
         end
 
+        if @evidence_mode != 'full'
+          return append_compact_candidate(parts, sources, candidate, unit, budget, tokens_used)
+        end
+
         text = format_unit(unit, candidate)
         tokens = estimate_tokens(text)
         remaining = budget - tokens_used
@@ -308,6 +340,23 @@ module Woods
         end
       end
 
+      def append_compact_candidate(parts, sources, candidate, unit, budget, tokens_used)
+        header = "## #{unit_field(unit, :identifier)} (#{unit_field(unit, :type)})\n" \
+                 "File: #{unit_field(unit, :file_path)}\n\n"
+        remaining = budget - tokens_used
+        return tokens_used unless remaining.positive?
+
+        evidence = SourceEvidence.new(unit: unit, query: @evidence_query, generation: @evidence_generation)
+                                 .render(mode: @evidence_mode, budget: remaining,
+                                         counter: ->(text) { estimate_tokens(header + text) })
+        return tokens_used if evidence.text.empty?
+
+        text = header + evidence.text
+        parts << text
+        sources << build_source_attribution(candidate, unit).merge(evidence: evidence.provenance)
+        tokens_used + estimate_tokens(text)
+      end
+
       # Format a unit for inclusion in context.
       #
       # @param unit [Hash] Unit data from metadata store
@@ -400,20 +449,6 @@ module Woods
         "#{text[0...target_chars]}\n... [truncated]"
       end
 
-      # Estimate token count. Prefers the injected {TokenCounter} — which
-      # loads the provider's real tokenizer and returns exact counts — and
-      # falls back to the configured chars-per-token ratio when no counter
-      # is wired.
-      #
-      # @param text [String]
-      # @return [Integer]
-      def estimate_tokens(text)
-        return 0 if text.nil? || text.empty?
-        return @token_counter.count(text) if @token_counter
-
-        (text.length / @chars_per_token).ceil
-      end
-
       # Effective chars-per-token for chunk-size sizing. When an exact
       # counter is present, prefer its native ratio (e.g. 1.2 for
       # nomic-embed-text) so truncation and estimation agree. Falls back

data/lib/woods/retrieval/lexical_assembler.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require_relative 'context_assembler'
+require_relative 'lexical_index'
+
+module Woods
+  module Retrieval
+    # Lexical context keeps matching evidence visible and charges every notice,
+    # header and truncation marker to the same character-based token estimate.
+    class LexicalAssembler
+      def estimate_tokens(text)
+        (text.length / 4.0).ceil
+      end
+
+      def assemble(candidates:, budget:, evidence: 'full', query: nil, generation: nil, **)
+        SourceEvidence.validate_mode!(evidence)
+        raise ArgumentError, 'budget must be a positive Integer' unless budget.is_a?(Integer) && budget.positive?
+
+        context = 'Mode: lexical (field-aware BM25; ranked top 20; token counts estimated).'
+        context += "\nNo lexical matches." if candidates.empty?
+        context = context[0, budget * 4]
+        sources = []
+        candidates.each do |candidate|
+          unit = candidate.metadata
+          header = "\n\n## #{unit['identifier']} (#{unit['type']})\nFile: #{unit['file_path']}\n" \
+                   "Matched: #{candidate.matched_fields.join(', ')}\n\n"
+          remaining = (budget * 4) - context.length - header.length
+          next unless remaining.positive?
+
+          if evidence != 'full'
+            selected = SourceEvidence.new(unit: unit, query: query, generation: generation)
+                                     .render(mode: evidence, budget: budget,
+                                             counter: ->(text) { estimate_tokens(context + header + text) })
+            next if selected.text.empty?
+
+            context += header + selected.text
+            sources << { identifier: unit['identifier'], type: unit['type'], file_path: unit['file_path'],
+                         score: candidate.score, matched_fields: candidate.matched_fields,
+                         evidence: selected.provenance }
+            next
+          end
+
+          source = evidence_text(candidate)
+          truncated = source.length > remaining
+          marker = "\n[Published evidence truncated; use lookup for the full unit.]"
+          next if truncated && remaining <= marker.length
+
+          context += header + (truncated ? source[0, remaining - marker.length] + marker : source)
+          sources << { identifier: unit['identifier'], type: unit['type'], file_path: unit['file_path'],
+                       score: candidate.score, matched_fields: candidate.matched_fields, truncated: truncated }
+          break if truncated
+        end
+        AssembledContext.new(context: context, tokens_used: estimate_tokens(context), budget: budget,
+                             sources: sources, sections: [:primary], skipped_missing_metadata: 0)
+      end
+
+      private
+
+      def evidence_text(candidate)
+        unit = candidate.metadata
+        source = unit['source_code'].to_s
+        return source unless candidate.matched_fields.any? { |field| field.start_with?('runtime:') }
+
+        metadata = unit['metadata'].is_a?(Hash) ? unit['metadata'] : {}
+        values = LexicalIndex::RUNTIME_FIELDS.each_with_object({}) do |key, selected|
+          value = metadata[key] || unit[key]
+          selected[key] = value unless value.nil?
+        end
+        "Published runtime metadata:\n#{JSON.pretty_generate(values)}\n\n#{source}"
+      end
+    end
+  end
+end

data/lib/woods/retrieval/lexical_index.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require 'json'
+require_relative 'query_classifier'
+require_relative 'search_executor'
+
+module Woods
+  module Retrieval
+    # Immutable field-aware lexical snapshot. Only published unit values enter
+    # the vocabulary; bookkeeping and arbitrary JSON keys cannot become hits.
+    class LexicalIndex
+      FIELD_WEIGHTS = { 'identifier' => 4.0, 'file_path' => 2.0, 'source_code' => 1.0, 'runtime' => 2.0 }.freeze
+      RUNTIME_FIELDS = %w[callbacks associations validations scopes concerns included_modules
+                          methods instance_methods class_methods actions routes columns table_name
+                          description purpose dependencies].freeze
+      K1 = 1.2
+      B = 0.75
+      Document = Struct.new(:key, :unit, :fields, keyword_init: true)
+      private_constant :Document
+
+      def initialize(metadata_store:)
+        @documents = metadata_store.all_identifiers.sort.map do |key|
+          unit = metadata_store.find(key)
+          raise ArgumentError, "missing unit metadata for #{key.inspect}" unless unit.is_a?(Hash)
+
+          unit = JSON.parse(JSON.generate(unit))
+          fields = field_values(unit).transform_values { |value| tokenize(value).tally.freeze }.freeze
+          Document.new(key: key.freeze, unit: deep_freeze(unit), fields: fields).freeze
+        end.compact.freeze
+        @averages = FIELD_WEIGHTS.to_h do |field, _|
+          lengths = @documents.map { |doc| doc.fields.fetch(field).values.sum }
+          [field, lengths.empty? ? 1.0 : [lengths.sum.fdiv(lengths.size), 1.0].max]
+        end.freeze
+        @frequencies = Hash.new(0)
+        @documents.each { |doc| doc.fields.values.flat_map(&:keys).uniq.each { |term| @frequencies[term] += 1 } }
+        @frequencies.freeze
+      end
+
+      def execute(query:, limit: 20, type_filter: nil, exclude_types: nil)
+        terms = tokenize(query).uniq
+        candidates = @documents.filter_map do |doc|
+          next unless eligible?(doc.unit, type_filter, exclude_types)
+
+          score, fields = score_document(doc, terms)
+          exact = doc.unit['identifier'].to_s.casecmp?(query.strip)
+          score += 1.0 if exact
+          fields << 'identifier:exact' if exact
+          next unless score.positive?
+
+          SearchExecutor::Candidate.new(identifier: doc.key, score: score, source: :lexical,
+                                        metadata: doc.unit, matched_fields: fields.sort)
+        end
+        candidates.sort_by! do |candidate|
+          [candidate.matched_fields.include?('identifier:exact') ? 0 : 1, -candidate.score, candidate.identifier]
+        end
+        SearchExecutor::ExecutionResult.new(candidates: candidates.first(limit), strategy: :lexical, query: query)
+      end
+
+      private
+
+      def tokenize(value)
+        value.to_s.gsub(/(\p{Ll}|\d)(\p{Lu})/u, '\1 \2')
+             .gsub(/(\p{Lu})(\p{Lu}\p{Ll})/u, '\1 \2').downcase
+             .scan(/[\p{L}\p{N}]+/u).reject { |term| QueryClassifier::STOP_WORDS.include?(term) }
+      end
+
+      def field_values(unit)
+        metadata = unit['metadata'].is_a?(Hash) ? unit['metadata'] : {}
+        runtime = RUNTIME_FIELDS.filter_map { |key| metadata[key] || unit[key] }
+        { 'identifier' => unit['identifier'], 'file_path' => unit['file_path'],
+          'source_code' => unit['source_code'], 'runtime' => values_text(runtime) }
+      end
+
+      def values_text(value)
+        case value
+        when Hash then value.values.map { |child| values_text(child) }.join(' ')
+        when Array then value.map { |child| values_text(child) }.join(' ')
+        when String, Symbol, Numeric then value.to_s
+        else ''
+        end
+      end
+
+      def eligible?(unit, allowed, excluded)
+        return allowed.map(&:to_s).include?(unit['type']) if allowed && !allowed.empty?
+
+        !Array(excluded).map(&:to_s).include?(unit['type'])
+      end
+
+      def score_document(doc, terms)
+        fields = []
+        score = FIELD_WEIGHTS.sum do |field, weight|
+          counts = doc.fields.fetch(field)
+          normalization = K1 * (1 - B + (B * counts.values.sum / @averages.fetch(field)))
+          terms.sum do |term|
+            frequency = counts.fetch(term, 0)
+            next 0.0 if frequency.zero?
+
+            fields << "#{field}:#{term}"
+            document_frequency = @frequencies.fetch(term)
+            idf = Math.log(1 + ((@documents.size - document_frequency + 0.5) / (document_frequency + 0.5)))
+            weight * idf * frequency * (K1 + 1) / (frequency + normalization)
+          end
+        end
+        [score, fields]
+      end
+
+      def deep_freeze(value)
+        case value
+        when Hash then value.each do |key, child|
+          key.freeze
+          deep_freeze(child)
+        end
+        when Array then value.each { |child| deep_freeze(child) }
+        end
+        value.freeze
+      end
+    end
+  end
+end

data/lib/woods/retrieval/ranker.rb

@@ -378,7 +378,9 @@ module Woods
 
       # Lazily-computed rank-percentile map derived from the graph store's PageRank.
       #
-      # Top-ranked identifier gets 1.0, bottom-ranked gets 1/n. Identifiers absent
+      # Top-ranked identifier gets 1.0, bottom-ranked gets 1/n. Equal PageRank scores
+      # are ordered lexically by identifier so their ordinal percentiles do not
+      # depend on graph insertion order or Ruby's unstable sort. Identifiers absent
       # from PageRank (new units, ephemeral candidates) return nil and fall back
       # to the bucketed importance signal.
       #
@@ -402,7 +404,7 @@ module Woods
         scores = @graph_store.pagerank
         return {} if scores.nil? || scores.empty?
 
-        ranked = scores.sort_by { |_id, score| -score }
+        ranked = scores.sort_by { |identifier, score| [-score, identifier] }
         total = ranked.size.to_f
         ranked.each_with_index.to_h do |(identifier, _score), rank|
           [identifier, 1.0 - (rank / total)]