woods 2.0.0.beta1 → 2.0.0.beta3

data/lib/woods/graph_analyzer.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require 'digest'
 require 'set'
 
 module Woods
@@ -55,11 +56,32 @@ module Woods
     # can tell whether it was truncated (B-182).
     DEFAULT_VOLATILE_LIMIT = 20
 
+    # How many distinct cycles {#detect_cycles} enumerates before it stops.
+    # The DFS finds one cycle per back-edge, and a dense graph has tens of
+    # thousands of them; nobody reads past the first few hundred, and the
+    # per-cycle signature work is what made analysis the fixed floor of every
+    # incremental run. `nil` means no cap.
+    DEFAULT_CYCLE_LIMIT = 500
+
+    # The longest cycle {#detect_cycles} will record, counted in distinct
+    # nodes. A back-edge deep in a DFS closes a cycle as long as the path,
+    # which on a large graph is thousands of nodes: unreadable as a report and
+    # expensive to canonicalize. `nil` means no cap.
+    DEFAULT_CYCLE_MAX_LENGTH = 50
+
     # @param dependency_graph [DependencyGraph] The graph to analyze
     # @param volatile_ratio [Numeric] see {#volatile_dependencies}
-    def initialize(dependency_graph, volatile_ratio: DEFAULT_VOLATILE_RATIO)
+    # @param volatile_limit_per_target [Integer, nil] maximum edges per typed dependency, before the global limit
+    # @param cycle_limit [Integer, nil] see {DEFAULT_CYCLE_LIMIT}
+    # @param cycle_max_length [Integer, nil] see {DEFAULT_CYCLE_MAX_LENGTH}
+    def initialize(dependency_graph, volatile_ratio: DEFAULT_VOLATILE_RATIO, volatile_limit_per_target: nil,
+                   cycle_limit: DEFAULT_CYCLE_LIMIT, cycle_max_length: DEFAULT_CYCLE_MAX_LENGTH)
       @graph = dependency_graph
       @volatile_ratio = volatile_ratio.to_f
+      @volatile_limit_per_target = volatile_limit_per_target
+      @cycle_limit = cycle_limit
+      @cycle_max_length = cycle_max_length
+      @cycle_limit_reached = false
     end
 
     # ══════════════════════════════════════════════════════════════════════
@@ -147,6 +169,19 @@ module Woods
       @cycles ||= detect_cycles
     end
 
+    # Whether {#cycles} is a truncated view of the graph's cycles.
+    #
+    # True when either cap fired: the count cap stopped enumeration, or at
+    # least one cycle was longer than the length cap and was skipped. A reader
+    # of the array alone cannot tell, so this is published as
+    # `stats[:cycle_limit_reached]` alongside it.
+    #
+    # @return [Boolean]
+    def cycle_limit_reached?
+      cycles
+      @cycle_limit_reached
+    end
+
     # Units that bridge different types in the graph.
     #
     # Computes a simplified betweenness centrality metric — for each unit, we
@@ -179,6 +214,7 @@ module Woods
 
       pairs.each do |source, target|
         path = bfs_shortest_path(source, target)
+
         next unless path && path.size > 2
 
         # Credit intermediate nodes (exclude source and target)
@@ -262,15 +298,16 @@ module Woods
     # dependencies with fewer than {VOLATILE_MIN_COMMITS} commits or a
     # `new` change frequency are skipped. Ranked by the dependency's
     # PageRank so the most-depended-on volatile unit comes first. `limit`
-    # caps what this method hands back; {#analyze}'s
+    # caps what this method hands back after the optional per-target cap; {#analyze}'s
     # `stats[:volatile_dependency_count]` reports the full qualifying count
     # regardless of `limit`, and `stats[:volatile_dependencies_limit]` reports
-    # the cap, so a reader of the array alone can tell it was truncated.
+    # the global cap. An enabled per-target cap also publishes its setting
+    # and the final reported count; the full qualifying count is unchanged.
     #
     # @param limit [Integer] maximum entries
     # @return [Array<Hash>] `{ from:, from_type:, to:, to_type:, via:, from_commits:, to_commits:, ratio:, pagerank: }`
     def volatile_dependencies(limit: DEFAULT_VOLATILE_LIMIT)
-      all_volatile_dependencies.first(limit)
+      capped_volatile_dependencies.first(limit)
     end
 
     # Edges that cross a Packwerk package boundary the source package never
