woods 1.6.1 → 2.0.0.beta2

data/lib/woods/extractor.rb

@@ -7,10 +7,12 @@ require 'open3'
 require 'pathname'
 require 'set'
 
+require_relative 'atomic_file'
 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 'extractors/model_extractor'
 require_relative 'extractors/controller_extractor'
@@ -46,9 +48,13 @@ require_relative 'extractors/factory_extractor'
 require_relative 'extractors/test_mapping_extractor'
 require_relative 'extractors/poro_extractor'
 require_relative 'extractors/lib_extractor'
+require_relative 'extractors/package_extractor'
 require_relative 'graph_analyzer'
 require_relative 'model_name_cache'
 require_relative 'flow_precomputer'
+require_relative 'change_set'
+require_relative 'generation'
+require_relative 'path_dispatcher'
 
 module Woods
   # Extractor is the main orchestrator for codebase extraction.
@@ -66,6 +72,7 @@ module Woods
   #
   class Extractor
     include FilenameUtils
+    include Extractors::SourceNesting
 
     # Directories under app/ that contain classes we need to extract.
     # Used by eager_load_extraction_directories as a fallback when
@@ -126,7 +133,8 @@ module Woods
       test_mappings: Extractors::TestMappingExtractor,
       rails_source: Extractors::RailsSourceExtractor,
       poros: Extractors::PoroExtractor,
-      libs: Extractors::LibExtractor
+      libs: Extractors::LibExtractor,
+      packages: Extractors::PackageExtractor
     }.freeze
 
     # Maps singular unit types (as stored in ExtractedUnit/graph nodes)
@@ -169,8 +177,17 @@ module Woods
       factory: :factories,
       test_mapping: :test_mappings,
       rails_source: :rails_source,
+      # RailsSourceExtractor emits BOTH :rails_source and :gem_source units
+      # into the rails_source/ output directory. Without this entry the
+      # wholesale-replacement path could not prune a stale gem_source unit
+      # ({EXTRACTOR_KEY_TO_TYPES} would not list the type) and {#remove_unit}
+      # could not resolve its JSON file on disk (#169) — the GraphQL history
+      # in CLAUDE.md is the cautionary tale for an extractor whose emitted
+      # types are not all mapped.
+      gem_source: :rails_source,
       poro: :poros,
-      lib: :libs
+      lib: :libs,
+      package: :packages
     }.freeze
 
     # Maps unit types to class-based extractor methods (constantize + call).
@@ -203,13 +220,170 @@ module Woods
     # GraphQL types all use the same extractor method.
     GRAPHQL_TYPES = %i[graphql_type graphql_mutation graphql_resolver graphql_query].freeze
 
+    # File-based unit types the full path ALSO discovers by class, with the
+    # 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
+
+    # Unit types each extractor owns — the inverse of {TYPE_TO_EXTRACTOR_KEY}.
+    #
+    # Wholesale replacement of an extractor's output has to know every type it
+    # can produce, and one extractor can own several (`graphql` covers types,
+    # mutations, resolvers and queries).
+    #
+    # @return [Hash{Symbol => Array<Symbol>}]
+    EXTRACTOR_KEY_TO_TYPES = TYPE_TO_EXTRACTOR_KEY.each_with_object({}) do |(type, key), map|
+      (map[key] ||= []) << type
+    end.freeze
+
+    # Class-based extractors, which discover their units by walking runtime
+    # descendants rather than by globbing files. The incremental path
+    # reconciles each extractor's `discoverable_classes` against the
+    # identifiers already in the graph, so a class added since the last
+    # extraction is found without having to guess a constant name from a
+    # path (#164, gap 1).
+    #
+    # `reconcile_removals: false` opts an entry out of the removal half. Only
+    # GraphQL sets it, and the reason is that its unit type is produced by two
+    # independent discovery mechanisms whose union is the truth: runtime schema
+    # introspection *and* a static file pass over `app/graphql`. Every other
+    # entry here owns its type outright, which is what makes
+    # "in the graph but not in `discoverable_classes`" mean "deleted".
+    #
+    # For GraphQL that inference is wrong twice over. Without graphql-ruby
+    # loaded the runtime set is empty, so removal would delete every GraphQL
+    # unit in the index; with it loaded, a type defined in a file but not
+    # attached to the schema is legitimately absent from the type map, so
+    # removal would delete units a full extraction still emits. Additions are
+    # safe in both worlds — they are exactly the runtime-only types no changed
+    # path can dispatch to, which is the #167 divergence.
+    #
+    # The consequence, stated so it does not read as a bug later: a runtime-only
+    # type that *disappears* is never removed by an incremental run. It survives
+    # until a full extraction rebuilds the type. Confirmed against a live schema
+    # during review — probe units outlived deletion of the file that defined
+    # them. That is the cost of the opt-out, and it is the right side to err on:
+    # a stale unit is recoverable by one full run, whereas the removal half
+    # would delete units a full extraction still emits.
+    #
+    # @return [Hash{Symbol => Hash}] extractor key => { type:, method: }
+    CLASS_BASED_DISCOVERY = {
+      models: { type: :model, method: :extract_model },
+      controllers: { type: :controller, method: :extract_controller },
+      mailers: { type: :mailer, method: :extract_mailer },
+      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
+      # entry whose discovery set is not authoritative for its unit type
+      # (#167).
+      # `types:` because this extractor emits four unit types, not one:
+      # `classify_runtime_type` returns :graphql_type, :graphql_mutation,
+      # :graphql_resolver or :graphql_query. Declaring only :graphql_type made
+      # `known` miss the others — the schema's query root is always in
+      # `Schema.types` and classifies as :graphql_query — so they were
+      # re-"discovered" and re-added on *every* incremental run. That leaves
+      # `touched` non-empty on a genuine no-op, which rewrites the manifest and
+      # bumps the generation each cycle: the #164 gap-4 symptom, reintroduced.
+      graphql: { type: :graphql_type, types: GRAPHQL_TYPES,
+                 method: :extract_from_runtime_type, reconcile_removals: false }
+    }.freeze
+
+    # Extractors with no per-file entry point: they scan the whole app (or
+    # introspect the whole runtime) in one pass, so an incremental run
+    # replaces their output wholesale rather than per unit. Before #164
+    # these types were simply skipped by incremental runs while
+    # `config/routes.rb` still triggered one — the run rewrote the manifest,
+    # zeroing the staleness clock, without updating the data.
+    #
+    # @return [Hash{Symbol => Symbol}] extractor key => unit type
+    WHOLE_APP_EXTRACTORS = {
+      routes: :route,
+      middleware: :middleware,
+      engines: :engine,
+      scheduled_jobs: :scheduled_job,
+      state_machines: :state_machine,
+      factories: :factory,
+      events: :event,
+      # DatabaseViewExtractor keeps only the highest `_vNN` of each Scenic
+      # view, so its unit set is a function of the whole directory rather
+      # than of each file independently: dispatching db/views/foo_v01.sql to
+      # the per-file method would index a version a full extraction drops.
+      database_views: :database_view,
+      # Framework/gem sources are a function of the installed dependency set,
+      # so `Gemfile.lock` is their trigger path (#169). Before this the only
+      # incremental writer was `woods:extract_framework`, which hand-wrote
+      # JSON around the whole pipeline — no AtomicFile, no _index.json, no
+      # manifest counts, no lock, no generation bump — and its output then
+      # sat stale forever. The value here names the primary unit type, like
+      # every other entry; the extractor also owns :gem_source, and
+      # {EXTRACTOR_KEY_TO_TYPES} (which wholesale replacement consults) lists
+      # both. Participation is gated by `include_framework_sources` — see
+      # {#skip_by_configuration?}.
+      rails_source: :rails_source,
+      # A package root decides which package every other unit belongs to,
+      # and the undeclared-edge report reads the whole declared set, so any
+      # package.yml change re-runs the extractor wholesale (#280). Task 8
+      # re-annotates unit membership in the same run.
+      packages: :package
+    }.freeze
+
+    # Extractors whose output embeds the route table, and which therefore go
+    # stale when routes change even though none of their own files did.
+    #
+    # ControllerExtractor writes each action's routes into unit metadata and
+    # into the action chunks; everything that includes `RouteHelperResolver`
+    # resolves `_path`/`_url` references into navigation edges against the
+    # same table. The dependency graph can't express this — a route unit
+    # depends *on* its controller, so walking dependents from
+    # `config/routes.rb` never reaches it — so the relationship is declared
+    # here instead and these types are re-extracted wholesale whenever the
+    # route set is re-run (#164).
+    #
+    # @return [Array<Symbol>] extractor keys
+    ROUTE_CONSUMER_EXTRACTORS = %i[
+      controllers
+      mailers
+      components
+      view_components
+      view_templates
+    ].freeze
+
+    # Payload artifacts that live at the top of a payload directory rather
+    # than inside a per-type directory. Used when seeding a payload from a
+    # 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 directories that are not per-type unit directories.
+    PAYLOAD_DIRS = %w[flows].freeze
+
     attr_reader :output_dir, :dependency_graph
 
     def initialize(output_dir: nil)
       @output_dir = Pathname.new(output_dir || Rails.root.join('tmp/woods'))
+      @payload_store = PayloadStore.new(@output_dir)
+      @payload_dir = nil
+      @payload_generation = nil
       @dependency_graph = DependencyGraph.new
       @results = {}
       @extractors = {}
+      @publication_error = nil
+    end
+
+    # Where this run reads and writes payload artifacts.
+    #
+    # A run publishes into an immutable per-generation directory, so that the
+    # single atomic write of `generation.json` commits the whole payload at
+    # once. Falls back to the output root when no payload directory could be
+    # opened — a flat index is non-atomic but perfectly readable, and failing
+    # the extraction over it would be worse.
+    #
+    # @return [Pathname]
+    def payload_dir
+      @payload_dir || @output_dir
     end
 
     # ══════════════════════════════════════════════════════════════════════
@@ -222,23 +396,43 @@ module Woods
     def extract_all
       setup_output_directory
       ModelNameCache.reset!
+      # @package_resolver alone is not enough: #package_resolver builds
+      # through #extractor_for, which memoizes into @incremental_extractors.
+      # Without this reset, a second full run on the same instance would
+      # resolve membership through the first run's PackageExtractor and its
+      # already-memoized (now stale) package_files/package_roots, missing a
+      # package added between the two runs.
+      @package_resolver = nil
+      @incremental_extractors = nil
+      @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
 
-      # Rebuild graph from deduped results — Phase 1 registered all units including
-      # duplicates, and DependencyGraph has no remove/unregister API.
+      # Phase 1.6: Package membership. Runs before the graph is rebuilt so
+      # registration copies metadata[:package] onto the node (#280).
+      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) } }
 
@@ -246,13 +440,15 @@ module Woods
       Rails.logger.info '[Woods] Resolving dependents...'
       resolve_dependents
 
-      # Phase 3: Graph analysis (PageRank, structural metrics)
-      Rails.logger.info '[Woods] Analyzing dependency graph...'
-      @graph_analysis = GraphAnalyzer.new(@dependency_graph).analyze
-
-      # Phase 4: Enrich with git data
+      # 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
+
+      # Phase 4: Graph analysis (PageRank, structural metrics)
+      Rails.logger.info '[Woods] Analyzing dependency graph...'
+      @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...'
@@ -260,23 +456,43 @@ module Woods
 
       # 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
 
       # Phase 5.5: Precompute request flows (opt-in). Must run AFTER
       # write_results — FlowAssembler loads unit JSON from disk, so running
       # earlier assembled every flow from absent (fresh output dir) or
       # stale (previous run's) data. precompute_flows re-writes the
       # controller units it annotates with metadata[:flow_paths].
+      #
+      # Fail closed (M3 review round 3): a failure anywhere in the family —
+      # assembly, index write, annotation rewrite, sweep — raises and aborts
+      # the run here, BEFORE the graph, manifest, snapshot, and generation
+      # publish below. The previously published generation stays resolved
+      # and readable; the aborted run's payload directory is left
+      # unreachable for the next run's PayloadStore#create to reclaim.
+      # Publishing a partial flow index, stale prior flow artifacts
+      # alongside a new graph, or half-rewritten annotations would violate
+      # the atomic-generation and full/incremental-equivalence contracts;
+      # 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
+      profile_phase('manifest and summary') do
+        write_manifest
+        write_structural_summary
+      end
       capture_snapshot
+      profile_phase('publish') { publish_generation('full') }
 
       log_summary
 
@@ -287,57 +503,600 @@ module Woods
     # Incremental Extraction
     # ══════════════════════════════════════════════════════════════════════
 
-    # Extract only units affected by changed files
-    # Used for incremental indexing in CI
+    # Extract only units affected by changed files.
+    #
+    # Used for incremental indexing in CI and by any caller that maintains a
+    # live index. The goal is equivalence: after this returns, the on-disk
+    # index should match what a cold full extraction of the same tree would
+    # have produced.
+    #
+    # The run proceeds in a fixed order, and the order matters:
+    #
+    # 1. Blast radius is computed against the *pre-change* graph, so
+    #    dependents of a file that just disappeared still get re-extracted.
+    # 2. Known units in the blast radius are re-extracted.
+    # 3. Changed paths the index has never seen are dispatched to an
+    #    extractor by path ({PathDispatcher}).
+    # 4. Class-based types are reconciled against their runtime discovery
+    #    sets, catching classes added since the last extraction.
+    # 5. Whole-app extractors whose trigger paths changed are re-run and
+    #    their type replaced wholesale.
+    # 6. Units whose source file has vanished are pruned last, so anything
+    #    resurrected by steps 2–5 against a deleted file is swept in the
+    #    same run rather than surviving as a ghost until the next one.
     #
     # @param changed_files [Array<String>] List of changed file paths
-    # @return [Array<String>] List of re-extracted unit identifiers
+    # @return [Array<String>] Identifiers of units re-extracted, added, or removed
     def extract_changed(changed_files)
-      # Load existing graph
-      graph_path = @output_dir.join('dependency_graph.json')
-      @dependency_graph = DependencyGraph.from_h(JSON.parse(File.read(graph_path))) if graph_path.exist?
+      prepare_incremental_run
 
-      ModelNameCache.reset!
+      change_set = ChangeSet.new(paths: changed_files, root: Rails.root)
+      affected_types = Set.new
+
+      # 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 = profile_phase('re-extraction') do
+        acc = reconcile_changed_paths(change_set, affected_types)
+
+        (affected_ids - acc.to_a).each do |unit_id|
+          acc.add(unit_id) if re_extract_unit(unit_id, affected_types: affected_types)
+        end
+
+        acc
+      end
 
-      # Eager load to ensure newly-added classes are discoverable.
-      safe_eager_load!
+      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)
+
+      # 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)
+                    ))
+
+      finalize_incremental_unit_json(affected_types)
 
