woods 2.0.0.beta2 → 2.0.0.beta4

data/lib/woods/retrieval/source_evidence.rb

@@ -0,0 +1,200 @@
+# frozen_string_literal: true
+
+require 'digest'
+require 'json'
+require_relative '../ast/parser'
+require_relative 'lexical_index'
+
+module Woods
+  module Retrieval
+    # Selects complete spans from published unit bytes, never from host files.
+    # Published coordinates deliberately do not claim physical source locations:
+    # extractors may synthesize headers or inline commented concern bodies.
+    class SourceEvidence
+      MODES = %w[full compact outline].freeze
+      Result = Struct.new(:text, :provenance, keyword_init: true)
+      Span = Struct.new(:kind, :name, :lexical_owner, :receiver, :start_byte, :end_byte, :start_line, :end_line,
+                        keyword_init: true)
+      private_constant :Span
+
+      def self.validate_mode!(mode)
+        return mode if MODES.include?(mode)
+
+        raise ArgumentError, 'evidence must be full, compact, or outline'
+      end
+
+      def initialize(unit:, query: nil, generation: nil, parser: Ast::Parser.new)
+        @unit = unit
+        @source = field(:source_code).to_s
+        @query = terms(query)
+        @generation = generation
+        @parser = parser
+      end
+
+      # The caller's counter includes the same tokenizer/estimate used by its
+      # response budget. No selected definition or metadata value is cut in half.
+      def render(mode:, budget:, counter:)
+        self.class.validate_mode!(mode)
+        raise ArgumentError, 'budget must be a positive Integer' unless budget.is_a?(Integer) && budget.positive?
+        raise ArgumentError, 'compact evidence requires compact or outline mode' if mode == 'full'
+
+        spans = source_spans
+        selected = []
+        metadata = []
+        ordered = spans.sort_by { |span| [-relevance(span), span.start_byte] }
+        relevant, other = ordered.partition { |span| @query.empty? || relevance(span).positive? }
+        relevant.each do |span|
+          trial = selected + [span]
+          selected = trial if counter.call(format_evidence(mode, trial, metadata, spans.size)) <= budget
+        end
+        runtime_records.each do |record|
+          trial = metadata + [record]
+          metadata = trial if counter.call(format_evidence(mode, selected, trial, spans.size)) <= budget
+        end
+        other.each do |span|
+          trial = selected + [span]
+          selected = trial if counter.call(format_evidence(mode, trial, metadata, spans.size)) <= budget
+        end
+        text = format_evidence(mode, selected, metadata, spans.size)
+        return Result.new(text: '', provenance: provenance(mode, [], [], spans)) if counter.call(text) > budget
+
+        Result.new(text: text, provenance: provenance(mode, selected, metadata, spans))
+      end
+
+      private
+
+      def field(key)
+        @unit[key] || @unit[key.to_s]
+      end
+
+      def source_spans
+        return [] if @source.empty?
+
+        spans = []
+        walk(@parser.parse(@source), nil, spans)
+        return whole_source_span('whole_source_fallback') unless spans.all? { |span| complete_definition?(span) }
+
+        spans.concat(concern_spans)
+        return spans unless spans.empty?
+
+        whole_source_span('published_source')
+      rescue Woods::ExtractionError
+        # Non-Ruby or legacy synthesized source remains available as one whole
+        # published span. An unavailable boundary is never guessed with regex.
+        whole_source_span('unparsed_source')
+      end
+
+      def whole_source_span(kind)
+        [Span.new(kind: kind, name: field(:identifier), lexical_owner: nil,
+                  start_byte: 0, end_byte: @source.bytesize, start_line: 1, end_line: @source.lines.size)]
+      end
+
+      # A heredoc body may live outside a def node's syntactic range (notably
+      # endless defs and same-line `def ...; <<~DOC; end`). Refuse a broken
+      # isolated definition and fall back to the complete published source.
+      def complete_definition?(span)
+        @parser.valid_fragment?(span_text(span))
+      end
+
+      def walk(node, owner, spans, singleton_scope: false)
+        return unless node.is_a?(Ast::Node)
+
+        if %i[class module].include?(node.type)
+          singleton_scope = false
+          name = node.method_name.to_s
+          owner = name.start_with?('::') ? name.delete_prefix('::') : [owner, name].compact.join('::')
+        elsif %i[def defs].include?(node.type)
+          if node.start_byte && node.end_byte
+            kind = if singleton_scope
+                     'singleton_body_method'
+                   else
+                     (node.type == :def ? 'instance_method' : 'singleton_method')
+                   end
+            spans << Span.new(kind: kind,
+                              name: node.method_name, lexical_owner: owner, receiver: node.receiver,
+                              start_byte: node.start_byte,
+                              end_byte: node.end_byte, start_line: node.line, end_line: node.end_line)
+          end
+          return # Nested definitions/blocks are already covered by the complete outer method.
+        end
+        node.children&.each do |child|
+          walk(child, owner, spans, singleton_scope: singleton_scope || node.type == :sclass)
+        end
+      end
+
+      # These are Woods' published display blocks, not physical concern source.
+      # Require matching published metadata and delimiters; preserve every byte,
+      # including comment prefixes, instead of reconstructing executable Ruby.
+      def concern_spans
+        metadata = field(:metadata) || {}
+        Array(metadata['inlined_concerns'] || metadata[:inlined_concerns]).filter_map do |name|
+          escaped = Regexp.escape(name.to_s)
+          pattern = /^# │ Included from: #{escaped}[^\S\r\n]*│\r?\n.*?^# ─+ End #{escaped} ─+\r?$/m
+          match = pattern.match(@source)
+          next unless match
+
+          start_byte = @source[0...match.begin(0)].bytesize
+          end_byte = @source[0...match.end(0)].bytesize
+          Span.new(kind: 'inlined_concern_display', name: name, lexical_owner: name,
+                   start_byte: start_byte, end_byte: end_byte,
+                   start_line: @source.byteslice(0, start_byte).count("\n") + 1,
+                   end_line: @source.byteslice(0, end_byte).count("\n") + 1)
+        end
+      end
+
+      def terms(value)
+        value.to_s.gsub(/(\p{Ll}|\d)(\p{Lu})/u, '\1 \2').downcase.scan(/[\p{L}\p{N}]+/u)
+             .reject { |term| QueryClassifier::STOP_WORDS.include?(term) }.uniq
+      end
+
+      def relevance(span)
+        ((terms(span.name) & @query).size * 4) + (terms(span_text(span)) & @query).size
+      end
+
+      def span_text(span)
+        @source.byteslice(span.start_byte...span.end_byte)
+      end
+
+      def runtime_records
+        metadata = field(:metadata)
+        return [] unless metadata.is_a?(Hash)
+
+        LexicalIndex::RUNTIME_FIELDS.filter_map do |key|
+          value = metadata[key] || metadata[key.to_sym]
+          next if value.nil?
+
+          record = [key, value]
+          record if @query.empty? || (terms(JSON.generate(record)) & @query).any?
+        end
+      end
+
+      def format_evidence(mode, selected, metadata, total)
+        parts = ["Evidence: #{mode}; published-unit coordinates (physical location unavailable).",
+                 "Unit: #{field(:type)}:#{field(:identifier)}; path: #{field(:file_path)}",
+                 "Source SHA256: #{Digest::SHA256.hexdigest(@source)}",
+                 "Generation: #{@generation || 'unavailable (not recorded by this metadata store)'}"]
+        selected.each do |span|
+          label = "#{span.kind} #{span.lexical_owner} #{span.name}; published lines #{span.start_line}-#{span.end_line}"
+          parts << (mode == 'outline' ? label : "#{label}\n```ruby\n#{span_text(span)}\n```")
+        end
+        parts << "Published runtime metadata:\n#{JSON.generate(metadata.to_h)}" unless metadata.empty?
+        parts << "Omitted: #{total - selected.size} source spans; remaining source/metadata not reproduced. " \
+                 'Use lookup with evidence: full for the complete published unit.'
+        parts.join("\n\n")
+      end
+
+      def provenance(mode, selected, metadata, all)
+        { mode: mode, owner: { identifier: field(:identifier), type: field(:type) },
+          coordinate_system: 'published_unit', source_sha256: Digest::SHA256.hexdigest(@source),
+          source_path: field(:file_path), physical_location: nil,
+          physical_location_reason: 'published unit may contain synthesized or inlined source',
+          generation: @generation, generation_status: @generation ? 'recorded' : 'unavailable',
+          spans: selected.map { |span| span.to_h.merge(sha256: Digest::SHA256.hexdigest(span_text(span))) },
+          omitted_spans: all.size - selected.size, runtime_fields: metadata.map(&:first),
+          source_complete: false, full_evidence: { tool: 'lookup', evidence: 'full',
+                                                   identifier: field(:identifier), type: field(:type),
+                                                   source_sha256: Digest::SHA256.hexdigest(@source) } }
+      end
+    end
+  end
+end

