woods 2.0.0 → 2.1.0

data/lib/woods/source_references/pass.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+require 'set'
+require 'woods'
+require_relative 'collector'
+require_relative 'registry'
+require_relative 'inputs'
+require_relative 'cache'
+
+module Woods
+  module SourceReferences
+    # Retained references cannot be reconstructed safely from current bytes when
+    # their extraction provenance or edge ownership is unavailable.
+    class RebuildRequired < Woods::ExtractionError; end
+
+    # Resolves candidates against the complete current typed registry. Parsing is
+    # cached by captured HMAC, including candidates whose targets do not yet exist.
+    # Runtime lookup is repeated every run: source text alone cannot fingerprint
+    # changed ancestors, aliases or lexical shadows in a reloaded application.
+    class Pass
+      CALLER_TYPES = %w[model controller service poro lib concern].freeze
+      Result = Struct.new(:dependencies, :cache, :paths, keyword_init: true)
+
+      # @param root [String, Pathname] application root
+      # @param session [SourceInputs::Session] original source capture
+      # @param units [Array<Hash>] complete string-keyed typed unit set
+      # @param extractor_keys [Hash{Symbol => Symbol}] unit type to consumer key
+      # @param baseline [Hash, nil] validated preceding generation cache
+      # @param refreshed [Array<Array<String>>] units genuinely re-extracted
+      # @param full [Boolean] all runtime units were re-extracted
+      # @param collector [Collector] source-only parser
+      # rubocop:disable Metrics/ParameterLists -- explicit per-run collaborators and provenance state
+      def initialize(root:, session:, units:, extractor_keys:, baseline: nil, refreshed: [], full: false,
+                     collector: Collector.new)
+        @root = File.expand_path(root.to_s)
+        @session = session
+        @units = units
+        @keys = extractor_keys
+        @baseline = baseline
+        @refreshed = refreshed.to_set
+        @full = full
+        @collector = collector
+      end
+
+      # rubocop:enable Metrics/ParameterLists
+
+      # @return [Result] complete dependency replacements and next cache
+      def call
+        raise_rebuild('reference cache is missing') if !@full && !@baseline
+
+        @inputs = Inputs.new(root: @root, session: @session, collector: @collector)
+        @files = @inputs.call(units: @units, baseline: @baseline, fresh: method(:fresh?), extractor_keys: @keys)
+        sources = @files.transform_values { |entry| entry['analysis'] }
+        @registry = Registry.new(units: @units, sources: sources, root: @root)
+        @previous = Array(@baseline&.fetch('owners')).to_h { |owner| [[owner['type'], owner['identifier']], owner] }
+        build_result
+      end
+
+      private
+
+      def build_result
+        dependencies = {}
+        owners = @units.filter_map do |unit|
+          key = [unit['type'], unit['identifier']]
+          path = @inputs.relative(unit['file_path'])
+          additions = []
+          if CALLER_TYPES.include?(unit['type'])
+            base = original_dependencies(unit, key)
+            additions = all_resolved_dependencies(unit) - base
+            dependencies[key] = base + additions
+          end
+          # Target-only units also crossed Inputs' consumption gate. Retain
+          # their exact ownership so bounded freshness can reuse that proof.
+          owner_record(unit, path, additions)
+        end
+        owners.sort_by! { |owner| [owner['type'], owner['identifier']] }
+        cache = { 'version' => Cache::VERSION, 'files' => @files, 'owners' => owners }
+        Result.new(dependencies: dependencies, cache: cache, paths: @files.keys)
+      end
+
+      def owner_record(unit, path, additions)
+        return unless Registry::TYPES.include?(unit['type']&.to_sym)
+        return unless @files.key?(path) && RuntimeLookup::CONSTANT.match?(unit['identifier'].to_s)
+
+        record = { 'type' => unit['type'], 'identifier' => unit['identifier'], 'file_path' => path,
+                   'added' => additions }
+        record['file_paths'] = reference_paths(unit) if SourceContributors.multiple?(unit)
+        record
+      end
+
+      def fresh?(unit)
+        @full || @refreshed.include?([unit['type'], unit['identifier']])
+      end
+
+      def original_dependencies(unit, key)
+        dependencies = unit.fetch('dependencies', []).map { |edge| normalize_edge(edge) }
+        return dependencies if @full || @refreshed.include?(key)
+
+        prior = ownership_record(unit, key)
+        return dependencies unless prior
+
+        prior.fetch('added').each do |edge|
+          position = dependencies.index(edge)
+          raise_rebuild("reference ownership differs for #{key.join(':')}") unless position
+
+          dependencies.delete_at(position)
+        end
+        dependencies
+      end
+
+      def ownership_record(unit, key)
+        path = @inputs.relative(unit['file_path'])
+        prior = @previous[key]
+        expected = @files.key?(path) || @baseline.fetch('files').key?(path)
+        if expected && RuntimeLookup::CONSTANT.match?(unit['identifier'].to_s) &&
+           !same_owner_paths?(prior, unit, path)
+          raise_rebuild("reference ownership is missing or incompatible for #{key.join(':')}")
+        end
+        prior
+      end
+
+      def all_resolved_dependencies(unit)
+        reference_paths(unit).flat_map { |source| resolved_dependencies(unit, source) }.uniq
+      end
+
+      def same_owner_paths?(prior, unit, path)
+        prior && prior['file_path'] == path && (prior['file_paths'] || [path]) == reference_paths(unit)
+      end
+
+      def reference_paths(unit)
+        SourceContributors.paths(unit).map { |path| @inputs.relative(path) }
+      end
+
+      def normalize_edge(edge)
+        edge.transform_keys(&:to_s).transform_values { |value| value.is_a?(Symbol) ? value.to_s : value }
+      end
+
+      def resolved_dependencies(unit, path)
+        records = @files.dig(path, 'analysis', 'references') || []
+        owned = records.select { |reference| reference['owner'] == unit['identifier'] }
+        edges = owned.filter_map { |reference| @registry.resolve(reference, file_path: path) }
+        edges.map! { |edge| normalize_edge(edge) }
+        edges.uniq.sort_by { |edge| [edge['type'], edge['target'], edge['via']] }
+      end
+
+      def raise_rebuild(reason)
+        raise RebuildRequired, "Source-reference baseline needs a full extraction (#{reason}). " \
+                               'Run bin/rails woods:extract; the previous published generation remains active.'
+      end
+    end
+  end
+end

