woods 2.0.0.beta1 → 2.0.0.beta3

data/lib/woods/extractor.rb

@@ -8,12 +8,14 @@ require 'pathname'
 require 'set'
 
 require_relative 'atomic_file'
+require_relative 'version'
 require_relative 'filename_utils'
 require_relative 'token_utils'
 require_relative 'extracted_unit'
 require_relative 'dependency_graph'
 require_relative 'payload_store'
 require_relative 'git_provenance'
+require_relative 'git_history'
 require_relative 'extractors/model_extractor'
 require_relative 'extractors/controller_extractor'
 require_relative 'extractors/phlex_extractor'
@@ -55,6 +57,7 @@ require_relative 'flow_precomputer'
 require_relative 'change_set'
 require_relative 'generation'
 require_relative 'path_dispatcher'
+require_relative 'source_inputs/session'
 
 module Woods
   # Extractor is the main orchestrator for codebase extraction.
@@ -355,7 +358,7 @@ 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 dependency_graph.json graph_analysis.json SUMMARY.md].freeze
+    PAYLOAD_FILES = %w[manifest.json source_inputs.json dependency_graph.json graph_analysis.json SUMMARY.md].freeze
 
     # Payload directories that are not per-type unit directories.
     PAYLOAD_DIRS = %w[flows].freeze
@@ -394,7 +397,9 @@ module Woods
     #
     # @return [Hash] Results keyed by extractor type
     def extract_all
+      profile_started = Process.clock_gettime(Process::CLOCK_MONOTONIC) if profiling?
       setup_output_directory
+      profile_phase('source capture') { begin_source_inputs('full') }
       ModelNameCache.reset!
       # @package_resolver alone is not enough: #package_resolver builds
       # through #extractor_for, which memoizes into @incremental_extractors.
@@ -404,61 +409,69 @@ module Woods
       # package added between the two runs.
       @package_resolver = nil
       @incremental_extractors = nil
-      begin_payload!
+      @persisted_index_stats = nil
+      @graph_sha = nil
+      profile_phase('payload seed') { begin_payload! }
 
       # Eager load once — all extractors need loaded classes for introspection.
-      safe_eager_load!
+      profile_phase('eager load') { safe_eager_load! }
 
       # Phase 1: Extract all units
-      if Woods.configuration.concurrent_extraction
-        extract_all_concurrent
-      else
-        extract_all_sequential
+      profile_phase('extraction') do
+        if Woods.configuration.concurrent_extraction
+          extract_all_concurrent
+        else
+          extract_all_sequential
+        end
       end
 
       # Phase 1.5: Deduplicate results
       Rails.logger.info '[Woods] Deduplicating results...'
-      deduplicate_results
+      profile_phase('deduplication') { deduplicate_results }
 
       # Phase 1.6: Package membership. Runs before the graph is rebuilt so
       # registration copies metadata[:package] onto the node (#280).
-      annotate_packages
+      profile_phase('package annotation') { annotate_packages }
 
       # Rebuild the graph from deduped results. #164 gave DependencyGraph
       # `#remove`/`#unregister`, so surgical removal is now possible — but a
       # full extraction has just registered every unit including duplicates,
       # and rebuilding from the deduped set is both cheaper and less
       # error-prone than unwinding registrations one at a time.
-      @dependency_graph = DependencyGraph.new
-      @results.each_value { |units| units.each { |u| @dependency_graph.register(u) } }
+      profile_phase('graph rebuild') do
+        @dependency_graph = DependencyGraph.new
+        @results.each_value { |units| units.each { |u| @dependency_graph.register(u) } }
+      end
 
       # Phase 2: Resolve dependents (reverse dependencies)
       Rails.logger.info '[Woods] Resolving dependents...'
-      resolve_dependents
+      profile_phase('dependents') { resolve_dependents }
 
       # Phase 3: Enrich with git data. Runs BEFORE analysis now: the
       # volatile_dependencies report reads commit counts off graph nodes.
       Rails.logger.info '[Woods] Enriching with git data...'
-      enrich_with_git_data
-      annotate_graph_with_git_data
+      profile_phase('git enrichment') do
+        enrich_with_git_data
+        annotate_graph_with_git_data
+      end
 
       # Phase 4: Graph analysis (PageRank, structural metrics)
       Rails.logger.info '[Woods] Analyzing dependency graph...'
-      @graph_analysis = build_graph_analyzer.analyze
+      @graph_analysis = profile_phase('graph analysis') { build_graph_analyzer.analyze }
 
       # Phase 4.5: Normalize file_path to relative paths
       Rails.logger.info '[Woods] Normalizing file paths...'
-      normalize_file_paths
+      profile_phase('path normalization') { normalize_file_paths }
 
       # Phase 5: Write output
       Rails.logger.info '[Woods] Writing output...'
-      write_results
+      profile_phase('write results') { write_results }
 
       # Phase 5.1: Sweep unit files no current unit accounts for (#177). Must
       # run after write_results — the just-written set is what defines
       # "legitimate" — and belongs to the full path only; the incremental path
       # deletes through the graph instead. See {#sweep_orphaned_unit_files}.
-      sweep_orphaned_unit_files
+      profile_phase('orphan sweep') { sweep_orphaned_unit_files }
 
       # Phase 5.5: Precompute request flows (opt-in). Must run AFTER
       # write_results — FlowAssembler loads unit JSON from disk, so running
@@ -478,19 +491,26 @@ module Woods
       # being opt-in does not excuse it.
       if Woods.configuration.precompute_flows
         Rails.logger.info '[Woods] Precomputing request flows...'
-        precompute_flows
+        profile_phase('flows') { precompute_flows }
       end
 
-      write_dependency_graph
-      write_graph_analysis
-      write_manifest
-      write_structural_summary
-      capture_snapshot
+      profile_phase('graph write') do
+        write_dependency_graph
+        write_graph_analysis
+      end
+      profile_phase('manifest and summary') do
+        write_manifest
+        write_structural_summary
+      end
+      profile_phase('snapshot') { capture_snapshot }
+      @source_inputs.full_units(@results, consumers: @extractors)
       publish_generation('full')
 
       log_summary
 
       @results
+    ensure
+      log_profile_total('full', profile_started)
     end
 
     # ══════════════════════════════════════════════════════════════════════
@@ -522,62 +542,78 @@ module Woods
     # @param changed_files [Array<String>] List of changed file paths
     # @return [Array<String>] Identifiers of units re-extracted, added, or removed
     def extract_changed(changed_files)
-      prepare_incremental_run
+      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)
       affected_types = Set.new
 