@@ -361,9 +398,9 @@ module Woods
           dead_end_count: computed_dead_ends.size,
           hub_count: computed_hubs.size,
           cycle_count: computed_cycles.size,
+          cycle_limit_reached: cycle_limit_reached?,
           cross_database_edge_count: computed_cross_database.size,
-          volatile_dependency_count: all_volatile_dependencies.size,
-          volatile_dependencies_limit: DEFAULT_VOLATILE_LIMIT,
+          **volatile_dependency_stats(computed_volatile),
           undeclared_package_edge_count: computed_undeclared.size
         }
       }
@@ -687,6 +724,33 @@ module Woods
       @all_volatile_dependencies ||= compute_volatile_dependencies
     end
 
+    # Apply the optional hub cap after ranking, before the overall report
+    # limit. Keep individual relationship edges; two `via` values consume two
+    # slots. Type is part of dependency identity, never just the display name.
+    def capped_volatile_dependencies
+      return all_volatile_dependencies unless @volatile_limit_per_target
+
+      counts = Hash.new(0)
+      all_volatile_dependencies.select do |entry|
+        target = [entry[:to_type], entry[:to]]
+        counts[target] += 1
+        counts[target] <= @volatile_limit_per_target
+      end
+    end
+
+    # Preserve the default artifact exactly; expose extra selection metadata
+    # only when the per-target cap was requested. The full count always means
+    # all ratio-qualified edges, before either cap.
+    def volatile_dependency_stats(reported)
+      stats = { volatile_dependency_count: all_volatile_dependencies.size,
+                volatile_dependencies_limit: DEFAULT_VOLATILE_LIMIT }
+      if @volatile_limit_per_target
+        stats[:volatile_dependencies_limit_per_target] = @volatile_limit_per_target
+        stats[:volatile_dependency_reported_count] = reported.size
+      end
+      stats
+    end
+
     # Short-circuits to `[]`, skipping the PageRank computation entirely,
     # when no node carries an Integer `commit_count` (git enrichment never
     # ran): there is nothing to rank.
@@ -802,6 +866,7 @@ module Woods
     # @return [Array<Array<String>>] Detected cycles
     def detect_cycles
       nodes = graph_nodes
+      @cycle_limit_reached = false
       return [] if nodes.empty?
 
       white = 0
@@ -813,53 +878,48 @@ module Woods
       found_cycles = []
       seen_cycle_signatures = Set.new
 
-      nodes.keys.sort.each do |start_node|
-        next unless color[start_node] == white
+      catch(:cycle_limit) do
+        nodes.keys.sort.each do |start_node|
+          next unless color[start_node] == white
 
-        # Iterative DFS using an explicit stack.
-        # Each entry is [node, :enter] or [node, :exit].
-        stack = [[start_node, :enter]]
+          # Iterative DFS using an explicit stack.
+          # Each entry is [node, :enter] or [node, :exit].
+          stack = [[start_node, :enter]]
 
-        # Track the current DFS path for cycle extraction.
-        path = []
+          # Track the current DFS path for cycle extraction.
+          path = []
 
-        while stack.any?
-          node, action = stack.pop
+          while stack.any?
+            node, action = stack.pop
 
-          if action == :exit
-            color[node] = black
-            path.pop
-            next
-          end
+            if action == :exit
+              color[node] = black
+              path.pop
+              next
+            end
 
-          # :enter action
-          next unless color[node] == white
-
-          color[node] = gray
-          path.push(node)
-          stack.push([node, :exit])
-
-          # Not sorted, deliberately: this list is the unit's own declared
-          # dependency order, which is identical in a full and an incremental
-          # run, so sorting it would change nothing any test can observe.
-          neighbors = @graph.dependencies_of(node)
-          neighbors.each do |neighbor|
-            case color[neighbor]
-            when white
-              parent[neighbor] = node
-              stack.push([neighbor, :enter])
-            when gray
-              # Found a cycle — extract it from the path
-              cycle = extract_cycle_from_path(path, neighbor)
-              if cycle
-                sig = normalize_cycle_signature(cycle)
-                unless seen_cycle_signatures.include?(sig)
-                  seen_cycle_signatures.add(sig)
-                  found_cycles << cycle
-                end
+            # :enter action
+            next unless color[node] == white
+
+            color[node] = gray
+            path.push(node)
+            stack.push([node, :exit])
+
+            # Not sorted, deliberately: this list is the unit's own declared
+            # dependency order, which is identical in a full and an incremental
+            # run, so sorting it would change nothing any test can observe.
+            neighbors = @graph.dependencies_of(node)
+            neighbors.each do |neighbor|
+              case color[neighbor]
+              when white
+                parent[neighbor] = node
+                stack.push([neighbor, :enter])
+              when gray
+                # Found a cycle: extract it from the path
+                collect_cycle(path, neighbor, found_cycles, seen_cycle_signatures)
               end
