woods 2.0.1 → 2.1.0

data/lib/woods/extractor.rb

@@ -13,6 +13,7 @@ require_relative 'filename_utils'
 require_relative 'token_utils'
 require_relative 'extracted_unit'
 require_relative 'dependency_graph'
+require_relative 'extraction_identities'
 require_relative 'payload_store'
 require_relative 'git_provenance'
 require_relative 'git_history'
@@ -58,6 +59,8 @@ require_relative 'change_set'
 require_relative 'generation'
 require_relative 'path_dispatcher'
 require_relative 'source_inputs/session'
+require_relative 'source_references/extraction'
+require_relative 'module_reconciliation'
 
 module Woods
   # Extractor is the main orchestrator for codebase extraction.
@@ -74,8 +77,11 @@ module Woods
   #   extractor.extract_changed(["app/models/user.rb", "app/services/checkout.rb"])
   #
   class Extractor
+    include ExtractionIdentities
     include FilenameUtils
     include Extractors::SourceNesting
+    include SourceReferences::Extraction
+    include ModuleReconciliation
 
     # Directories under app/ that contain classes we need to extract.
     # Used by eager_load_extraction_directories as a fallback when
@@ -215,7 +221,7 @@ module Woods
       database_view: :extract_view_file,
       caching: :extract_caching_file,
       test_mapping: :extract_test_file,
-      poro: :extract_poro_file,
+      poro: :extract_poro_units,
       lib: :extract_lib_file
     }.freeze
 
@@ -226,7 +232,12 @@ module Woods
     # class-based entry point to re-extract them through. Re-extracting one
     # of these by file is faithful only when the file names the unit; see
     # {#re_extracted_units}.
-    CLASS_DISCOVERED_FALLBACK = { job: :extract_job_class }.freeze
+    CLASS_DISCOVERED_FALLBACK = { job: :extract_job_class, serializer: :extract_serializer_class }.freeze
+
+    # These families combine file discovery with runtime descendants. Only
+    # their union can authorize removals; a per-file pass cannot see nested
+    # classes, while a descendant-only pass cannot see source-only units.
+    HYBRID_DISCOVERY_EXTRACTORS = %i[jobs serializers].freeze
 
     # Unit types each extractor owns — the inverse of {TYPE_TO_EXTRACTOR_KEY}.
     #
@@ -277,7 +288,8 @@ module Woods
       components: { type: :component, method: :extract_component },
       view_components: { type: :view_component, method: :extract_component },
       action_cable_channels: { type: :action_cable_channel, method: :extract_channel },
-      # Additions only — see `reconcile_removals: false`. GraphQL is the one
+      # Additions and known-type role changes, without discovery-based removals.
+      # See `reconcile_removals: false`. GraphQL is the one
       # entry whose discovery set is not authoritative for its unit type
       # (#167).
       # `types:` because this extractor emits four unit types, not one:
@@ -301,6 +313,7 @@ module Woods
     #
     # @return [Hash{Symbol => Symbol}] extractor key => unit type
     WHOLE_APP_EXTRACTORS = {
+      libs: :lib,
       rake_tasks: :rake_task,
       routes: :route,
       middleware: :middleware,
@@ -358,7 +371,9 @@ module Woods
     # flat index — the output root also holds `generation.json`, `dumps/`,
     # `tasks/`, `woods.sqlite3` and `payloads/` itself, none of which belong
     # to a generation's payload.
-    PAYLOAD_FILES = %w[manifest.json source_inputs.json dependency_graph.json graph_analysis.json SUMMARY.md].freeze
+    PAYLOAD_FILES = %w[
+      manifest.json source_inputs.json source_references.json dependency_graph.json graph_analysis.json SUMMARY.md
+    ].freeze
 
     # Payload directories that are not per-type unit directories.
     PAYLOAD_DIRS = %w[flows].freeze
@@ -432,6 +447,7 @@ module Woods
       # Phase 1.6: Package membership. Runs before the graph is rebuilt so
       # registration copies metadata[:package] onto the node (#280).
       profile_phase('package annotation') { annotate_packages }
+      profile_phase('source references') { enrich_source_references_full }
 
       # Rebuild the graph from deduped results. #164 gave DependencyGraph
       # `#remove`/`#unregister`, so surgical removal is now possible — but a
@@ -492,6 +508,8 @@ module Woods
       if Woods.configuration.precompute_flows
         Rails.logger.info '[Woods] Precomputing request flows...'
         profile_phase('flows') { precompute_flows }
+      else
+        withdraw_disabled_flows
       end
 
       profile_phase('graph write') do
@@ -541,11 +559,19 @@ module Woods
     #
     # @param changed_files [Array<String>] List of changed file paths
     # @return [Array<String>] Identifiers of units re-extracted, added, or removed
+    # @raise [Woods::ExtractionError] when boot-captured inputs require a fresh
+    #   Rails process and full extraction instead of reusing this runtime
     def extract_changed(changed_files)
       profile_started = Process.clock_gettime(Process::CLOCK_MONOTONIC) if profiling?
-      prepare_incremental_run(operation: 'incremental')
-
       change_set = ChangeSet.new(paths: changed_files, root: Rails.root)
+      require_relative 'input_rules'
+      restart_paths = change_set.relative_paths.select { |path| InputRules.new.action(path) == :full }
+      unless restart_paths.empty?
+        raise Woods::ExtractionError,
+              "Restart-sensitive inputs (#{restart_paths.join(', ')}) require a fresh Rails process; " \
+              'run woods:extract after applying schema/configuration changes'
+      end
+      prepare_incremental_run(operation: 'incremental')
       affected_types = Set.new
 
       # Blast radius from the pre-change graph, bounded by
@@ -553,6 +579,7 @@ module Woods
       affected_ids = profile_phase('blast radius') do
         @dependency_graph.affected_by(change_set.absolute_paths, max_depth: blast_radius_depth)
       end
+      @hybrid_discovery_keys = hybrid_discovery_keys(change_set, affected_ids)
       @flow_scope = profile_phase('flow radius') { flow_scope_for(change_set) }
       Rails.logger.info "[Woods] #{change_set.size} changed files affect #{affected_ids.size} units"
 
@@ -567,6 +594,7 @@ module Woods
       end
 
       profile_phase('reconciliation') do
+        @hybrid_discovery_keys.each { |key| touched.merge(replace_type_wholesale(key, affected_types)) }
         touched.merge(reconcile_class_based_types(affected_types))
         touched.merge(reconcile_model_mixins(affected_types))
         touched.merge(rerun_whole_app_extractors(change_set, affected_types))
@@ -601,6 +629,7 @@ module Woods
       end
 
       raise_on_handled_extraction_failure!
+      touched.merge(profile_phase('source references') { enrich_source_references_incremental(affected_types) })
       finalize_incremental_unit_json(affected_types)
 
       # Regenerate type indexes for affected types
@@ -663,7 +692,9 @@ module Woods
         acc.merge(replace_type_wholesale(key, affected_types))
       end
 
+      touched.merge(reconcile_model_mixins(affected_types)) if (known & %i[models poros concerns]).any?
       raise_on_handled_extraction_failure!
+      touched.merge(profile_phase('source references') { enrich_source_references_incremental(affected_types) })
       finalize_incremental_unit_json(affected_types)
       profile_phase('type index') { affected_types.each { |type_key| regenerate_type_index(type_key) } }
       finalize_incremental_run(touched, reason: "refresh:#{known.sort.join(',')}")
@@ -680,8 +711,9 @@ module Woods
     # the resident watch daemon can keep its recoverable posture: it detects
     # the unchanged generation, reports degraded, and carries the paths into
     # a later cycle. One-shot callers have no later cycle, so the rake tasks
-    # call this method before reporting success and receive a typed non-zero
-    # failure instead of claiming an unreachable payload was published.
+    # and embedded pipeline tool call this method before reporting success.
+    # They receive a typed failure instead of claiming an unreachable payload
+    # was published.
     #
     # @return [void]
     # @raise [Woods::ExtractionError] when the generation marker could not be
@@ -780,6 +812,7 @@ module Woods
     # @return [void]
     # @raise [Woods::ExtractionError] see {#begin_payload!}
     def prepare_incremental_run(operation: 'incremental')
+      ensure_supported_incremental_writer!
       profile_phase('source capture') { begin_source_inputs(operation) }
       profile_phase('payload seed') { begin_payload!(strict: true) }
       graph_path = payload_dir.join('dependency_graph.json')
@@ -788,16 +821,20 @@ module Woods
         @dependency_graph = DependencyGraph.from_h(JSON.parse(AtomicFile.read(graph_path))) if graph_path.exist?
       end
 
+      prepare_source_reference_baseline
       ModelNameCache.reset!
       profile_phase('eager load') { safe_eager_load! }
 
       @dependents_dirty = Set.new
       @incremental_written = {}
+      @library_replacement_touched = nil
+      @identity_claims = {}
       # nil = no scope was computed for this run, so every re-extracted
       # controller has its flows reassembled. {#refresh} leaves it that way.
       @flow_scope = nil
       @previous_flow_index_entries = nil
       @incremental_extractors = nil
+      @hybrid_discovery_keys = Set.new
       @active_record_names = nil
       @package_resolver = nil
       @persisted_index_stats = nil
@@ -830,9 +867,10 @@ module Woods
     #   reading "incremental" after a `woods:refresh[routes]` is being misled
     # @return [void]
     def finalize_incremental_run(touched, reason: 'incremental')
+      withdrew_flows = withdraw_disabled_flows unless Woods.configuration.precompute_flows
       profile_phase('graph write') { write_dependency_graph }
 
-      if touched.empty?
+      if touched.empty? && !withdrew_flows
         Rails.logger.info '[Woods] Incremental run changed nothing — leaving manifest timestamp untouched'
         return
       end
@@ -892,6 +930,9 @@ module Woods
     # handoff can additionally establish the pre-Bundler/Rails boot boundary.
     def begin_source_inputs(operation)
       @failed_consumers = Set.new
+      @source_reference_refreshed = Set.new
+      @source_reference_paths = nil
+      @source_reference_baseline = nil
       @source_inputs = SourceInputs::Session.new(root: Rails.root, output_dir: @output_dir,
                                                  baseline_path: source_input_baseline_path,
                                                  operation: operation)
@@ -940,6 +981,10 @@ module Woods
       return unless @source_inputs
 
       manifest = @source_inputs.finish(generation: @payload_generation, eager_load_complete: @eager_load_complete)
+      verify_source_reference_publication!(manifest)
+      if manifest.unavailable?
+        manifest.bind_reference_cache!(SourceReferences::Cache.read(payload_dir.join(SourceReferences::Cache::FILE_NAME)))
+      end
       AtomicFile.write(payload_dir.join(SourceInputs::Manifest::FILE_NAME), JSON.pretty_generate(manifest.data))
     end
 
@@ -1001,6 +1046,31 @@ module Woods
       @payload_generation = nil
     end
 
+    # Readers retain legacy compatibility, but partial writers cannot migrate
+    # retained v1 units. A missing version in a generation manifest is allowed:
+    # early v2 prereleases published generations before recording provenance.
+    def ensure_supported_incremental_writer!
+      generation = Generation.new(output_dir: @output_dir)
+      directory = generation.payload_dir
+      manifest_path = directory.join('manifest.json')
+      return unless manifest_path.file?
+
+      if directory == generation.root
+        raise Woods::ExtractionError,
+              "Cannot incrementally update a legacy flat index under #{@output_dir}; run a full woods:extract first"
+      end
+
+      manifest = JSON.parse(AtomicFile.read(manifest_path))
+      writer = manifest.fetch('woods_version', nil)
+      return if writer.nil? || Gem::Version.new(writer).segments.first >= 2
+
+      raise Woods::ExtractionError,
+            "Cannot incrementally update an index written by Woods #{writer}; run a full woods:extract first"
+    rescue JSON::ParserError, ArgumentError, TypeError, NoMethodError => e
+      raise Woods::ExtractionError,
+            "Cannot verify the baseline manifest writer (#{e.class}); run a full woods:extract first"
+    end
+
     # Refuse an incremental run that has no baseline to be incremental
     # against (CORE-2). With no published generation and no dependency
     # graph — a failed CI cache restore, a typo'd WOODS_OUTPUT, a first run
@@ -1011,8 +1081,9 @@ module Woods
     # until a full extraction. The watch daemon already enforces this
     # invariant on its side (a missing generation marker means one full
     # extraction); the one-shot entry points must refuse rather than
-    # publish silently. A pre-generation flat index passes: its graph was
-    # seeded into this run's payload directory by {#begin_payload!}.
+    # publish silently. Legacy flat manifests are refused by the writer
+    # compatibility check before seeding; a bare graph can still provide an
+    # embedding caller's baseline without asserting a legacy writer version.
     #
     # @param graph_path [Pathname] the seeded payload's dependency graph
     # @return [void]
@@ -1432,17 +1503,17 @@ module Woods
       retained_paths = {}
 
       units.each do |unit|
-        if retained_paths.key?(unit.identifier)
-          prior_path = retained_paths[unit.identifier]
-          if unit.file_path != prior_path
-            raise Woods::ExtractionError, same_type_collision_message(type, unit, prior_path)
-          end
+        identity = unit.identifier
+        path = identity_source(unit.file_path)
+        if retained_paths.key?(identity)
+          prior_path = retained_paths[identity]
+          reject_identity_collision!(unit, prior_path) if path != prior_path
 
           dropped += 1
           next
         end
 
-        retained_paths[unit.identifier] = unit.file_path
+        retained_paths[identity] = path
         deduped << unit
       end
 
@@ -1461,6 +1532,7 @@ module Woods
         'only one unit could ever be indexed, so extraction aborted. ' \
         'Wrapper-nested class naming requires Zeitwerk mode with Zeitwerk >= 2.6.9; on older loaders or ' \
         'classic-mode hosts, check that support before changing valid namespace wrappers. ' \
+        'After moving a class, run woods:extract in a fresh Rails process if incremental ownership cannot be proven. ' \
         'For a genuine duplicate, merge the declarations into one file or split them into distinct constants'
     end
 
@@ -1485,6 +1557,31 @@ module Woods
       Rails.logger.info "[Woods] Precomputed #{flow_map.size} request flows"
     end
 
+    # Withdraw the derived family in this unpublished payload. Atomic unit
+    # replacement preserves hardlinked bytes in the preceding generation.
+    # @return [Boolean] whether disabling precomputation changed the payload
+    def withdraw_disabled_flows
+      flows = payload_dir.join('flows')
+      changed = flows.exist?
+      FileUtils.remove_entry(flows) if changed
+      controllers = payload_dir.join('controllers')
+      return changed unless controllers.directory?
+
+      annotated = false
+      controllers.children.sort.each do |file|
+        next unless file.extname == '.json' && file.basename.to_s != '_index.json'
+
+        data = JSON.parse(AtomicFile.read(file))
+        next unless data.fetch('metadata', {}).key?('flow_paths')
+
+        data['metadata'].delete('flow_paths')
+        AtomicFile.write(file, json_serialize(data), durable: payload_writes_durable?)
+        annotated = true
+      end
+      regenerate_type_index(:controllers) if annotated
+      changed || annotated
+    end
+
     # Precompute runs after write_results (FlowAssembler reads unit JSON
     # from disk), so units annotated in memory with metadata[:flow_paths]
     # must be re-written and their type index refreshed to pick up the
@@ -1789,8 +1886,10 @@ module Woods
         next if %i[rails_source gem_source].include?(type)
 
         units.each do |unit|
-          path = unit.file_path
-          file_paths << path if git_enrichable_path?(path, root)
+          SourceContributors.paths(unit).each do |source|
+            path = File.expand_path(source, Rails.root)
+            file_paths << path if git_enrichable_path?(path, root)
+          end
         end
       end
 
@@ -1804,8 +1903,12 @@ module Woods
         units.each do |unit|
           next unless unit.file_path
 
-          relative = unit.file_path.sub(root, '')
-          unit.metadata[:git] = git_data[relative] if git_data[relative]
+          if SourceContributors.multiple?(unit)
+            SourceContributors.annotate_git(unit, git_data)
+          else
+            relative = unit.file_path.sub(root, '')
+            unit.metadata[:git] = git_data[relative] if git_data[relative]
+          end
         end
       end
     end
@@ -1881,7 +1984,7 @@ module Woods
     def annotate_package(unit)
       return nil if %i[rails_source gem_source].include?(unit.type) || unit.file_path.nil?
 
-      package = package_resolver.package_for(unit.file_path)
+      package = SourceContributors.annotate_package(unit, package_resolver)
       if package
         unit.metadata[:package] = package
       else
@@ -1937,15 +2040,17 @@ module Woods
       relative_path = data['file_path']
       return nil if relative_path.nil? || relative_path.start_with?('/')
 
-      package = package_resolver.package_for(relative_path)
       metadata = (data['metadata'] ||= {})
-      return nil if metadata['package'] == package
+      before = JSON.generate(metadata)
+      package = SourceContributors.annotate_package(data, package_resolver)
 
       if package
         metadata['package'] = package
       else
         metadata.delete('package')
       end
+      return nil if JSON.generate(metadata) == before
+
       AtomicFile.write(file, json_serialize(data), durable: payload_writes_durable?)
 
       identifier = data['identifier']
@@ -1992,10 +2097,9 @@ module Woods
     # time, so the fsync is the cost being avoided here; the comparison read is
     # cheaper than the write it replaces.
     #
-    # Only the *write* is skipped. Graph registration, the dependents marking
-    # and `@incremental_written` all still happen for every unit, because those
-    # are what equivalence and the git-enrichment pass depend on — skipping any
-    # of them would make an unchanged unit differ from a full extraction.
+    # This helper skips only the write. Incremental registration separately
+    # checks complete serialized equality before marking dependents or Git work;
+    # differences in those derived fields still require the normal finalization.
     #
     # Compared as bytes: `AtomicFile.write` is binmode, and the encoding a read
     # comes back tagged with depends on the process's default external encoding
@@ -2464,7 +2568,13 @@ module Woods
     #
     # @return [Hash{Symbol => Hash}] type => `{ count:, chunks:, namespaces: }`
     def persisted_index_stats
-      @persisted_index_stats ||= Dir[payload_dir.join('*/_index.json').to_s].each_with_object({}) do |path, stats|
+      return @persisted_index_stats if @persisted_index_stats
+
+      directories = payload_dir.directory? ? payload_dir.children.sort : []
+      paths = directories.filter_map do |directory|
+        directory.join('_index.json') if directory.directory? && directory.join('_index.json').file?
+      end
+      @persisted_index_stats ||= paths.each_with_object({}) do |path, stats|
         entries = JSON.parse(AtomicFile.read(path))
         stats[File.basename(File.dirname(path)).to_sym] = {
           count: entries.size,
@@ -2664,8 +2774,8 @@ module Woods
       @persisted_index_stats = nil
 
       # Scan existing unit JSON files (exclude _index.json)
-      index = Dir[type_dir.join('*.json')].filter_map do |file|
-        next if File.basename(file) == '_index.json'
+      index = type_dir.children.sort.filter_map do |file|
+        next unless file.extname == '.json' && file.basename.to_s != '_index.json'
 
         data = JSON.parse(AtomicFile.read(file))
         {
@@ -2780,6 +2890,7 @@ module Woods
 
       @incremental_extractors[key] = EXTRACTORS[key]&.new
     rescue StandardError => e
+      (@failed_consumers ||= Set.new).add(key)
       @source_inputs&.unverified("extractor:#{key}")
       Rails.logger.warn "[Woods] Could not build #{key} extractor: #{e.message}"
       @incremental_extractors[key] = nil
@@ -2798,6 +2909,18 @@ module Woods
         end
     end
 
+    # Runtime metadata can depend on Ruby outside a class's definition or its
+    # recorded graph edges (for example, queue_as Settings::QUEUE). A Ruby edit
+    # therefore refreshes both complete hybrid inventories after Rails reload.
+    # Non-Ruby batches retain the narrower pre-change graph selection.
+    def hybrid_discovery_keys(change_set, affected_ids)
+      return HYBRID_DISCOVERY_EXTRACTORS.to_set if change_set.absolute_paths.any? { |path| path.end_with?('.rb') }
+
+      affected_ids.flat_map { |id| @dependency_graph.node_types(id) }
+                  .filter_map { |type| TYPE_TO_EXTRACTOR_KEY[type] }
+                  .intersection(HYBRID_DISCOVERY_EXTRACTORS).to_set
+    end
+
     # Re-extract every file-based unit defined by the changed paths that still
     # exist on disk, and prune the ones those paths no longer define.
     #
@@ -2817,46 +2940,47 @@ module Woods
     # @param affected_types [Set<Symbol>] out-param of touched extractor keys
     # @return [Set<String>] identifiers written or removed
     def reconcile_changed_paths(change_set, affected_types)
-      dispatcher = PathDispatcher.new
+      batches = collect_changed_path_batches(change_set)
       touched = Set.new
 
-      change_set.existing_paths.each do |absolute_path|
-        rules = dispatcher.file_rules_for(change_set.relativize(absolute_path))
-        next if rules.empty?
+      with_changed_path_ownership(batches) do
+        batches.each do |absolute_path, rules, entries|
+          produced = Set.new
+          entries.each do |rule, units|
+            next unless units
 
-        produced = Set.new
-        # A rule whose extraction *raised* tells us nothing about what the path
-        # defines, so it must not license pruning what the path defined before.
-        raised = false
-        rules.each do |rule|
-          units = extract_with_rule(rule, absolute_path)
-          if units.nil?
-            raised = true
-            next
+            produced.merge(units.map { |unit| [unit.identifier, unit.type] })
+            touched.merge(register_and_write(rule.extractor_key, units, affected_types))
+            unless source_consumer_failed?(rule.extractor_key)
+              @source_inputs&.consume_file(rule.extractor_key, absolute_path)
+            end
           end
 
-          # (identifier, type) pairs, not bare identifiers: two rules can
-          # claim one path (policies/pundit_policies) and mint the same
-          # identifier for different unit types. When one of them stops
-          # producing, an identifier-keyed set would let the survivor shield
-          # the stale sibling-type node from the prune below (the #225 shape,
-          # one method over — CORE-1).
-          produced.merge(units.map { |unit| [unit.identifier, unit.type] })
-          touched.merge(register_and_write(rule.extractor_key, units, affected_types))
-          unless source_consumer_failed?(rule.extractor_key)
-            @source_inputs&.consume_file(rule.extractor_key,
-                                         absolute_path)
-          end
+          next if entries.any? { |_rule, units| units.nil? }
+
+          touched.merge(prune_path_leftovers(absolute_path, rules, produced, affected_types))
         end
+      end
+      touched
+    end
 
-        next if raised
+    # Collect every path before verifying ownership or mutating the graph.
+    # An empty successful result can release an owner; a failed/skipped rule
+    # provides no such evidence. Keep (identifier, type) pairs independent.
+    def collect_changed_path_batches(change_set)
+      dispatcher = PathDispatcher.new
+      change_set.existing_paths.filter_map do |absolute_path|
+        rules = dispatcher.file_rules_for(change_set.relativize(absolute_path))
+        rules = rules.reject { |rule| rule.extractor_key == :libs }
+        rules = rules.reject { |rule| @hybrid_discovery_keys&.include?(rule.extractor_key) }
+        next if rules.empty?
 
-        touched.merge(
-          prune_path_leftovers(absolute_path, rules, produced, affected_types)
-        )
+        entries = rules.map do |rule|
+          units = extract_with_rule(rule, absolute_path)
+          [rule, units && authoritative_module_units(units)]
+        end
+        [absolute_path, rules, entries]
       end
-
-      touched
     end
 
     # Run one {PathDispatcher::Rule} against one file.
@@ -2874,12 +2998,12 @@ module Woods
       # broken constructor licensed pruning every previously-registered unit
       # on every changed path of that type, with the generation bumped over
       # the loss. Construction failure tells us nothing about the path; only
-      # a genuinely constructed extractor that lacks the method earns the [].
+      # a completed supported extraction can establish the path's identities.
       if extractor.nil?
         source_consumer_failed?(rule.extractor_key, extractor)
         return nil
       end
-      return [] unless extractor.respond_to?(rule.method_name)
+      return nil unless extractor.respond_to?(rule.method_name)
 
       result = checked_extraction(rule.extractor_key, extractor) do
         if rule.extractor_key == :poros
@@ -2923,6 +3047,7 @@ module Woods
       @dependency_graph.units_for_path(absolute_path).each do |identifier, node_type|
         next if produced.include?([identifier, node_type])
         next unless covered_keys.include?(TYPE_TO_EXTRACTOR_KEY[node_type])
+        next if retain_partial_module?(identifier, node_type)
 
         removed.add(identifier) if remove_unit(identifier, affected_types, type: node_type)
       end
@@ -2957,6 +3082,9 @@ module Woods
         known = Array(spec[:types] || spec[:type])
                 .flat_map { |type| @dependency_graph.units_of_type(type) }.to_set
 
+        if key == :graphql
+          touched.merge(reconcile_graphql_classification(extractor, discovered, excluded, affected_types))
+        end
         touched.merge(add_discovered_classes(key, spec, discovered, known, excluded, affected_types))
         next if spec[:reconcile_removals] == false
 
@@ -2966,32 +3094,29 @@ module Woods
       touched
     end
 
-    # Runtime-only model mixins can enter or leave discovery when their
-    # includer changes, even if the mixin file itself is untouched.
-    # @param affected_types [Set<Symbol>]
-    # @return [Set<String>] Added or removed concern identifiers
-    def reconcile_model_mixins(affected_types)
-      extractor = extractor_for(:concerns)
-      return Set.new unless extractor.respond_to?(:runtime_model_mixins)
+    # A new schema can promote an unchanged object to a query root. All four
+    # GraphQL kinds share one payload filename, so withdraw the old typed owner
+    # before writing its replacement. An incomplete inventory cannot demote it.
+    def reconcile_graphql_classification(extractor, discovered, excluded, affected_types)
+      unless extractor.runtime_discovery_complete?
+        (@failed_consumers ||= Set.new).add(:graphql)
+        return Set.new
+      end
+      return Set.new unless @eager_load_complete
 
-      live = extractor.runtime_model_mixins
-      known = @dependency_graph.units_of_type(:concern).to_set
-      added = live.flat_map do |path, modules|
-        next [] if modules.all? { |mod| known.include?(mod.name) }
+      discovered.each_with_object(Set.new) do |klass, touched|
+        next if excluded.include?(klass.name)
 
-        Array(extractor.extract_model_mixin_file(path)).reject { |unit| known.include?(unit.identifier) }
-      end
-      touched = register_and_write(:concerns, added, affected_types)
-      return touched unless @eager_load_complete
+        previous = @dependency_graph.node_types(klass.name) & GRAPHQL_TYPES
+        expected = extractor.runtime_unit_type(klass)
+        next if previous.empty? || !expected || previous == [expected]
 
-      live_names = live.values.flatten.to_set(&:name)
-      known.each do |identifier|
-        path = @dependency_graph.node(identifier, type: :concern)[:file_path]
-        next if extractor.conventional_concern_path?(path) || live_names.include?(identifier)
+        unit = extractor.extract_from_runtime_type(klass)
+        source_consumer_failed?(:graphql, extractor)
+        next unless unit
 
-        touched.add(identifier) if remove_unit(identifier, affected_types, type: :concern)
+        touched.merge(register_and_write(:graphql, [unit], affected_types))
       end
-      touched
     end
 
     # Pruned class-based identifiers the tree still governs, and that the
@@ -3178,11 +3303,12 @@ module Woods
     # subject to the same eager-load gate the reconciler applies, see
     # {#remove_replaced_units}.
     #
-    # Fail closed (M8): the rescue exists so a re-run that learned nothing —
-    # `extract_all` itself raising — costs the run nothing. It must not swallow
-    # a failure that lands AFTER the replacement started mutating state a
-    # published generation would carry: {#register_and_write} registers the
-    # graph node before writing the unit file, and {#remove_unit_of_type} rm_f's
+    # A re-run that raises before mutation retains the previous units and
+    # records a failed consumer. The batch guard then refuses publication even
+    # if another extractor succeeded, so callers can retry the complete batch.
+    # Failures AFTER replacement starts mutating state abort immediately:
+    # {#register_and_write} registers the graph node before writing the unit
+    # file, and {#remove_unit_of_type} rm_f's
     # the file before dropping the graph node, so a raise in either window
     # leaves the graph and the payload directory disagreeing. Swallowed, the run
     # went on to publish a generation whose dependency_graph.json held nodes
@@ -3200,9 +3326,10 @@ module Woods
     # then fails before changing anything. And the counter is reset BEFORE
     # `extract_all`, not after: {#register_and_write} is shared with the
     # reconcile paths that run earlier in the same pass, and one of those
-    # leaving the counter positive must not turn a later, mutation-free
-    # wholesale failure into an abort — only the current key's wholesale pass
-    # contributes to the decision.
+    # leaving the counter positive must not misreport a later, mutation-free
+    # failure as a half-written replacement. Only the current key's wholesale
+    # pass contributes to the immediate-abort decision; either failure still
+    # prevents the batch from publishing.
     #
     # @param key [Symbol] extractor key
     # @param affected_types [Set<Symbol>]
@@ -3210,6 +3337,8 @@ module Woods
     # @raise [Woods::ExtractionError] when the replacement failed after
     #   mutating durable state
     def replace_type_wholesale(key, affected_types)
+      return @library_replacement_touched if key == :libs && @library_replacement_touched
+
       extractor = extractor_for(key)
       if extractor.nil?
         source_consumer_failed?(key, extractor)
@@ -3221,13 +3350,16 @@ module Woods
       result = checked_extraction(key, extractor) { extractor.extract_all }
       return Set.new if SourceInputs::ConsumerErrors.failed?(extractor)
 
-      units = Array(result).compact.uniq(&:identifier)
+      units = authoritative_module_units(deduplicate_type_units(key, Array(result).compact))
       Rails.logger.info "[Woods] Re-ran #{key} wholesale: #{units.size} units"
 
-      touched = register_and_write(key, units, affected_types)
+      touched = with_replacement_ownership(key) { register_and_write(key, units, affected_types) }
       touched.merge(remove_replaced_units(key, units, affected_types))
-      @source_inputs&.consume_extractor(key, units) unless source_consumer_failed?(key, extractor)
+      consume_module_aware_refresh(key, units) unless source_consumer_failed?(key, extractor)
+      @library_replacement_touched = touched if key == :libs
       touched
+    rescue IdentityCollisionError
+      raise
     rescue StandardError => e
       if @wholesale_mutations.to_i.positive?
         raise Woods::ExtractionError, <<~MSG.tr("\n", ' ').strip
@@ -3240,6 +3372,7 @@ module Woods
         MSG
       end
 
+      (@failed_consumers ||= Set.new).add(key)
       @source_inputs&.unverified("extractor:#{key}")
       Rails.logger.error "[Woods] Wholesale re-run of #{key} failed: #{e.message}"
       Set.new
@@ -3315,7 +3448,7 @@ module Woods
     # @param affected_types [Set<Symbol>]
     # @return [Set<String>] identifiers removed
     def remove_replaced_units(key, units, affected_types)
-      if CLASS_BASED_DISCOVERY.key?(key) && !@eager_load_complete
+      unless replacement_discovery_complete?(key)
         Rails.logger.warn(
           "[Woods] Skipping stale-unit removal for #{key}: the eager load was incomplete, " \
           'so its discovery set is known-partial — the type may hold stale units until a clean boot'
@@ -3326,6 +3459,8 @@ module Woods
       EXTRACTOR_KEY_TO_TYPES.fetch(key, []).each_with_object(Set.new) do |unit_type, removed|
         fresh = units.select { |u| u.type == unit_type }.to_set(&:identifier)
         (@dependency_graph.units_of_type(unit_type) - fresh.to_a).each do |stale|
+          next if retain_partial_module?(stale, unit_type)
+
           removed.add(stale) if remove_unit(stale, affected_types, type: unit_type)
         end
       end
@@ -3480,15 +3615,23 @@ module Woods
     # @param affected_types [Set<Symbol>]
     # @return [Set<String>] identifiers written
     def register_and_write(extractor_key, units, affected_types)
-      units = Array(units).compact
+      units = authoritative_module_units(deduplicate_type_units(extractor_key, Array(units).compact))
       return Set.new if units.empty?
 
-      affected_types&.add(extractor_key)
+      verify_identity_claims!(units)
+      withdraw_previous_graphql_kinds(units, affected_types) if extractor_key == :graphql
       type_dir = payload_dir.join(extractor_key.to_s)
       FileUtils.mkdir_p(type_dir)
 
       units.each_with_object(Set.new) do |unit, written|
         annotate_package(unit)
+        unless source_consumer_failed?(extractor_key)
+          SourceContributors.paths(unit).each { |path| @source_inputs&.consume_unit(extractor_key, path) }
+        end
+        (@source_reference_refreshed ||= Set.new).add([unit.type.to_s, unit.identifier])
+        next if unchanged_registered_unit?(type_dir, unit)
+
+        affected_types&.add(extractor_key)
         mark_dependents_dirty(unit.identifier)
         # Marked BEFORE registration: DependencyGraph#register inserts the
         # node before it iterates the unit's dependencies, so a malformed
@@ -3506,11 +3649,52 @@ module Woods
         (@incremental_written ||= {})[unit.identifier] = unit.file_path
 
         write_unit_file(type_dir.join(collision_safe_filename(unit.identifier)), unit)
-        @source_inputs&.consume_unit(extractor_key, unit.file_path) unless source_consumer_failed?(extractor_key)
         written.add(unit.identifier)
       end
     end
 
+    # Only exact serialized equality (apart from the extraction timestamp)
+    # permits skipping graph and enrichment work. Derived metadata or changed
+    # edges keep the ordinary registration path; identity checks already ran.
+    def unchanged_registered_unit?(type_dir, unit)
+      return false unless @dependency_graph.node(unit.identifier, type: unit.type)
+
+      normalized = unit.dup
+      normalized.file_path = normalize_file_path(unit.file_path)
+      identical_on_disk?(type_dir.join(collision_safe_filename(unit.identifier)), json_serialize(normalized.to_h))
+    end
+
+    # GraphQL kinds share a payload filename. Validate retained source ownership
+    # for the whole batch, then remove old kinds before any replacement write.
+    # This covers discovery, changed-file dispatch, and targeted refresh alike.
+    def withdraw_previous_graphql_kinds(units, affected_types)
+      replacements = units.flat_map do |unit|
+        current = identity_source(unit.file_path)
+        GRAPHQL_TYPES.each do |type|
+          key = [type, unit.identifier]
+          next unless @identity_claims.key?(key) && @identity_claims[key] != current
+
+          reject_identity_collision!(unit, @identity_claims[key])
+        end
+        previous = (@dependency_graph.node_types(unit.identifier) & GRAPHQL_TYPES) - [unit.type]
+        previous.map do |type|
+          prior = identity_source(@dependency_graph.node(unit.identifier, type: type)[:file_path])
+          unless Array(@authoritative_replacement_types).include?(unit.type) ||
+                 prior == current || confirmed_source_move?(prior, current)
+            reject_identity_collision!(unit, prior)
+          end
+          [unit.identifier, type]
+        end
+      end
+      if replacements.any? && !@eager_load_complete
+        (@failed_consumers ||= Set.new).add(:graphql)
+        raise Woods::ExtractionError,
+              'GraphQL classification changed during an incomplete eager load; retry after a complete application boot'
+      end
+
+      replacements.each { |identifier, type| remove_unit(identifier, affected_types, type: type) }
+    end
+
     # Remove a unit from the graph and delete its JSON from the index.
     #
     # Callers that know which type they mean must say so. An identifier can
@@ -3648,7 +3832,10 @@ module Woods
       end
 
       git = git_data && git_for_type(identifier, type, git_data)
-      if git
+      if git_data && SourceContributors.multiple?(data)
+        SourceContributors.annotate_git(data, git_data)
+        @dependency_graph.annotate(identifier, type: type, commit_count: nil, change_frequency: nil)
+      elsif git
         (data['metadata'] ||= {})['git'] = JSON.parse(JSON.generate(git))
         annotate_node_from_git(identifier, type, git)
       end
@@ -3709,10 +3896,10 @@ module Woods
 
       root = "#{Rails.root}/"
       paths = identifiers.flat_map do |identifier|
-        @dependency_graph.nodes_for(identifier).filter_map do |node|
-          next if %i[rails_source gem_source].include?(node[:type])
+        @dependency_graph.nodes_for(identifier).flat_map do |node|
+          next [] if %i[rails_source gem_source].include?(node[:type])
 
-          node[:file_path] if git_enrichable_path?(node[:file_path], root)
+          (node[:source_paths] || Array(node[:file_path])).select { |path| git_enrichable_path?(path, root) }
         end
       end
 
@@ -3757,6 +3944,11 @@ module Woods
     # @param affected_types [Set<Symbol>, nil]
     # @return [String, nil] the identifier when this type was re-extracted and written
     def re_extract_unit_of_type(unit_id, type, affected_types)
+      if type == :lib
+        touched = replace_type_wholesale(:libs, affected_types)
+        return touched.include?(unit_id) ? unit_id : nil
+      end
+
       node = @dependency_graph.node(unit_id, type: type)
       file_path = node && node[:file_path]
 
@@ -3765,6 +3957,7 @@ module Woods
 
       extractor_key = TYPE_TO_EXTRACTOR_KEY[type]
       return nil unless extractor_key
+      return nil if @hybrid_discovery_keys&.include?(extractor_key)
 
       extractor = extractor_for(extractor_key)
       if extractor.nil?
@@ -3780,17 +3973,21 @@ module Woods
       units = Array(result).compact
       return nil if units.empty?
 
-      register_and_write(extractor_key, units, affected_types)
-      unit_id
+      written = register_and_write(extractor_key, units, affected_types)
+      unit_id if written.include?(unit_id)
     end
 
     # Dispatch one re-extraction to the right extractor entry point.
     #
     # @return [ExtractedUnit, Array<ExtractedUnit>, nil]
     def re_extracted_units(extractor, type, unit_id, file_path, extractor_key)
-      if (method = CLASS_BASED[type])
+      if type == :configuration && unit_id == 'BehavioralProfile'
+        extractor.extract_behavioral_profile
+      elsif (method = CLASS_BASED[type])
         klass = constant_for_identifier(unit_id)
         klass && extractor.public_send(method, klass)
+      elsif runtime_model_mixin_file?(extractor, type, file_path)
+        extractor.extract_model_mixin_file(file_path)
       elsif (method = FILE_BASED[type])
         units = Array(extract_file_based_unit(extractor, method, file_path, extractor_key)).compact
         return units unless CLASS_DISCOVERED_FALLBACK.key?(type)