data/lib/woods/retriever.rb

@@ -8,6 +8,11 @@ require_relative 'retrieval/query_classifier'
 require_relative 'retrieval/search_executor'
 require_relative 'retrieval/ranker'
 require_relative 'retrieval/context_assembler'
+require_relative 'retrieval/lexical_index'
+require_relative 'retrieval/lexical_assembler'
+require_relative 'retrieval/scope'
+require_relative 'retrieval/scoped_vector_store'
+require_relative 'retrieval/scoped_graph_store'
 require_relative 'embedding/token_counter'
 require_relative 'token_utils'
 
@@ -59,6 +64,7 @@ module Woods
     ).freeze
 
     # Diagnostic trace for retrieval quality analysis.
+    # +tokens_used+ counts the final delivered context, including postprocessing.
     #
     # +skipped_missing_metadata+ carries {Retrieval::ContextAssembler}'s count
     # of candidates dropped because the metadata store had no record for
@@ -98,7 +104,7 @@ module Woods
     #
     # Nil for unfiltered queries.
     RetrievalResult = Struct.new(:context, :sources, :classification, :strategy, :tokens_used, :budget, :trace,
-                                 :type_rank_context, keyword_init: true)
+                                 :type_rank_context, :applied_scope, 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
@@ -191,7 +197,7 @@ module Woods
     # The reload transaction swaps the whole struct via {#swap_stores!}.
     #
     # @return [Pipeline]