+              # black nodes are fully explored, skip them
             end
-            # black nodes are fully explored, skip them
           end
         end
       end
@@ -869,16 +929,52 @@ module Woods
       found_cycles
     end
 
+    # Record the cycle closed by a back-edge to +cycle_start+.
+    #
+    # Skips a cycle longer than the length cap and one already recorded under
+    # another rotation. Throws +:cycle_limit+ once the count cap is full,
+    # which ends the whole scan in {#detect_cycles}.
+    #
+    # @param path [Array<String>] Current DFS path
+    # @param cycle_start [String] The node that closes the cycle
+    # @param found_cycles [Array<Array<String>>] Accumulator
+    # @param seen [Set<String>] Signatures already recorded
+    # @return [void]
+    def collect_cycle(path, cycle_start, found_cycles, seen)
+      cycle = extract_cycle_from_path(path, cycle_start, max_length: @cycle_max_length)
+      if cycle == :too_long
+        @cycle_limit_reached = true
+        return
+      end
+      return unless cycle
+
+      signature = normalize_cycle_signature(cycle)
+      return if seen.include?(signature)
+
+      seen.add(signature)
+      found_cycles << cycle
+      return unless @cycle_limit && found_cycles.size >= @cycle_limit
+
+      @cycle_limit_reached = true
+      throw :cycle_limit
+    end
+
     # Extracts a cycle from the current DFS path when a back-edge to
     # +cycle_start+ is found.
     #
+    # The length check runs on indexes, before the slice: an over-long cycle
+    # costs nothing beyond the +index+ lookup that found it.
+    #
     # @param path [Array<String>] Current DFS path
     # @param cycle_start [String] The node that closes the cycle
-    # @return [Array<String>, nil] The cycle path ending with cycle_start repeated,
-    #   or nil if cycle_start is not in the path
-    def extract_cycle_from_path(path, cycle_start)
+    # @param max_length [Integer, nil] Longest cycle to build, in distinct nodes
+    # @return [Array<String>, Symbol, nil] The cycle path ending with cycle_start
+    #   repeated; +:too_long+ when it exceeds +max_length+; nil when cycle_start
+    #   is not in the path
+    def extract_cycle_from_path(path, cycle_start, max_length: nil)
       start_index = path.index(cycle_start)
       return nil unless start_index
+      return :too_long if max_length && (path.size - start_index) > max_length
 
       path[start_index..] + [cycle_start]
     end
@@ -886,17 +982,20 @@ module Woods
     # Normalize a cycle so that duplicate rotations are treated as the same cycle.
     # For example, [A, B, C, A] and [B, C, A, B] are the same cycle.
     #
+    # Keyed by digest rather than by the joined path: the set holds one
+    # 64-byte key per cycle instead of a string as long as the cycle, so
+    # membership stays constant-cost however deep the DFS went.
+    #
     # @param cycle [Array<String>] Cycle path with repeated last element
-    # @return [String] Canonical string representation
+    # @return [String] Canonical hex digest of the rotated loop
     def normalize_cycle_signature(cycle)
       # Remove the trailing repeated element to get the raw loop
       loop_nodes = cycle[0..-2]
-      return loop_nodes.join('->') if loop_nodes.empty?
+      return Digest::SHA256.hexdigest('') if loop_nodes.empty?
 
       # Rotate so the lexicographically smallest element is first
       min_index = loop_nodes.each_with_index.min_by { |node, _i| node }.last
-      rotated = loop_nodes.rotate(min_index)
-      rotated.join('->')
+      Digest::SHA256.hexdigest(loop_nodes.rotate(min_index).join('->'))
     end
 
     # ──────────────────────────────────────────────────────────────────────
@@ -927,32 +1026,65 @@ module Woods
       pairs.to_a
     end
 
+    # Forward adjacency, resolved once per node per analyzer instance.
+    #
+    # {#bridges} runs `sample_size` whole-graph traversals, and
+    # `DependencyGraph#dependencies_of` sorts and flattens the node's edge
+    # buckets on every call, so an uncached BFS re-derived the same adjacency
+    # list up to 200 times per node. Populated on demand rather than up front:
+    # a traversal that never reaches a node should not pay for it.
+    #
+    # @return [Hash{String => Array<String>}]
+    def adjacency
+      @adjacency ||= Hash.new { |cache, identifier| cache[identifier] = @graph.dependencies_of(identifier) }
+    end
+
     # BFS shortest path between two nodes, following forward edges.
     #
