woods 2.0.1 → 2.1.0

data/lib/woods/mcp/index_reader.rb

@@ -46,12 +46,15 @@ module Woods
 
       # Most output directories contain one unit type. RailsSourceExtractor
       # emits gem_source units in rails_source/, while GraphQL publishes four
-      # subtypes in graphql/. Directory-filtered search retains its historical
-      # family labels while artifact readers preserve the actual unit type.
+      # subtypes in graphql/. Search accepts directory-family aliases and
+      # concrete types, and returns each unit's actual public type.
       UNIT_TYPES_BY_DIR = DIR_TO_TYPE.transform_values { |type| [type].freeze }
                                      .merge('rails_source' => %w[rails_source gem_source].freeze,
                                             'graphql' => %w[graphql_type graphql_mutation graphql_resolver graphql_query].freeze)
                                      .freeze
+      UNIT_TYPE_TO_DIR = UNIT_TYPES_BY_DIR.each_with_object({}) do |(directory, types), result|
+        types.each { |type| result[type] = directory }
+      end.freeze
 
       # Maximum number of loaded unit files to cache in memory.
       MAX_UNIT_CACHE = 50
@@ -375,14 +378,14 @@ module Woods
       def find_unit(identifier, type: nil)
         if type
           return with_pinned_generation do
-            dir = UNIT_TYPES_BY_DIR.find { |_, types| types.include?(type) }&.first
+            dir = UNIT_TYPE_TO_DIR[type] || TYPE_TO_DIR[type]
             next nil unless dir
             raise IOError, "symlink unit directory: #{dir}" if current_payload_dir.join(dir).symlink?
 
             next nil unless search_index_entries(dir).any? { |entry| entry['identifier'] == identifier }
 
             unit = read_published_unit(dir, identifier)
-            unit if unit['type'] == type
+            unit if unit['type'] == type || !UNIT_TYPE_TO_DIR.key?(type)
           end
         end
         ensure_fresh!
@@ -489,6 +492,7 @@ module Woods
       # @api private
       def search_within_pin(query = nil, types: nil, fields: %w[identifier], limit: 20,
                             exact_prefix: nil, exact_suffix: nil, packages: nil, source_paths: nil)
+        types = normalize_search_types(types)
         scope = search_scope(packages, source_paths, types)
         prefix = exact_prefix.blank? ? nil : exact_prefix.downcase
         suffix = exact_suffix.blank? ? nil : exact_suffix.downcase
@@ -508,7 +512,7 @@ module Woods
         phase2_scanned = 0
 
         begin
-          dirs = scope || !types ? TYPE_DIRS : types.filter_map { |type| TYPE_TO_DIR[type] }.uniq
+          dirs = types ? types.map { |type| UNIT_TYPE_TO_DIR.fetch(type) }.uniq : TYPE_DIRS
           # Identifier matches retain priority. Deep candidates are interleaved
           # across types so an early large directory cannot consume their budget.
           phase2_queues = {}
@@ -516,7 +520,13 @@ module Woods
             dirs.each do |dir|
               type_name = DIR_TO_TYPE[dir]
               entries = search_index_entries(dir)
-              entries = scoped_search_entries(entries, dir, scope) if scope
+              entries = if scope
+                          scoped_search_entries(entries, dir, scope)
+                        elsif types
+                          typed_search_entries(entries, dir, types, results)
+                        else
+                          entries
+                        end
               if entries.size > 1
                 matching_count = entries.count do |entry|
                   identifier_passes_filters?(entry['identifier'], pattern, prefix, suffix)
@@ -527,11 +537,13 @@ module Woods
               end
 
               entries.each do |entry|
-                type_name = entry.fetch('scope_type', DIR_TO_TYPE[dir])
                 id = entry['identifier']
                 next unless identifier_passes_prefix_suffix?(id, prefix, suffix)
 
                 if fields.include?('identifier') && pattern.match?(id)
+                  type_name = search_entry_type(entry, dir, results)
+                  next unless type_name
+
                   results.add(identifier: id, type: type_name, match_field: 'identifier')
                   throw :search_done if results.result_limit_reached?
 