-    attr_reader :pipeline
+    attr_reader :pipeline, :mode, :default_budget
 
     # Optional callback invoked with the pipeline struct the moment
     # {#retrieve} resolves it, before any pipeline work runs. Nil in
@@ -207,7 +213,13 @@ module Woods
     # @param graph_store [Storage::GraphStore::Interface] Graph store adapter
     # @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)
+    # @param default_budget [Integer] Token budget when retrieve omits budget
+    def initialize(vector_store:, metadata_store:, graph_store:, embedding_provider:, formatter: nil, mode: :semantic,
+                   default_budget: 8000)
+      raise ArgumentError, 'unknown retrieval mode' unless %i[semantic lexical].include?(mode)
+
+      @mode = mode
+      @default_budget = default_budget
       @embedding_provider = embedding_provider
       @formatter = formatter
       @classifier = Retrieval::QueryClassifier.new
@@ -246,7 +258,9 @@ module Woods
     # 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:)
+    def build_pipeline(vector_store:, metadata_store:, graph_store:) # rubocop:disable Metrics/MethodLength
+      return build_lexical_pipeline(metadata_store, graph_store) if @mode == :lexical
+
       translated_vector = translate_store(vector_store, :vector)
       translated_metadata = translate_store(metadata_store, :metadata)
       translated_graph = translate_store(graph_store, :graph)
@@ -269,6 +283,14 @@ module Woods
         graph_store: graph_store
       )
     end
+
+    def build_lexical_pipeline(metadata_store, graph_store)
+      executor = Retrieval::LexicalIndex.new(metadata_store: translate_store(metadata_store, :metadata))
+      Pipeline.new(executor: executor, assembler: Retrieval::LexicalAssembler.new, metadata_store: metadata_store,
+                   vector_store: nil, graph_store: graph_store)
+    end
+    private :build_lexical_pipeline
+
     private :build_pipeline
 
     # Wrap one store adapter for the pipeline components. Nil stays nil — a
@@ -357,16 +379,29 @@ module Woods
     #   unit types (overrides DEFAULT_EXCLUDE_TYPES).
     # @param exclude_types [Array<String, Symbol>, nil] Additional types to
     #   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)
+    # @param packages [Array<String>, nil] Exact published nearest package owners
+    # @param source_paths [Array<String>, nil] Application-relative directory prefixes
+    # @return [RetrievalResult] Complete retrieval result; scoped calls carry applied_scope
+    def retrieve(query, budget: @default_budget, types: nil, exclude_types: nil, packages: nil, source_paths: nil,
+                 evidence: 'full', evidence_generation: nil) # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
       validate_query!(query)