+    # Carries parent pointers rather than a path per queue entry. The old form
+    # allocated a copy of the path so far for every node it enqueued, which on
+    # a large graph is a full array per node per traversal; the path is now
+    # built once, for the one node that matched.
+    #
     # @param source [String] Starting node identifier
     # @param target [String] Target node identifier
     # @return [Array<String>, nil] Shortest path or nil if unreachable
     def bfs_shortest_path(source, target)
       return [source] if source == target
 
-      visited = Set.new([source])
-      queue = [[source, [source]]]
+      parents = { source => nil }
+      queue = [source]
+      head = 0
 
-      while queue.any?
-        current, path = queue.shift
+      while head < queue.size
+        current = queue[head]
+        head += 1
 
-        @graph.dependencies_of(current).each do |neighbor|
-          next if visited.include?(neighbor)
+        adjacency[current].each do |neighbor|
+          next if parents.key?(neighbor)
 
-          new_path = path + [neighbor]
-          return new_path if neighbor == target
+          parents[neighbor] = current
+          return path_to(parents, neighbor) if neighbor == target
 
-          visited.add(neighbor)
-          queue.push([neighbor, new_path])
+          queue.push(neighbor)
         end
       end
 
       nil
     end
+
+    # Walk parent pointers back to the source and reverse.
+    #
+    # @param parents [Hash{String => String, nil}] node => the node it was reached from
+    # @param node [String] the end of the path
+    # @return [Array<String>] source-first path ending at +node+
+    def path_to(parents, node)
+      path = []
+      while node
+        path << node
+        node = parents[node]
+      end
+      path.reverse
+    end
   end
 end

data/lib/woods/hooks/context_cli.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'timeout'
+
+module Woods
+  module Hooks
+    # The plugin's independent process-group deadline also includes bundle/Ruby
+    # startup. This inner deadline keeps ordinary direct calls short as well.
+    class ContextCLI
+      MAX_INPUT_BYTES = 1_048_576
+      HELP = 'Usage: woods-hook-context SessionStart|PostToolUse < claude-event.json; ' \
+             'opt in with WOODS_HOOK_CONTEXT_ENABLED=1. Prefer the bounded plugin hook entry point.'
+
+      def self.run(kind, input: $stdin, output: $stdout)
+        return output.puts(HELP) || 0 if kind == '--help'
+
+        return 0 if ENV['WOODS_HOOKS_DISABLED'] == '1' || ENV['WOODS_HOOK_CONTEXT_ENABLED'] != '1'
+        return 0 unless %w[SessionStart PostToolUse].include?(kind)
+
+        Timeout.timeout(0.65) do
+          require 'woods'
+          require 'woods/hooks/context_hint'
+          require 'woods/hooks/context_state'
+          emit(kind, input, output)
+        end
+        0
+      rescue Timeout::Error, JSON::ParserError, ArgumentError, KeyError, TypeError, SystemCallError, IOError
+        # Missing/degraded/slow inputs are optional context, not permission to
+        # run extraction, read application data, or acknowledge queued edits.
+        0
+      end
+
+      def self.emit(kind, input, output)
+        bytes = input.read(MAX_INPUT_BYTES + 1)
+        return if bytes.bytesize > MAX_INPUT_BYTES
+
+        event = JSON.parse(bytes)
+        return unless event.is_a?(Hash) && event['hook_event_name'] == kind
+
+        root = ENV['WOODS_HOOK_CONTEXT_ROOT'] || event.fetch('cwd')
+        directory = File.expand_path(ENV.fetch('WOODS_OUTPUT', 'tmp/woods'), root)
+        result = ContextHint.new(event: event, output_dir: directory, root: root).call
+        return unless result
+
+        ContextState.new(directory).emit(result) do
+          output.write(ContextOutput.new(kind).encode(result.fetch(:context)))
+          output.flush
+        end
+      end
+      private_class_method :emit
+    end
+  end
+end