-      # Normalize relative paths (from git diff) to absolute (as stored in file_map)
-      absolute_files = changed_files.map do |f|
-        Pathname.new(f).absolute? ? f : Rails.root.join(f).to_s
+      # Regenerate type indexes for affected types
+      profile_phase('type index') do
+        affected_types.each do |type_key|
+          regenerate_type_index(type_key)
+        end
       end
 
-      # Compute affected units
-      affected_ids = @dependency_graph.affected_by(absolute_files)
-      Rails.logger.info "[Woods] #{changed_files.size} changed files affect #{affected_ids.size} units"
+      finalize_incremental_run(touched)
+
+      touched.to_a
+    end
+
+    # ══════════════════════════════════════════════════════════════════════
+    # Targeted Refresh
+    # ══════════════════════════════════════════════════════════════════════
 
-      # Re-extract affected units
+    # Re-run one or more extractors wholesale against the already-booted app,
+    # replacing every unit of the types they own.
+    #
+    # This is the escape hatch for the unit types that have no per-file entry
+    # point — routes are derived from `Rails.application.routes`, the
+    # middleware unit from the live stack, events from a two-pass scan of all
+    # of `app/`. Incremental runs reach them by trigger path
+    # ({PathDispatcher.whole_app_rules}); this reaches them by name, for a
+    # caller that already knows what went stale: a resident process that just
+    # reloaded, a `woods:refresh` invocation after editing `config/routes.rb`,
+    # a deploy hook after a dependency bump.
+    #
+    # "Full extraction required for these types" was always a cold-boot
+    # artifact rather than something inherent: in a booted process re-running
+    # one extractor is seconds.
+    #
+    # Any extractor key works, not just the whole-app ones — `refresh(:models)`
+    # is a legitimate way to re-derive every model after a schema change.
+    #
+    # @example After editing config/routes.rb
+    #   Woods::Extractor.new(output_dir: "tmp/woods").refresh(:routes)
+    #
+    # @param keys [Array<Symbol>] keys into {EXTRACTORS}
+    # @return [Hash] `{ types:, touched:, unknown: }` — the extractors that
+    #   ran, the identifiers written or removed, and any key that isn't an
+    #   extractor
+    # @raise [ArgumentError] when no recognized key is given
+    def refresh(*keys)
+      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?
+
+      known += ROUTE_CONSUMER_EXTRACTORS if known.include?(:routes)
+      known.uniq!
+
+      prepare_incremental_run
       affected_types = Set.new
-      affected_ids.each do |unit_id|
-        re_extract_unit(unit_id, affected_types: affected_types)
+      touched = known.each_with_object(Set.new) do |key, acc|
+        acc.merge(replace_type_wholesale(key, affected_types))
       end
 
-      # Regenerate type indexes for affected types
-      affected_types.each do |type_key|
-        regenerate_type_index(type_key)
+      finalize_incremental_unit_json(affected_types)
+      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 }
+    end
+
+    # Raise when the most recent extraction run wrote a payload but could not
+    # publish its generation marker.
+    #
+    # The extractor records this failure instead of raising immediately so
+    # 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.
+    #
+    # @return [void]
+    # @raise [Woods::ExtractionError] when the generation marker could not be
+    #   published; the previously published generation remains active
+    def raise_on_publication_failure!
+      raise @publication_error if @publication_error
+    end
+
+    private
+
+    # 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
+    # `@incremental_written` holding a previous run's state.
+    #
+    # `begin_payload!(strict: true)`: an incremental write set is only the
+    # touched units, so a degrade to flat here (see {#begin_payload!}) would
+    # both read the wrong baseline graph below and publish an index missing
+    # every unit it didn't touch. Raises rather than degrading; the caller
+    # sees {Woods::ExtractionError} and the generation is left unbumped.
+    #
+    # @return [void]
+    # @raise [Woods::ExtractionError] see {#begin_payload!}
+    def prepare_incremental_run
+      profile_phase('payload seed') { begin_payload!(strict: true) }
+      graph_path = payload_dir.join('dependency_graph.json')
+      ensure_incremental_baseline!(graph_path)
+      profile_phase('previous graph load') do
+        @dependency_graph = DependencyGraph.from_h(JSON.parse(AtomicFile.read(graph_path))) if graph_path.exist?
       end
 
-      # Update graph, manifest, and summary. No capture_snapshot here:
-      # snapshots must hash the FULL unit set, and incremental runs only
-      # re-extract affected units (@results stays empty) — capturing would
-      # record a snapshot whose diff reports every unit as deleted.
-      # Snapshots are captured on full extraction only.
+      ModelNameCache.reset!
+      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.
+    #
+    # The manifest is rewritten only when the run actually changed something.
+    # `staleness_seconds` is derived from the manifest timestamp, so touching
+    # it after a no-op run reports the index as freshly synced when nothing
+    # was re-read — the misleading half of #164 gap 4. The graph write itself
+    # is unconditional, but on a no-op run it is inert, not meaningful: under
+    # payloads it lands in this run's not-yet-published directory, and a
+    # no-op run returns below before {#publish_generation}, so nothing ever
+    # points at what it just wrote — the next run's {PayloadStore#create}
+    # empties that same (unbumped-generation-numbered) directory before
+    # writing into it again. The graph's content is unchanged on a no-op run
+    # regardless (no touched units, no new edges), so nothing is lost; it is
+    # the write itself, not the recomputation, that goes nowhere.
+    #
+    # No `capture_snapshot` here: snapshots must hash the FULL unit set, and
+    # incremental runs only hold changed units in memory — capturing would
+    # record a snapshot whose diff reports every other unit as deleted.
+    #
+    # @param touched [Set<String>] identifiers added, re-extracted, or removed
+    # @param reason [String] what produced this run, recorded on the generation
+    #   so `woods_status` can distinguish a targeted refresh from a file-driven
+    #   incremental run — they have different blast radii and an operator
+    #   reading "incremental" after a `woods:refresh[routes]` is being misled
+    # @return [void]
+    def finalize_incremental_run(touched, reason: 'incremental')
       write_dependency_graph
-      write_manifest(incremental: true)
-      write_structural_summary
-      if Woods.configuration.enable_snapshots
-        Rails.logger.info '[Woods] Skipping snapshot capture — snapshots are captured on full extraction only'
+
+      if touched.empty?
+        Rails.logger.info '[Woods] Incremental run changed nothing — leaving manifest timestamp untouched'
+        return
       end
 
-      affected_ids
+      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
+      profile_phase('publish') { publish_generation(reason) }
+
+      return unless Woods.configuration.enable_snapshots
+
+      Rails.logger.info '[Woods] Skipping snapshot capture — snapshots are captured on full extraction only'
     end
 