data/lib/woods/source_references/prism_adapter.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require 'prism'
+
+module Woods
+  module SourceReferences
+    # Retains AST context that the general Woods flow AST intentionally omits.
+    class PrismAdapter
+      KINDS = { class_node: :declaration, module_node: :declaration, constant_read_node: :constant,
+                constant_path_node: :constant, singleton_class_node: :singleton, def_node: :method }.freeze
+      CONSTANT_WRITES = %i[
+        constant_write_node constant_path_write_node constant_operator_write_node constant_path_operator_write_node
+        constant_and_write_node constant_path_and_write_node constant_or_write_node constant_path_or_write_node
+      ].freeze
+      DYNAMIC_BLOCK_METHODS = %i[class_eval module_eval instance_eval class_exec module_exec instance_exec].freeze
+
+      def parse(source)
+        result = Prism.parse(source)
+        error = result.errors.first
+        [result.value, error && { 'message' => error.message, 'line' => error.location.start_line }]
+      end
+
+      def kind(node)
+        return KINDS[node.type] if KINDS.key?(node.type)
+
+        case node.type
+        when :constant_write_node, :constant_path_write_node then value_constructor(node) ? :value_class : :other
+        when :call_node then dynamic_scope?(node) ? :dynamic_scope : :other
+        else :other
+        end
+      end
+
+      def constant_name(node)
+        return unless node
+        return node.name.to_s if node.type == :constant_read_node
+        return unless node.type == :constant_path_node
+
+        parent = node.parent ? constant_name(node.parent) : ''
+        name = node.respond_to?(:name) ? node.name : node.child.name
+        "#{parent}::#{name}" if parent
+      end
+
+      def children(node)
+        return [node.value].compact if CONSTANT_WRITES.include?(node.type)
+        return [] if %i[constant_target_node constant_path_target_node].include?(node.type)
+        return [node.value].compact if node.type == :multi_write_node
+        return [node.parameters, node.body].compact if node.type == :def_node
+
+        node.compact_child_nodes
+      end
+
+      def value_constructor(node)
+        call = node.value
+        return unless call&.type == :call_node
+
+        name = constant_name(call.receiver)
+        name if { new: %w[Struct ::Struct], define: %w[Data ::Data] }.fetch(call.name, []).include?(name)
+      end
+
+      def assignment_name(node)
+        node.type == :constant_write_node ? node.name.to_s : constant_name(node.target)
+      end
+
+      def declaration_name(node)
+        constant_name(node.constant_path)
+      end
+
+      def declaration_kind(node)
+        node.type == :class_node ? 'class' : 'module'
+      end
+
+      def superclass(node)
+        node.superclass if node.type == :class_node
+      end
+
+      def body(node)
+        node.body
+      end
+
+      def self_receiver?(node)
+        node.expression.type == :self_node
+      end
+
+      def local_method?(node)
+        node.receiver.nil? || node.receiver.type == :self_node
+      end
+
+      def line(node)
+        node.location.start_line
+      end
+
+      def end_line(node)
+        node.location.end_line
+      end
+
+      private
+
+      def dynamic_scope?(node)
+        return false unless node.block&.type == :block_node
+        return true if DYNAMIC_BLOCK_METHODS.include?(node.name)
+
+        foreign_method?(node) || anonymous_class?(node.name, node.receiver)
+      end
+
+      def foreign_method?(node)
+        %i[define_method define_singleton_method].include?(node.name) &&
+          node.receiver && node.receiver.type != :self_node
+      end
+
+      def anonymous_class?(method, receiver)
+        name = constant_name(receiver)&.delete_prefix('::')
+        { new: %w[Class Module Struct], define: ['Data'] }.fetch(method, []).include?(name)
+      end
+    end
+  end
+end