@@ -539,7 +551,7 @@ module Woods
                 end
                 next unless fields.include?('metadata') || fields.include?('source_code')
 
-                (phase2_queues[dir] ||= []) << [type_name, id]
+                (phase2_queues[dir] ||= []) << [entry, dir]
               end
             end
 
@@ -553,10 +565,21 @@ module Woods
                   results.stop('scan_budget')
                   throw :search_done
                 end
-                type_name, id = queue.shift
+                entry, dir = queue.shift
+                id = entry['identifier']
                 progressed = true
                 phase2_scanned += 1
-                unit = scope ? scope.metadata_store.find(StorageIdentity.key(id, type_name)) : load_search_unit(type_name, id)
+                type_name = search_entry_type(entry, dir, results)
+                next unless type_name
+
+                unit = if scope
+                         scope.metadata_store.find(StorageIdentity.key(id, type_name))
+                       else
+                         readable_search_unit(type_name, id, results)
+                       end
+                next unless unit
+
+                type_name = unit['type']
                 field = if fields.include?('source_code') && unit['source_code'] && pattern.match?(unit['source_code'])
                           'source_code'
                         elsif fields.include?('metadata') && unit['metadata'] && pattern.match?(unit['metadata'].to_json)
@@ -593,6 +616,53 @@ module Woods
       end
       private :search_scope
 
+      def normalize_search_types(types)
+        return nil if types.nil? || types == []
+        unless types.is_a?(Array) && types.all?(String)
+          raise ArgumentError, 'search types must be an array of type names'
+        end
+
+        types.flat_map do |type|
+          if TYPE_TO_DIR.key?(type)
+            UNIT_TYPES_BY_DIR.fetch(TYPE_TO_DIR.fetch(type))
+          elsif UNIT_TYPE_TO_DIR.key?(type)
+            [type]
+          else
+            raise ArgumentError, "unknown search type: #{type}"
+          end
+        end.uniq
+      end
+      private :normalize_search_types
+
+      # Modern summaries carry their public type. Resolve legacy family types
+      # only when a type filter or matching candidate needs that identity.
+      def search_entry_type(entry, dir, results)
+        actual = entry['scope_type'] || entry['type']
+        possible = UNIT_TYPES_BY_DIR.fetch(dir)
+        actual ||= possible.one? ? possible.first : readable_search_unit(DIR_TO_TYPE.fetch(dir), entry['identifier'], results)&.fetch('type')
+        return actual if possible.include?(actual)
+
+        results.stop('unreadable_or_corrupt_source')
+        nil
+      end
+      private :search_entry_type
+
+      def readable_search_unit(type, identifier, results)
+        load_search_unit(type, identifier)
+      rescue JSON::ParserError, IOError, SystemCallError
+        results.stop('unreadable_or_corrupt_source')
+        nil
+      end
+      private :readable_search_unit
+
+      def typed_search_entries(entries, dir, types, results)
+        entries.filter_map do |entry|
+          actual = search_entry_type(entry, dir, results)
+          entry.merge('scope_type' => actual) if types.include?(actual)
+        end
+      end
+      private :typed_search_entries
+
       def scoped_search_entries(entries, dir, scope)
         entries.flat_map do |entry|
           UNIT_TYPES_BY_DIR.fetch(dir).filter_map do |type|
@@ -870,7 +940,7 @@ module Woods
             expected_dir.join('manifest.json').to_s, File::RDONLY
           )
           file.flock(File::LOCK_SH)
-          marker = @generation.current
+          marker = published_marker
           resolved = resolve_payload_dir(marker)
           marker_still_matches = marker.number.zero? || (same_generation?(marker) && resolved == expected_dir)
           if marker_still_matches && expected_dir.directory?
@@ -881,13 +951,16 @@ module Woods
           file.flock(File::LOCK_UN)
           file.close
           load_generation(marker) unless marker.number.zero?
+        rescue Woods::Generation::InvalidMarker
+          file&.close unless file&.closed?
+          raise
         rescue Errno::ENOENT
           file&.close unless file&.closed?
           return if saw_missing_manifest && missing_manifest_dir == expected_dir
 
           saw_missing_manifest = true
           missing_manifest_dir = expected_dir