-    private
+    # Publish a new generation — the last write of any successful run.
+    #
+    # Every extraction mode does this, so a long-lived reader can detect that
+    # the index moved without stat-ing the whole directory, whatever produced
+    # the change: a full run, an incremental run, a targeted refresh, or the
+    # watch daemon. Ordering is the contract: the generation goes last, so a
+    # reader that sees generation N knows N's files are already on disk. A run
+    # that raised, or that changed nothing, never reaches this.
+    #
+    # @param reason [String] what produced this generation
+    # @return [void]
+    def publish_generation(reason)
+      generation = Generation.new(output_dir: @output_dir)
+      # 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('payload sync') { sync_payload }
+      marker = generation.bump!(reason: reason, payload: payload)
+      prune_payloads(marker.number)
+      marker
+    rescue StandardError => e
+      # A failed bump must not fail the extraction that produced a perfectly
+      # good index. But "readers keep their current view until the next run" is
+      # too comfortable a way to put it: the generation *is* the freshness
+      # contract, so readers keep serving the old index for as long as the
+      # cause persists, and the next incremental may be a no-op that bumps
+      # nothing either. Error, not warn — and `Watch::Daemon` cross-checks that
+      # the number actually moved so the daemon reports degraded rather than
+      # running.
+      @publication_error = Woods::ExtractionError.new(
+        "Could not publish generation for #{@output_dir} (#{e.class}: #{e.message}); " \
+        'the previous generation remains active'
+      )
+      Rails.logger.error "[Woods] #{@publication_error.message}"
+      nil
+    end
+
+    # Open the payload directory this run publishes into, seeded from the
+    # generation currently on disk.
+    #
+    # Seeding is what lets a run that touches ten files publish a whole
+    # generation: the unchanged artifacts are hardlinked in, and the run
+    # overwrites only what it changed. It also means every payload read during
+    # the run — the persisted graph, the per-type indexes, the unit JSON an
+    # incremental run patches — sees the previous generation, exactly as it
+    # did when the index was flat.
+    #
+    # A failure here degrades to the flat layout rather than failing the run
+    # — but only when a flat publish can actually be complete. A full
+    # extraction's write set is every unit in the app, so a flat publish from
+    # it is a whole index; the next successful run restores the payload
+    # boundary. `strict:` opts out of that degrade for {#extract_changed} and
+    # {#refresh}, whose write set is only the units they touched: over a
+    # payload-born index (`marker.payload` set), the flat root holds nothing
+    # newer than the last time this index was flat — possibly nothing at all
+    # — so publishing there would both compute the wrong incremental baseline
+    # ({#prepare_incremental_run} reads its graph from wherever `payload_dir`
+    # resolves to) and, even with the right baseline, redirect every reader
+    # to a near-empty directory missing every untouched unit. There is no
+    # complete flat index an incremental degrade can produce, so this raises
+    # instead — see {Woods::ExtractionError}. The generation is never bumped
+    # over a raised run, so readers keep serving the last good index.
+    #
+    # @param strict [Boolean] raise instead of degrading to a flat publish
+    #   when the published generation names a payload
+    # @return [void]
+    # @raise [Woods::ExtractionError] when `strict` and a payload-born index's
+    #   payload directory could not be opened for this run
+    def begin_payload!(strict: false)
+      @publication_error = nil
+      marker = Generation.new(output_dir: @output_dir).current
+      @payload_generation = marker.number + 1
+      @payload_dir = @payload_store.create(@payload_generation)
+      seed_payload(marker)
+    rescue StandardError => e
+      if strict && marker&.payload
+        raise Woods::ExtractionError, <<~MSG.tr("\n", ' ').strip
+          Could not open a payload directory for this incremental run
+          (#{e.class}: #{e.message}), and generation #{marker.number}'s payload
+          lives in #{marker.payload} rather than the flat output root. An
+          incremental run only writes the units it touched, so publishing flat
+          here would produce an index missing every untouched unit. Fix the
+          underlying filesystem issue (permissions, free space, a broken
+          mount), or run a full `woods:extract` to rebuild a complete flat
+          index before incremental runs resume.
+        MSG
+      end
+
+      Rails.logger.warn(
+        "[Woods] Could not open a payload directory (#{e.class}: #{e.message}) — publishing flat"
+      )
+      @payload_dir = nil
+      @payload_generation = nil
+    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
+    # on a fresh runner — {#extract_changed} would compute an empty blast
+    # radius, dispatch only the diffed paths, and publish generation 1: a
+    # near-empty index that readers, `woods:validate`, and retrieval all
+    # treat as the complete truth of the app, and that nothing self-heals
+    # 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!}.
+    #
+    # @param graph_path [Pathname] the seeded payload's dependency graph
+    # @return [void]
+    # @raise [Woods::ExtractionError] when no baseline exists
+    def ensure_incremental_baseline!(graph_path)
+      return if graph_path.exist?
+      return if Generation.new(output_dir: @output_dir).current.number.positive?
+      # An embedding caller that already holds a populated graph (a prior
+      # in-process run, or seeded registrations) IS the baseline —
+      # {#prepare_incremental_run} keeps the in-memory graph whenever no
+      # disk graph exists.
+      return unless @dependency_graph.nil? || @dependency_graph.empty?
+
+      raise Woods::ExtractionError, <<~MSG.tr("\n", ' ').strip
+        No baseline index found under #{@output_dir}: no generation has been
+        published and no dependency_graph.json exists. An incremental run
+        only re-extracts what changed relative to an existing index, so
+        running it here would publish a near-empty index as the complete
+        truth of the application. Run a full `woods:extract` first (or point
+        WOODS_OUTPUT at the directory holding the existing index).
+      MSG
+    end
+
+    # Copy the published generation's payload into this run's directory.
+    #
+    # Two sources. A generation that already names a payload directory is
+    # cloned wholesale — by construction it holds payload artifacts and
+    # nothing else. A flat index (every index written before payloads, and any
+    # index whose last run degraded) is cloned entry by entry from an
+    # allowlist, because the output root also holds `generation.json`,
+    # `dumps/`, `tasks/`, `woods.sqlite3` and `payloads/` itself.
+    #
+    # @param marker [Woods::Generation::Marker] the published generation
+    # @return [void]
+    def seed_payload(marker)
+      if marker.payload && (source = @output_dir.join(marker.payload)).directory?
+        @payload_store.clone(source, @payload_dir)
+      else
+        seed_payload_from_flat_root
+      end
+    end
+
+    # Uses {PayloadStore#link_or_copy} rather than a bare +FileUtils.ln+ for
+    # the same reason {PayloadStore#clone} does: a filesystem that disallows
+    # hardlinks (EXDEV/EPERM/EMLINK/NotImplementedError) must still seed the
+    # payload, just by copying. Before this, that raise was caught by
+    # {#begin_payload!}'s rescue and degraded every run on such a filesystem
+    # to a flat publish — the fallback existed in {PayloadStore} but this,
+    # the only other file-level linker, never reached it.
+    #
+    # @return [void]
+    def seed_payload_from_flat_root
+      (PAYLOAD_FILES + payload_entry_dirs).each do |entry|
+        source = @output_dir.join(entry)
+        next unless source.exist?
+
+        @payload_store.clone(source, @payload_dir.join(entry)) if source.directory?
+        @payload_store.link_or_copy(source, @payload_dir.join(entry)) if source.file?
+      end
+    end
+
+    # @return [Array<String>] every directory name a payload can contain
+    def payload_entry_dirs
+      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
+    # publish as. Writers serialize on `PipelineLock`, so that prediction holds
+    # — but if it ever did not, the pointer would name a directory belonging to
+    # a different generation, so the directory is renamed to match rather than
+    # published under a name that lies.
+    #
+    # @param generation [Woods::Generation]
+    # @return [String, nil]
+    def publishable_payload_name(generation)
+      return nil unless @payload_dir
+
+      actual = generation.current.number + 1
+      if actual != @payload_generation
+        @payload_dir = rename_payload(actual)
+        @payload_generation = actual
+      end
+
+      PayloadStore.name_for(@payload_generation)
+    end
+
+    # @param number [Integer] the generation number actually being published
+    # @return [Pathname] the payload directory under its corrected name
+    def rename_payload(number)
+      destination = @payload_store.path_for(number)
+      FileUtils.rm_rf(destination.to_s)
+      FileUtils.mv(@payload_dir.to_s, destination.to_s)
+      destination
+    end
+
+    # @param published [Integer] the generation just published
+    # @return [void]
+    def prune_payloads(published)
+      return unless @payload_dir
+
+      @payload_store.prune(keep: payload_retention, protect: published)
+    rescue StandardError => e
+      Rails.logger.warn "[Woods] Payload retention failed: #{e.message}"
+    end
+
+    # @return [Integer] how many payload generations to keep on disk
+    def payload_retention
+      value = ENV.fetch('WOODS_PAYLOAD_RETENTION', nil).to_i
+      value.positive? ? value : PayloadStore::DEFAULT_RETENTION
+    end
+
+    # Recompute graph_analysis.json after an incremental graph write.
+    #
+    # Structural analysis (orphans, hubs, cycles, bridges) is derived purely
+    # from the graph, so leaving it at the last full extraction's values let
+    # it drift continuously between full runs (#164 gap 5).
+    #
+    # Re-raises rather than warn-and-continue: a caller that swallowed this
+    # went on to write the manifest and publish a fresh generation over an
+    # index whose graph_analysis.json never updated — a failed analysis write
+    # must abort the run the same way a failed extraction does, not ship
+    # under a generation that says everything landed.
+    #
+    # @return [void]
+    # @raise [StandardError] whatever GraphAnalyzer or the write raised
+    def write_incremental_graph_analysis
+      @graph_analysis = build_graph_analyzer.analyze
+      write_graph_analysis
+    rescue StandardError => e
+      Rails.logger.error "[Woods] Incremental graph analysis failed: #{e.message}"
+      raise
+    end
 
     # ──────────────────────────────────────────────────────────────────────
     # Eager Loading
@@ -351,9 +1110,16 @@ module Woods
     # loads only the directories we actually need for extraction.
     def safe_eager_load!
       Rails.application.eager_load!
+      # Recorded because it decides whether the runtime discovery sets are
+      # *complete*. On the fallback path they are known-partial — whole
+      # directories may have failed to load — and treating "absent from
+      # descendants" as "deleted" would then erase live units by the type.
+      # See {#stale_class_based_units}.
+      @eager_load_complete = true
     rescue NameError => e
       Rails.logger.warn "[Woods] eager_load! hit NameError: #{e.message}"
       Rails.logger.warn '[Woods] Falling back to per-directory eager loading'
+      @eager_load_complete = false
       eager_load_extraction_directories
     end
 
@@ -387,8 +1153,36 @@ module Woods
     # Extraction Strategies
     # ──────────────────────────────────────────────────────────────────────
 
+    # Should this extractor be skipped under the current configuration?
+    #
+    # `include_framework_sources` (default: true — see
+    # docs/CONFIGURATION_REFERENCE.md) was documented and consumed by nothing
+    # (#169). It now gates both automatic paths at once: the full-run pass
+    # over {EXTRACTORS} and the `Gemfile.lock` whole-app trigger
+    # ({#rerun_whole_app_extractors}). The {PathDispatcher} rule itself stays
+    # ungated — rules are memoized per-process while configuration is not,
+    # and `relevant?` stays correct either way because `Gemfile.lock` already
+    # triggers :engines and :middleware — so the gate sits where the
+    # extractor would actually run. Gating only one side would either extract
+    # units a knob-off full run does not produce (a phantom `touched` cycle
+    # bumping the generation) or leave a knob-on host with framework sources
+    # that never refresh on a dependency bump.
+    #
+    # A by-name {#refresh} (and its `woods:extract_framework` alias) is
+    # deliberately NOT gated: the knob controls automatic participation, and
+    # the explicit refresh is the escape hatch for hosts that want framework
+    # sources on demand without paying for them every run.
+    #
+    # @param key [Symbol] key into {EXTRACTORS}
+    # @return [Boolean]
+    def skip_by_configuration?(key)
+      key == :rails_source && !Woods.configuration.include_framework_sources
+    end
+
     def extract_all_sequential
       EXTRACTORS.each do |type, extractor_class|
+        next if skip_by_configuration?(type)
+
         Rails.logger.info "[Woods] Extracting #{type}..."
         start_time = Time.current
 
@@ -427,7 +1221,9 @@ module Woods
       ModelNameCache.short_names_regex if ModelNameCache.respond_to?(:short_names_regex)
 
       results_mutex = Mutex.new
-      threads = EXTRACTORS.map do |type, extractor_class|
+      failures = []
+      active = EXTRACTORS.reject { |type, _| skip_by_configuration?(type) }
+      threads = active.map do |type, extractor_class|
         Thread.new do
           Rails.logger.info "[Woods] [Thread] Extracting #{type}..."
           start_time = Time.current
@@ -445,12 +1241,21 @@ module Woods
           end
         rescue StandardError => e
           Rails.logger.error "[Woods] [Thread] #{type} failed: #{e.message}"
-          results_mutex.synchronize { @results[type] = [] }
+          results_mutex.synchronize { failures << [type, e] }
         end
       end
 
       threads.each(&:join)
 
+      # Fail closed, matching sequential extraction: a raise there aborts
+      # before registering anything for the run. Silently substituting `[]`
+      # for a failed type let the run finish, register a partial graph, and
+      # publish it under a generation that says every type succeeded.
+      if failures.any?
+        names = failures.map { |(type, _e)| type }.sort.join(', ')
+        raise Woods::ExtractionError, "Concurrent extraction failed for: #{names}"
+      end
+
       # Register into dependency graph sequentially — DependencyGraph is not thread-safe
       EXTRACTORS.each_key do |type|
         (@results[type] || []).each { |unit| @dependency_graph.register(unit) }
@@ -464,7 +1269,7 @@ module Woods
     def setup_output_directory
       FileUtils.mkdir_p(@output_dir)
       EXTRACTORS.each_key do |type|
-        FileUtils.mkdir_p(@output_dir.join(type.to_s))
+        FileUtils.mkdir_p(payload_dir.join(type.to_s))
       end
     end
 
@@ -472,56 +1277,122 @@ module Woods
     # Dependency Resolution
     # ──────────────────────────────────────────────────────────────────────
 
+    # `unit_map` is identifier => Array<unit>, not identifier => unit (#225).
+    # An identifier is not unique across types (a Scenic view and a factory
+    # can both be `reports`), so a single-valued map let the later
+    # registration overwrite the earlier one and every dependent land on
+    # whichever unit happened to be indexed last — the other unit serialized
+    # `dependents: []` forever. {#rewrite_unit_json_of_type} already treats
+    # `dependents` as a property of the identifier and writes the same list
+    # to every type that identifier owns; this brings the full-extraction
+    # path into agreement with it.
     def resolve_dependents
       # Build complete unit map first (cross-type dependencies require all units indexed).
-      unit_map = @results.each_with_object({}) do |(_type, units), map|
-        units.each { |u| map[u.identifier] = u }
+      unit_map = @results.each_with_object(Hash.new { |h, k| h[k] = [] }) do |(_type, units), map|
+        units.each { |u| map[u.identifier] << u }
       end
 
       # Resolve dependents using the complete map.
       @results.each_value do |units|
         units.each do |unit|
           unit.dependencies.each do |dep|
-            target_unit = unit_map[dep[:target]]
-            next unless target_unit
-
-            target_unit.dependents ||= []
-            target_unit.dependents << {
-              type: unit.type,
-              identifier: unit.identifier
-            }
+            unit_map[dep[:target]].each do |target_unit|
+              target_unit.dependents ||= []
+              target_unit.dependents << {
+                type: unit.type,
+                identifier: unit.identifier
+              }
+            end
           end
         end
       end
     end
 
     # Remove duplicate units (same identifier) within each type, keeping the first occurrence.
-    # Duplicates arise when multiple extractors produce the same unit (e.g., engine-mounted
-    # routes duplicating app routes). Without dedup, downstream phases would produce inflated
-    # counts, duplicate _index.json entries, and last-writer-wins file overwrites.
+    # Duplicates arise when the same identifier is legitimately re-derived from the same
+    # source (e.g., engine-mounted routes duplicating app routes: both carry no file path).
+    # Without dedup, downstream phases would produce inflated counts, duplicate
+    # _index.json entries, and last-writer-wins file overwrites.
+    #
+    # A duplicate derived from a DIFFERENT file is not a duplicate — it is two distinct
+    # real-world constants collapsing onto one identifier (finding G-1: wrapper-named
+    # sources all indexed as the wrapper class). Only one could ever be indexed; the
+    # other silently vanished. That is unrepresentable — `variants:` carries cross-type
+    # graph identity only — so extraction aborts with both files named.
     def deduplicate_results
       @results.each do |type, units|
-        deduped = units.uniq(&:identifier)
-        dropped = units.size - deduped.size
+        @results[type] = deduplicate_type_units(type, units)
+      end
+    end
+
+    # First-occurrence dedup for one type, fail-closed on cross-file collisions.
+    #
+    # A retained identifier remembers its source file. A later unit with the
+    # same identifier and the same file (or the same absence of one — runtime
+    # and engine units carry nil) is the legitimate re-derivation {#deduplicate_results}
+    # documents and is dropped. A later unit from a different file raises
+    # {Woods::ExtractionError} listing both paths.
+    #
+    # @param type [Symbol] Result type, for the log line and error message
+    # @param units [Array<ExtractedUnit>]
+    # @return [Array<ExtractedUnit>] Deduplicated units, first occurrence order
+    # @raise [Woods::ExtractionError] when one type+identifier is derived
+    #   from two different files
+    def deduplicate_type_units(type, units)
+      deduped = []
+      dropped = 0
+      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
 
-        Rails.logger.warn "[Woods] Deduplicated #{type}: dropped #{dropped} duplicate(s)" if dropped.positive?
+          dropped += 1
+          next
+        end
 
-        @results[type] = deduped
+        retained_paths[unit.identifier] = unit.file_path
+        deduped << unit
       end
+
+      Rails.logger.warn "[Woods] Deduplicated #{type}: dropped #{dropped} duplicate(s)" if dropped.positive?
+
+      deduped
+    end
+
+    # @param type [Symbol]
+    # @param unit [ExtractedUnit] The colliding (later) unit
+    # @param prior_path [String, nil] File path of the retained unit
+    # @return [String]
+    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'
     end
 
     # ──────────────────────────────────────────────────────────────────────
     # Flow Precomputation
     # ──────────────────────────────────────────────────────────────────────
 
+    # Full-path counterpart of {#refresh_incremental_flows}: assemble every
+    # controller's flows, annotate the in-memory units, rewrite them, and
+    # sweep orphans. Failure-closed — any error raises to {#extract_all},
+    # which aborts before write_manifest/publish_generation, so a partial
+    # flow index or half-rewritten annotations can never be published.
+    #
+    # @return [void]
+    # @raise [Woods::ExtractionError] when any flow-family step fails
     def precompute_flows
       all_units = @results.values.flatten(1)
-      precomputer = FlowPrecomputer.new(units: all_units, graph: @dependency_graph, output_dir: @output_dir.to_s)
+      precomputer = FlowPrecomputer.new(units: all_units, graph: @dependency_graph, output_dir: payload_dir.to_s)
       flow_map = precomputer.precompute
       rewrite_flow_annotated_units
+      sweep_orphaned_flow_files
       Rails.logger.info "[Woods] Precomputed #{flow_map.size} request flows"
-    rescue StandardError => e
-      Rails.logger.error "[Woods] Flow precomputation failed: #{e.message}"
     end
 
     # Precompute runs after write_results (FlowAssembler reads unit JSON
@@ -540,75 +1411,578 @@ module Woods
         annotated = units.select { |u| u.metadata[:flow_paths] }
         next if annotated.empty?
 
-        type_dir = @output_dir.join(type.to_s)
+        type_dir = payload_dir.join(type.to_s)
         annotated.each do |unit|
-          File.write(
+          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
-        File.write(
+        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
 
-    # ──────────────────────────────────────────────────────────────────────
-    # Git Enrichment
-    # ──────────────────────────────────────────────────────────────────────
-
-    def enrich_with_git_data
-      return unless git_available?
-
-      # Collect all file paths that need git data
-      file_paths = []
-      @results.each do |type, units|
-        next if %i[rails_source gem_source].include?(type)
+    # Incremental counterpart of Phase 5.5 (M3): the run's controller delta
+    # gets the same flow annotations a full run would give it, flow
+    # documents and flow_index.json are refreshed for the touched
+    # controllers while untouched controllers' entries carry forward, and
+    # flows/ documents no entry references are swept. Without this, a
+    # controller re-extracted incrementally lost metadata[:flow_paths],
+    # flow_index.json described pre-change routes, and flows/ files for
+    # deleted or renamed controllers persisted across every generation —
+    # seeded forward by PAYLOAD_DIRS.
+    #
+    # Runs inside {#finalize_incremental_run} so both extract_changed and
+    # refresh (whose routes cascade rewrites controllers wholesale) get it,
+    # and so a no-op run — which returns before this — leaves flows alone.
+    #
+    # Skip rule: the refresh participates whenever the gate is on and
+    # something is touched. A genuinely absent family — no flows/ directory,
+    # or an empty one — skips: there is nothing to carry forward, publication
+    # proceeds, and the next full extraction with the gate on builds the
+    # family. Once the family holds ANY artifact it is authoritative: a
+    # missing flow_index.json among documents, a corrupt one, a failed
+    # rehydration, write, patch, sweep, or type-index regeneration raises,
+    # and the raise propagates out of {#finalize_incremental_run} BEFORE
+    # {#publish_generation} — no generation bump, the preceding generation
+    # stays resolved and readable. ( woods:validate applies the same rule
+    # for a populated family without an index.)
+    #
+    # @param touched [Set<String>] identifiers added, re-extracted, or removed
+    # @return [void]
+    # @raise [Woods::ExtractionError] when authoritative flow state is
+    #   missing or corrupt, or a flow-family write fails
+    def refresh_incremental_flows(touched)
+      return unless Woods.configuration.precompute_flows
+      return if touched.empty?
+      return unless flow_family_present?
+
+      controllers_dir = payload_dir.join('controllers')
+      reextracted = touched.select { |id| controllers_dir.join(collision_safe_filename(id)).exist? }
+      removed = previous_flow_index_controllers & (touched.to_set - reextracted.to_set)
+      return if reextracted.empty? && removed.empty?
+
+      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: reassemble,
+        removed_identifiers: removed.to_a,
+        carried_identifiers: carried.map(&:identifier)
+      )
+      patch_flow_annotations(annotations)
+      sweep_orphaned_flow_files
+      # The annotation patch changed controller JSON after the run's type
+      # index regeneration; the index carries estimated_tokens, which the
+      # flow_paths are part of — a full run builds its index from the
+      # annotated in-memory units, so the incremental one re-derives it from
+      # the annotated files to match. A failure here raises like every
+      # other refresh failure.
+      regenerate_type_index(:controllers) if annotations.any?
+    end
 
-        units.each do |unit|
-          file_paths << unit.file_path if unit.file_path && File.exist?(unit.file_path)
-        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
 
-      # Batch-fetch all git data in minimal subprocess calls
-      git_data = batch_git_data(file_paths)
-      root = "#{Rails.root}/"
+    # 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
 
-      # Assign results to units
-      @results.each do |type, units|
-        next if %i[rails_source gem_source].include?(type)
+    # 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
 
-        units.each do |unit|
-          next unless unit.file_path
+    # 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
+    # refresh rather than publishing a delta-only index.
+    #
+    # @return [Boolean]
+    def flow_family_present?
+      flows_dir = payload_dir.join('flows')
+      return false unless flows_dir.directory?
 
-          relative = unit.file_path.sub(root, '')
-          unit.metadata[:git] = git_data[relative] if git_data[relative]
-        end
-      end
+      !Dir[flows_dir.join('*.json')].empty?
     end
 
-    # Normalize all unit file_paths to relative paths (relative to Rails.root).
+    # Controller identifiers that hold entries in the previous generation's
+    # flow_index.json. Only these can be flow-removed this run: a controller
+    # with no index entries has no documents to sweep and no annotation to
+    # clear.
     #
-    # Extractors set file_path via source_location, which returns absolute paths.
-    # This normalization ensures consistent relative paths (e.g., "app/models/user.rb")
-    # across all environments (local, Docker, CI) where Rails.root differs.
+    # The read is authoritative ({#flow_family_present?} guaranteed the
+    # family holds artifacts): a missing index among documents, or a corrupt
+    # one, raises so publication aborts.
     #
-    # Must run after enrich_with_git_data, which needs absolute paths for
-    # File.exist? checks and git log commands.
-    def normalize_file_paths
-      @results.each_value do |units|
-        units.each do |unit|
-          unit.file_path = normalize_file_path(unit.file_path)
-        end
-      end
+    # @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
 
-    # Strip Rails.root prefix from a file path, converting it to a relative path.
+    # The previous generation's flow index itself, read once per run: both
+    # the removal set and the reassembly partition are derived from it.
     #
-    # @param path [String, nil] Absolute or relative file path
-    # @return [String, nil] Relative path, or the original value if already relative,
-    #   nil, or not under Rails.root (e.g., a gem path)
+    # @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?
+
+      @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
+
+    # Rehydrate one unit from its payload JSON for the incremental flow
+    # pass. FlowPrecomputer only needs the identifier and the actions
+    # metadata; the source lives on disk, where FlowAssembler reads it.
+    #
+    # @param type_key [Symbol] extractor key naming the payload directory
+    # @param identifier [String]
+    # @return [ExtractedUnit, nil]
+    # @raise [Woods::ExtractionError] when the unit JSON does not parse —
+    #   skipping it would publish annotations against stale state
+    def unit_from_payload(type_key, identifier)
+      path = payload_dir.join(type_key.to_s, collision_safe_filename(identifier))
+      return unless File.exist?(path)
+
+      data = JSON.parse(AtomicFile.read(path))
+      unit = ExtractedUnit.new(
+        type: data['type'],
+        identifier: data['identifier'] || identifier,
+        file_path: data['file_path']
+      )
+      unit.metadata = data['metadata'] || {}
+      unit.source_code = data['source_code']
+      unit
+    rescue JSON::ParserError => e
+      raise Woods::ExtractionError, "could not rehydrate #{identifier} for flow refresh: #{e.message}"
+    end
+
+    # Write metadata[:flow_paths] into the re-extracted controllers' unit
+    # JSON — the incremental counterpart of {#rewrite_flow_annotated_units}.
+    # A controller with no flows this run loses any annotation a previous
+    # run had written, which is what a full run would have produced for the
+    # same tree. Read-compare-write, like {#rewrite_unit_json_of_type}; a
+    # read or write failure raises so publication aborts.
+    #
+    # @param annotations [Hash{String => Hash{String => String}}] from
+    #   {FlowPrecomputer#recompute_delta}
+    # @return [void]
+    def patch_flow_annotations(annotations)
+      annotations.each do |identifier, flow_paths|
+        path = payload_dir.join('controllers', collision_safe_filename(identifier))
+        next unless File.exist?(path)
+
+        data = JSON.parse(AtomicFile.read(path))
+        before = JSON.generate(data)
+
+        metadata = (data['metadata'] ||= {})
+        if flow_paths.any?
+          metadata['flow_paths'] = flow_paths
+        else
+          metadata.delete('flow_paths')
+        end
+        next if JSON.generate(data) == before
+
+        AtomicFile.write(path, json_serialize(data), durable: payload_writes_durable?)
+      end
+    end
+
+    # Remove flows/ documents no entry of flow_index.json references.
+    #
+    # Deliberately NOT part of {#sweep_orphaned_unit_files}: that sweep
+    # deletes per-type unit files no in-memory unit accounts for, while
+    # flows/ holds neither units nor an _index.json. The flow family is
+    # defined by flow_index.json's references, and this validates against
+    # exactly those (M3) — the same artifact the validator treats separately
+    # (G-2). Before this, a controller deleted or renamed incrementally left
+    # its flow documents behind forever.
+    #
+    # Reconciled skip rule: a genuinely empty directory is an absence and is
+    # skipped; a populated one whose index is missing, or an index that does
+    # not parse, is corruption and raises — with nothing to validate
+    # against, deleting every document would be the one outcome worse than
+    # keeping orphans. Failures raise so the incremental caller aborts
+    # publication.
+    #
+    # @return [void]
+    # @raise [Woods::ExtractionError] when authoritative flow state is
+    #   missing or corrupt
+    def sweep_orphaned_flow_files
+      flows_dir = payload_dir.join('flows')
+      return unless flows_dir.directory?
+
+      index_path = flows_dir.join('flow_index.json')
+      unless index_path.exist?
+        return if Dir[flows_dir.join('*.json')].empty?
+
+        raise Woods::ExtractionError, 'flows/ is populated but flow_index.json is missing'
+      end
+
+      keep = parse_flow_index_for_sweep(index_path)
+             .to_set { |relative| File.basename(relative.to_s) } << 'flow_index.json'
+      orphans = Dir[flows_dir.join('*.json').to_s].reject { |file| keep.include?(File.basename(file)) }
+      return if orphans.empty?
+
+      orphans.each { |file| FileUtils.rm_f(file) }
+      Rails.logger.info "[Woods] Swept #{orphans.size} orphaned flow file(s)"
+    end
+
+    # @param index_path [Pathname]
+    # @return [Array<String>] the referenced document paths
+    # @raise [Woods::ExtractionError] when the index does not parse
+    def parse_flow_index_for_sweep(index_path)
+      JSON.parse(AtomicFile.read(index_path)).values
+    rescue JSON::ParserError => e
+      raise Woods::ExtractionError, "flow_index.json does not parse: #{e.message}"
+    end
+
+    # ──────────────────────────────────────────────────────────────────────
+    # Git Enrichment
+    # ──────────────────────────────────────────────────────────────────────
+
+    def enrich_with_git_data
+      return unless git_available?
+
+      # Collect all file paths that need git data. Only app-owned paths under
+      # Rails.root qualify — see {#git_enrichable_path?}.
+      root = "#{Rails.root}/"
+      file_paths = []
+      @results.each do |type, units|
+        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)
+        end
+      end
+
+      # Batch-fetch all git data in minimal subprocess calls
+      git_data = batch_git_data(file_paths)
+
+      # Assign results to units
+      @results.each do |type, units|
+        next if %i[rails_source gem_source].include?(type)
+
+        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]
+        end
+      end
+    end
+
+    # Copy git facts onto graph nodes so the analyzer can read them without
+    # the units (an incremental run never holds every unit in memory).
+    #
+    # @return [void]
+    # build_file_metadata always emits commit_count and change_frequency together
+    # and non-nil, so no nil compaction is needed here (contrast annotate_node_from_git).
+    def annotate_graph_with_git_data
+      @results.each_value do |units|
+        units.each do |unit|
+          git = unit.metadata[:git]
+          next unless git.is_a?(Hash)
+
+          @dependency_graph.annotate(
+            unit.identifier,
+            type: unit.type,
+            commit_count: git[:commit_count],
+            change_frequency: git[:change_frequency]
+          )
+        end
+      end
+    end
+
+    # The one constructor for the analyzer both extraction paths use.
+    # `Woods.configuration` can be nil in specs that reset it; fall back to
+    # the analyzer's own default rather than raising mid-run.
+    #
+    # @return [GraphAnalyzer]
+    def build_graph_analyzer
+      config = Woods.configuration
+      ratio = config&.volatile_dependency_ratio || GraphAnalyzer::DEFAULT_VOLATILE_RATIO
+      GraphAnalyzer.new(
+        @dependency_graph,
+        volatile_ratio: ratio,
+        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
+
+    # ──────────────────────────────────────────────────────────────────────
+    # Package membership (#280)
+    # ──────────────────────────────────────────────────────────────────────
+
+    # The package extractor instance this run resolves membership through.
+    # Always built through {#extractor_for}, never `@extractors[:packages]`
+    # (the instance Phase 1 used to extract package units): reading that one
+    # would tie package-membership lookups to whichever instance happened to
+    # run first, instead of to this run's own memoized, on-demand build.
+    # Reset at the start of every run (both {#extract_all} and
+    # {#prepare_incremental_run}), so a later run never resolves membership
+    # against a prior run's package set.
+    #
+    # @return [Extractors::PackageExtractor]
+    def package_resolver
+      @package_resolver ||= extractor_for(:packages) || Extractors::PackageExtractor.new
+    end
+
+    # Set or clear metadata[:package] on one unit. Framework units and
+    # units with no path are never members. The key is deleted rather than
+    # set to nil so a unit outside every package serializes as before.
+    #
+    # `unit.file_path` may be absolute (the full path, before Phase 4.5
+    # relativization, and {#register_and_write}'s incremental path, before
+    # its own normalization) or Rails.root-relative (unit JSON already on
+    # disk); {Extractors::PackageExtractor#package_for} accepts either.
+    #
+    # @param unit [ExtractedUnit]
+    # @return [String, nil] the package name
+    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)
+      if package
+        unit.metadata[:package] = package
+      else
+        unit.metadata.delete(:package)
+      end
+      package
+    end
+
+    # Full-path pass over every extracted unit. Skipped entirely when the
+    # app declares no packages, so a non-Packwerk app's output is unchanged
+    # (I5): no work, and no `package` key on any unit or node.
+    #
+    # @return [void]
+    def annotate_packages
+      return if package_resolver.package_roots.empty?
+
+      @results.each_value { |units| units.each { |unit| annotate_package(unit) } }
+    end
+
+    # Incremental counterpart: when a package file changed, membership of
+    # units this run never touched may have changed too (a new package
+    # root, a renamed package). Walk the payload's unit JSON, rewrite the
+    # ones whose package differs, and annotate their nodes. Bounded to runs
+    # where a package trigger fired, which is rare; every other run pays
+    # nothing.
+    #
+    # @param change_set [ChangeSet]
+    # @param affected_types [Set<Symbol>]
+    # @return [Set<String>] identifiers rewritten
+    def reannotate_packages(change_set, affected_types)
+      keys = PathDispatcher.new.whole_app_keys_for_all(change_set.relative_paths)
+      return Set.new unless keys.include?(:packages)
+
+      Dir[payload_dir.join('*', '*.json').to_s].each_with_object(Set.new) do |file, touched|
+        next if File.basename(file) == '_index.json'
+
+        type_dir = File.basename(File.dirname(file))
+        next if type_dir == 'rails_source' || PAYLOAD_DIRS.include?(type_dir)
+
+        identifier = reannotate_unit_file(file, type_dir)
+        next unless identifier
+
+        touched.add(identifier)
+        affected_types&.add(type_dir.to_sym)
+      end
+    end
+
+    # @param file [String] absolute path to one unit JSON file
+    # @param type_dir [String] the extractor key directory it lives in
+    # @return [String, nil] the identifier when the file was rewritten
+    def reannotate_unit_file(file, type_dir)
+      data = JSON.parse(AtomicFile.read(file))
+      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
+
+      if package
+        metadata['package'] = package
+      else
+        metadata.delete('package')
+      end
+      AtomicFile.write(file, json_serialize(data), durable: payload_writes_durable?)
+
+      identifier = data['identifier']
+      type = (data['type'] || type_dir.singularize).to_sym
+      @dependency_graph.annotate(identifier, type: type, package: package)
+      identifier
+    rescue JSON::ParserError => e
+      Rails.logger.warn "[Woods] Could not re-annotate package on #{file}: #{e.message}"
+      nil
+    end
+
+    # 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
+    # vendored at `vendor/bundle` puts the same gem files under the root
+    # prefix, gitignored, so sending them is wasted pathspec work every run.
+    # Same exclusions as {Extractors::SharedUtilityMethods#app_source?}.
+    #
+    # @param path [String, nil] absolute file path
+    # @param root [String] Rails.root with a trailing separator
+    # @return [Boolean]
+    def git_enrichable_path?(path, root)
+      return false unless path&.start_with?(root)
+      return false if path.include?('/vendor/') || path.include?('/node_modules/')
+
+      File.exist?(path)
+    end
+
+    # Normalize all unit file_paths to relative paths (relative to Rails.root).
+    #
+    # Extractors set file_path via source_location, which returns absolute paths.
+    # This normalization ensures consistent relative paths (e.g., "app/models/user.rb")
+    # across all environments (local, Docker, CI) where Rails.root differs.
+    #
+    # Must run after enrich_with_git_data, which needs absolute paths for
+    # File.exist? checks and git log commands.
+    # Write a unit's JSON, unless the bytes on disk are already exactly that.
+    #
+    # A routes change replaces every `ROUTE_CONSUMER_EXTRACTORS` type wholesale
+    # — on a production-shaped host that measured 1,707 units, roughly a quarter
+    # of the index — and almost all of them re-serialize to the bytes already
+    # there. `AtomicFile.write` is a tempfile plus an fsync plus a rename each
+    # 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.
+    #
+    # Compared as bytes: `AtomicFile.write` is binmode, and the encoding a read
+    # comes back tagged with depends on the process's default external encoding
+    # (US-ASCII under `LANG=C`, which is where the daemon runs).
+    #
+    # @param path [Pathname] destination
+    # @param unit [ExtractedUnit] unit to serialize
+    # @return [void]
+    def write_unit_file(path, unit)
+      payload = json_serialize(unit.to_h)
+      return if identical_on_disk?(path, payload)
+
+      AtomicFile.write(path, payload, durable: payload_writes_durable?)
+    end
+
+    # The serialized `extracted_at` scalar as {ExtractedUnit#to_h} +
+    # {#json_serialize} emit it, compact or pretty. `Time#iso8601` produces
+    # 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.
+    EXTRACTED_AT_SCALAR =
+      /("extracted_at":\s*")\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:Z|[+-]\d{2}:\d{2})(?=")/
+    # An implementation detail of the byte comparison, not part of the
+    # extractor's surface (`private` does not scope constants).
+    private_constant :EXTRACTED_AT_SCALAR
+
+    # @return [Boolean] true when the file already holds exactly these bytes,
+    #   the `extracted_at` stamp aside
+    def identical_on_disk?(path, payload)
+      return false unless File.exist?(path)
+
+      mask_extracted_at(AtomicFile.read(path).b) == mask_extracted_at(payload.b)
+    rescue StandardError
+      # An unreadable or half-written file is not a match; fall through and
+      # rewrite it.
+      false
+    end
+
+    # Blank the `extracted_at` value so the byte comparison ignores it.
+    #
+    # {ExtractedUnit#to_h} stamps `extracted_at: Time.now.iso8601` on every
+    # serialization, so compared raw the two sides *always* differed across
+    # runs and the skip was inert (#208): every write did the comparison read
+    # and then paid the fsync anyway. Masked with a regex rather than parsed,
+    # because a JSON parse of both sides would cost more than the write being
+    # avoided. A skipped write leaves the older stamp on disk deliberately —
+    # the equivalence oracle (`spec/support/index_comparison.rb`) lists
+    # `extracted_at` in `VOLATILE_UNIT_KEYS`: "a unit an incremental run
+    # correctly left alone keeps an older stamp".
+    #
+    # @param bytes [String] serialized unit JSON, binary-tagged (`.b`) — the
+    #   ASCII-only pattern matches bytewise regardless of the content's
+    #   original encoding
+    # @return [String] the bytes with the stamp's value removed
+    def mask_extracted_at(bytes)
+      bytes.gsub(EXTRACTED_AT_SCALAR, '\1')
+    end
+
+    def normalize_file_paths
+      @results.each_value do |units|
+        units.each do |unit|
+          unit.file_path = normalize_file_path(unit.file_path)
+        end
+      end
+    end
+
+    # Strip Rails.root prefix from a file path, converting it to a relative path.
+    #
+    # @param path [String, nil] Absolute or relative file path
+    # @return [String, nil] Relative path, or the original value if already relative,
+    #   nil, or not under Rails.root (e.g., a gem path)
     def normalize_file_path(path)
       return path unless path
 