-      # Blast radius from the pre-change graph.
-      affected_ids = @dependency_graph.affected_by(change_set.absolute_paths)
+      # Blast radius from the pre-change graph, bounded by
+      # `incremental_blast_radius_depth` (nil = the unbounded closure).
+      affected_ids = profile_phase('blast radius') do
+        @dependency_graph.affected_by(change_set.absolute_paths, max_depth: blast_radius_depth)
+      end
+      @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"
 
-      touched = reconcile_changed_paths(change_set, affected_types)
-
-      (affected_ids - touched.to_a).each do |unit_id|
-        touched.add(unit_id) if re_extract_unit(unit_id, affected_types: affected_types)
-      end
+      touched = profile_phase('re-extraction') do
+        acc = reconcile_changed_paths(change_set, affected_types)
 
-      touched.merge(reconcile_class_based_types(affected_types))
-      touched.merge(rerun_whole_app_extractors(change_set, affected_types))
-      touched.merge(reannotate_packages(change_set, affected_types))
-      pruned = prune_vanished_units(change_set, affected_types)
-      touched.merge(pruned)
+        (affected_ids - acc.to_a).each do |unit_id|
+          acc.add(unit_id) if re_extract_unit(unit_id, affected_types: affected_types)
+        end
 
-      # Reconcile once more, because pruning can un-know a class the first pass
-      # skipped. A class-based file moved between autoload directories with its
-      # constant unchanged is still registered under the old path when
-      # reconciliation runs, so it looks known and is not re-extracted; the
-      # prune that follows then removes it for its vanished path. This pass
-      # re-adds it in the same run (M1) instead of leaving the unit missing
-      # until some later run happens to notice. Idempotent when nothing was
-      # pruned: the discovery set is compared against the graph, so an
-      # already-registered class is skipped.
-      #
-      # But not everything pruning removed may come back. `except:` keeps the
-      # *deletion* shape pruned: without a reload, a constant outlives the file
-      # that defined it — so deleting `app/models/user.rb` prunes `User`, and
-      # this pass finds `User` still in `ActiveRecord::Base.descendants`.
-      # Re-registering it would pin the unit to a path that no longer exists,
-      # and nothing could ever remove it: the sweep excludes class-based units
-      # and no future change set names that path again. A resident daemon
-      # processing a batch before its reload hits this every time. What
-      # separates the two shapes is the filesystem — only pruned identifiers
-      # that a still-existing file in the change set actually declares are
-      # re-addable. See {#readdable_pruned_classes}.
-      touched.merge(reconcile_class_based_types(
-                      affected_types, except: pruned - readdable_pruned_classes(pruned, change_set)
-                    ))
+        acc
+      end
+
+      profile_phase('reconciliation') do
+        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))
+        touched.merge(reannotate_packages(change_set, affected_types))
+        pruned = prune_vanished_units(change_set, affected_types)
+        touched.merge(pruned)
+
+        # Reconcile once more, because pruning can un-know a class the first pass
+        # skipped. A class-based file moved between autoload directories with its
+        # constant unchanged is still registered under the old path when
+        # reconciliation runs, so it looks known and is not re-extracted; the
+        # prune that follows then removes it for its vanished path. This pass
+        # re-adds it in the same run (M1) instead of leaving the unit missing
+        # until some later run happens to notice. Idempotent when nothing was
+        # pruned: the discovery set is compared against the graph, so an
+        # already-registered class is skipped.
+        #
+        # But not everything pruning removed may come back. `except:` keeps the
+        # *deletion* shape pruned: without a reload, a constant outlives the file
+        # that defined it — so deleting `app/models/user.rb` prunes `User`, and
+        # this pass finds `User` still in `ActiveRecord::Base.descendants`.
+        # Re-registering it would pin the unit to a path that no longer exists,
+        # and nothing could ever remove it: the sweep excludes class-based units
+        # and no future change set names that path again. A resident daemon
+        # processing a batch before its reload hits this every time. What
+        # separates the two shapes is the filesystem — only pruned identifiers
+        # that a still-existing file in the change set actually declares are
+        # re-addable. See {#readdable_pruned_classes}.
+        touched.merge(reconcile_class_based_types(
+                        affected_types, except: pruned - readdable_pruned_classes(pruned, change_set)
+                      ))
+      end
 
       finalize_incremental_unit_json(affected_types)
 
       # Regenerate type indexes for affected types
-      affected_types.each do |type_key|
-        regenerate_type_index(type_key)
+      profile_phase('type index') do
+        affected_types.each do |type_key|
+          regenerate_type_index(type_key)
+        end
       end
 
       finalize_incremental_run(touched)
 
       touched.to_a
+    ensure
+      log_profile_total('incremental', profile_started)
     end
 
     # ══════════════════════════════════════════════════════════════════════
@@ -612,6 +648,7 @@ module Woods
     #   extractor
     # @raise [ArgumentError] when no recognized key is given
     def refresh(*keys)
+      profile_started = Process.clock_gettime(Process::CLOCK_MONOTONIC) if profiling?
       keys = Array(keys).flatten.map(&:to_sym).uniq
       known, unknown = keys.partition { |key| EXTRACTORS.key?(key) }
       raise ArgumentError, "No known extractor in #{keys.inspect}" if known.empty?
@@ -619,17 +656,19 @@ module Woods
       known += ROUTE_CONSUMER_EXTRACTORS if known.include?(:routes)
       known.uniq!
 
-      prepare_incremental_run
+      prepare_incremental_run(operation: 'refresh')
       affected_types = Set.new
       touched = known.each_with_object(Set.new) do |key, acc|
         acc.merge(replace_type_wholesale(key, affected_types))
       end
 
       finalize_incremental_unit_json(affected_types)
-      affected_types.each { |type_key| regenerate_type_index(type_key) }
+      profile_phase('type index') { affected_types.each { |type_key| regenerate_type_index(type_key) } }
       finalize_incremental_run(touched, reason: "refresh:#{known.sort.join(',')}")
 
       { types: known, touched: touched.to_a, unknown: unknown }
+    ensure
+      log_profile_total('refresh', profile_started)
     end
 
     # Raise when the most recent extraction run wrote a payload but could not
@@ -651,6 +690,80 @@ module Woods
 
     private
 