data/lib/woods/hooks/context_event.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require 'digest'
+require 'woods/input_rules'
+
+module Woods
+  module Hooks
+    # Claude context events are deliberately separate from refresh queue records.
+    class ContextEvent
+      MAX_FILE_BYTES = 1_048_576
+      attr_reader :root, :path, :kind, :session
+
+      def initialize(input, root: nil)
+        validate_root!(input)
+
+        @logical_root = File.expand_path(input['cwd'])
+        @root = File.realpath(root || @logical_root)
+        @kind = input['hook_event_name']
+        @session = input['session_id'] if valid_string?(input['session_id'], 256)
+        return if kind == 'SessionStart'
+
+        raise ArgumentError unless kind == 'PostToolUse' && %w[Edit Write MultiEdit].include?(input['tool_name'])
+
+        @path = relative_path(input.fetch('tool_input').fetch('file_path'))
+      end
+
+      def eligible?
+        return true if kind == 'SessionStart'
+
+        require 'woods/extractor' unless defined?(Woods::Extractor::EXTRACTORS)
+        InputRules.new.action(path) != :ignore
+      end
+
+      def fingerprint
+        return 'orientation' if kind == 'SessionStart'
+
+        flags = File::RDONLY | File::NONBLOCK
+        flags |= File::NOFOLLOW if defined?(File::NOFOLLOW)
+        File.open(File.join(root, path), flags) do |file|
+          return nil unless file.stat.file? && file.stat.size <= MAX_FILE_BYTES
+
+          bytes = file.read(MAX_FILE_BYTES + 1)
+          return nil if bytes.bytesize > MAX_FILE_BYTES
+
+          Digest::SHA256.hexdigest(bytes)
+        end
+      rescue Errno::ENOENT
+        'missing'
+      rescue SystemCallError, IOError
+        nil
+      end
+
+      private
+
+      def validate_root!(input)
+        raise ArgumentError unless input.is_a?(Hash) && valid_string?(input['cwd']) && input['cwd'].start_with?('/')
+      end
+
+      def valid_string?(value, limit = 4096)
+        value.is_a?(String) && !value.empty? && value.bytesize <= limit &&
+          value.valid_encoding? && !value.include?("\0")
+      end
+
+      def relative_path(value)
+        raise ArgumentError unless valid_string?(value)
+
+        prefix = [@logical_root, root].find { |base| value.start_with?("#{base}/") }
+        relative = prefix ? value.delete_prefix("#{prefix}/") : value
+        validate_parts!(relative)
+        validate_containment!(relative)
+        relative
+      end
+
+      def validate_parts!(relative)
+        parts = relative.split('/', -1)
+        raise ArgumentError if relative.start_with?('/') || parts.size > 64
+        raise ArgumentError if parts.any? { |part| ['', '.', '..'].include?(part) }
+      end
+
+      def validate_containment!(relative)
+        candidate = File.join(root, relative)
+        candidate = File.dirname(candidate) until File.exist?(candidate) || File.symlink?(candidate)
+        resolved = File.realpath(candidate)
+        raise ArgumentError unless resolved == root || resolved.start_with?("#{root}/")
+      end
+    end
+  end
+end

data/lib/woods/hooks/context_hint.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require 'woods/mcp/index_reader'
+require_relative 'context_event'
+require_relative 'context_output'
+require_relative 'context_impact'
+
+module Woods
+  module Hooks
+    # A bounded snapshot hint. The outer hook process owns the end-to-end deadline.
+    class ContextHint
+      MAX_ARTIFACT_BYTES = 16 * 1024 * 1024
+
+      def initialize(event:, output_dir:, root: nil)
+        @event = ContextEvent.new(event, root: root)
+        @output = File.expand_path(output_dir, @event.root)
+        @renderer = ContextOutput.new(@event.kind)
+      rescue ArgumentError, KeyError, TypeError, SystemCallError
+        @event = nil
+      end
+
+      def call
+        return nil unless @event&.eligible?
+
+        @reader = MCP::IndexReader.new(@output)
+        @reader.with_pinned_generation do
+          @generation = @reader.generation_identity
+          raise ArgumentError if @reader.payload_dir.to_s == @output
+
+          check_artifacts!
+          freshness = source_freshness
+          text = if @event.kind == 'SessionStart'
+                   orientation(freshness)
+                 else
+                   ContextImpact.new(@reader, @renderer).call(@event.path, @generation.first, freshness)
+                 end
+          result(text)
+        end
+      rescue ArgumentError, KeyError, TypeError, NoMethodError, JSON::ParserError, SystemCallError, IOError
+        { context: ContextOutput::UNAVAILABLE, identity: nil, session: nil }
+      end
+
+      private
+
+      def check_artifacts!
+        %w[manifest.json dependency_graph.json source_inputs.json].each do |name|
+          file = @reader.payload_dir.join(name)
+          next if name == 'source_inputs.json' && !file.exist?
+
+          raise ArgumentError unless file.file? && file.size <= MAX_ARTIFACT_BYTES
+        end
+      end
+
+      def source_freshness
+        SourceInputs::Status.new(output_dir: @output, root: @event.root, payload_dir: @reader.payload_dir,
+                                 generation: @reader.loaded_generation).call.fetch('state')
+      end
+
+      def orientation(freshness)
+        @renderer.context("Woods index generation #{@generation.first}; source freshness: #{freshness}. " \
+                          'Use woods_status, search and typed lookup; dependents explain:true suggests checks.')
+      end
+
+      def result(text)
+        fingerprint = @event.fingerprint
+        identity = if fingerprint && @event.session
+                     Digest::SHA256.hexdigest(JSON.generate([@event.root, @event.path, @generation, fingerprint, text]))
+                   end
+        { context: text, identity: identity, session: @event.session, root: @event.root }
+      end
+    end
+  end
+end