@@ -617,15 +1991,60 @@ module Woods
       path.start_with?(prefix) ? path.sub(prefix, '') : path
     end
 
+    # Can this run's git calls produce real facts?
+    #
+    # `rev-parse --git-dir` alone is not enough. Over a linked worktree whose
+    # private git directory is reachable but whose `commondir` is not, it
+    # answers while every ref lookup fails and `git log` exits 0 with nothing
+    # 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.
+    #
+    # Memoized, so the warning below is emitted at most once per run.
+    #
+    # @return [Boolean]
     def git_available?
       return @git_available if defined?(@git_available)
 
-      @git_available = begin
-        _, status = Open3.capture2('git', 'rev-parse', '--git-dir')
-        status.success?
-      rescue StandardError
-        false
-      end
+      _output, error, status = Open3.capture3(*git_argv('rev-parse', 'HEAD'))
+      @git_available = status.success?
+      warn_unresolvable_git(error) unless @git_available
+      @git_available
+    rescue StandardError
+      @git_available = 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.
+    #
+    # @param error [String] git's own stderr
+    # @return [void]
+    def warn_unresolvable_git(error)
+      return unless File.exist?(File.join(Rails.root.to_s, '.git'))
+
+      cause = error.to_s.lines.first.to_s.strip
+      Rails.logger.warn(
+        '[Woods] git cannot resolve HEAD for this working tree, so no unit will carry git ' \
+        "metadata: #{cause}. Over a linked worktree in a container, mount the canonical git " \
+        'directory and point WOODS_GIT_DIR at it; GIT_DIR alone is not enough, because the ' \
+        "worktree's private git directory reaches the shared one through a relative pointer."
+      )
+    end
+
+    # The git command line every enrichment call runs.
+    #
+    # `-C <root>` keeps the result independent of the process working
+    # directory. `WOODS_GIT_DIR` wins when set: it names the canonical git
+    # directory directly, which is the escape hatch for a container that can
+    # mount that directory but not the host path a worktree pointer names
+    # (B-181).
+    #
+    # @param args [Array<String>] git arguments
+    # @return [Array<String>] full argv
+    def git_argv(*args)
+      GitCommand.argv(Rails.root, *args)
     end
 
     # Safe git command execution — no shell interpolation