+    # Whole-run wall time, including unprofiled setup and failed runs. This
+    # separate log family must never be added to the individual phase times.
+    def log_profile_total(name, started)
+      return unless started
+
+      elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - started
+      Rails.logger.info "[Woods] [profile total] #{name} in #{elapsed.round(2)}s"
+    end
+
+    # Time one phase of a run and log how long it took, when WOODS_PROFILE=1.
+    #
+    # The per-extractor lines (see {#extract_all_sequential}) already report
+    # extraction itself. Everything after it (the graph load, the analysis,
+    # the flows, the publish) was unattributed, so a slow run could only be
+    # split by guessing. Off by default and free when off: the block is
+    # yielded directly, with no timing and no log line. Timed on the
+    # monotonic clock, so a wall-clock adjustment mid-run cannot produce a
+    # negative phase.
+    #
+    # @param name [String] phase name, as it appears in the log line
+    # @return [Object] whatever the block returned
+    def profile_phase(name)
+      return yield unless profiling?
+
+      start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      result = yield
+      elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
+      Rails.logger.info "[Woods] [profile] #{name} in #{elapsed.round(2)}s"
+      result
+    end
+
+    # How many reverse hops {#extract_changed} walks from the changed files
+    # before it stops re-extracting dependents.
+    #
+    # Unbounded by default. A unit outside the cap keeps its content, and the
+    # one derived field a re-extraction elsewhere can change (`dependents`)
+    # is refreshed regardless: {#register_and_write} marks every target of a
+    # re-extracted unit's edges, before and after registration, so a unit
+    # that gains or loses an inbound edge is rewritten by
+    # {#finalize_incremental_unit_json} whether or not the walk reached it.
+    #
+    # @return [Integer, nil]
+    def blast_radius_depth
+      Woods.configuration&.incremental_blast_radius_depth
+    end
+
+    # The units a controller's flow document could reach from this run's
+    # changed files, read off the pre-change graph.
+    #
+    # {FlowAssembler} stops expanding at {FlowPrecomputer::DEFAULT_MAX_DEPTH},
+    # so a controller further than that from everything the run changed
+    # assembles the same document it already has. The bound is the
+    # assembler's own constant, not a second literal: raising the assembly
+    # depth widens this walk with it.
+    #
+    # Reverse reachability is the same relation the refresh already rested on
+    # (`touched` is itself the graph's reverse closure), so this narrows the
+    # distance without changing the edge set behind the decision.
+    #
+    # @param change_set [Woods::ChangeSet]
+    # @return [Set<String>]
+    def flow_scope_for(change_set)
+      return Set.new unless Woods.configuration.precompute_flows
+
+      @dependency_graph.affected_by(
+        change_set.absolute_paths, max_depth: FlowPrecomputer::DEFAULT_MAX_DEPTH
+      ).to_set
+    end
+
+    # @return [Boolean] whether phase timing is enabled for this process
+    def profiling?
+      ENV.fetch('WOODS_PROFILE', nil) == '1'
+    end
+
     # Load the persisted graph and reset the per-run bookkeeping that the
     # incremental helpers read. Shared by {#extract_changed} and {#refresh};
     # calling either without this leaves `@dependents_dirty` and
@@ -664,20 +777,29 @@ module Woods
     #
     # @return [void]
     # @raise [Woods::ExtractionError] see {#begin_payload!}
-    def prepare_incremental_run
-      begin_payload!(strict: true)
+    def prepare_incremental_run(operation: 'incremental')
+      profile_phase('source capture') { begin_source_inputs(operation) }
+      profile_phase('payload seed') { begin_payload!(strict: true) }
       graph_path = payload_dir.join('dependency_graph.json')
       ensure_incremental_baseline!(graph_path)
-      @dependency_graph = DependencyGraph.from_h(JSON.parse(AtomicFile.read(graph_path))) if graph_path.exist?
+      profile_phase('previous graph load') do
+        @dependency_graph = DependencyGraph.from_h(JSON.parse(AtomicFile.read(graph_path))) if graph_path.exist?
+      end
 
       ModelNameCache.reset!
-      safe_eager_load!
+      profile_phase('eager load') { safe_eager_load! }
 
       @dependents_dirty = Set.new
       @incremental_written = {}
+      # 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
       @active_record_names = nil
       @package_resolver = nil
+      @persisted_index_stats = nil
+      @graph_sha = nil
     end
 
     # Write the graph and the derived artifacts after an incremental run.
@@ -706,17 +828,19 @@ module Woods
     #   reading "incremental" after a `woods:refresh[routes]` is being misled
     # @return [void]
     def finalize_incremental_run(touched, reason: 'incremental')
-      write_dependency_graph
+      profile_phase('graph write') { write_dependency_graph }
 
       if touched.empty?
         Rails.logger.info '[Woods] Incremental run changed nothing — leaving manifest timestamp untouched'
         return
       end
 
-      write_incremental_graph_analysis
-      refresh_incremental_flows(touched)
-      write_manifest(incremental: true)
-      write_structural_summary
+      profile_phase('graph analysis') { write_incremental_graph_analysis }
+      profile_phase('flows') { refresh_incremental_flows(touched) }
+      profile_phase('manifest and summary') do
+        write_manifest(incremental: true)
+        write_structural_summary
+      end
       publish_generation(reason)
 
       return unless Woods.configuration.enable_snapshots
@@ -737,8 +861,13 @@ module Woods
     # @return [void]
     def publish_generation(reason)
       generation = Generation.new(output_dir: @output_dir)
-      marker = generation.bump!(reason: reason, payload: publishable_payload_name(generation))
-      prune_payloads(marker.number)
+      # Resolve (and if necessary rename) the payload first, so the flush
+      # below covers the directory under the name the pointer will carry.
+      payload = publishable_payload_name(generation)
+      profile_phase('source verification') { write_source_inputs } if payload
+      profile_phase('payload sync') { sync_payload }
+      marker = profile_phase('publish') { generation.bump!(reason: reason, payload: payload) }
+      profile_phase('payload prune') { prune_payloads(marker.number) }
       marker
     rescue StandardError => e
       # A failed bump must not fail the extraction that produced a perfectly
@@ -757,6 +886,38 @@ module Woods
       nil
     end
 
+    # Capture before eager loading or extraction; only an explicit fresh-launch
+    # handoff can additionally establish the pre-Bundler/Rails boot boundary.
+    def begin_source_inputs(operation)
+      @source_inputs = SourceInputs::Session.new(root: Rails.root, output_dir: @output_dir,
+                                                 baseline_path: source_input_baseline_path,
+                                                 operation: operation)
+    end
+
+    def source_input_baseline_path
+      generation = Generation.new(output_dir: @output_dir)
+      marker = generation.current
+      directory = generation.payload_dir(marker)
+      return nil unless marker.payload && directory != generation.root
+
+      directory.join(SourceInputs::Manifest::FILE_NAME)
+    rescue TypeError, NoMethodError
+      nil
+    end
+
+    def source_consumer_failed?(key, consumer = extractor_for(key))
+      failed = consumer.nil? || SourceInputs::ConsumerErrors.failed?(consumer)
+      @source_inputs&.unverified("extractor:#{key}") if failed
+      failed
+    end
+
+    def write_source_inputs
+      return unless @source_inputs
+
+      manifest = @source_inputs.finish(generation: @payload_generation, eager_load_complete: @eager_load_complete)
+      AtomicFile.write(payload_dir.join(SourceInputs::Manifest::FILE_NAME), JSON.pretty_generate(manifest.data))
+    end
+
     # Open the payload directory this run publishes into, seeded from the
     # generation currently on disk.
     #