data/lib/woods/source_references/registry.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+require 'pathname'
+require_relative 'runtime_lookup'
+require_relative 'value_class'
+require_relative '../source_contributors'
+
+module Woods
+  module SourceReferences
+    # Maps verified source declarations to extracted constant-owned units.
+    # File-profile and other non-constant identities are never resolution targets.
+    class Registry # rubocop:disable Metrics/ClassLength -- keep runtime, source and autoload ownership checks together
+      TYPES = %i[model controller service poro lib concern job mailer component view_component
+                 graphql_type graphql_mutation graphql_resolver graphql_query serializer manager
+                 policy validator pundit_policy decorator action_cable_channel].freeze
+
+      # @param units [Array<ExtractedUnit, Hash>] current complete typed unit set
+      # @param sources [Hash{String => Hash}] path to collector result
+      # @param root [String, Pathname] application root
+      def initialize(units:, sources:, root:)
+        @root = File.expand_path(root.to_s)
+        @lookup = RuntimeLookup.new
+        @sources = sources.to_h { |path, result| [absolute(path), result] }
+        @all_types = units.group_by { |unit| field(unit, :identifier) }
+        @entries = units.flat_map { |unit| SourceContributors.paths(unit).filter_map { |path| entry(unit, path) } }
+        @owners = @entries.group_by { |record| [record[:path], record[:identifier]] }
+        @targets = @entries.group_by { |record| record[:identifier] }
+      end
+
+      # @param reference [Hash] JSON-compatible collector reference record
+      # @param file_path [String] source containing the reference
+      # @return [Hash, nil] a dependency, or nil for an unresolved reference
+      def resolve(reference, file_path:)
+        result = explain(reference, file_path: file_path)
+        return unless result['status'] == 'resolved'
+
+        { type: result.fetch('type').to_sym, target: result.fetch('target'), via: :code_reference }
+      end
+
+      # @param reference [Hash] collected spelling, owner and lexical nesting
+      # @param file_path [String] original source path
+      # @return [Hash] JSON-compatible resolution or explicit unresolved reason
+      def explain(reference, file_path:)
+        return unresolved('unverified_owner') unless owner?(reference['owner'], file_path: file_path)
+
+        return unresolved('unsupported_singleton_scope') if reference.fetch('singleton_depth', 0).positive?
+
+        result = @lookup.call(reference['name'], nesting: reference.fetch('nesting', []))
+        target = result[:target] || autoload_target(result) || source_only_target(reference, result)
+        return unresolved(result[:reason] || 'constant_missing') unless target
+
+        target_result(target, owner: reference['owner'])
+      end
+
+      # @param identifier [String] source declaration identity
+      # @param file_path [String] original source path
+      # @return [Boolean] whether exactly one extracted type owns the declaration
+      def owner?(identifier, file_path:)
+        records = @owners[[absolute(file_path), identifier]]
+        records && !records.empty? && !ambiguous?(identifier)
+      end
+
+      private
+
+      def target_result(target, owner:)
+        return unresolved('ambiguous_target') if ambiguous?(target)
+
+        entries = @targets[target]
+        return unresolved('target_not_indexed') unless entries&.any?
+        return unresolved('self_reference') if target == owner
+
+        { 'status' => 'resolved', 'target' => target, 'type' => entries.first[:type].to_s }
+      end
+
+      def entry(unit, path)
+        type = field(unit, :type)&.to_sym
+        return unless TYPES.include?(type)
+
+        identifier = field(unit, :identifier)
+        return unless eligible_identity?(identifier, path)
+
+        path = absolute(path)
+        source = @sources[path]
+        return unless verified_declaration?(source, identifier, type, path)
+
+        { identifier: identifier, type: type, path: path }
+      end
+
+      def eligible_identity?(identifier, path)
+        path && identifier.is_a?(String) && RuntimeLookup::CONSTANT.match?(identifier)
+      end
+
+      def verified_declaration?(source, identifier, type, path)
+        return false unless source && source['parse_error'].nil?
+
+        source.fetch('declarations', []).any? { |decl| declaration?(decl, identifier, type, path) }
+      end
+
+      def declaration?(declaration, identifier, type, path)
+        return false unless declaration['owner'] == identifier
+        return false if declaration.fetch('singleton_depth', 0).positive?
+
+        return ValueClass.new.call(declaration, file_path: path) == identifier if declaration['constructor']
+
+        result = @lookup.call(declaration['name'], nesting: declaration.fetch('enclosing_nesting', []),
+                                                   allow_private: true)
+        return runtime_declaration?(declaration, identifier, result) if result[:status] == :resolved
+
+        source_declaration?(declaration, identifier, type, path)
+      end
+
+      def source_declaration?(declaration, identifier, type, path)
+        return false unless type == :lib && static_declaration?(declaration, identifier)
+
+        root_result = @lookup.call("::#{identifier}", allow_private: true)
+        root_result[:status] == :missing || autoload_declaration?(root_result, identifier, path)
+      end
+
+      def runtime_declaration?(declaration, identifier, result)
+        kind = @lookup.class_object?(result[:value]) ? 'class' : 'module'
+        result[:target] == identifier && declaration['kind'] == kind
+      end
+
+      def static_declaration?(declaration, identifier)
+        name = declaration['name']
+        return false unless name.is_a?(String) && RuntimeLookup::CONSTANT.match?(name)
+        return name.delete_prefix('::') == identifier if name.start_with?('::')
+
+        nesting = declaration.fetch('enclosing_nesting', [])
+        return name == identifier if nesting.empty?
+
+        !name.include?('::') && [nesting.first, name].join('::') == identifier
+      end
+
+      def autoload_declaration?(result, identifier, path)
+        registered = result[:autoload_path]
+        result[:pending_target] == identifier && registered.is_a?(String) &&
+          Pathname.new(registered).absolute? && absolute(registered) == path
+      end
+
+      def autoload_target(result)
+        name = result[:pending_target]
+        candidates = @targets[name]
+        return unless candidates&.any?
+
+        name if candidates.all? { |entry| entry[:type] == :lib && autoload_declaration?(result, name, entry[:path]) }
+      end
+
+      def source_only_target(reference, result)
+        return unless result[:status] == :missing
+
+        return unless reference['name'].to_s.start_with?('::') || result[:root_lookup]
+
+        name = reference['name'].to_s.delete_prefix('::')
+        candidates = @targets[name]
+        name if candidates&.all? { |entry| entry[:type] == :lib }
+      end
+
+      def ambiguous?(identifier)
+        @all_types.fetch(identifier, []).map { |unit| field(unit, :type).to_s }.uniq.size > 1
+      end
+
+      def field(unit, name)
+        return unit.public_send(name) unless unit.is_a?(Hash)
+
+        unit.key?(name) ? unit[name] : unit[name.to_s]
+      end
+
+      def absolute(path)
+        File.expand_path(path.to_s, @root)
+      end
+
+      def unresolved(reason)
+        { 'status' => 'unresolved', 'reason' => reason }
+      end
+    end
+  end
+end