-          marker = @generation.current
+          marker = published_marker
           load_generation(marker) unless marker.number.zero?
         end
       end
@@ -934,13 +1007,26 @@ module Woods
         return nil if @pin_depth.positive?
 
         signature = generation_signature
-        return nil if signature.nil? || signature == @generation_signature
+        if signature.nil?
+          published_marker if @loaded_generation
+          return nil
+        end
+        return nil if signature == @generation_signature
 
+        marker = published_marker
+        resolve_payload_dir(marker)
+        load_generation(marker) unless marker.number.zero? || same_generation?(marker)
         @generation_signature = signature
-        marker = @generation.current
-        return nil if marker.number.zero? || same_generation?(marker)
+        @loaded_generation
+      end
 
-        load_generation(marker)
+      def published_marker
+        marker = @generation.current!
+        if marker.number.zero? && @loaded_generation&.positive? && current_payload_dir != @index_dir
+          raise Woods::Generation::InvalidMarker, 'Published generation marker is missing'
+        end
+
+        marker
       end
 
       # Adopt one already-read marker as the reader's loaded generation.
@@ -949,8 +1035,9 @@ module Woods
       # @param marker [Woods::Generation::Marker]
       # @return [void]
       def load_generation(marker)
+        directory = resolve_payload_dir(marker)
         reload!
-        @payload_dir = resolve_payload_dir(marker)
+        @payload_dir = directory
         @loaded_token = marker.token
         @loaded_generation = marker.number
       end
@@ -968,7 +1055,7 @@ module Woods
 
         marker = Woods::Generation.new(output_dir: @index_dir).current
         resolve_payload_dir(marker).join('manifest.json').file?
-      rescue TypeError, NoMethodError
+      rescue TypeError, NoMethodError, Woods::Generation::InvalidMarker
         # Match Bootstrapper's startup preflight for malformed marker shapes.
         # Keep this local: errors during later generation refresh still surface.
         false
@@ -995,7 +1082,12 @@ module Woods
       # @param marker [Woods::Generation::Marker]
       # @return [Pathname]
       def resolve_payload_dir(marker)
-        Woods::Generation.new(output_dir: @index_dir).payload_dir(marker)
+        directory = Woods::Generation.new(output_dir: @index_dir).payload_dir(marker)
+        if marker.payload && !marker.payload.empty? && directory == @index_dir
+          raise Woods::Generation::InvalidMarker, 'Published generation payload is unavailable or outside the index'
+        end
+
+        directory
       end
 
       # Compare the *token*, not the number.
@@ -1103,9 +1195,11 @@ module Woods
       #   generation file
       def generation_signature
         stat = File.stat(@generation.path)
-        [stat.mtime.to_f, stat.size, stat.ino]
-      rescue SystemCallError
+        [stat.mtime.to_f, stat.ctime.to_f, stat.size, stat.ino]
+      rescue Errno::ENOENT
         nil
+      rescue SystemCallError
+        raise Woods::Generation::InvalidMarker, 'Published generation marker is unavailable'
       end
 
       # Case-insensitive literal prefix/suffix check on an identifier.
@@ -1211,8 +1305,9 @@ module Woods
       # Read the selected type bucket, never the identifier-only lookup map.
       # Keep the existing per-file signature checks and LRU cache for deep reads.
       def load_search_unit(type, identifier)
-        data = load_unit(TYPE_TO_DIR.fetch(type), unit_filename(identifier))
-        unless valid_published_unit?(data, TYPE_TO_DIR.fetch(type), identifier)
+        directory = TYPE_TO_DIR[type] || UNIT_TYPE_TO_DIR.fetch(type)
+        data = load_unit(directory, unit_filename(identifier))
+        unless valid_published_unit?(data, directory, identifier)
           raise IOError, "typed unit identity mismatch: #{type}:#{identifier}"
         end
 
@@ -1263,7 +1358,13 @@ module Woods
         data = File.open(path, File::RDONLY | File::NOFOLLOW | File::NONBLOCK) do |file|
           raise IOError, "non-regular unit file: #{dir}/#{filename}" unless file.stat.file?
 