@@ -893,6 +1054,47 @@ module Woods
       EXTRACTORS.keys.map(&:to_s) + PAYLOAD_DIRS
     end
 
+    # Whether payload files pay for their own durability as they are written.
+    #
+    # False by default and false on every host that has not asked otherwise:
+    # {#sync_payload} makes the whole payload durable in one flush before the
+    # pointer names it, so a per-file fsync buys only the window in which
+    # nothing can read the file anyway. `durable_payload_writes = true`
+    # restores the per-file cost for a host that wants it; it does not, and
+    # cannot, remove the publish flush.
+    #
+    # @return [Boolean]
+    def payload_writes_durable?
+      Woods.configuration&.durable_payload_writes ? true : false
+    end
+
+    # One filesystem flush that makes this run's whole payload durable,
+    # immediately before the pointer that names it is written durably.
+    #
+    # This is the guarantee that replaces the per-file fsync {#write_results}
+    # used to pay for every unit: **when `generation.json` is durable, every
+    # file in the payload it names is durable.** What is given up is an
+    # individual payload file being durable before the pointer exists, and
+    # nobody reads a payload file in that window: every reader resolves
+    # through the pointer, and a crash leaves an unreferenced partial payload
+    # that the next run prunes.
+    #
+    # Unconditional on purpose. `durable_payload_writes` decides whether the
+    # per-file fsyncs are *also* paid; it can never turn this off, because
+    # that would be the one change that actually weakens the contract.
+    # {Woods::AtomicFile.sync_directory_tree} degrades through `sync -f`, a
+    # bare `sync`, and finally a per-file fsync pass, so the flush cannot
+    # silently become a no-op either.
+    #
+    # A run that degraded to a flat publish has no payload directory;
+    # {#payload_dir} then returns the output directory, which is the tree that
+    # needs flushing in exactly the same way.
+    #
+    # @return [Symbol, nil] the strategy {Woods::AtomicFile} used
+    def sync_payload
+      AtomicFile.sync_directory_tree(payload_dir)
+    end
+
     # The pointer to publish, or nil when this run built no payload directory.
     #
     # The directory was named from the generation number this run expected to
@@ -1132,9 +1334,6 @@ module Woods
 
     def setup_output_directory
       FileUtils.mkdir_p(@output_dir)
-      EXTRACTORS.each_key do |type|
-        FileUtils.mkdir_p(payload_dir.join(type.to_s))
-      end
     end
 
     # ──────────────────────────────────────────────────────────────────────
@@ -1234,8 +1433,10 @@ module Woods
     def same_type_collision_message(type, unit, prior_path)
       "same-type identifier collision: #{type.to_s.singularize} '#{unit.identifier}' derived from " \
         "two different sources ('#{prior_path || 'no file'}' and '#{unit.file_path || 'no file'}'); " \
-        'only one unit could ever be indexed, so extraction aborted — either merge the ' \
-        'declarations into one file or split them into distinct constants'
+        '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. ' \
+        'For a genuine duplicate, merge the declarations into one file or split them into distinct constants'
     end
 
     # ──────────────────────────────────────────────────────────────────────
@@ -1279,12 +1480,14 @@ module Woods
         annotated.each do |unit|
           AtomicFile.write(
             type_dir.join(collision_safe_filename(unit.identifier)),
-            json_serialize(unit.to_h)
+            json_serialize(unit.to_h),
+            durable: payload_writes_durable?
           )
         end
         AtomicFile.write(
           type_dir.join('_index.json'),
-          json_serialize(type_index_entries(units))
+          json_serialize(type_index_entries(units)),
+          durable: payload_writes_durable?
         )
       end
     end
@@ -1329,12 +1532,16 @@ module Woods
       removed = previous_flow_index_controllers & (touched.to_set - reextracted.to_set)
       return if reextracted.empty? && removed.empty?
 
-      Rails.logger.info "[Woods] Refreshing flows for #{reextracted.size} controller(s), " \
-                        "#{removed.size} removed..."
+      reassemble, carried = partition_flow_controllers(
+        reextracted.filter_map { |id| unit_from_payload(:controllers, id) }
+      )
+      Rails.logger.info "[Woods] Refreshing flows for #{reassemble.size} controller(s), " \
+                        "#{carried.size} carried forward, #{removed.size} removed..."
       precomputer = FlowPrecomputer.new(units: [], graph: @dependency_graph, output_dir: payload_dir.to_s)
       annotations = precomputer.recompute_delta(
-        touched_units: reextracted.filter_map { |id| unit_from_payload(:controllers, id) },
-        removed_identifiers: removed.to_a
+        touched_units: reassemble,
+        removed_identifiers: removed.to_a,
+        carried_identifiers: carried.map(&:identifier)
       )
       patch_flow_annotations(annotations)
       sweep_orphaned_flow_files
@@ -1347,6 +1554,52 @@ module Woods
       regenerate_type_index(:controllers) if annotations.any?
     end
 
+    # Split the run's re-extracted controllers into the ones whose flow
+    # documents have to be reassembled and the ones that only need their
+    # annotation back.
+    #
+    # A controller is reassembled when the run changed something its flow can
+    # reach ({#flow_scope_for}), or when its own action set no longer matches
+    # the previous generation's index. The second test is what catches an
+    # action arriving from further up a controller inheritance chain than the
+    # flow radius reaches, and a controller the index has never seen.
+    #
+    # Without a scope (a targeted {#refresh}, or a routes re-run) everything
+    # is reassembled, which is what this path always did.
+    #
+    # @param units [Array<ExtractedUnit>] the run's re-extracted controllers
+    # @return [Array(Array<ExtractedUnit>, Array<ExtractedUnit>)]
+    def partition_flow_controllers(units)
+      return [units, []] if @flow_scope.nil?
+
+      previous = previous_flow_index_actions
+      units.partition do |unit|
+        @flow_scope.include?(unit.identifier) || flow_actions_of(unit) != previous[unit.identifier]
+      end
+    end
+
+    # The actions a unit's metadata declares, as the index records them.
+    #
+    # @param unit [ExtractedUnit]
+    # @return [Set<String>]
+    def flow_actions_of(unit)
+      Array(unit.metadata[:actions] || unit.metadata['actions']).to_set(&:to_s)
+    end
+
+    # The previous generation's flow index, grouped by controller.
+    #
+    # @return [Hash{String => Set<String>}] controller identifier to its
+    #   recorded action names, defaulting to an empty set
+    # @raise [Woods::ExtractionError] when the index is missing or corrupt
+    def previous_flow_index_actions
+      previous_flow_index_entries.keys.each_with_object(Hash.new { Set.new }) do |entry_point, grouped|
+        controller, action = entry_point.to_s.split('#', 2)
+        next unless action
+
+        grouped[controller] = grouped[controller] + [action]
+      end
+    end
+
     # Does the run's seeded payload hold a flow family at all? An absent
     # family (no flows/ directory, or an empty one) is a genuine absence —
     # typically an index built while the gate was off — and skips the