data/lib/woods/source_references/runtime_lookup.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module Woods
+  module SourceReferences
+    # Reads already-loaded constant tables without invoking application overrides,
+    # const_missing, or an autoload. Results are scoped to one extraction run.
+    class RuntimeLookup
+      CORE_TYPE = Module.instance_method(:===)
+      CORE_EQUAL = BasicObject.instance_method(:equal?)
+      CONSTANT = /\A(?:::)?[[:upper:]][[:word:]]*(?:::[[:upper:]][[:word:]]*)*\z/
+      REFLECTION = %i[const_defined? const_get autoload? ancestors name constants].to_h do |method|
+        [method, Module.instance_method(method)]
+      end.freeze
+
+      # @param name [String] a literal constant path
+      # @param nesting [Array<String>] lexical scopes, innermost first
+      # @return [Hash] lookup status and canonical target or unresolved reason
+      def call(name, nesting: [], allow_private: false)
+        return unknown('invalid_constant') unless valid_name?(name)
+
+        parts = name.delete_prefix('::').split('::')
+        scopes = name.start_with?('::') ? { scopes: [Object] } : lexical_scopes(nesting)
+        return scopes unless scopes[:scopes]
+
+        result = first_constant(scopes[:scopes], parts.shift, public_only: name.start_with?('::') && !allow_private)
+        parts.each do |part|
+          return result.except(:pending_target, :autoload_path) unless module_object?(result[:value])
+
+          result = first_constant(qualified_scopes(result[:value]), part, public_only: !allow_private)
+        end
+        result
+      end
+
+      # @param scope [Module] runtime module to inspect
+      # @param method [Symbol] one of the bound core reflection methods
+      # @return [Object] core reflection result
+      def reflect(scope, method, *args)
+        REFLECTION.fetch(method).bind(scope).call(*args)
+      end
+
+      # @return [Boolean] core class/module checks that cannot dispatch to application overrides
+      def module_object?(value)
+        CORE_TYPE.bind(Module).call(value)
+      end
+
+      # @return [Boolean] whether a runtime object is a class
+      def class_object?(value)
+        CORE_TYPE.bind(Class).call(value)
+      end
+
+      private
+
+      def valid_name?(name)
+        name.is_a?(String) && CONSTANT.match?(name)
+      end
+
+      def identical?(left, right)
+        CORE_EQUAL.bind(left).call(right)
+      end
+
+      def qualified_scopes(receiver)
+        ancestors = reflect(receiver, :ancestors)
+        return [receiver, *ancestors] if identical?(receiver, Object)
+
+        [receiver, *ancestors.take_while { |ancestor| !identical?(ancestor, Object) }]
+      end
+
+      def lexical_scopes(nesting)
+        return { scopes: [Object] } if nesting.empty?
+
+        modules = nesting.map do |name|
+          result = call("::#{name}", allow_private: true)
+          return unknown('unloaded_scope') unless module_object?(result[:value])
+
+          result[:value]
+        end
+        ancestors = reflect(modules.first, :ancestors)
+        ancestors += [Object] unless class_object?(modules.first)
+        { scopes: modules + ancestors }
+      end
+
+      def first_constant(scopes, name, public_only: false)
+        scopes.each do |scope|
+          next unless reflect(scope, :const_defined?, name, false)
+          return unknown('private_constant') if private_access?(scope, name, public_only)
+
+          autoload_path = reflect(scope, :autoload?, name, false)
+          return pending_autoload(scope, name, autoload_path) if autoload_path
+
+          return constant_value(scope, name)
+        end
+        { status: :missing, reason: 'constant_missing', root_lookup: scopes.any? { |scope| identical?(scope, Object) } }
+      rescue NameError
+        unknown('constant_changed')
+      end
+
+      # Expose registration evidence without evaluating the source file. Only
+      # Registry may promote it, after matching a captured library declaration.
+      def pending_autoload(scope, name, path)
+        namespace = identical?(scope, Object) ? nil : reflect(scope, :name)
+        return unknown('autoload_pending') if namespace.nil? && !identical?(scope, Object)
+
+        unknown('autoload_pending').merge(pending_target: [namespace, name].compact.join('::'), autoload_path: path)
+      end
+
+      def private_access?(scope, name, public_only)
+        public_only && !reflect(scope, :constants, false).include?(name.to_sym)
+      end
+
+      def constant_value(scope, name)
+        value = reflect(scope, :const_get, name, false)
+        return unknown('non_module_constant') unless module_object?(value)
+
+        canonical = reflect(value, :name)
+        namespace = identical?(scope, Object) ? nil : reflect(scope, :name)
+        expected = [namespace, name].compact.join('::')
+        return unknown('constant_alias') unless canonical == expected
+
+        { status: :resolved, target: canonical, value: value }
+      end
+
+      def unknown(reason)
+        { status: :unknown, reason: reason }
+      end
+    end
+  end
+end