@@ -633,7 +2052,7 @@ module Woods
     # @param args [Array<String>] Git command arguments
     # @return [String] Command output (empty string on failure)
     def run_git(*args)
-      output, status = Open3.capture2('git', *args)
+      output, _error, status = Open3.capture3(*git_argv(*args))
       status.success? ? output.strip : ''
     rescue StandardError
       ''
@@ -641,13 +2060,18 @@ module Woods
 
     # 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
     def batch_git_data(file_paths)
       return {} if file_paths.empty?
 
       root = "#{Rails.root}/"
-      relative_paths = file_paths.map { |f| f.sub(root, '') }
+      relative_paths = file_paths.map { |f| f.sub(root, '') }.uniq
       result = {}
       relative_paths.each { |rp| result[rp] = {} }
 
@@ -735,23 +2159,91 @@ module Woods
 
     def write_results
       @results.each do |type, units|
-        type_dir = @output_dir.join(type.to_s)
+        type_dir = payload_dir.join(type.to_s)
 
         units.each do |unit|
-          File.write(
+          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
-        File.write(
+        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
 
+    # Delete unit JSON files in the just-written type directories that this
+    # full run did not write (#177).
+    #
+    # A full extraction never wipes the output directory —
+    # {#setup_output_directory} only mkdir_p's — so extracting into a
+    # directory that saw a different version of the app left the previous
+    # run's `<Unit>_<digest>.json` files behind. The manifest and the freshly
+    # written `_index.json` were correct, but the NEXT incremental run's
+    # {#regenerate_type_index} rebuilds the index from a disk glob of the type
+    # dir, resurrecting every orphan into the listed index, and
+    # {#persisted_counts} then writes the inflated counts into the manifest —
+    # orphans became listed, retrievable-by-listing units the graph knows
+    # nothing about. On a full run the in-memory `@results` are authoritative
+    # — the same argument {#rewrite_flow_annotated_units} makes for refusing
+    # the disk glob — so a unit file no current unit accounts for is stale by
+    # definition and is removed here.
+    #
+    # The boundary is deliberately narrow:
+    #
+    # * Only the per-type directories this run produced — `@results` keys —
+    #   are entered. When `include_framework_sources` gates rails_source out
+    #   of the run ({#skip_by_configuration?}), `@results` holds no
+    #   `:rails_source` key, so a knob-off full run leaves explicitly
+    #   extracted framework units (`woods:extract_framework`) alone — the
+    #   #169 preservation decision. Nothing outside those directories is
+    #   reachable: manifest, graph, generation, `woods.json`, `dumps/`,
+    #   `flows/` and the lock/status files all live in the output root or in
+    #   directories no extractor key names.
+    # * Only `*.json` directly inside a type dir is considered, and
+    #   `_index.json` is always kept. Non-JSON files and subdirectories are
+    #   never touched.
+    # * Legitimate names are exactly what {#write_results} just wrote —
+    #   {FilenameUtils#collision_safe_filename} over the type's deduped units
+    #   (which covers every unit type the extractor emits: gem_source shares
+    #   `@results[:rails_source]`). Legacy {FilenameUtils#safe_filename} names
+    #   carry no digest suffix, so they never match a current name and are by
+    #   definition orphans of a pre-collision-safe run.
+    #
+    # The incremental path deliberately has no counterpart: it holds only
+    # changed units in memory, so "not in memory" means nothing there —
+    # deletion on that path is driven by the graph and the change set
+    # ({#prune_vanished_units}, {#remove_replaced_units}).
+    #
+    # @return [void]
+    def sweep_orphaned_unit_files
+      @results.each do |type, units|
+        type_dir = payload_dir.join(type.to_s)
+        next unless type_dir.directory?
+
+        keep = units.to_set { |unit| collision_safe_filename(unit.identifier) }
+        keep << '_index.json'
+
+        orphans = Dir[type_dir.join('*.json').to_s].reject { |file| keep.include?(File.basename(file)) }
+        next if orphans.empty?
+
+        orphans.each { |file| FileUtils.rm_f(file) }
+        Rails.logger.info "[Woods] Swept #{orphans.size} orphaned unit file(s) from #{type}/"
+      end
+    rescue StandardError => e
+      # The extraction itself already succeeded; aborting the run over cleanup
+      # would trade orphaned files for a lost index. Error, not warn: the
+      # files this leaves behind are exactly what the next incremental run's
+      # disk glob resurrects.
+      Rails.logger.error "[Woods] Orphaned-unit sweep failed: #{e.message}"
+    end
+
     # Build the `_index.json` entry list for a set of in-memory units.
     # Shared by {#write_results} and {#rewrite_flow_annotated_units} so both
     # emit the index from the authoritative in-memory `@results` rather than
@@ -773,12 +2265,28 @@ module Woods
 
     def write_dependency_graph
       graph_data = @dependency_graph.to_h
-      graph_data[:pagerank] = @dependency_graph.pagerank
+      # Key-sorted for the same reason `to_h` sorts its own sections: the
+      # digest published as `graph_sha` covers these bytes, so node
+      # registration order must not reach it (B-180).
+      graph_data[:pagerank] = @dependency_graph.pagerank.sort_by { |identifier, _| identifier }.to_h
+
+      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
 
-      File.write(
-        @output_dir.join('dependency_graph.json'),
-        json_serialize(graph_data)
-      )
+    # 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
@@ -786,14 +2294,13 @@ module Woods
 
       enriched = @graph_analysis.merge(
         generated_at: Time.current.iso8601,
-        graph_sha: Digest::SHA256.hexdigest(
-          File.read(@output_dir.join('dependency_graph.json'))
-        )
+        graph_sha: graph_sha
       )
 
-      File.write(
-        @output_dir.join('graph_analysis.json'),
-        json_serialize(enriched)
+      AtomicFile.write(
+        payload_dir.join('graph_analysis.json'),
+        json_serialize(enriched),
+        durable: payload_writes_durable?
       )
     end
 
@@ -836,34 +2343,57 @@ module Woods
         schema_sha: schema_sha
       }
 
-      File.write(
-        @output_dir.join('manifest.json'),
-        json_serialize(manifest)
+      AtomicFile.write(
+        payload_dir.join('manifest.json'),
+        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
+      stats = persisted_index_stats
+      [stats.transform_values { |type_stats| type_stats[:count] },
+       stats.sum { |_type, type_stats| type_stats[:chunks] }]
+    end
 
-      Dir[@output_dir.join('*/_index.json').to_s].each do |index_path|
-        entries = JSON.parse(File.read(index_path))
-        counts[File.basename(File.dirname(index_path)).to_sym] = entries.size
-        chunks += entries.sum { |e| e['chunk_count'].to_i }
+    # 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.
@@ -876,10 +2406,10 @@ module Woods
     def capture_snapshot
       return unless Woods.configuration.enable_snapshots
 
-      manifest_path = @output_dir.join('manifest.json')
+      manifest_path = payload_dir.join('manifest.json')
       return unless manifest_path.exist?
 
-      manifest = JSON.parse(File.read(manifest_path))
+      manifest = JSON.parse(AtomicFile.read(manifest_path))
       # Snapshots are keyed on the commit SHA — an unresolvable provenance
       # ("unknown", see GitProvenance/#137) must not key or collide a snapshot.
       git_sha = manifest['git_sha']
@@ -932,32 +2462,39 @@ module Woods
     # category with count and top-5 namespace breakdown, rather than enumerating
     # every unit. Per-unit detail is available in the per-category _index.json files.
     #
+    # The full path derives its numbers from the in-memory results. An
+    # incremental run holds only changed units in memory, so it derives the
+    # same shape from the persisted per-type _index.json files — the same
+    # source {#persisted_counts} feeds the manifest from, which is what keeps
+    # SUMMARY.md's totals agreeing with manifest.json. (M4: the hardlinked
+    # previous generation's summary this path used to leave in place carried
+    # stale totals after any run that added or removed units.) The `Generated:`
+    # stamp keeps its meaning either way: it names the moment the summary was
+    # written.
+    #
     # @return [void]
     def write_structural_summary
-      return if @results.empty?
+      stats = @results.empty? ? persisted_summary_stats : results_summary_stats
+      return unless stats
 
-      total_units    = @results.values.sum(&:size)
-      total_chunks   = @results.sum { |_, units| units.sum { |u| [u.chunks.size, 1].max } }
-      category_count = @results.count { |_, units| units.any? }
+      total_units    = stats.sum { |_, s| s[:count] }
+      # Matches the manifest's count (`write_manifest`/`persisted_counts`
+      # both sum chunk counts directly) — the previous `[size, 1].max`
+      # floor made SUMMARY.md disagree with manifest.json for every
+      # unchunked unit.
+      total_chunks   = stats.sum { |_, s| s[:chunks] }
 
       summary = []
       summary << '# Codebase Index Summary'
       summary << "Generated: #{Time.current.iso8601}"
       summary << "Rails #{Rails.version} / Ruby #{RUBY_VERSION}"
-      summary << "Units: #{total_units} | Chunks: #{total_chunks} | Categories: #{category_count}"
+      summary << "Units: #{total_units} | Chunks: #{total_chunks} | Categories: #{stats.size}"
       summary << ''
 
-      @results.each do |type, units|
-        next if units.empty?
-
-        summary << "## #{type.to_s.titleize} (#{units.size})"
-
-        ns_counts = units
-                    .group_by { |u| u.namespace.nil? || u.namespace.empty? ? '(root)' : u.namespace }
-                    .transform_values(&:size)
-                    .sort_by { |_, count| -count }
-                    .first(5)
+      stats.each do |type, s|
+        summary << "## #{type.to_s.titleize} (#{s[:count]})"
 
+        ns_counts = s[:namespaces].sort_by { |_, count| -count }.first(5)
         ns_parts = ns_counts.map { |ns, count| "#{ns} #{count}" }
         summary << "Namespaces: #{ns_parts.join(', ')}" unless ns_parts.empty?
         summary << ''
@@ -979,25 +2516,75 @@ module Woods
           hub_names = significant_hubs.map { |h| h[:identifier] }.join(', ')
           summary << "- Hub nodes (>20 dependents): #{hub_names}"
         end
+
+        volatile = Array(@graph_analysis[:volatile_dependencies]).first(5)
+        if volatile.any?
+          lines = volatile.map { |v| "#{v[:from]} -> #{v[:to]} (#{v[:from_commits]} vs #{v[:to_commits]} commits)" }
+          summary << "- Volatile dependencies (top #{lines.size}): #{lines.join('; ')}"
+        end
       end
 
       summary << ''
 
-      File.write(
-        @output_dir.join('SUMMARY.md'),
-        summary.join("\n")
+      AtomicFile.write(
+        payload_dir.join('SUMMARY.md'),
+        summary.join("\n"),
+        durable: payload_writes_durable?
       )
     end
 
+    # Per-type `{ count:, chunks:, namespaces: }` for {#write_structural_summary},
+    # derived from the in-memory results a full extraction holds.
+    #
+    # @return [Hash{Symbol => Hash}]
+    def results_summary_stats
+      @results.each_with_object({}) do |(type, units), stats|
+        next if units.empty?
+
+        stats[type] = {
+          count: units.size,
+          chunks: units.sum { |u| u.chunks.size },
+          namespaces: namespace_histogram(units.map(&:namespace))
+        }
+      end
+    end
+
+    # The incremental path's counterpart to {#results_summary_stats}: the same
+    # 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 = persisted_index_stats.reject { |_type, type_stats| type_stats[:count].zero? }
+
+      stats.empty? ? nil : stats
+    end
+
+    # Group namespaces for a SUMMARY.md section: a missing or empty namespace
+    # is the root, everything else counts as-is.
+    #
+    # @param namespaces [Array<String, nil>]
+    # @return [Hash{String => Integer}]
+    def namespace_histogram(namespaces)
+      namespaces.group_by { |ns| ns.nil? || ns.empty? ? '(root)' : ns }
+                .transform_values(&:size)
+    end
+
     def regenerate_type_index(type_key)
-      type_dir = @output_dir.join(type_key.to_s)
+      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'
 
-        data = JSON.parse(File.read(file))
+        data = JSON.parse(AtomicFile.read(file))
         {
           identifier: data['identifier'],
           file_path: data['file_path'],
@@ -1010,15 +2597,25 @@ module Woods
         }
       end
 
-      File.write(
+      AtomicFile.write(
         type_dir.join('_index.json'),
-        json_serialize(index)
+        json_serialize(index),
+        durable: payload_writes_durable?
       )
     end
 
     # Token estimate for a unit parsed back from JSON, mirroring
     # ExtractedUnit#estimated_tokens (see docs/TOKEN_BENCHMARK.md).
     #
+    # `JSON.generate`, not `Hash#to_json`: with ActiveSupport loaded the
+    # latter applies HTML-safe escaping, rendering `>` as `\\u003e` — six
+    # characters where the file on disk has one. A model with
+    # `scope :recent, -> { ... }` in its metadata therefore estimated one
+    # token higher here than {ExtractedUnit#estimated_tokens} did over the
+    # same content, so a full and an incremental run disagreed on that unit's
+    # `_index.json` entry (#164). Both sides now measure the serialization
+    # {#json_serialize} actually writes.
+    #
     # @param data [Hash] Parsed unit JSON (string keys)
     # @return [Integer]
     def estimated_tokens_from(data)
@@ -1026,7 +2623,7 @@ module Woods
       metadata = data['metadata'] || {}
 
       source_tokens = source ? TokenUtils.estimate_tokens(source) : 0
-      metadata_tokens = metadata.any? ? TokenUtils.estimate_tokens(metadata.to_json) : 0
+      metadata_tokens = metadata.any? ? TokenUtils.estimate_tokens(JSON.generate(metadata)) : 0
       source_tokens + metadata_tokens
     end
 
@@ -1087,78 +2684,1026 @@ module Woods
     # Incremental Re-extraction
     # ──────────────────────────────────────────────────────────────────────
 
+    # Extractor instances are reused across a single incremental run, the way
+    # full extraction uses one instance per type. Several of them do real
+    # setup work in `initialize` (route-helper maps, routes maps), so a fresh
+    # instance per file would make an N-file change N times more expensive.
+    #
+    # @param key [Symbol] key into {EXTRACTORS}
+    # @return [Object, nil] the memoized extractor instance
+    def extractor_for(key)
+      @incremental_extractors ||= {}
+      return @incremental_extractors[key] if @incremental_extractors.key?(key)
+
+      @incremental_extractors[key] = EXTRACTORS[key]&.new
+    rescue StandardError => e
+      Rails.logger.warn "[Woods] Could not build #{key} extractor: #{e.message}"
+      @incremental_extractors[key] = nil
+    end
+
+    # ActiveRecord model names, needed by PoroExtractor to tell a plain class
+    # under app/models apart from a persisted model. Computed once per run.
+    #
+    # @return [Set<String>]
+    def active_record_names
+      @active_record_names ||=
+        if defined?(ActiveRecord::Base)
+          ActiveRecord::Base.descendants.filter_map(&:name).to_set
+        else
+          Set.new
+        end
+    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.
+    #
+    # This is the fix for #164 gap 1 (a path the index has never seen routed
+    # nowhere, so new files were silently ignored) and the per-path half of
+    # gap 3 (a file that defines several units — a `.rake` file with multiple
+    # tasks, an i18n YAML — could only ever resolve to one identifier).
+    # Reconciling the whole path at once means a task deleted from a
+    # multi-task file is removed rather than left behind.
+    #
+    # Removal is scoped to the unit types the matching rules could have
+    # produced, so a class-based unit sharing the path (the `User` model unit
+    # for `app/models/user.rb`) is never collaterally deleted here.
+    #
+    # @param change_set [ChangeSet]
+    # @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
+      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?
+
+        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
+          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))
+        end
+
+        next if raised
+
+        touched.merge(
+          prune_path_leftovers(absolute_path, rules, produced, affected_types)
+        )
+      end
+
+      touched
+    end
+
+    # Run one {PathDispatcher::Rule} against one file.
+    #
+    # @param rule [PathDispatcher::Rule]
+    # @param absolute_path [String]
+    # @return [Array<ExtractedUnit>, nil] the units the path defines, or nil
+    #   when the attempt says nothing about what it defines (see the rescue)
+    def extract_with_rule(rule, absolute_path)
+      extractor = extractor_for(rule.extractor_key)
+      # nil, not [] — the same distinction the rescue below defends (#198).
+      # {#extractor_for} rescues a raising *constructor* and memoizes nil, and
+      # nil fails the respond_to? guard — so a failed construction used to fall
+      # through to the [] "this path defines nothing any more" answer, and one
+      # 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 [].
+      return nil if extractor.nil?
+      return [] unless extractor.respond_to?(rule.method_name)
+
+      result =
+        if rule.extractor_key == :poros
+          # PoroExtractor needs the AR name set to reject persisted models;
+          # its default is an empty set, which would misfile every model
+          # under app/models as a PORO on the incremental path.
+          extractor.public_send(rule.method_name, absolute_path, ar_names: active_record_names)
+        else
+          extractor.public_send(rule.method_name, absolute_path)
+        end
+
+      Array(result).compact
+    rescue StandardError => e
+      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
+      # returning [] here turns a *transient* failure (a watcher batch catching
+      # an editor mid-write, an encoding hiccup) into silent deletion of a
+      # perfectly good unit, which nothing restores until that file is next
+      # touched. "Extraction raised" and "extracted successfully, defines
+      # nothing" are different answers and only the second licenses a prune.
+      nil
+    end
+
+    # Remove units the graph still attributes to a path that the path no
+    # longer produces — but only for the types the matching rules cover.
+    #
+    # @param absolute_path [String]
+    # @param rules [Array<PathDispatcher::Rule>]
+    # @param produced [Set<Array(String, Symbol)>] (identifier, type) pairs
+    #   just extracted from the path
+    # @param affected_types [Set<Symbol>]
+    # @return [Set<String>] identifiers removed
+    def prune_path_leftovers(absolute_path, rules, produced, affected_types)
+      covered_keys = rules.to_set(&:extractor_key)
+      removed = Set.new
+
+      @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])
+
+        removed.add(identifier) if remove_unit(identifier, affected_types, type: node_type)
+      end
+
+      removed
+    end
+
+    # Reconcile class-based types against their runtime discovery sets.
+    #
+    # Models, controllers, mailers, components and channels are discovered by
+    # walking descendants, not by globbing files, so a class added since the
+    # last extraction is invisible to any path-based dispatch. Comparing each
+    # extractor's `discoverable_classes` against the identifiers already in
+    # the graph finds exactly those additions, using the same discovery code
+    # a full extraction uses.
+    #
+    # Removals are handled here too, but only against a *complete* discovery
+    # set — see {#stale_class_based_units} for why that qualifier carries the
+    # whole safety argument.
+    #
+    # @param affected_types [Set<Symbol>]
+    # @return [Set<String>] identifiers added or removed
+    def reconcile_class_based_types(affected_types, except: nil)
+      touched = Set.new
+      excluded = except&.to_set || Set.new
+
+      CLASS_BASED_DISCOVERY.each do |key, spec|
+        extractor = extractor_for(key)
+        next unless extractor.respond_to?(:discoverable_classes)
+
+        discovered = extractor.discoverable_classes.reject { |k| k.name.nil? }
+        known = Array(spec[:types] || spec[:type])
+                .flat_map { |type| @dependency_graph.units_of_type(type) }.to_set
+
+        touched.merge(add_discovered_classes(key, spec, discovered, known, excluded, affected_types))
+        next if spec[:reconcile_removals] == false
+
+        touched.merge(remove_stale_classes(spec, discovered, known, affected_types))
+      end
+
+      touched
+    end
+
+    # Pruned class-based identifiers the tree still governs, and that the
+    # second reconciliation pass may therefore re-add.
+    #
+    # The class-based *move* shape — the file moved, the constant did not
+    # (M1) — prunes the unit for the vanished old path while the class stays
+    # in the discovery set; the move target is a changed file the active
+    # loader governs for exactly that constant, so re-adding produces the
+    # unit a full extraction produces. The *deletion* shape must stay
+    # pruned: without a reload a constant outlives the file that defined
+    # it, so liveness alone proves nothing.
+    #
+    # Identity is loader-derived, not textual: {SourceNesting#
+    # governed_class_name} returns the constant path the active Zeitwerk
+    # loader expects the changed file to define (its inflector, ignores,
+    # and root namespaces decide, via +cpath_expected_at+), gated on the
+    # file actually declaring it. A loader non-claim — an unmanaged or
+    # declined path — is authoritative and re-adds nothing, exactly the
+    # governed-naming contract. That kills the two resurrection shapes a
+    # demodulized class-name regex allowed: a changed file declaring
+    # `Public::User` no longer resurrects a pruned `Admin::User`, and a
+    # file whose comments or string literals mention `class User` no
+    # longer resurrects anything.
+    #
+    # @param pruned [Set<String>] identifiers removed by {#prune_vanished_units}
+    # @param change_set [ChangeSet]
+    # @return [Set<String>] identifiers safe to re-add this run
+    def readdable_pruned_classes(pruned, change_set)
+      readdable = Set.new
+      return readdable if pruned.empty?
+
+      claimed = changed_governed_names(change_set)
+      return readdable if claimed.empty?
+
+      CLASS_BASED_DISCOVERY.each_key do |key|
+        extractor = extractor_for(key)
+        next unless extractor.respond_to?(:discoverable_classes)
+
+        extractor.discoverable_classes.each do |klass|
+          next if klass.name.nil? || !pruned.include?(klass.name)
+
+          readdable.add(klass.name) if claimed.include?(klass.name)
+        end
+      end
+
+      readdable
+    rescue StandardError => e
+      # A failure here must not turn a deletion into a resurrection: the
+      # empty set keeps every pruned identifier excluded, which is the
+      # pre-M1 behavior.
+      Rails.logger.warn "[Woods] Could not determine re-addable pruned classes: #{e.message}"
+      Set.new
+    end
+
+    # Governed constant names of the change set's still-existing Ruby
+    # files. The shared governed-naming helper consults the active Zeitwerk
+    # loader and returns nil for anything it does not claim, so unmanaged
+    # paths (anything outside the loader's roots, under an old Zeitwerk
+    # without +cpath_expected_at+, or a declined file) contribute nothing.
+    #
+    # @param change_set [ChangeSet]
+    # @return [Set<String>] governed constant names of changed files
+    def changed_governed_names(change_set)
+      change_set.existing_paths.filter_map do |path|
+        path = path.to_s
+        next unless path.end_with?('.rb')
+
+        governed_class_name(path, File.read(path))
+      end.compact.to_set
+    end
+
+    def add_discovered_classes(key, spec, discovered, known, excluded, affected_types)
+      new_classes = discovered.reject { |k| known.include?(k.name) || excluded.include?(k.name) }
+      return Set.new if new_classes.empty?
+
+      units = new_classes.filter_map do |klass|
+        extractor_for(key).public_send(spec[:method], klass)
+      rescue StandardError => e
+        Rails.logger.warn "[Woods] #{key} extraction of #{klass} failed: #{e.message}"
+        nil
+      end
+
+      register_and_write(key, units, affected_types)
+    end
+
+    def remove_stale_classes(spec, discovered, known, affected_types)
+      stale = stale_class_based_units(spec[:type], discovered, known)
+      return Set.new if stale.empty?
+
+      Rails.logger.info "[Woods] removing #{stale.size} #{spec[:type]} unit(s) whose class no longer exists"
+      stale.each_with_object(Set.new) do |identifier, removed|
+        removed.add(identifier) if remove_unit(identifier, affected_types, type: spec[:type])
+      end
+    end
+
+    # Class-based units the graph still holds that a full extraction would not
+    # produce.
+    #
+    # {#prune_vanished_units} keys on the source file being gone, which cannot
+    # see this case: a class removed from a file that still exists leaves no
+    # missing path, and class-based units register a *convention* path derived
+    # from the constant name, so a class defined somewhere unconventional was
+    # never attributed to the file it actually lived in. Two models in one
+    # `.rb`, one of them deleted, and the survivor's own re-extraction says
+    # nothing about the other. Nothing else in the run removes it, so it
+    # outlives every subsequent incremental — a permanent divergence from a
+    # full run, not a transient one.
+    #
+    # For all six class-based extractors `extract_all` is literally
+    # `discoverable_classes.map { ... }.compact`, so absence from that set is
+    # exactly "a full extraction would not produce this" — the equivalence the
+    # incremental path is held to.
+    #
+    # The `@eager_load_complete` gate is the whole safety argument, and it is
+    # why this is not simply the inverse of the addition pass:
+    #
+    # * **A partial eager load.** The documented NameError fallback loads only
+    #   `EXTRACTION_DIRECTORIES`, so descendants are known-incomplete and the
+    #   difference here would be most of the app. Deleting by the type is far
+    #   worse than a stale unit, so a partial load removes nothing.
+    # * **A constant outliving its file.** A resident daemon that has not
+    #   reloaded still holds a deleted class as a descendant, so it is *in* the
+    #   set and not stale — which is correct for that process, and the
+    #   subsequent reload is what makes it removable.
+    #
+    # @param type [Symbol] unit type
+    # @param discovered [Array<Class>] the extractor's current discovery set
+    # @param known [Set<String>] identifiers of that type already in the graph
+    # @return [Array<String>] identifiers to remove
+    def stale_class_based_units(type, discovered, known)
+      return [] unless @eager_load_complete
+
+      live = discovered.to_set(&:name)
+      known.reject { |identifier| live.include?(identifier) }
+           # Not redundant with `units_of_type`: an identifier can be listed in
+           # this type's index while also naming a unit of another type, and
+           # the caller removes by (identifier, type), so it has to be told
+           # which node it is allowed to take.
+           .select { |identifier| @dependency_graph.node_types(identifier).include?(type) }
+    end
+
+    # Re-run whole-app extractors whose trigger paths changed, replacing that
+    # unit type wholesale.
+    #
+    # These extractors have no per-file entry point — a route unit is derived
+    # from `Rails.application.routes`, the middleware unit from the live
+    # stack, events from a two-pass scan of all of `app/`. Before this,
+    # incremental runs skipped them entirely, so a routes-only change
+    # triggered a run that re-extracted nothing while still rewriting the
+    # manifest (#164 gap 4). In an already-booted process re-running them is
+    # cheap, which is what makes wholesale replacement the right shape.
+    #
+    # @param change_set [ChangeSet]
+    # @param affected_types [Set<Symbol>]
+    # @return [Set<String>] identifiers written or removed
+    def rerun_whole_app_extractors(change_set, affected_types)
+      keys = PathDispatcher.new.whole_app_keys_for_all(change_set.relative_paths)
+      # The dispatch rules are configuration-blind (memoized per-process), so
+      # the configuration gate applies here — a knob-off host must not re-run
+      # an extractor whose units a full extraction of the same tree would not
+      # produce. See {#skip_by_configuration?}.
+      keys = keys.reject { |key| skip_by_configuration?(key) }.to_set
+      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))
+      end
+    end
+
+    # Replace every unit an extractor owns with a fresh extraction.
+    #
+    # Units of the extractor's types that the fresh run no longer produces are
+    # removed, which is what makes this a replacement rather than an upsert —
+    # 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
+    # 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
+    # with no unit file — `dependencies`/`dependents` reported `found: true`
+    # while lookup returned nil. The counter from {#note_wholesale_mutation}
+    # turns any such failure into a re-raise: the run aborts before
+    # {#publish_generation}, and the preceding generation stays resolved, the
+    # same posture the flow family takes on the full path.
+    #
+    # Two counter rules make that decision sound. The marker is placed BEFORE
+    # each mutation, because registration itself can fail mid-mutation (a
+    # malformed dependency raises after the node is inserted) and a rm_f can
+    # fail part-way; a marker placed after the fact would miss the window it
+    # exists for, at the cost of a conservative abort when the marked mutation
+    # 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.
+    #
+    # @param key [Symbol] extractor key
+    # @param affected_types [Set<Symbol>]
+    # @return [Set<String>] identifiers written or removed
+    # @raise [Woods::ExtractionError] when the replacement failed after
+    #   mutating durable state
+    def replace_type_wholesale(key, affected_types)
+      extractor = extractor_for(key)
+      return Set.new unless extractor.respond_to?(:extract_all)
+
+      @wholesale_mutations = 0
+      units = Array(extractor.extract_all).compact.uniq(&:identifier)
+      Rails.logger.info "[Woods] Re-ran #{key} wholesale: #{units.size} units"
+
+      touched = register_and_write(key, units, affected_types)
+      touched.merge(remove_replaced_units(key, units, affected_types))
+    rescue StandardError => e
+      if @wholesale_mutations.to_i.positive?
+        raise Woods::ExtractionError, <<~MSG.tr("\n", ' ').strip
+          Wholesale re-run of #{key} failed after this run had already
+          registered, written, or removed #{@wholesale_mutations} unit
+          artifact(s) (#{e.class}: #{e.message}). Continuing would publish a
+          generation whose dependency graph disagrees with the unit files on
+          disk, so the run aborts before publication and the previous
+          generation stays resolved.
+        MSG
+      end
+
+      Rails.logger.error "[Woods] Wholesale re-run of #{key} failed: #{e.message}"
+      Set.new
+    end
+
+    # Record that the in-flight wholesale replacement is about to mutate state
+    # a published generation would carry: a graph registration, a unit-file
+    # write, or a unit-file removal. Callers mark BEFORE mutating — register
+    # itself can raise mid-mutation (a malformed dependency raises after the
+    # node is inserted), so a marker placed after the fact can miss the very
+    # window it exists for. The cost is a conservative abort when the marked
+    # mutation then fails before changing anything; that direction is safe.
+    # {#replace_type_wholesale} resets the counter to 0 before `extract_all` —
+    # so only the current key's wholesale pass contributes, never the earlier
+    # reconcile passes that share {#register_and_write} — and re-raises from
+    # its rescue when the count is non-zero. Increments from non-wholesale
+    # callers of {#register_and_write} are inert outside that window: nothing
+    # reads the counter between resets.
+    #
+    # @return [void]
+    def note_wholesale_mutation
+      @wholesale_mutations = @wholesale_mutations.to_i + 1
+    end
+
+    # The removal half of a wholesale replacement: drop every unit of `key`'s
+    # types that the fresh run no longer produced.
+    #
+    # Gated exactly the way {#stale_class_based_units} is, and for the same
+    # reason (#198): for the extractors in {CLASS_BASED_DISCOVERY},
+    # `extract_all` is `discoverable_classes.map { ... }` — a function of the
+    # runtime descendants — so on the documented NameError-fallback boot the
+    # fresh set is known-partial and "absent from it" does not mean "deleted".
+    # The reconciler's gate ("the whole safety argument") never protected this
+    # path, and {ROUTE_CONSUMER_EXTRACTORS} routes four descendants-discovered
+    # types through here on *every* routes change — so one routes edit on a
+    # fallback boot mass-deleted most controller units. Registration above is
+    # not gated: additions are safe against a partial set (the same asymmetry
+    # {#reconcile_class_based_types} relies on); only removal needs the
+    # complete one.
+    #
+    # File-derived whole-app types (routes, view_templates, events, ...) keep
+    # unconditional removal — their `extract_all` globs files or introspects
+    # structures that do not depend on eager loading, so their fresh set is
+    # authoritative on any boot.
+    #
+    # The skip is warned, not silent: until a run with a clean boot removes
+    # them, the type may hold stale units, and an operator chasing a ghost
+    # unit needs to know which run declined to delete it and why.
+    #
+    # `fresh` is computed PER unit_type, not once for the whole extractor key
+    # (#225). An identifier is not unique across types — a Scenic view and a
+    # factory can both be named `reports` — so a single identifier-level
+    # `fresh` set let a factories re-run's `database_view` deletion pass see
+    # the surviving `factories` identifier as "still fresh" and skip removing
+    # nothing, then later delete both nodes anyway once `remove_unit` was
+    # called without `type:` (the same call also had to be fixed — see
+    # below). A per-type set also covers a unit reclassified between two
+    # types this same key owns (GraphQL's four): the old type's identifier is
+    # absent from ITS OWN fresh set even though the identifier as a whole is
+    # still "fresh" under the new type, so the stale old-type node is
+    # correctly dropped instead of surviving because the identifier still
+    # exists somewhere in the extractor's output.
+    #
+    # `remove_unit` is called WITH `type: unit_type` for the same reason:
+    # `DependencyGraph#remove`'s own doc warns that a typeless removal fans
+    # over every type registered under the identifier, so calling it here
+    # without `type:` deleted the sibling type's node and JSON file too —
+    # reproduced live as a factories re-run deleting a same-named Scenic-view
+    # unit.
+    #
+    # @param key [Symbol] extractor key
+    # @param units [Array<ExtractedUnit>] the fresh extraction
+    # @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
+        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'
+        )
+        return Set.new
+      end
+
+      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|
+          removed.add(stale) if remove_unit(stale, affected_types, type: unit_type)
+        end
+      end
+    end
+
+    # Prune units whose source file no longer exists (#164 gap 2).
+    #
+    # Two inputs, with deliberately different authority:
+    #
+    # * **The change set.** A path the caller reports as changed which is no
+    #   longer on disk is authoritative — every unit the graph attributes to
+    #   it goes, whatever its type. This is the path that handles a deleted
+    #   model or controller, and the old side of a rename (git's
+    #   `--no-renames` semantics).
+    # * **A sweep** over registered paths, for callers whose change set is
+    #   incomplete: a git diff that omits deletions, a watcher that missed an
+    #   unlink, a branch switch. The sweep is a heuristic, so it is bounded
+    #   twice — see {#sweep_candidates} and the class-based exclusion below.
+    #
+    # Only paths under `Rails.root` are considered either way. Framework
+    # units point at gem paths, and an index restored from a CI artifact can
+    # carry paths produced under a different root; neither is a deletion.
+    #
+    # @param change_set [ChangeSet]
+    # @param affected_types [Set<Symbol>]
+    # @return [Set<String>] identifiers removed
+    def prune_vanished_units(change_set, affected_types)
+      removed = prune_paths(change_set.missing_paths, affected_types, class_based: true)
+      removed.merge(prune_paths(sweep_candidates(change_set), affected_types, class_based: false))
+
+      Rails.logger.info "[Woods] Pruned #{removed.size} unit(s) whose source file is gone" if removed.any?
+      removed
+    end
+
+    # Registered paths that have vanished and that the sweep is allowed to act
+    # on: under Rails.root, gone from disk, and claimed by a file dispatch
+    # rule.
+    #
+    # The file-rule bound exists because some units point at a *nominal* path
+    # rather than a source file — `BehavioralProfile` names
+    # `config/application.rb`, which no rule claims — and sweeping those would
+    # delete units a full extraction still produces.
+    #
+    # @param change_set [ChangeSet]
+    # @return [Array<String>] absolute paths
+    def sweep_candidates(change_set)
+      root_prefix = "#{Rails.root}/"
+      dispatcher = PathDispatcher.new
+      already_named = change_set.missing_paths.to_set
+
+      @dependency_graph.registered_paths.reject do |path|
+        already_named.include?(path) ||
+          !path.to_s.start_with?(root_prefix) ||
+          File.exist?(path) ||
+          dispatcher.file_rules_for(change_set.relativize(path)).empty?
+      end
+    end
+
+    # Remove every unit the graph attributes to each of `paths`.
+    #
+    # @param paths [Enumerable<String>] absolute paths believed to be gone
+    # @param affected_types [Set<Symbol>]
+    # @param class_based [Boolean] whether class-based units may be pruned
+    # @return [Set<String>] identifiers removed
+    def prune_paths(paths, affected_types, class_based:)
+      root_prefix = "#{Rails.root}/"
+
+      paths.each_with_object(Set.new) do |path, removed|
+        next unless path.to_s.start_with?(root_prefix)
+        next if File.exist?(path)
+
+        @dependency_graph.units_for_path(path).each do |identifier, type|
+          next if !class_based && convention_path_unit?(type)
+
+          removed.add(identifier) if remove_unit(identifier, affected_types, type: type)
+        end
+      end
+    end
+
+    # Does this unit's `file_path` name a *convention* that need not exist?
+    #
+    # The sweep deletes units whose file is gone, which is wrong for anything
+    # that derives its path from a constant name rather than from a file it was
+    # read out of. Class-based types have always been excluded for that reason.
+    #
+    # Today the predicate keys on {CLASS_BASED} and nothing else (L4): the six
+    # class-based families — models, controllers, components, view components,
+    # mailers, channels. GRAPHQL_TYPES are deliberately NOT spared. An earlier
+    # version of this comment narrated GraphQL units being spared through a
+    # `source_file_for_class` convention-path fallback, but that fallback now
+    # returns nil rather than fabricating a convention path
+    # (`graphql_extractor.rb`), a runtime-defined GraphQL unit registers no
+    # path at all ({DependencyGraph#register} skips nil), and the static file
+    # pass records the real file it read — so the sweep's own bounds decide,
+    # and this predicate has no say in GraphQL either way.
+    #
+    # The original case: on Rails < 7.1 `ActiveRecord::SchemaMigration` and
+    # `InternalMetadata` are real `ActiveRecord::Base` descendants a full
+    # extraction emits with `app/models/active_record/schema_migration.rb` as
+    # their path — a file no application has, and one the PORO rule *does*
+    # claim, so the sweep's file-rule bound doesn't cover it and this check has
+    # to. Deleting such a unit requires the caller to name the path; the sweep
+    # never infers it.
+    #
+    # KNOWN COST (B-070 / #171): this keys on unit *type*, but the property is
+    # per-unit — CLASS_BASED is also true of units whose recorded path has
+    # since been moved elsewhere, which is exactly the move shape
+    # {#readdable_pruned_classes} exists to re-add in the same run. For
+    # deletions the cost stays: a class-based unit whose file is gone survives
+    # an unnamed-path sweep. Named-path deletion still works, so
+    # `woods:incremental` on a git diff is unaffected; the exposed caller is the
+    # daemon's catch-up, which runs an empty change set precisely because
+    # deletions leave no mtime.
+    #
+    # Two obvious fixes were tried and **both are wrong** — do not re-attempt
+    # them without reading this:
+    #
+    # 1. *Compare the recorded path against the convention path derived from the
+    #    constant.* `Types::ForgottenType` conventionally lives at
+    #    `app/graphql/types/forgotten_type.rb`, which IS its convention path — so
+    #    a conventionally-named file-defined type is indistinguishable from a
+    #    runtime-defined one, and the common case stays spared. Disproven by
+    #    `spec/integration/incremental_equivalence_spec.rb`'s pending example.
+    # 2. *Let the sweep prune GraphQL and rely on the reconciler's addition half
+    #    to re-add whatever the schema still holds.* This is what `except: pruned`
+    #    exists to prevent (see the comment at its call site): without a reload a
+    #    constant outlives its deleted file, and the re-add resurrects the deleted
+    #    unit against a path that no longer exists — permanently, since the sweep
+    #    then spares it.
+    #
+    # What would actually work is provenance: record at extraction time whether a
+    # source file existed for the unit and spare only the units that never had
+    # one. That needs the graph node to carry the flag, so it is a serialization
+    # change rather than a predicate tweak.
+    #
+    # @param type [Symbol, nil] the unit type the caller is about to remove
+    # @return [Boolean]
+    def convention_path_unit?(type)
+      CLASS_BASED.key?(type)
+    end
+
+    # Register a batch of freshly-extracted units and write their JSON.
+    #
+    # Registration happens BEFORE path normalization — the graph's file map
+    # stores absolute paths (that is what changed files are matched against),
+    # exactly as full extraction registers in Phase 1 and only normalizes in
+    # Phase 4.5. Unit JSON carries the relative path.
+    #
+    # @param extractor_key [Symbol]
+    # @param units [Array<ExtractedUnit>]
+    # @param affected_types [Set<Symbol>]
+    # @return [Set<String>] identifiers written
+    def register_and_write(extractor_key, units, affected_types)
+      units = Array(units).compact
+      return Set.new if units.empty?
+
+      affected_types&.add(extractor_key)
+      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)
+        mark_dependents_dirty(unit.identifier)
+        # Marked BEFORE registration: DependencyGraph#register inserts the
+        # node before it iterates the unit's dependencies, so a malformed
+        # dependency raises with the graph already mutated — a marker placed
+        # after the call would never run, and the phantom would ship. The
+        # cost of this ordering is a conservative abort when registration
+        # fails before mutating anything; that is the safe direction to err
+        # in. See {#note_wholesale_mutation}.
+        note_wholesale_mutation
+        @dependency_graph.register(unit)
+        mark_dependents_dirty(unit.identifier)
+
+        unit.file_path = normalize_file_path(unit.file_path)
+        # Keyed by relative path, which is how batch_git_data keys its result.
+        (@incremental_written ||= {})[unit.identifier] = unit.file_path
+
+        write_unit_file(type_dir.join(collision_safe_filename(unit.identifier)), unit)
+        written.add(unit.identifier)
+      end
+    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
+    # name units of several types (a Scenic view `reports` and a factory
+    # `reports`), each with its own `<extractor_key>/<identifier>.json`, and
+    # removing the identifier wholesale takes the sibling with it.
+    #
+    # @param identifier [String]
+    # @param affected_types [Set<Symbol>]
+    # @param type [Symbol, nil] remove only this type; without it, every type
+    #   registered under the identifier
+    # @return [String, nil] the identifier when it existed and was removed
+    def remove_unit(identifier, affected_types, type: nil)
+      types = type ? [type] : @dependency_graph.node_types(identifier)
+      types = types.select { |t| @dependency_graph.node(identifier, type: t) }
+      return nil if types.empty?
+
+      # Before the removals: this reads the identifier's forward edges, which
+      # go with the nodes.
+      mark_dependents_dirty(identifier)
+
+      types.each { |t| remove_unit_of_type(identifier, t, affected_types) }
+      Rails.logger.debug { "[Woods] Removed #{identifier}" }
+      identifier
+    end
+
+    # @param identifier [String]
+    # @param type [Symbol]
+    # @param affected_types [Set<Symbol>]
+    # @return [void]
+    def remove_unit_of_type(identifier, type, affected_types)
+      extractor_key = TYPE_TO_EXTRACTOR_KEY[type]
+
+      if extractor_key
+        affected_types&.add(extractor_key)
+        path = payload_dir.join(extractor_key.to_s, collision_safe_filename(identifier))
+        # Marked BEFORE the removal, same ordering as the write half: a
+        # rm_f that fails part-way (or a failure immediately after it) must
+        # not leave the counter at zero while the file is already gone. See
+        # {#note_wholesale_mutation}.
+        note_wholesale_mutation
+        FileUtils.rm_f(path)
+      end
+
+      @dependency_graph.remove(identifier, type: type)
+    end
+
+    # Record that a unit's edges changed, so every target it points at (and
+    # the unit itself) has its `dependents` list rewritten at the end of the
+    # run.
+    #
+    # @param identifier [String]
+    # @return [void]
+    def mark_dependents_dirty(identifier)
+      @dependents_dirty ||= Set.new
+      @dependents_dirty.add(identifier)
+      @dependency_graph.dependencies_of(identifier).each { |target| @dependents_dirty.add(target) }
+    end
+
+    # Second pass over the unit JSON an incremental run touched, mirroring the
+    # two full-extraction phases that operate on already-extracted units:
+    # {#resolve_dependents} (Phase 2) and {#enrich_with_git_data} (Phase 4).
+    #
+    # Both were full-extraction-only, so incremental runs left `dependents`
+    # and `metadata.git` frozen at whatever the last full run wrote —
+    # divergence that compounds run over run in an incremental CI chain.
+    #
+    # @param affected_types [Set<Symbol>]
+    # @return [void]
+    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)
+
+      (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
+
+    # Read one unit's JSON, apply the second-pass patches, and write it back
+    # only if something actually changed.
+    #
+    # @param identifier [String]
+    # @param affected_types [Set<Symbol>]
+    # @param refresh_dependents [Boolean]
+    # @param git_data [Hash{String => Hash}, nil] batch git data keyed by
+    #   relative path (per {#batch_git_data}), or nil when this identifier
+    #   isn't git-dirty this run
+    # @return [void]
+    def rewrite_unit_json(identifier, affected_types, refresh_dependents:, git_data:)
+      @dependency_graph.node_types(identifier).each do |type|
+        rewrite_unit_json_of_type(identifier, type, affected_types,
+                                  refresh_dependents: refresh_dependents, git_data: git_data)
+      end
+    end
+
+    # One (identifier, type) pair's JSON. The `dependents` list is a property
+    # of the identifier, not of the type, so every file the identifier owns
+    # gets the same refreshed list — which is what a full extraction writes.
+    #
+    # Git metadata is NOT a property of the identifier (#225): a colliding
+    # identifier's types each have their own `file_path` (a Scenic view and a
+    # factory both named `reports` live in different files with different
+    # histories), so this resolves git data against THIS type's own node
+    # rather than a single pre-resolved hash shared across every type — the
+    # previous shape let one type's commit history land in every colliding
+    # type's `metadata.git`, keyed by whichever type {#register_and_write}
+    # happened to touch last for that identifier.
+    #
+    # @param identifier [String]
+    # @param type [Symbol]
+    # @param affected_types [Set<Symbol>]
+    # @param refresh_dependents [Boolean]
+    # @param git_data [Hash{String => Hash}, nil]
+    # @return [void]
+    def rewrite_unit_json_of_type(identifier, type, affected_types, refresh_dependents:, git_data:)
+      extractor_key = TYPE_TO_EXTRACTOR_KEY[type]
+      return unless extractor_key
+
+      path = payload_dir.join(extractor_key.to_s, collision_safe_filename(identifier))
+      return unless File.exist?(path)
+
+      data = JSON.parse(AtomicFile.read(path))
+      # Serialized comparison, not `data.dup`: the git patch mutates the
+      # nested metadata hash in place, which a shallow copy would follow.
+      before = JSON.generate(data)
+
+      if refresh_dependents
+        data['dependents'] = @dependency_graph.dependents_detail(identifier)
+                                              .map { |d| { 'type' => d[:type].to_s, 'identifier' => d[:identifier] } }
+      end
+
+      git = git_data && git_for_type(identifier, type, git_data)
+      if git
+        (data['metadata'] ||= {})['git'] = JSON.parse(JSON.generate(git))
+        annotate_node_from_git(identifier, type, git)
+      end
+
+      return if JSON.generate(data) == before
+
+      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}"
+    end
+
+    # This (identifier, type) pair's own git data, looked up by its own
+    # `file_path` rather than by identifier — see {#rewrite_unit_json_of_type}.
+    #
+    # @param identifier [String]
+    # @param type [Symbol]
+    # @param git_data [Hash{String => Hash}] keyed by relative path
+    # @return [Hash, nil]
+    def git_for_type(identifier, type, git_data)
+      node = @dependency_graph.node(identifier, type: type)
+      return nil unless node && node[:file_path]
+
+      git_data[normalize_file_path(node[:file_path])]
+    end
+
+    # Mirror of {#annotate_graph_with_git_data} for one incrementally
+    # patched unit. Git data arrives symbol-keyed from {#batch_git_data} and
+    # string-keyed when a caller hands in parsed JSON; both are accepted.
+    #
+    # Unlike {#annotate_graph_with_git_data}, a missing key is never forwarded
+    # as an explicit `nil`: {DependencyGraph#annotate} treats `nil` as
+    # "clear this attribute", and this batch's git data can be missing one of
+    # the two keys without meaning the other's last-known value is gone.
+    #
+    # @param identifier [String]
+    # @param type [Symbol]
+    # @param git [Hash]
+    # @return [void]
+    def annotate_node_from_git(identifier, type, git)
+      attributes = {
+        commit_count: git[:commit_count] || git['commit_count'],
+        change_frequency: git[:change_frequency] || git['change_frequency']
+      }.compact
+      return if attributes.empty?
+
+      @dependency_graph.annotate(identifier, type: type, **attributes)
+    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
+    # {#batch_git_data} returns it.
+    #
+    # @param identifiers [Array<String>]
+    # @return [Hash{String => Hash}]
+    def incremental_git_data(identifiers)
+      return {} if identifiers.empty? || !git_available?
+
+      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])
+        end
+      end
+
+      batch_git_data(paths.uniq)
+    rescue StandardError => e
+      Rails.logger.warn "[Woods] Incremental git enrichment failed: #{e.message}"
+      {}
+    end
+
+    # Re-extract a single known unit, identified by its graph node.
+    #
+    # Used for the transitive half of the blast radius — units whose own file
+    # did not change but which depend on something that did. Files that *did*
+    # change go through {#reconcile_changed_paths} instead, which reconciles
+    # the whole path rather than one identifier.
+    #
+    # @param unit_id [String]
+    # @param affected_types [Set<Symbol>, nil]
+    # @return [String, nil] the identifier when it was re-extracted and written
     def re_extract_unit(unit_id, affected_types: nil)
       # Framework source only changes on version updates
       if unit_id.start_with?('rails/') || unit_id.start_with?('gems/')