@@ -1372,11 +1625,21 @@ module Woods
     # @return [Set<String>]
     # @raise [Woods::ExtractionError] when the index is missing or corrupt
     def previous_flow_index_controllers
+      previous_flow_index_entries.keys.to_set { |entry_point| entry_point.to_s.split('#', 2).first }
+    end
+
+    # The previous generation's flow index itself, read once per run: both
+    # the removal set and the reassembly partition are derived from it.
+    #
+    # @return [Hash{String => String}] entry point to relative document path
+    # @raise [Woods::ExtractionError] when the index is missing or corrupt
+    def previous_flow_index_entries
+      return @previous_flow_index_entries if @previous_flow_index_entries
+
       index_path = payload_dir.join('flows', 'flow_index.json')
       raise Woods::ExtractionError, 'flows/ is populated but flow_index.json is missing' unless index_path.exist?
 
-      JSON.parse(AtomicFile.read(index_path))
-          .keys.to_set { |entry_point| entry_point.to_s.split('#', 2).first }
+      @previous_flow_index_entries = JSON.parse(AtomicFile.read(index_path))
     rescue JSON::ParserError => e
       raise Woods::ExtractionError, "previous flow_index.json does not parse: #{e.message}"
     end
@@ -1433,7 +1696,7 @@ module Woods
         end
         next if JSON.generate(data) == before
 
-        AtomicFile.write(path, json_serialize(data))
+        AtomicFile.write(path, json_serialize(data), durable: payload_writes_durable?)
       end
     end
 
@@ -1550,8 +1813,15 @@ module Woods
     #
     # @return [GraphAnalyzer]
     def build_graph_analyzer
-      ratio = Woods.configuration&.volatile_dependency_ratio || GraphAnalyzer::DEFAULT_VOLATILE_RATIO
-      GraphAnalyzer.new(@dependency_graph, volatile_ratio: ratio)
+      config = Woods.configuration
+      ratio = config&.volatile_dependency_ratio || GraphAnalyzer::DEFAULT_VOLATILE_RATIO
+      GraphAnalyzer.new(
+        @dependency_graph,
+        volatile_ratio: ratio,
+        volatile_limit_per_target: config&.volatile_dependency_limit_per_target,
+        cycle_limit: config ? config.graph_cycle_limit : GraphAnalyzer::DEFAULT_CYCLE_LIMIT,
+        cycle_max_length: config ? config.graph_cycle_max_length : GraphAnalyzer::DEFAULT_CYCLE_MAX_LENGTH
+      )
     end
 
     # ──────────────────────────────────────────────────────────────────────
@@ -1651,7 +1921,7 @@ module Woods
       else
         metadata.delete('package')
       end
-      AtomicFile.write(file, json_serialize(data))
+      AtomicFile.write(file, json_serialize(data), durable: payload_writes_durable?)
 
       identifier = data['identifier']
       type = (data['type'] || type_dir.singularize).to_sym
@@ -1665,11 +1935,9 @@ module Woods
     # Is this a path worth asking git about?
     #
     # A gem-owned unit (an engine model) carries its real path. Outside
-    # Rails.root, git refuses the whole `log` invocation when any pathspec is
-    # outside the repository — one gem path would erase the git metadata of
-    # the other 499 units in its 500-path batch. Inside Rails.root, a bundle
+    # Rails.root, it has no app repository history. Inside Rails.root, a bundle
     # vendored at `vendor/bundle` puts the same gem files under the root
-    # prefix, gitignored, so sending them is wasted pathspec work every run.
+    # prefix, gitignored, so requesting their history serves no app-owned unit.
     # Same exclusions as {Extractors::SharedUtilityMethods#app_source?}.
     #
     # @param path [String, nil] absolute file path
@@ -1715,7 +1983,7 @@ module Woods
       payload = json_serialize(unit.to_h)
       return if identical_on_disk?(path, payload)
 
-      AtomicFile.write(path, payload)
+      AtomicFile.write(path, payload, durable: payload_writes_durable?)
     end
 
     # The serialized `extracted_at` scalar as {ExtractedUnit#to_h} +
@@ -1723,13 +1991,13 @@ module Woods
     # exactly this value shape — no fractional seconds, `Z` or a `±hh:mm`
     # offset — and `spec/extracted_unit_spec.rb` pins that, so a change to the
     # stamp's shape fails a spec instead of quietly un-matching this mask.
-    # The value constraint is what keeps the mask honest against user code: a
-    # bare `"extracted_at":` cannot occur inside any JSON *string* value
-    # (interior quotes serialize as `\"`), so only a real JSON key can match,
-    # and only when it holds a timestamp — which no extractor emits below the
-    # top level.
+    # Match only the final top-level stamp, followed by the source_hash field
+    # and the document's closing brace. Nested metadata may use the same key
+    # and timestamp shape; changing it must still rewrite the unit. Escaped
+    # quotes inside string values cannot match these JSON field boundaries.
     EXTRACTED_AT_SCALAR =