+      Retrieval::SourceEvidence.validate_mode!(evidence)
+      evidence_options = evidence == 'full' ? {} : { evidence: evidence, query: query, generation: evidence_generation }
       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)
+      scope = resolve_scope(pipeline, packages, source_paths, types, exclude_types)
+      pipeline = scoped_pipeline(pipeline, scope) if scope
       classification = @classifier.classify(query)
+      if @mode == :lexical
+        result = retrieve_lexical(pipeline, query, classification, budget, types, exclude_types, start_time,
+                                  **evidence_options)
+        return attach_scope(result, scope)
+      end
+
       execution_result = pipeline.executor.execute(query: query, classification: classification)
       ranked = pipeline.ranker.rank(execution_result.candidates, classification: classification)
 
@@ -374,20 +409,61 @@ module Woods
       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(pipeline, filtered, classification, budget)
-      trace = build_trace(classification, execution_result, filtered, assembled, start_time)
+      type_rank_context = unless scope
+                            build_type_rank_context_for(ranked, pipeline, type_list, filtered,
+                                                        fallback_ran: fallback_ran)
+                          end
 
+      assembled = assemble_context(pipeline, filtered, classification, budget, **evidence_options)
       build_result(
-        assembled: assembled, classification: classification, strategy: execution_result.strategy,
-        budget: budget, trace: trace, type_rank_context: type_rank_context
-      )
+        assembled: assembled, assembler: pipeline.assembler, classification: classification,
+        strategy: execution_result.strategy, budget: budget, type_rank_context: type_rank_context
+      ).tap do |result|
+        result.trace = build_trace(result, execution_result, filtered, assembled, start_time)
+        attach_scope(result, scope)
+      end
     end
 
     private
 
+    def resolve_scope(pipeline, packages, source_paths, types, excluded)
+      return unless Retrieval::Scope.requested?(packages: packages, source_paths: source_paths)
+
+      Retrieval::Scope.new(metadata_store: translate_store(pipeline.metadata_store, :metadata),
+                           packages: packages, source_paths: source_paths, types: types,
+                           exclude_types: DEFAULT_EXCLUDE_TYPES + Array(excluded).map(&:to_s))
+    end
+
+    def scoped_pipeline(pipeline, scope)
+      vector = Retrieval::ScopedVectorStore.new(store: pipeline.vector_store, scope: scope)
+      graph = Retrieval::ScopedGraphStore.new(store: pipeline.graph_store, scope: scope)
+      build_pipeline(vector_store: vector, metadata_store: scope.metadata_store, graph_store: graph)
+    end
+
+    def attach_scope(result, scope)
+      return result unless scope
+
+      result.applied_scope = scope.summary.merge(
+        outcome: if scope.keys.empty?
+                   :empty_scope
+                 else
+                   (result.trace.ranked_count.zero? ? :no_match : :matched)
+                 end,
+        candidate_count: result.trace.candidate_count, returned_units: result.sources.size
+      )
+      result
+    end
+
+    def retrieve_lexical(pipeline, query, classification, budget, types, exclude_types, start_time, **evidence_options)
+      excluded = DEFAULT_EXCLUDE_TYPES + Array(exclude_types).map(&:to_s)
+      execution = pipeline.executor.execute(query: query, type_filter: types, exclude_types: excluded)
+      assembled = pipeline.assembler.assemble(candidates: execution.candidates, budget: budget, **evidence_options)
+      result = build_result(assembled: assembled, assembler: pipeline.assembler, classification: classification,
+                            strategy: :lexical, budget: budget)
+      result.trace = build_trace(result, execution, execution.candidates, assembled, start_time)
+      result
+    end
+
     # Validate +query+ before any classify/execute/rank work happens.
     #
     # @param query [Object] The caller-supplied query
@@ -464,23 +540,24 @@ module Woods
     # @param ranked [Array<Candidate>] Ranked search candidates
     # @param classification [QueryClassifier::Classification] Query classification
     # @return [AssembledContext]
-    def assemble_context(pipeline, ranked, classification, budget)
+    def assemble_context(pipeline, ranked, classification, budget, **evidence_options)
       pipeline.assembler.assemble(
         candidates: ranked,
         classification: classification,
         structural_context: build_structural_context(pipeline.metadata_store),
-        budget: budget
+        budget: budget, **evidence_options
       )
     end
 
     # Build a RetrievalResult from assembled context and pipeline metadata.
     #
     # @param assembled [AssembledContext] Assembled context