-        Rails.logger.debug "[Woods] Skipping framework re-extraction for #{unit_id}"
-        return
+        Rails.logger.debug { "[Woods] Skipping framework re-extraction for #{unit_id}" }
+        return nil
       end
 
-      # Find the unit's type from the graph
-      node = @dependency_graph.to_h[:nodes][unit_id]
-      return unless node
+      # An identifier can name units of several types, each with its own
+      # extractor and its own file; re-extracting one and calling it done would
+      # leave the others frozen at the pre-change extraction.
+      types = @dependency_graph.node_types(unit_id)
+      return nil if types.empty?
+
+      re_extracted = types.count { |type| re_extract_unit_of_type(unit_id, type, affected_types) }
+      return nil if re_extracted.zero?
+
+      Rails.logger.info "[Woods] Re-extracted #{unit_id}"
+      unit_id
+    end
 
-      type = node[:type]&.to_sym
-      file_path = node[:file_path]
+    # @param unit_id [String]
+    # @param type [Symbol]
+    # @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)
+      node = @dependency_graph.node(unit_id, type: type)
+      file_path = node && node[:file_path]
 
-      return unless file_path && File.exist?(file_path)
+      # A vanished file is not re-extractable; {#prune_vanished_units} owns it.
+      return nil unless file_path && File.exist?(file_path)
 