-      /("extracted_at":\s*")\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:Z|[+-]\d{2}:\d{2})(?=")/
+      /("extracted_at":\s*")\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:Z|[+-]\d{2}:\d{2})
+       (?=",\s*"source_hash":\s*"[0-9a-f]{64}"\s*}\s*\z)/x
     # An implementation detail of the byte comparison, not part of the
     # extractor's surface (`private` does not scope constants).
     private_constant :EXTRACTED_AT_SCALAR
@@ -1763,7 +2031,7 @@ module Woods
     #   original encoding
     # @return [String] the bytes with the stamp's value removed
     def mask_extracted_at(bytes)
-      bytes.gsub(EXTRACTED_AT_SCALAR, '\1')
+      bytes.sub(EXTRACTED_AT_SCALAR, '\1')
     end
 
     def normalize_file_paths
@@ -1795,7 +2063,7 @@ module Woods
     # to say. Enrichment then wrote `commit_count: 0` and
     # `change_frequency: new` onto every unit, which reads exactly like a file
     # that was never committed, where an absent git directory correctly omits
-    # the keys (B-186). HEAD has to resolve.
+    # the keys (B-186). HEAD has to resolve, with complete ancestry (B-189).
     #
     # Memoized, so the warning below is emitted at most once per run.
     #
@@ -1804,13 +2072,31 @@ module Woods
       return @git_available if defined?(@git_available)
 
       _output, error, status = Open3.capture3(*git_argv('rev-parse', 'HEAD'))
-      @git_available = status.success?
-      warn_unresolvable_git(error) unless @git_available
-      @git_available
+      unless status.success?
+        warn_unresolvable_git(error)
+        return @git_available = false
+      end
+
+      @git_available = complete_git_history?
     rescue StandardError
       @git_available = false
     end
 
+    # A shallow HEAD resolves but represents an incomplete ancestry. Do not
+    # turn that boundary into apparent one-commit/new-file churn facts.
+    def complete_git_history?
+      output, _error, status = Open3.capture3(*git_argv('rev-parse', '--is-shallow-repository'))
+      return true if status.success? && output.strip == 'false'
+
+      shallow = status.success? && output.strip == 'true'
+      reason = shallow ? 'shallow repository' : 'repository depth could not be verified'
+      Rails.logger.warn(
+        "[Woods] Git enrichment omitted: #{reason}. Fetch full history with git fetch --unshallow " \
+        '(or actions/checkout fetch-depth: 0), then run full extraction to refresh git metadata.'
+      )
+      false
+    end
+
     # Say once why no unit will carry git metadata, but only when there is a
     # working tree to explain. No `.git` at the root is the ordinary source
     # tarball or `COPY`-without-`.git` case, and it is not a fault.
@@ -1854,63 +2140,19 @@ module Woods
       ''
     end
 
-    # Batch-fetch git data for all file paths in two git commands.
-    #
-    # Duplicate paths are collapsed before slicing (audit P9d): many units
-    # share one file_path, and duplicates only repeat a pathspec another
-    # batch also sent. The result is keyed by relative path, so the output
-    # is identical.
-    #
-    # @param file_paths [Array<String>] Absolute file paths
-    # @return [Hash{String => Hash}] Keyed by relative path
+    # One HEAD history walk, independent of requested-path grouping. See
+    # GitHistory for explicit merge semantics and binary record framing.
+    # @param file_paths [Array<String>] absolute file paths
+    # @return [Hash{String => Hash}] keyed by Rails.root-relative path
     def batch_git_data(file_paths)
       return {} if file_paths.empty?
 
-      root = "#{Rails.root}/"
-      relative_paths = file_paths.map { |f| f.sub(root, '') }.uniq
-      result = {}
-      relative_paths.each { |rp| result[rp] = {} }
-
-      path_set = relative_paths.to_set
-      relative_paths.each_slice(500) do |batch|
-        log_output = run_git(
-          'log', '--all', '--name-only',
-          '--format=__COMMIT__%H|||%an|||%cI|||%s',
-          '--since=365 days ago',
-          '--', *batch
-        )
-        parse_git_log_output(log_output, path_set, result)
-      end
-
-      ninety_days_ago = (Time.current - 90.days).iso8601
-      result.each do |relative_path, data|
-        result[relative_path] = build_file_metadata(data, ninety_days_ago)
-      end
+      relative_paths = file_paths.map { |path| normalize_file_path(path) }.uniq
+      recent_after = Time.current - 90.days
+      raw = GitHistory.new(root: Rails.root, logger: Rails.logger).read(relative_paths, recent_after: recent_after)
+      return {} unless raw
 
-      result
-    end
-
-    # Parse git log output line-by-line, populating result with per-file commit data.
-    def parse_git_log_output(log_output, path_set, result)
-      current_commit = nil
-
-      log_output.each_line do |line|
-        line = line.strip
-        next if line.empty?
-
-        if line.start_with?('__COMMIT__')
-          parts = line.sub('__COMMIT__', '').split('|||', 4)
-          current_commit = { sha: parts[0], author: parts[1], date: parts[2], message: parts[3] }
-        elsif current_commit && path_set.include?(line)
-          entry = result[line] ||= {}
-          unless entry[:last_modified]
-            entry[:last_modified] = current_commit[:date]
-            entry[:last_author] = current_commit[:author]
-          end
-          (entry[:commits] ||= []) << current_commit
-          (entry[:contributors] ||= Hash.new(0))[current_commit[:author]] += 1
-        end
-      end
+      raw.transform_values { |data| build_file_metadata(data, recent_after.iso8601) }
     end
 
     # Classify how frequently a file changes based on commit counts.
@@ -1932,12 +2174,13 @@ module Woods
     def build_file_metadata(data, ninety_days_ago)
       all_commits = data[:commits] || []
       contributor_counts = data[:contributors] || {}
-      recent_count = all_commits.count { |c| c[:date] && c[:date] > ninety_days_ago }
+      recent_count = data.fetch(:recent_count) { all_commits.count { |c| c[:date] && c[:date] > ninety_days_ago } }
+      total_count = data.fetch(:commit_count, all_commits.size)
 
       {
         last_modified: data[:last_modified],
         last_author: data[:last_author],
-        commit_count: all_commits.size,
+        commit_count: total_count,
         contributors: contributor_counts
                       .sort_by { |_, count| -count }
                       .first(5)
@@ -1945,7 +2188,7 @@ module Woods
         recent_commits: all_commits.first(5).map do |c|
           { sha: c[:sha]&.first(8), message: c[:message], date: c[:date], author: c[:author] }
         end,
-        change_frequency: classify_change_frequency(all_commits.size, recent_count)
+        change_frequency: classify_change_frequency(total_count, recent_count)
       }
     end
 
@@ -1960,14 +2203,16 @@ module Woods
         units.each do |unit|
           AtomicFile.write(
             type_dir.join(collision_safe_filename(unit.identifier)),
-            json_serialize(unit.to_h)
+            json_serialize(unit.to_h),
+            durable: payload_writes_durable?
           )
         end
 
         # Also write a type index for fast lookups
         AtomicFile.write(
           type_dir.join('_index.json'),
-          json_serialize(type_index_entries(units))
+          json_serialize(type_index_entries(units)),
+          durable: payload_writes_durable?
         )
       end
     end
@@ -2064,10 +2309,23 @@ module Woods
       # registration order must not reach it (B-180).
       graph_data[:pagerank] = @dependency_graph.pagerank.sort_by { |identifier, _| identifier }.to_h
 
-      AtomicFile.write(
-        payload_dir.join('dependency_graph.json'),
-        json_serialize(graph_data)
-      )
+      payload = json_serialize(graph_data)
+      # The bytes about to land on disk are the bytes `graph_sha` covers, so
+      # keep the digest here rather than reading a whole large-app graph back
+      # to compute it. AtomicFile writes in binary mode and reads back as
+      # UTF-8, so the two digests are the same either way.
+      @graph_sha = Digest::SHA256.hexdigest(payload)
+      AtomicFile.write(payload_dir.join('dependency_graph.json'), payload, durable: payload_writes_durable?)
+    end
+
+    # The digest of the dependency graph this run wrote.
+    #
+    # Falls back to reading the file for a caller that writes the analysis
+    # without having written the graph in the same run.
+    #
+    # @return [String] hex SHA256 of dependency_graph.json
+    def graph_sha
+      @graph_sha || Digest::SHA256.hexdigest(AtomicFile.read(payload_dir.join('dependency_graph.json')))
     end
 
     def write_graph_analysis
@@ -2075,14 +2333,13 @@ module Woods
 
       enriched = @graph_analysis.merge(
         generated_at: Time.current.iso8601,
-        graph_sha: Digest::SHA256.hexdigest(
-          AtomicFile.read(payload_dir.join('dependency_graph.json'))
-        )
+        graph_sha: graph_sha
       )
 
       AtomicFile.write(
         payload_dir.join('graph_analysis.json'),
-        json_serialize(enriched)
+        json_serialize(enriched),
+        durable: payload_writes_durable?
       )
     end
 
@@ -2106,6 +2363,7 @@ module Woods
 
       manifest = {
         extracted_at: Time.current.iso8601,
+        woods_version: Woods::VERSION,
         rails_version: Rails.version,
         ruby_version: RUBY_VERSION,
 
@@ -2127,32 +2385,55 @@ module Woods
 
       AtomicFile.write(
         payload_dir.join('manifest.json'),
-        json_serialize(manifest)
+        json_serialize(manifest),
+        durable: payload_writes_durable?
       )
     end
 
     # Unit and chunk counts derived from the per-type _index.json files on
-    # disk — the source of truth after an incremental run, where only the
+    # disk: the source of truth after an incremental run, where only the
     # affected units were re-extracted.
     #
     # @return [Array(Hash{Symbol => Integer}, Integer)] counts by type, total chunk count
     def persisted_counts
-      counts = {}
-      chunks = 0
-
-      Dir[payload_dir.join('*/_index.json').to_s].each do |index_path|
-        entries = JSON.parse(AtomicFile.read(index_path))
-        counts[File.basename(File.dirname(index_path)).to_sym] = entries.size
-        chunks += entries.sum { |e| e['chunk_count'].to_i }
+      stats = persisted_index_stats
+      [stats.transform_values { |type_stats| type_stats[:count] },
+       stats.sum { |_type, type_stats| type_stats[:chunks] }]
+    end
+
+    # One pass over the persisted per-type _index.json files.
+    #
+    # {#persisted_counts} feeds the manifest and {#persisted_summary_stats}
+    # feeds SUMMARY.md, they run back to back at the end of every incremental
+    # run, and each used to parse every type index for itself. Reading once and
+    # deriving both is also what keeps the two artifacts from disagreeing about
+    # totals, which was previously a property of them using the same source
+    # rather than the same read.
+    #
+    # An unreadable index drops that whole type from the manifest and the
+    # summary alike, with one warning rather than the two the separate passes
+    # emitted. Sorted for determinism, since the glob order is the
+    # filesystem's.
+    #
+    # Memoized per run: invalidated at the start of {#extract_all} and
+    # {#prepare_incremental_run}, and again whenever {#regenerate_type_index}
+    # rewrites an index underneath it.
+    #
+    # @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|
+        entries = JSON.parse(AtomicFile.read(path))
+        stats[File.basename(File.dirname(path)).to_sym] = {
+          count: entries.size,
+          chunks: entries.sum { |entry| entry['chunk_count'].to_i },
+          namespaces: namespace_histogram(entries.map { |entry| entry['namespace'] })
+        }
       rescue JSON::ParserError => e
-        # An unreadable index silently drops that whole type from the manifest
-        # counts — warn rather than undercount without a trace.
-        type = File.basename(File.dirname(index_path))
-        Rails.logger.warn("[Woods] Skipping unreadable #{type}/_index.json in manifest counts: #{e.message}")
-        next
+        type = File.basename(File.dirname(path))
+        Rails.logger.warn(
+          "[Woods] Skipping unreadable #{type}/_index.json in manifest counts and summary totals: #{e.message}"
+        )
       end
-
-      [counts, chunks]
     end
 
     # Capture a temporal snapshot after extraction completes.
@@ -2287,7 +2568,8 @@ module Woods
 
       AtomicFile.write(
         payload_dir.join('SUMMARY.md'),
-        summary.join("\n")
+        summary.join("\n"),
+        durable: payload_writes_durable?
       )
     end
 
@@ -2308,32 +2590,14 @@ module Woods
     end
 
     # The incremental path's counterpart to {#results_summary_stats}: the same
-    # shape read back from the persisted per-type _index.json files, the source
-    # {#persisted_counts} uses for the manifest — so the two artifacts cannot
-    # disagree about totals. Sorted for determinism, since the glob order is
-    # the filesystem's.
-    #
-    # @return [Hash{Symbol => Hash}, nil] nil when the payload holds no type
-    #   indexes at all, so a bare index writes no summary — matching the full
-    #   path's early return when it extracted nothing
+    # shape, read back through {#persisted_index_stats}. A type whose index is
+    # empty is left out, where the manifest still counts it as zero.
+    #
+    # @return [Hash{Symbol => Hash}, nil] nil when the payload holds no
+    #   non-empty type index, so a bare index writes no summary, matching the
+    #   full path's early return when it extracted nothing
     def persisted_summary_stats
-      stats = {}
-
-      Dir[payload_dir.join('*/_index.json').to_s].each do |index_path|
-        entries = JSON.parse(AtomicFile.read(index_path))
-        next if entries.empty?
-
-        stats[File.basename(File.dirname(index_path)).to_sym] = {
-          count: entries.size,
-          chunks: entries.sum { |e| e['chunk_count'].to_i },
-          namespaces: namespace_histogram(entries.map { |e| e['namespace'] })
-        }
-      rescue JSON::ParserError => e
-        # Same posture as {#persisted_counts}: an unreadable index drops that
-        # type from the manifest and the summary alike, so the two still agree.
-        type = File.basename(File.dirname(index_path))
-        Rails.logger.warn("[Woods] Skipping unreadable #{type}/_index.json in summary totals: #{e.message}")
-      end
+      stats = persisted_index_stats.reject { |_type, type_stats| type_stats[:count].zero? }
 
       stats.empty? ? nil : stats
     end
@@ -2352,6 +2616,10 @@ module Woods
       type_dir = payload_dir.join(type_key.to_s)
       return unless type_dir.directory?
 
+      # This run's counts and summary totals are read from the index files;
+      # rewriting one invalidates whatever was read before.
+      @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'
@@ -2371,7 +2639,8 @@ module Woods
 
       AtomicFile.write(
         type_dir.join('_index.json'),
-        json_serialize(index)
+        json_serialize(index),
+        durable: payload_writes_durable?
       )
     end
 
@@ -2468,6 +2737,7 @@ module Woods
 
       @incremental_extractors[key] = EXTRACTORS[key]&.new
     rescue StandardError => e
+      @source_inputs&.unverified("extractor:#{key}")
       Rails.logger.warn "[Woods] Could not build #{key} extractor: #{e.message}"
       @incremental_extractors[key] = nil
     end
@@ -2529,6 +2799,10 @@ module Woods
           # 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
         end
 
         next if raised
@@ -2557,7 +2831,10 @@ module Woods
       # 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 [].
-      return nil if extractor.nil?
+      if extractor.nil?
+        source_consumer_failed?(rule.extractor_key, extractor)
+        return nil
+      end
       return [] unless extractor.respond_to?(rule.method_name)
 
       result =
@@ -2572,6 +2849,7 @@ module Woods
 
       Array(result).compact
     rescue StandardError => e
+      @source_inputs&.unverified("extractor:#{rule.extractor_key}")
       Rails.logger.warn "[Woods] #{rule.extractor_key} re-extraction of #{absolute_path} failed: #{e.message}"
       # `nil`, not `[]`. The caller treats an empty result as "this path defines
       # nothing any more" and prunes the units previously registered to it — so
@@ -2642,6 +2920,34 @@ 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)
+
+      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) }
+
+        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
+
+      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)
+
+        touched.add(identifier) if remove_unit(identifier, affected_types, type: :concern)
+      end
+      touched
+    end
+
     # Pruned class-based identifiers the tree still governs, and that the
     # second reconciliation pass may therefore re-add.
     #