+    # @param assembler [Retrieval::ContextAssembler] Counter configuration used for assembly
     # @param classification [QueryClassifier::Classification] Query classification
     # @param strategy [Symbol] Search strategy used
     # @param budget [Integer] Token budget
     # @return [RetrievalResult]
-    def build_result(assembled:, classification:, strategy:, budget:, trace: nil, type_rank_context: nil)
+    def build_result(assembled:, assembler:, classification:, strategy:, budget:, type_rank_context: nil)
       context = @formatter ? @formatter.call(assembled.context) : assembled.context
       context = append_type_rank_context(context, type_rank_context) if type_rank_context
 
@@ -489,9 +566,8 @@ module Woods
         sources: assembled.sources,
         classification: classification,
         strategy: strategy,
-        tokens_used: assembled.tokens_used,
+        tokens_used: assembler.estimate_tokens(context),
         budget: budget,
-        trace: trace,
         type_rank_context: type_rank_context
       )
     end
@@ -534,14 +610,14 @@ module Woods
       filter_by_type(pipeline, ranked, types: type_array, exclude_types: exclude_types)
     end
 
-    def build_trace(classification, execution_result, filtered, assembled, start_time)
+    def build_trace(result, execution_result, filtered, assembled, start_time)
       elapsed_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time) * 1000).round(1)
       RetrievalTrace.new(
-        classification: classification,
+        classification: result.classification,
         strategy: execution_result.strategy,
         candidate_count: execution_result.candidates.size,
         ranked_count: filtered.size,
-        tokens_used: assembled.tokens_used,
+        tokens_used: result.tokens_used,
         elapsed_ms: elapsed_ms,
         skipped_missing_metadata: assembled.skipped_missing_metadata.to_i
       )

data/lib/woods/ruby_analyzer/trace_enricher.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'fiber'
+
 require_relative '../extracted_unit'
 
 module Woods
@@ -19,6 +21,10 @@ module Woods
     class TraceEnricher
       # Record method calls during block execution using TracePoint.
       #
+      # Records the current thread only, with independent stacks for its fibers.
+      # Caller fields identify the nearest observed Ruby method, not native or
+      # block frames. Calls entered before recording have an unknown caller.
+      #
       # @yield Block to trace
       # @return [Array<Hash>] Collected trace events
       # @raise [ArgumentError] if no block is given
@@ -26,21 +32,15 @@ module Woods
         raise ArgumentError, 'block required' unless block
 
         traces = []
-
+        stacks = Hash.new { |frames, fiber| frames[fiber] = [] }
         trace = TracePoint.new(:call, :return) do |tp|
-          traces << {
-            class_name: tp.defined_class&.name || tp.defined_class.to_s,
-            method_name: tp.method_id.to_s,
-            event: tp.event.to_s,
-            path: tp.path,
-            line: tp.lineno,
-            caller_class: extract_caller_class(tp),
-            caller_method: extract_caller_method(tp),
-            return_class: tp.event == :return ? safe_return_class(tp) : nil
-          }
+          fiber = Fiber.current
+          stack = stacks[fiber]
+          traces << record_event(tp, stack)
+          stacks.delete(fiber) if stack.empty?
         end
 
-        trace.enable(&block)
+        trace.enable(target_thread: Thread.current, &block)
         traces
       end
 
@@ -55,14 +55,11 @@ module Woods
       def self.merge(units:, trace_data:)
         return units if trace_data.nil? || trace_data.empty?
 
-        # Index traces by class_name + method_name
+        # Index by defining owner, method name, and instance/singleton kind.
         grouped = group_traces(trace_data)
 
         units.each do |unit|
-          class_name, method_name = parse_identifier(unit.identifier)
-          next unless class_name && method_name
-
-          key = "#{class_name}##{method_name}"
+          key = parse_identifier(unit.identifier)
           next unless grouped.key?(key)
 
           traces = grouped[key]
@@ -75,7 +72,10 @@ module Woods
             caller_method = fetch_key(t, :caller_method)
             next unless caller_class
 
-            { 'caller_class' => caller_class, 'caller_method' => caller_method }
+            caller = { 'caller_class' => caller_class, 'caller_method' => caller_method }
+            kind = fetch_key(t, :caller_method_kind)
+            caller['caller_method_kind'] = kind.to_s if kind
+            caller
           end
 
           return_types = returns.filter_map do |t|