-      # Re-extract based on type
       extractor_key = TYPE_TO_EXTRACTOR_KEY[type]
-      return unless extractor_key
+      return nil unless extractor_key
 
-      extractor = EXTRACTORS[extractor_key]&.new
-      return unless extractor
-
-      unit = if (method = CLASS_BASED[type])
-               klass = if unit_id.match?(/\A[A-Z][A-Za-z0-9_:]*\z/)
-                         begin
-                           unit_id.constantize
-                         rescue StandardError
-                           nil
-                         end
-                       end
-               extractor.public_send(method, klass) if klass
-             elsif (method = FILE_BASED[type])
-               extractor.public_send(method, file_path)
-             elsif GRAPHQL_TYPES.include?(type)
-               extractor.extract_graphql_file(file_path)
-             end
-
-      return unless unit
+      extractor = extractor_for(extractor_key)
+      return nil unless extractor
 
       # File-based extractors can return several units from one file (a .rake
       # file defining multiple tasks, etc.); class-based extractors return one.
-      # Normalize to an array so every unit is registered and written — passing
-      # an Array straight to DependencyGraph#register crashes on unit.identifier.
-      units = unit.is_a?(Array) ? unit : [unit]
-      return if units.empty?
+      units = Array(re_extracted_units(extractor, type, unit_id, file_path, extractor_key)).compact
+      return nil if units.empty?
 