@@ -2719,10 +3025,12 @@ module Woods
       units = new_classes.filter_map do |klass|
         extractor_for(key).public_send(spec[:method], klass)
       rescue StandardError => e
+        @source_inputs&.unverified("extractor:#{key}")
         Rails.logger.warn "[Woods] #{key} extraction of #{klass} failed: #{e.message}"
         nil
       end
 
+      source_consumer_failed?(key)
       register_and_write(key, units, affected_types)
     end
 
@@ -2806,6 +3114,11 @@ module Woods
       return Set.new if keys.empty?
 
       keys += ROUTE_CONSUMER_EXTRACTORS if keys.include?(:routes)
+      # A routes re-run replaces every controller, and a flow document
+      # carries the route itself, which no dependency edge connects to the
+      # controller. Nothing about that is reachable by a graph walk, so the
+      # run drops its flow scope and reassembles every touched controller.
+      @flow_scope = nil if keys.include?(:routes)
 
       keys.each_with_object(Set.new) do |key, touched|
         touched.merge(replace_type_wholesale(key, affected_types))
@@ -2852,6 +3165,10 @@ module Woods
     #   mutating durable state
     def replace_type_wholesale(key, affected_types)
       extractor = extractor_for(key)
+      if extractor.nil?
+        source_consumer_failed?(key, extractor)
+        return Set.new
+      end
       return Set.new unless extractor.respond_to?(:extract_all)
 
       @wholesale_mutations = 0