data/lib/woods/source_references/value_class.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require_relative 'runtime_lookup'
+
+module Woods
+  module SourceReferences
+    # Verifies literal value-class assignment evidence against loaded Ruby state.
+    # Bound core methods avoid application reflection overrides and never run a
+    # constructor, autoload, const_missing, or an application method body.
+    class ValueClass
+      SOURCE_LOCATION = Module.instance_method(:const_source_location)
+      SINGLETON_CLASS = Object.instance_method(:singleton_class)
+      INSTANCE_METHOD = Module.instance_method(:instance_method)
+      METHOD_OWNER = UnboundMethod.instance_method(:owner)
+      METHOD_SOURCE = UnboundMethod.instance_method(:source_location)
+
+      def initialize
+        @lookup = RuntimeLookup.new
+      end
+
+      # @param declaration [Hash] collector declaration with a literal constructor
+      # @param file_path [String] original file containing the assignment
+      # @return [String, nil] canonical, source-owned class identity
+      def call(declaration, file_path:)
+        return unless candidate?(declaration)
+
+        factory = factory(declaration)
+        return unless factory
+
+        result = @lookup.call(declaration['name'], nesting: declaration['enclosing_nesting'], allow_private: true)
+        return unless value_class?(result, declaration, factory)
+        return unless owns_assignment?(result[:target], declaration, file_path)
+
+        result[:target]
+      rescue NameError, TypeError, ArgumentError
+        nil
+      end
+
+      private
+
+      def candidate?(declaration)
+        declaration['constructor'] && declaration.fetch('singleton_depth', 0).zero?
+      end
+
+      def value_class?(result, declaration, factory)
+        result[:target] == declaration['owner'] && @lookup.class_object?(result[:value]) &&
+          @lookup.reflect(result[:value], :ancestors).any? { |ancestor| identical?(ancestor, factory) }
+      end
+
+      def factory(declaration)
+        name = declaration['constructor']
+        core_name = name.delete_prefix('::')
+        return unless %w[Struct Data].include?(core_name)
+
+        actual = @lookup.call(name, nesting: declaration['enclosing_nesting'])[:value]
+        core = @lookup.call("::#{core_name}")[:value]
+        return unless core && identical?(actual, core)
+
+        singleton = SINGLETON_CLASS.bind(core).call
+        method = INSTANCE_METHOD.bind(singleton).call(core_name == 'Struct' ? :new : :define)
+        return unless identical?(METHOD_OWNER.bind(method).call, singleton) && METHOD_SOURCE.bind(method).call.nil?
+
+        core
+      end
+
+      def owns_assignment?(identifier, declaration, file_path)
+        parts = identifier.split('::')
+        name = parts.pop
+        scope = parts.empty? ? Object : @lookup.call("::#{parts.join('::')}", allow_private: true)[:value]
+        return false unless @lookup.module_object?(scope)
+
+        location = SOURCE_LOCATION.bind(scope).call(name, false)
+        location && File.expand_path(location.first) == File.expand_path(file_path) &&
+          location.last.between?(declaration['line'], declaration['end_line'])
+      end
+
+      def identical?(left, right)
+        RuntimeLookup::CORE_EQUAL.bind(left).call(right)
+      end
+    end
+  end
+end

data/lib/woods/storage/metadata_store.rb

@@ -115,7 +115,10 @@ module Woods
           raise NotImplementedError
         end
 
-        # Every stored identifier.
+        # Every stored identity, including source-empty records without vectors.
+        # Return internal typed keys unchanged; do not collapse same-name units
+        # to their shared public identifier. Embedding reconciliation uses this
+        # inventory independently of the optional snapshot #each_entry seam.
         #
         # Used by the evaluation harness's {Woods::Evaluation::BaselineRunner}
         # to build naive baselines (grep/random/file-level) to score the real

data/lib/woods/storage/qdrant.rb

@@ -193,8 +193,8 @@ module Woods
         def self.validate_host_visibility!(host, allow_private_hosts:)
           return if allow_private_hosts
 
-          # Canonicalize (strip port, trailing dot, IPv6 brackets) via
-          # the shared helper so Qdrant and OriginGuard stay in sync.
+          # Canonicalize URL hosts before applying the numeric-host checks
+          # also used by the HTTP origin policy.
           canonical = Util::HostGuard.canonicalize(host)
 
           # Non-canonical numeric hosts (hex `0x7f000001`, octal