-      # Track which type was affected
-      affected_types&.add(extractor_key)
+      register_and_write(extractor_key, units, affected_types)
+      unit_id
+    end
 
-      type_dir = @output_dir.join(extractor_key.to_s)
+    # 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])
+        klass = constant_for_identifier(unit_id)
+        klass && extractor.public_send(method, klass)
+      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)
+        return units if units.any? { |unit| unit.identifier == unit_id }
+
+        re_extract_by_class(extractor, type, unit_id)
+      elsif GRAPHQL_TYPES.include?(type)
+        extractor.extract_graphql_file(file_path)
+      end
+    end
 
-      units.each do |extracted|
-        # Update dependency graph. Register BEFORE normalizing the path —
-        # the graph's file_map stores absolute paths (affected_by matches
-        # changed files against them), exactly as full extraction registers
-        # in Phase 1 and only normalizes in Phase 4.5.
-        @dependency_graph.register(extracted)
+    # Re-extract a unit the full path discovered by class, not by file.
+    #
+    # Jobs are found two ways ({Extractors::JobExtractor#extract_all}): a scan
+    # of the job directories, then a descendant walk for every job class the
+    # scan did not name. A class-discovered job can live in a file whose
+    # governed constant is not the job — a job nested inside a model — so
+    # re-deriving it from that file names the enclosing class instead, and
+    # registered a second job unit under the PORO's identifier that no full
+    # extraction emits: the wrapper-naming collision, reached incrementally.
+    # When the file entry point does not reproduce the unit, the full path
+    # found it by class; do the same, and register nothing the file scan
+    # would not have produced there either.
+    #
+    # Only a class the extractor itself would discover qualifies. A stale
+    # pre-2.0 wrapper identifier can still constantize (to the wrapper class),
+    # and re-extracting *that* by class would pin the stale unit with fresh
+    # metadata; it stays as it is until a full extraction replaces it.
+    #
+    # @return [ExtractedUnit, nil]
+    def re_extract_by_class(extractor, type, unit_id)
+      klass = constant_for_identifier(unit_id)
+      return nil unless klass && extractor.discoverable_classes.include?(klass)
 
-        # Unit JSON carries Rails.root-relative paths (full extraction's
-        # Phase 4.5); writing the raw absolute source_location here would
-        # leak container-absolute paths into the index after incremental runs.
-        extracted.file_path = normalize_file_path(extracted.file_path)
+      extractor.public_send(CLASS_DISCOVERED_FALLBACK[type], klass)
+    end
 
-        # Write updated unit
-        File.write(
-          type_dir.join(collision_safe_filename(extracted.identifier)),
-          json_serialize(extracted.to_h)
-        )
+    # @param unit_id [String]
+    # @return [Class, nil] the constant an identifier names, when it names one
+    def constant_for_identifier(unit_id)
+      return nil unless unit_id.match?(/\A[A-Z][A-Za-z0-9_:]*\z/)
+
+      begin
+        unit_id.constantize
+      rescue StandardError
+        nil
       end
+    end
 
-      Rails.logger.info "[Woods] Re-extracted #{unit_id}"
+    # Invoke a file-based extraction method, supplying the extra arguments
+    # the handful of non-uniform signatures need.
+    #
+    # @return [ExtractedUnit, Array<ExtractedUnit>, nil]
+    def extract_file_based_unit(extractor, method, file_path, extractor_key)
+      if extractor_key == :poros
+        extractor.public_send(method, file_path, ar_names: active_record_names)
+      else
+        extractor.public_send(method, file_path)
+      end
     end
   end
 end