@@ -104,35 +104,74 @@ module Woods
             method_name = fetch_key(trace, :method_name)
             next unless class_name && method_name
 
-            key = "#{class_name}##{method_name}"
-            grouped[key] << trace
+            # Legacy recorder output with a named owner describes instance
+            # methods. Never infer its kind from the units supplied to merge.
+            kind = (fetch_key(trace, :method_kind) || 'instance').to_s
+            next unless %w[instance singleton].include?(kind)
+            next if class_name.start_with?('#<')
+
+            grouped[[class_name, method_name, kind]] << trace
           end
           grouped
         end
 
         def parse_identifier(identifier)
-          # Handle both "Class#method" and "Class.method" formats
-          if identifier.include?('#')
-            identifier.split('#', 2)
-          elsif identifier.include?('.')
-            identifier.split('.', 2)
-          end
+          match = /\A(.+?)([#.])(.+)\z/.match(identifier)
+          return unless match
+
+          [match[1], match[3], match[2] == '#' ? 'instance' : 'singleton']
         end
 
-        def extract_caller_class(tp)
-          binding_obj = tp.binding
-          receiver = binding_obj.receiver
-          receiver.is_a?(Class) || receiver.is_a?(Module) ? receiver.name : receiver.class.name
-        rescue StandardError
-          nil
+        def event_identity(tp)
+          owner = tp.defined_class
+          singleton = owner&.singleton_class?
+          name = singleton ? singleton_owner_name(owner, tp.self) : owner&.name
+          { class_name: name, method_name: tp.method_id.to_s,
+            method_kind: singleton ? 'singleton' : 'instance' }
         end
 
-        def extract_caller_method(_tp)
-          # TracePoint doesn't directly expose caller method,
-          # but we can get it from the call stack
-          caller_locations(3, 1)&.first&.label
-        rescue StandardError
-          nil
+        # Ruby 3.0 has no Class#attached_object. Find the defining owner,
+        # not just the receiver: Child.run may be defined on Parent's singleton
+        # class. Singleton methods on individual objects have no named unit.
+        def singleton_owner_name(owner, receiver)
+          return unless receiver.is_a?(Module)
+
+          receiver.ancestors.find { |ancestor| ancestor.singleton_class.equal?(owner) }&.name
+        end
+
+        def record_event(tp, stack)
+          identity = event_identity(tp)
+          caller = if tp.event == :call
+                     caller_fields(stack.last)
+                   else
+                     returning_caller(identity, stack)
+                   end
+          event = identity.merge(
+            event: tp.event.to_s, path: tp.path, line: tp.lineno,
+            **caller, return_class: tp.event == :return ? safe_return_class(tp) : nil
+          )
+          stack << event if tp.event == :call
+          event
+        end
+
+        def caller_fields(frame)
+          frame = nil unless frame && frame[:class_name]
+          { caller_class: frame && frame[:class_name], caller_method: frame && frame[:method_name],
+            caller_method_kind: frame && frame[:method_kind] }
+        end
+
+        # Ruby emits :return during exceptional and nonlocal unwinds too. A
+        # return whose call predates recording has no known caller; discard an
+        # inconsistent stack instead of inventing an edge from unrelated frames.
+        def returning_caller(identity, stack)
+          frame = stack.pop
+          if frame && identity.all? { |key, value| frame[key] == value }
+            { caller_class: frame[:caller_class], caller_method: frame[:caller_method],
+              caller_method_kind: frame[:caller_method_kind] }
+          else
+            stack.clear
+            caller_fields(nil)
+          end
         end
 
         def safe_return_class(tp)

data/lib/woods/session_tracer/file_store.rb

@@ -116,7 +116,8 @@ module Woods
       def clear(session_id)
         with_store_lock do
           FileUtils.rm_f(session_path(session_id))
-          FileUtils.rm_f(legacy_session_path(session_id))
+          legacy = legacy_session_path(session_id)
+          FileUtils.rm_f(legacy) if legacy
         end
       end
 
@@ -158,6 +159,10 @@ module Woods
       def migrate_legacy_session!(session_id)
         target = session_path(session_id)
         legacy = legacy_session_path(session_id)
+        # Expire each half before a merge or append can refresh its mtime.
+        [target, legacy].compact.each do |path|
+          FileUtils.rm_f(path) if File.exist?(path) && expired?(path)
+        end
         return target unless legacy && File.exist?(legacy)
 
         if File.exist?(target)