-          JSON.parse(file.read)
+          # Decode the checked descriptor's bytes as UTF-8, independent of the
+          # process locale. JSON parsers may accept invalid UTF-8 verbatim, so
+          # validate before parsing instead of replacing malformed source bytes.
+          content = file.binmode.read.force_encoding(Encoding::UTF_8)
+          raise JSON::ParserError, "invalid UTF-8 in unit file: #{dir}/#{filename}" unless content.valid_encoding?
+
+          JSON.parse(content)
         end
         unless valid_published_unit?(data, dir, identifier)
           raise IOError, "typed unit identity mismatch: #{dir}/#{filename}"

data/lib/woods/mcp/index_reader_pinning.rb

@@ -64,6 +64,15 @@ module Woods
           return super unless reader && tool_names&.include?(request[:name])
 
           reader.with_pinned_generation { super }
+        rescue Woods::Generation::InvalidMarker
+          message = 'Published generation marker is unavailable or malformed; run woods:validate and restore or rebuild the index.'
+          meta = { error_code: :corrupt_artifact, tool: request[:name] }
+          meta[:completeness] = SearchResults.unavailable if request[:name] == 'search'
+          ::MCP::Tool::Response.new(
+            [{ type: 'text', text: message }], error: true,
+                                               structured_content: { text: message },
+                                               meta: meta
+          ).to_h
         end
 
         def read_resource_contents(request, **kwargs)
@@ -71,6 +80,13 @@ module Woods
           return super unless reader
 
           reader.with_pinned_generation { super }
+        rescue Woods::Generation::InvalidMarker => e
+          raise ::MCP::Server::RequestHandlerError.new(
+            'Published generation marker is unavailable or malformed.', request,
+            error_type: :internal_error, original_error: e,
+            error_code: ::JsonRpcHandler::ErrorCode::INTERNAL_ERROR,
+            error_data: { uri: request[:uri], error_code: 'corrupt_artifact' }
+          )
         end
       end
     end

data/lib/woods/mcp/renderers/markdown_renderer.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative '../../source_contributors'
+
 module Woods
   module MCP
     module Renderers
@@ -16,7 +18,11 @@ module Woods
           lines = []
           lines << "## #{data['identifier']} (#{data['type']})"
           lines << ''
-          lines << "**File:** `#{data['file_path']}`" if data['file_path']
+          if SourceContributors.multiple?(data)
+            lines << SourceContributors.label(data)
+          elsif data['file_path']
+            lines << "**File:** `#{data['file_path']}`"
+          end
           lines << "**Namespace:** #{data['namespace']}" if data['namespace']
           lines << ''
 

data/lib/woods/mcp/renderers/plain_renderer.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative '../../source_contributors'
+
 module Woods
   module MCP
     module Renderers
@@ -14,7 +16,7 @@ module Woods
           lines = []
           lines << "#{data['identifier']} (#{data['type']})"
           lines << DIVIDER
-          lines << "File: #{data['file_path']}" if data['file_path']
+          lines << SourceContributors.label(data) if data['file_path']
           lines << "Namespace: #{data['namespace']}" if data['namespace']
           lines << ''
 

data/lib/woods/mcp/search_results.rb

@@ -65,7 +65,13 @@ module Woods
           }
         }
         result[:partial] = true unless complete
-        result[:hint] = NARROWING_HINT unless complete
+        unless complete
+          result[:hint] = if @reason == 'unreadable_or_corrupt_source'
+                            'Run woods:validate and repair or republish unreadable unit artifacts.'
+                          else
+                            NARROWING_HINT
+                          end
+        end
         result[:note] = note unless note.nil? || note.empty?
         result
       end

data/lib/woods/mcp/server.rb

@@ -601,6 +601,8 @@ module Woods
             respond.call(renderer.render(:search, payload))
           rescue Retrieval::Scope::InvalidScopeError => e
             respond_err.call(e.message, code: :unsupported_argument, tool: 'search', argument: 'scope')