data/lib/woods/hooks/context_impact.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Woods
+  module Hooks
+    # Resolve one unambiguous edited identity, then reuse the bounded graph walk.
+    class ContextImpact
+      MAX_NODES = 50_000
+
+      def initialize(reader, renderer)
+        @reader = reader
+        @renderer = renderer
+      end
+
+      def call(path, generation, freshness)
+        graph = @reader.raw_graph_data
+        roots = roots_for(graph, path)
+        header = "Woods candidates from generation #{generation} (pre-refresh snapshot; " \
+                 "source freshness: #{freshness}). Changed path: #{JSON.generate(path)}."
+        return unresolved(header, roots) unless roots.size == 1
+
+        root = roots.first
+        traversal = @reader.traverse_dependents(root.fetch('identifier'), depth: 2, explain: true, max_nodes: 10,
+                                                                          max_edges: 100)
+        @renderer.context(header, rows_for(traversal), partial: !!traversal[:partial])
+      end
+
+      private
+
+      def rows_for(traversal)
+        rows = traversal.fetch(:explanation).fetch(:witnesses).filter_map do |_identifier, witness|
+          next if witness[:impact] == 'root'
+
+          edge = traversal[:explanation][:edges].fetch(witness.fetch(:edge_id))
+          evidence_row(edge, witness)
+        end
+        rows << 'No candidate found within this bounded snapshot; verify manually with dependents.' if rows.empty?
+        rows
+      end
+
+      def roots_for(graph, path)
+        records = records_for(graph)
+        matching = records.select { |node| node['file_path'] == path }
+        identities = matching.map { |node| node.slice('identifier', 'type') }.uniq
+        return identities if identities.size != 1
+
+        # A recorded edge target does not identify which same-named type it means.
+        records.select { |node| node['identifier'] == identities.first['identifier'] }
+               .map { |node| node.slice('identifier', 'type') }.uniq
+      end
+
+      def unresolved(header, roots)
+        reason = roots.empty? ? 'unresolved changed path' : 'ambiguous changed identity'
+        rows = roots.first(10).map { |root| "#{root['identifier']} (#{root['type']})" }
+        @renderer.context("#{header} #{reason}; verify with search and typed lookup.", rows, partial: true)
+      end
+
+      def evidence_row(edge, witness)
+        source = edge.fetch(:source)
+        target = edge.fetch(:target)
+        target_type = target[:type] || "ambiguous/unknown #{Array(target[:candidate_types]).join(',')}"
+        test_hint = source[:type] == 'test_mapping' ? '; test suggestion' : ''
+        uncertain = witness[:typed_path_complete] ? '' : '; typed path incomplete'
+        "#{witness[:impact]} candidate: #{source[:identifier]} (#{source[:type]}) " \
+          "--via=#{edge[:via] || 'unknown'}--> #{target[:identifier]} (#{target_type})#{test_hint}#{uncertain}"
+      end
+
+      def records_for(graph)
+        nodes = graph.fetch('nodes')
+        variants = graph.fetch('variants', [])
+        raise ArgumentError unless nodes.is_a?(Hash) && variants.is_a?(Array)
+        raise ArgumentError if nodes.size + variants.size > MAX_NODES
+
+        nodes.map { |identifier, node| node.merge('identifier' => identifier) } + variants
+      end
+    end
+  end
+end