@@ -2860,6 +3177,8 @@ module Woods
 
       touched = 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)
+      touched
     rescue StandardError => e
       if @wholesale_mutations.to_i.positive?
         raise Woods::ExtractionError, <<~MSG.tr("\n", ' ').strip
@@ -2872,6 +3191,7 @@ module Woods
         MSG
       end
 
+      @source_inputs&.unverified("extractor:#{key}")
       Rails.logger.error "[Woods] Wholesale re-run of #{key} failed: #{e.message}"
       Set.new
     end
@@ -3033,6 +3353,7 @@ module Woods
 
           removed.add(identifier) if remove_unit(identifier, affected_types, type: type)
         end
+        @source_inputs&.consume_deleted(path)
       end
     end
 
@@ -3136,6 +3457,7 @@ 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
@@ -3212,12 +3534,14 @@ module Woods
     def finalize_incremental_unit_json(affected_types)
       dependents_dirty = @dependents_dirty || Set.new
       git_dirty = @incremental_written || {}
-      git_data = incremental_git_data(git_dirty.keys)
+      git_data = profile_phase('git enrichment') { incremental_git_data(git_dirty.keys) }
 
-      (dependents_dirty | git_dirty.keys).each do |identifier|
-        rewrite_unit_json(identifier, affected_types,
-                          refresh_dependents: dependents_dirty.include?(identifier),
-                          git_data: git_dirty.key?(identifier) ? git_data : nil)
+      profile_phase('unit finalization') do
+        (dependents_dirty | git_dirty.keys).each do |identifier|
+          rewrite_unit_json(identifier, affected_types,
+                            refresh_dependents: dependents_dirty.include?(identifier),
+                            git_data: git_dirty.key?(identifier) ? git_data : nil)
+        end
       end
     end
 
@@ -3282,7 +3606,7 @@ module Woods
 
       return if JSON.generate(data) == before
 
-      AtomicFile.write(path, json_serialize(data))
+      AtomicFile.write(path, json_serialize(data), durable: payload_writes_durable?)
       affected_types&.add(extractor_key)
     rescue JSON::ParserError => e
       Rails.logger.warn "[Woods] Could not finalize #{identifier}: #{e.message}"
@@ -3326,7 +3650,7 @@ module Woods
     end
 
     # Batch-fetch git metadata for the units written by this run, in a single
-    # git invocation, keyed by Rails.root-relative path the way
+    # history walk, keyed by Rails.root-relative path the way
     # {#batch_git_data} returns it.
     #
     # @param identifiers [Array<String>]
@@ -3334,11 +3658,12 @@ module Woods
     def incremental_git_data(identifiers)
       return {} if identifiers.empty? || !git_available?
 
+      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])
 
-          node[:file_path] if node[:file_path] && File.exist?(node[:file_path])
+          node[:file_path] if git_enrichable_path?(node[:file_path], root)
         end
       end
 
@@ -3393,11 +3718,15 @@ module Woods
       return nil unless extractor_key
 
       extractor = extractor_for(extractor_key)
-      return nil unless extractor
+      if extractor.nil?
+        source_consumer_failed?(extractor_key, extractor)
+        return nil
+      end
 
       # File-based extractors can return several units from one file (a .rake
       # file defining multiple tasks, etc.); class-based extractors return one.
       units = Array(re_extracted_units(extractor, type, unit_id, file_path, extractor_key)).compact
+      source_consumer_failed?(extractor_key, extractor)
       return nil if units.empty?
 
       register_and_write(extractor_key, units, affected_types)