+          rescue ArgumentError => e
+            respond_err.call(e.message, code: :invalid_params, tool: 'search', argument: 'types')
           rescue IOError, SystemCallError, JSON::ParserError, EncodingError
             respond_err.call(
               'Search completeness: unknown (unreadable_or_corrupt_source). ' \
@@ -1169,6 +1171,10 @@ module Woods
             }
           ) do |entry_point:, server_context:, depth: nil|
             max_depth = coerce_int.call(depth) || 3
+            unless reader.find_unit(entry_point.split('#', 2).first)
+              next respond_err.call('Flow entry unit not found; use search and lookup to select an indexed unit.',
+                                    code: :not_found, tool: 'trace_flow', entry_point: entry_point)
+            end
 
             # Prefer the precomputed flow JSON written by FlowPrecomputer during
             # extraction (gated on `config.precompute_flows`) — it avoids
@@ -1316,6 +1322,7 @@ module Woods
                 require_relative '../extractor' unless defined?(Woods::Extractor)
                 extractor = Woods::Extractor.new(output_dir: output_dir)
                 incremental ? extractor.extract_changed(files) : extractor.extract_all
+                extractor.raise_on_publication_failure!
               end
             end
 
@@ -1893,7 +1900,7 @@ module Woods
 
         def define_snapshot_tools(server, snapshot_store, respond, respond_err, snap_missing)
           define_list_snapshots_tool(server, snapshot_store, respond, snap_missing)
-          define_snapshot_diff_tool(server, snapshot_store, respond, snap_missing)
+          define_snapshot_diff_tool(server, snapshot_store, respond, respond_err, snap_missing)
           define_unit_history_tool(server, snapshot_store, respond, snap_missing)
           define_snapshot_detail_tool(server, snapshot_store, respond, respond_err, snap_missing)
         end
@@ -1918,7 +1925,7 @@ module Woods
           end
         end
 
-        def define_snapshot_diff_tool(server, snapshot_store, respond, snap_missing)
+        def define_snapshot_diff_tool(server, snapshot_store, respond, respond_err, snap_missing)
           server.define_tool(
             name: 'snapshot_diff',
             description: 'Compare two extraction snapshots by git SHA. Returns lists of added, modified, and deleted units.',
@@ -1932,6 +1939,17 @@ module Woods
           ) do |sha_a:, sha_b:, server_context:|
             next snap_missing.call('snapshot_diff') unless snapshot_store
 
+            unless [sha_a, sha_b].all? { |sha| sha.match?(/\A[0-9a-f]+\z/i) }
+              next respond_err.call('Snapshot SHAs must be hexadecimal identifiers from list_snapshots.',
+                                    code: :invalid_params, tool: 'snapshot_diff')
+            end
+            sha_a = sha_a.downcase
+            sha_b = sha_b.downcase
+            unless snapshot_store.find(sha_a) && snapshot_store.find(sha_b)
+              next respond_err.call('One or both snapshots were not found; use list_snapshots for available SHAs.',
+                                    code: :not_found, tool: 'snapshot_diff')
+            end
+
             result = snapshot_store.diff(sha_a, sha_b)
             respond.call(JSON.pretty_generate({
                                                 sha_a: sha_a, sha_b: sha_b,
@@ -1981,6 +1999,7 @@ module Woods
           ) do |git_sha:, server_context:|
             next snap_missing.call('snapshot_detail') unless snapshot_store
 
+            git_sha = git_sha.downcase
             snapshot = snapshot_store.find(git_sha)
             if snapshot
               respond.call(JSON.pretty_generate(snapshot))
@@ -2497,8 +2516,9 @@ module Woods
 
           target = URI::DEFAULT_PARSER.unescape(raw_target).force_encoding(Encoding::UTF_8)
           return unless target.valid_encoding?
-          return if target.match?(%r{[%\\/\x00-\x1f\x7f]})
-          return if %w[. ..].include?(target)
+          return if target.match?(/[%\\\x00-\x1f\x7f]/) || target.start_with?('/')
+          return if target.split('/').any? { |part| %w[. ..].include?(part) }
+          return if parsed.host == 'type' && target.include?('/')
 
           [parsed.host.to_sym, target]
         rescue URI::InvalidURIError

data/lib/woods/module_reconciliation.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+module Woods
+  # Keeps callable app/models modules under one extractor owner as model
+  # inclusions change. Partial runtime discovery cannot establish removals.
+  module ModuleReconciliation # rubocop:disable Metrics/ModuleLength -- one ownership/provenance policy across writers
+    private
+
+    # @param affected_types [Set<Symbol>] extractor keys requiring index updates
+    # @return [Set<String>] added, migrated or removed module identifiers
+    def reconcile_model_mixins(affected_types)
+      concerns = extractor_for(:concerns)
+      return Set.new unless concerns.respond_to?(:runtime_model_mixins)
+
+      live = concerns.runtime_model_mixins
+      live_names = live.values.flatten.to_set(&:name)
+      known = @dependency_graph.units_of_type(:concern).to_set
+      added = newly_claimed_concerns(concerns, live, known)
+      touched = register_and_write(:concerns, added, affected_types)
+      touched.merge(remove_claimed_standalone_modules(live_names, affected_types))
+      touched.merge(remove_unclaimed_concerns(concerns, known - live_names, affected_types)) if @eager_load_complete
+      touched.merge(add_standalone_modules(affected_types))
+    end
+
+    def newly_claimed_concerns(concerns, live, known)
+      live.flat_map do |path, modules|
+        next [] if modules.all? { |mod| known.include?(mod.name) }
+
+        checked_extraction(:concerns, concerns) do
+          Array(concerns.extract_model_mixin_file(path)).reject { |unit| known.include?(unit.identifier) }
+        end || []
+      end
+    end
+
+    def remove_claimed_standalone_modules(live_names, affected_types)
+      live_names.each_with_object(Set.new) do |identifier, touched|
+        next unless standalone_module_identity?(identifier)
+
+        touched.add(identifier) if remove_unit(identifier, affected_types, type: :poro)
+      end
+    end
+
+    def remove_unclaimed_concerns(concerns, stale, affected_types)
+      stale.each_with_object(Set.new) do |identifier, touched|
+        path = @dependency_graph.node(identifier, type: :concern)[:file_path]
+        next if concerns.conventional_concern_path?(path)
+
+        touched.add(identifier) if remove_unit(identifier, affected_types, type: :concern)
+      end
+    end
+
+    def runtime_model_mixin_file?(extractor, type, path)
+      type == :concern && extractor.respond_to?(:extract_model_mixin_file) &&
+        extractor.respond_to?(:conventional_concern_path?) && !extractor.conventional_concern_path?(path)
+    end
+
+    def add_standalone_modules(affected_types)
+      poros = extractor_for(:poros)
+      return Set.new unless poros.respond_to?(:standalone_modules)
+
+      discovered = checked_extraction(:poros, poros) { poros.standalone_modules }
+      return Set.new unless discovered
+
+      added = discovered.values.flatten.reject do |unit|
+        @dependency_graph.node(unit.identifier, type: :poro) ||
+          @dependency_graph.node(unit.identifier, type: :concern)
+      end
+      register_and_write(:poros, added, affected_types)
+    end
+
+    def standalone_module_identity?(identifier)
+      return false unless @dependency_graph.node(identifier, type: :poro)
+
+      path = payload_dir.join('poros', collision_safe_filename(identifier))
+      return false unless path.file?
+
+      JSON.parse(AtomicFile.read(path)).fetch('metadata', {})['ruby_kind'] == 'module'
+    end
+
+    # A missing includer during fallback boot does not transfer its previously
+    # published concern to the PORO extractor. Filter fresh candidates too.
+    def authoritative_module_units(units)
+      return units if @eager_load_complete
+
+      units.reject do |unit|
+        unit.type == :poro && unit.metadata[:ruby_kind] == 'module' &&
+          @dependency_graph.node(unit.identifier, type: :concern)
+      end
+    end
+
+    # @param identifier [String] published typed identity
+    # @param type [Symbol] current owner
+    # @return [Boolean] whether incomplete loading requires retaining this unit
+    def retain_partial_module?(identifier, type)
+      return false if @eager_load_complete
+
+      return false unless runtime_module_identity?(identifier, type)
+      return false if type == :poro && live_concern_identity?(identifier)
+
+      verify_retained_module_source!(identifier, type)
+      true
+    end
+
+    def runtime_module_identity?(identifier, type)
+      return standalone_module_identity?(identifier) if type == :poro
+      return false unless type == :concern
+
+      concerns = extractor_for(:concerns)
+      path = @dependency_graph.node(identifier, type: type)[:file_path]
+      concerns.respond_to?(:conventional_concern_path?) && !concerns.conventional_concern_path?(path)
+    end
+
+    def live_concern_identity?(identifier)
+      concerns = extractor_for(:concerns)
+      concerns.respond_to?(:runtime_model_mixins) &&
+        concerns.runtime_model_mixins.values.any? { |modules| modules.any? { |mod| mod.name == identifier } }
+    end
+
+    # Cache identities predate every consumption update in this run. A freshly
+    # written shared-file sibling must not certify retained module metadata as
+    # having consumed changed source during incomplete eager loading.
+    def verify_retained_module_source!(identifier, type)
+      return unless @source_inputs
+
+      path = @dependency_graph.node(identifier, type: type)[:file_path]
+      relative = File.expand_path(path, Rails.root).delete_prefix("#{File.expand_path(Rails.root)}/")
+      before = @source_reference_baseline&.dig('files', relative, 'identity')
+      return if before && before == @source_inputs.source_identity(path)
+
+      raise SourceReferences::RebuildRequired,
+            "Cannot refresh retained #{type}:#{identifier} after incomplete eager loading. " \
+            'Retry in a fresh Rails process with a complete eager load; the previous generation remains active.'
+    end
+
+    def consume_module_aware_refresh(key, units)
+      if !@eager_load_complete && %i[poros concerns].include?(key)
+        @source_inputs&.unverified("extractor:#{key}")
+      else
+        @source_inputs&.consume_extractor(key, units)
+      end
+    end
+
+    # These formerly file-only families now retain runtime-discovered modules
+    # on a partial boot, so their replacement authority follows the same gate.
+    def replacement_discovery_complete?(key)
+      return @eager_load_complete if %i[poros concerns].include?(key)
+
+      super
+    end
+  end
+end

data/lib/woods/path_dispatcher.rb

@@ -165,7 +165,7 @@ module Woods
           file_rule(:migrations, :extract_migration_file, %w[db/migrate], recursive: false),
           # POROs are app/models classes that are *not* ActiveRecord models;
           # the extractor makes that call itself given ar_names.
-          file_rule(:poros, :extract_poro_file, %w[app/models], exclude: %w[/concerns/]),
+          file_rule(:poros, :extract_poro_units, %w[app/models], exclude: %w[/concerns/]),
           file_rule(:libs, :extract_lib_file, %w[lib], exclude: ex::LibExtractor::EXCLUDED_SEGMENTS),
           file_rule(:test_mappings, :extract_test_file, %w[spec], extensions: %w[_spec.rb]),
           file_rule(:test_mappings, :extract_test_file, %w[test], extensions: %w[_test.rb])
@@ -184,11 +184,16 @@ module Woods
         Woods::Extractors::ViewTemplateExtractor::ENGINES.flat_map { |k| k.new.extensions }.uniq
       end
 
+      def aggregate_source_rules
+        [whole_app_rule(:libs, %w[lib], extensions: %w[.rb], exclude: Woods::Extractors::LibExtractor::EXCLUDED_SEGMENTS),
+         whole_app_rule(:rake_tasks, Woods::Extractors::RakeTaskExtractor::RAKE_DIRECTORIES, extensions: %w[.rake])]
+      end
+
       def build_whole_app_rules
         [
           # A task may combine definitions from several files; any change or
           # deletion must reconcile the complete task set, not its primary file.
-          whole_app_rule(:rake_tasks, Woods::Extractors::RakeTaskExtractor::RAKE_DIRECTORIES, extensions: %w[.rake]),
+          *aggregate_source_rules,
           whole_app_rule(:routes, %w[config/routes], exact_paths: %w[config/routes.rb]),
           whole_app_rule(:engines, %w[config/routes], exact_paths: %w[config/routes.rb Gemfile.lock]),
           whole_app_rule(:middleware, %w[config/initializers config/environments],