woods 2.0.0.beta1 → 2.0.0.beta2

data/lib/woods/extractor.rb

@@ -404,16 +404,20 @@ module Woods
       # package added between the two runs.
       @package_resolver = nil
       @incremental_extractors = nil
-      begin_payload!
+      @persisted_index_stats = nil
+      @graph_sha = nil
+      profile_phase('payload seed') { begin_payload! }
 
       # Eager load once — all extractors need loaded classes for introspection.
-      safe_eager_load!
+      profile_phase('eager load') { safe_eager_load! }
 
       # Phase 1: Extract all units
-      if Woods.configuration.concurrent_extraction
-        extract_all_concurrent
-      else
-        extract_all_sequential
+      profile_phase('extraction') do
+        if Woods.configuration.concurrent_extraction
+          extract_all_concurrent
+        else
+          extract_all_sequential
+        end
       end
 
       # Phase 1.5: Deduplicate results
@@ -444,7 +448,7 @@ module Woods
 
       # Phase 4: Graph analysis (PageRank, structural metrics)
       Rails.logger.info '[Woods] Analyzing dependency graph...'
-      @graph_analysis = build_graph_analyzer.analyze
+      @graph_analysis = profile_phase('graph analysis') { build_graph_analyzer.analyze }
 
       # Phase 4.5: Normalize file_path to relative paths
       Rails.logger.info '[Woods] Normalizing file paths...'
@@ -452,7 +456,7 @@ 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
@@ -478,15 +482,17 @@ module Woods
       # being opt-in does not excuse it.
       if Woods.configuration.precompute_flows
         Rails.logger.info '[Woods] Precomputing request flows...'
-        precompute_flows
+        profile_phase('flows') { precompute_flows }
       end
 
       write_dependency_graph
       write_graph_analysis
-      write_manifest
-      write_structural_summary
+      profile_phase('manifest and summary') do
+        write_manifest
+        write_structural_summary
+      end
       capture_snapshot
-      publish_generation('full')
+      profile_phase('publish') { publish_generation('full') }
 
       log_summary
 
@@ -527,14 +533,22 @@ module Woods
       change_set = ChangeSet.new(paths: changed_files, root: Rails.root)
       affected_types = Set.new
 
-      # Blast radius from the pre-change graph.
-      affected_ids = @dependency_graph.affected_by(change_set.absolute_paths)
+      # Blast radius from the pre-change graph, bounded by
+      # `incremental_blast_radius_depth` (nil = the unbounded closure).
+      affected_ids = profile_phase('blast radius') do
+        @dependency_graph.affected_by(change_set.absolute_paths, max_depth: blast_radius_depth)
+      end
+      @flow_scope = profile_phase('flow radius') { flow_scope_for(change_set) }
       Rails.logger.info "[Woods] #{change_set.size} changed files affect #{affected_ids.size} units"
 
-      touched = reconcile_changed_paths(change_set, affected_types)
+      touched = profile_phase('re-extraction') do
+        acc = reconcile_changed_paths(change_set, affected_types)
 
-      (affected_ids - touched.to_a).each do |unit_id|
-        touched.add(unit_id) if re_extract_unit(unit_id, affected_types: affected_types)
+        (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
 
       touched.merge(reconcile_class_based_types(affected_types))
@@ -571,8 +585,10 @@ module Woods
       finalize_incremental_unit_json(affected_types)
 
       # Regenerate type indexes for affected types
-      affected_types.each do |type_key|
-        regenerate_type_index(type_key)
+      profile_phase('type index') do
+        affected_types.each do |type_key|
+          regenerate_type_index(type_key)
+        end
       end
 
       finalize_incremental_run(touched)
@@ -651,6 +667,71 @@ module Woods
 
     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
@@ -665,19 +746,27 @@ module Woods
     # @return [void]
     # @raise [Woods::ExtractionError] see {#begin_payload!}
     def prepare_incremental_run
-      begin_payload!(strict: true)
+      profile_phase('payload seed') { begin_payload!(strict: true) }
       graph_path = payload_dir.join('dependency_graph.json')
       ensure_incremental_baseline!(graph_path)
-      @dependency_graph = DependencyGraph.from_h(JSON.parse(AtomicFile.read(graph_path))) if graph_path.exist?
+      profile_phase('previous graph load') do
+        @dependency_graph = DependencyGraph.from_h(JSON.parse(AtomicFile.read(graph_path))) if graph_path.exist?
+      end
 
       ModelNameCache.reset!
-      safe_eager_load!
+      profile_phase('eager load') { safe_eager_load! }
 
       @dependents_dirty = Set.new
       @incremental_written = {}
+      # nil = no scope was computed for this run, so every re-extracted
+      # controller has its flows reassembled. {#refresh} leaves it that way.
+      @flow_scope = nil
+      @previous_flow_index_entries = nil
       @incremental_extractors = nil
       @active_record_names = nil
       @package_resolver = nil
+      @persisted_index_stats = nil
+      @graph_sha = nil
     end
 
     # Write the graph and the derived artifacts after an incremental run.
@@ -713,11 +802,13 @@ module Woods
         return
       end
 
-      write_incremental_graph_analysis
-      refresh_incremental_flows(touched)
-      write_manifest(incremental: true)
-      write_structural_summary
-      publish_generation(reason)
+      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
 
@@ -737,7 +828,11 @@ module Woods
     # @return [void]
     def publish_generation(reason)
       generation = Generation.new(output_dir: @output_dir)
-      marker = generation.bump!(reason: reason, payload: publishable_payload_name(generation))
+      # 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
@@ -893,6 +988,47 @@ module Woods
       EXTRACTORS.keys.map(&:to_s) + PAYLOAD_DIRS
     end
 
+    # Whether payload files pay for their own durability as they are written.
+    #
+    # False by default and false on every host that has not asked otherwise:
+    # {#sync_payload} makes the whole payload durable in one flush before the
+    # pointer names it, so a per-file fsync buys only the window in which
+    # nothing can read the file anyway. `durable_payload_writes = true`
+    # restores the per-file cost for a host that wants it; it does not, and
+    # cannot, remove the publish flush.
+    #
+    # @return [Boolean]
+    def payload_writes_durable?
+      Woods.configuration&.durable_payload_writes ? true : false
+    end
+
+    # One filesystem flush that makes this run's whole payload durable,
+    # immediately before the pointer that names it is written durably.
+    #
+    # This is the guarantee that replaces the per-file fsync {#write_results}
+    # used to pay for every unit: **when `generation.json` is durable, every
+    # file in the payload it names is durable.** What is given up is an
+    # individual payload file being durable before the pointer exists, and
+    # nobody reads a payload file in that window: every reader resolves
+    # through the pointer, and a crash leaves an unreferenced partial payload
+    # that the next run prunes.
+    #
+    # Unconditional on purpose. `durable_payload_writes` decides whether the
+    # per-file fsyncs are *also* paid; it can never turn this off, because
+    # that would be the one change that actually weakens the contract.
+    # {Woods::AtomicFile.sync_directory_tree} degrades through `sync -f`, a
+    # bare `sync`, and finally a per-file fsync pass, so the flush cannot
+    # silently become a no-op either.
+    #
+    # A run that degraded to a flat publish has no payload directory;
+    # {#payload_dir} then returns the output directory, which is the tree that
+    # needs flushing in exactly the same way.
+    #
+    # @return [Symbol, nil] the strategy {Woods::AtomicFile} used
+    def sync_payload
+      AtomicFile.sync_directory_tree(payload_dir)
+    end
+
     # The pointer to publish, or nil when this run built no payload directory.
     #
     # The directory was named from the generation number this run expected to
@@ -1279,12 +1415,14 @@ module Woods
         annotated.each do |unit|
           AtomicFile.write(
             type_dir.join(collision_safe_filename(unit.identifier)),
-            json_serialize(unit.to_h)
+            json_serialize(unit.to_h),
+            durable: payload_writes_durable?
           )
         end
         AtomicFile.write(
           type_dir.join('_index.json'),
-          json_serialize(type_index_entries(units))
+          json_serialize(type_index_entries(units)),
+          durable: payload_writes_durable?
         )
       end
     end
@@ -1329,12 +1467,16 @@ module Woods
       removed = previous_flow_index_controllers & (touched.to_set - reextracted.to_set)
       return if reextracted.empty? && removed.empty?
 
-      Rails.logger.info "[Woods] Refreshing flows for #{reextracted.size} controller(s), " \
-                        "#{removed.size} removed..."
+      reassemble, carried = partition_flow_controllers(
+        reextracted.filter_map { |id| unit_from_payload(:controllers, id) }
+      )
+      Rails.logger.info "[Woods] Refreshing flows for #{reassemble.size} controller(s), " \
+                        "#{carried.size} carried forward, #{removed.size} removed..."
       precomputer = FlowPrecomputer.new(units: [], graph: @dependency_graph, output_dir: payload_dir.to_s)
       annotations = precomputer.recompute_delta(
-        touched_units: reextracted.filter_map { |id| unit_from_payload(:controllers, id) },
-        removed_identifiers: removed.to_a
+        touched_units: reassemble,
+        removed_identifiers: removed.to_a,
+        carried_identifiers: carried.map(&:identifier)
       )
       patch_flow_annotations(annotations)
       sweep_orphaned_flow_files
@@ -1347,6 +1489,52 @@ module Woods
       regenerate_type_index(:controllers) if annotations.any?
     end
 
+    # Split the run's re-extracted controllers into the ones whose flow
+    # documents have to be reassembled and the ones that only need their
+    # annotation back.
+    #
+    # A controller is reassembled when the run changed something its flow can
+    # reach ({#flow_scope_for}), or when its own action set no longer matches
+    # the previous generation's index. The second test is what catches an
+    # action arriving from further up a controller inheritance chain than the
+    # flow radius reaches, and a controller the index has never seen.
+    #
+    # Without a scope (a targeted {#refresh}, or a routes re-run) everything
+    # is reassembled, which is what this path always did.
+    #
+    # @param units [Array<ExtractedUnit>] the run's re-extracted controllers
+    # @return [Array(Array<ExtractedUnit>, Array<ExtractedUnit>)]
+    def partition_flow_controllers(units)
+      return [units, []] if @flow_scope.nil?
+
+      previous = previous_flow_index_actions
+      units.partition do |unit|
+        @flow_scope.include?(unit.identifier) || flow_actions_of(unit) != previous[unit.identifier]
+      end
+    end
+
+    # The actions a unit's metadata declares, as the index records them.
+    #
+    # @param unit [ExtractedUnit]
+    # @return [Set<String>]
+    def flow_actions_of(unit)
+      Array(unit.metadata[:actions] || unit.metadata['actions']).to_set(&:to_s)
+    end
+
+    # The previous generation's flow index, grouped by controller.
+    #
+    # @return [Hash{String => Set<String>}] controller identifier to its
+    #   recorded action names, defaulting to an empty set
+    # @raise [Woods::ExtractionError] when the index is missing or corrupt
+    def previous_flow_index_actions
+      previous_flow_index_entries.keys.each_with_object(Hash.new { Set.new }) do |entry_point, grouped|
+        controller, action = entry_point.to_s.split('#', 2)
+        next unless action
+
+        grouped[controller] = grouped[controller] + [action]
+      end
+    end
+
     # Does the run's seeded payload hold a flow family at all? An absent
     # family (no flows/ directory, or an empty one) is a genuine absence —
     # typically an index built while the gate was off — and skips the
@@ -1372,11 +1560,21 @@ module Woods
     # @return [Set<String>]
     # @raise [Woods::ExtractionError] when the index is missing or corrupt
     def previous_flow_index_controllers
+      previous_flow_index_entries.keys.to_set { |entry_point| entry_point.to_s.split('#', 2).first }
+    end
+
+    # The previous generation's flow index itself, read once per run: both
+    # the removal set and the reassembly partition are derived from it.
+    #
+    # @return [Hash{String => String}] entry point to relative document path
+    # @raise [Woods::ExtractionError] when the index is missing or corrupt
+    def previous_flow_index_entries
+      return @previous_flow_index_entries if @previous_flow_index_entries
+
       index_path = payload_dir.join('flows', 'flow_index.json')
       raise Woods::ExtractionError, 'flows/ is populated but flow_index.json is missing' unless index_path.exist?
 
-      JSON.parse(AtomicFile.read(index_path))
-          .keys.to_set { |entry_point| entry_point.to_s.split('#', 2).first }
+      @previous_flow_index_entries = JSON.parse(AtomicFile.read(index_path))
     rescue JSON::ParserError => e
       raise Woods::ExtractionError, "previous flow_index.json does not parse: #{e.message}"
     end
@@ -1433,7 +1631,7 @@ module Woods
         end
         next if JSON.generate(data) == before
 
-        AtomicFile.write(path, json_serialize(data))
+        AtomicFile.write(path, json_serialize(data), durable: payload_writes_durable?)
       end
     end
 
@@ -1550,8 +1748,14 @@ module Woods
     #
     # @return [GraphAnalyzer]
     def build_graph_analyzer
-      ratio = Woods.configuration&.volatile_dependency_ratio || GraphAnalyzer::DEFAULT_VOLATILE_RATIO
-      GraphAnalyzer.new(@dependency_graph, volatile_ratio: ratio)
+      config = Woods.configuration
+      ratio = config&.volatile_dependency_ratio || GraphAnalyzer::DEFAULT_VOLATILE_RATIO
+      GraphAnalyzer.new(
+        @dependency_graph,
+        volatile_ratio: ratio,
+        cycle_limit: config ? config.graph_cycle_limit : GraphAnalyzer::DEFAULT_CYCLE_LIMIT,
+        cycle_max_length: config ? config.graph_cycle_max_length : GraphAnalyzer::DEFAULT_CYCLE_MAX_LENGTH
+      )
     end
 
     # ──────────────────────────────────────────────────────────────────────
@@ -1651,7 +1855,7 @@ module Woods
       else
         metadata.delete('package')
       end
-      AtomicFile.write(file, json_serialize(data))
+      AtomicFile.write(file, json_serialize(data), durable: payload_writes_durable?)
 
       identifier = data['identifier']
       type = (data['type'] || type_dir.singularize).to_sym
@@ -1715,7 +1919,7 @@ module Woods
       payload = json_serialize(unit.to_h)
       return if identical_on_disk?(path, payload)
 
-      AtomicFile.write(path, payload)
+      AtomicFile.write(path, payload, durable: payload_writes_durable?)
     end
 
     # The serialized `extracted_at` scalar as {ExtractedUnit#to_h} +
@@ -1960,14 +2164,16 @@ module Woods
         units.each do |unit|
           AtomicFile.write(
             type_dir.join(collision_safe_filename(unit.identifier)),
-            json_serialize(unit.to_h)
+            json_serialize(unit.to_h),
+            durable: payload_writes_durable?
           )
         end
 
         # Also write a type index for fast lookups
         AtomicFile.write(
           type_dir.join('_index.json'),
-          json_serialize(type_index_entries(units))
+          json_serialize(type_index_entries(units)),
+          durable: payload_writes_durable?
         )
       end
     end
@@ -2064,10 +2270,23 @@ module Woods
       # registration order must not reach it (B-180).
       graph_data[:pagerank] = @dependency_graph.pagerank.sort_by { |identifier, _| identifier }.to_h
 
-      AtomicFile.write(
-        payload_dir.join('dependency_graph.json'),
-        json_serialize(graph_data)
-      )
+      payload = json_serialize(graph_data)
+      # The bytes about to land on disk are the bytes `graph_sha` covers, so
+      # keep the digest here rather than reading a whole large-app graph back
+      # to compute it. AtomicFile writes in binary mode and reads back as
+      # UTF-8, so the two digests are the same either way.
+      @graph_sha = Digest::SHA256.hexdigest(payload)
+      AtomicFile.write(payload_dir.join('dependency_graph.json'), payload, durable: payload_writes_durable?)
+    end
+
+    # The digest of the dependency graph this run wrote.
+    #
+    # Falls back to reading the file for a caller that writes the analysis
+    # without having written the graph in the same run.
+    #
+    # @return [String] hex SHA256 of dependency_graph.json
+    def graph_sha
+      @graph_sha || Digest::SHA256.hexdigest(AtomicFile.read(payload_dir.join('dependency_graph.json')))
     end
 
     def write_graph_analysis
@@ -2075,14 +2294,13 @@ module Woods
 
       enriched = @graph_analysis.merge(
         generated_at: Time.current.iso8601,
-        graph_sha: Digest::SHA256.hexdigest(
-          AtomicFile.read(payload_dir.join('dependency_graph.json'))
-        )
+        graph_sha: graph_sha
       )
 
       AtomicFile.write(
         payload_dir.join('graph_analysis.json'),
-        json_serialize(enriched)
+        json_serialize(enriched),
+        durable: payload_writes_durable?
       )
     end
 
@@ -2127,32 +2345,55 @@ module Woods
 
       AtomicFile.write(
         payload_dir.join('manifest.json'),
-        json_serialize(manifest)
+        json_serialize(manifest),
+        durable: payload_writes_durable?
       )
     end
 
     # Unit and chunk counts derived from the per-type _index.json files on
-    # disk — the source of truth after an incremental run, where only the
+    # disk: the source of truth after an incremental run, where only the
     # affected units were re-extracted.
     #
     # @return [Array(Hash{Symbol => Integer}, Integer)] counts by type, total chunk count
     def persisted_counts
-      counts = {}
-      chunks = 0
-
-      Dir[payload_dir.join('*/_index.json').to_s].each do |index_path|
-        entries = JSON.parse(AtomicFile.read(index_path))
-        counts[File.basename(File.dirname(index_path)).to_sym] = entries.size
-        chunks += entries.sum { |e| e['chunk_count'].to_i }
+      stats = persisted_index_stats
+      [stats.transform_values { |type_stats| type_stats[:count] },
+       stats.sum { |_type, type_stats| type_stats[:chunks] }]
+    end
+
+    # One pass over the persisted per-type _index.json files.
+    #
+    # {#persisted_counts} feeds the manifest and {#persisted_summary_stats}
+    # feeds SUMMARY.md, they run back to back at the end of every incremental
+    # run, and each used to parse every type index for itself. Reading once and
+    # deriving both is also what keeps the two artifacts from disagreeing about
+    # totals, which was previously a property of them using the same source
+    # rather than the same read.
+    #
+    # An unreadable index drops that whole type from the manifest and the
+    # summary alike, with one warning rather than the two the separate passes
+    # emitted. Sorted for determinism, since the glob order is the
+    # filesystem's.
+    #
+    # Memoized per run: invalidated at the start of {#extract_all} and
+    # {#prepare_incremental_run}, and again whenever {#regenerate_type_index}
+    # rewrites an index underneath it.
+    #
+    # @return [Hash{Symbol => Hash}] type => `{ count:, chunks:, namespaces: }`
+    def persisted_index_stats
+      @persisted_index_stats ||= Dir[payload_dir.join('*/_index.json').to_s].each_with_object({}) do |path, stats|
+        entries = JSON.parse(AtomicFile.read(path))
+        stats[File.basename(File.dirname(path)).to_sym] = {
+          count: entries.size,
+          chunks: entries.sum { |entry| entry['chunk_count'].to_i },
+          namespaces: namespace_histogram(entries.map { |entry| entry['namespace'] })
+        }
       rescue JSON::ParserError => e
-        # An unreadable index silently drops that whole type from the manifest
-        # counts — warn rather than undercount without a trace.
-        type = File.basename(File.dirname(index_path))
-        Rails.logger.warn("[Woods] Skipping unreadable #{type}/_index.json in manifest counts: #{e.message}")
-        next
+        type = File.basename(File.dirname(path))
+        Rails.logger.warn(
+          "[Woods] Skipping unreadable #{type}/_index.json in manifest counts and summary totals: #{e.message}"
+        )
       end
-
-      [counts, chunks]
     end
 
     # Capture a temporal snapshot after extraction completes.
@@ -2287,7 +2528,8 @@ module Woods
 
       AtomicFile.write(
         payload_dir.join('SUMMARY.md'),
-        summary.join("\n")
+        summary.join("\n"),
+        durable: payload_writes_durable?
       )
     end
 
@@ -2308,32 +2550,14 @@ module Woods
     end
 
     # The incremental path's counterpart to {#results_summary_stats}: the same
-    # shape read back from the persisted per-type _index.json files, the source
-    # {#persisted_counts} uses for the manifest — so the two artifacts cannot
-    # disagree about totals. Sorted for determinism, since the glob order is
-    # the filesystem's.
-    #
-    # @return [Hash{Symbol => Hash}, nil] nil when the payload holds no type
-    #   indexes at all, so a bare index writes no summary — matching the full
-    #   path's early return when it extracted nothing
+    # shape, read back through {#persisted_index_stats}. A type whose index is
+    # empty is left out, where the manifest still counts it as zero.
+    #
+    # @return [Hash{Symbol => Hash}, nil] nil when the payload holds no
+    #   non-empty type index, so a bare index writes no summary, matching the
+    #   full path's early return when it extracted nothing
     def persisted_summary_stats
-      stats = {}
-
-      Dir[payload_dir.join('*/_index.json').to_s].each do |index_path|
-        entries = JSON.parse(AtomicFile.read(index_path))
-        next if entries.empty?
-
-        stats[File.basename(File.dirname(index_path)).to_sym] = {
-          count: entries.size,
-          chunks: entries.sum { |e| e['chunk_count'].to_i },
-          namespaces: namespace_histogram(entries.map { |e| e['namespace'] })
-        }
-      rescue JSON::ParserError => e
-        # Same posture as {#persisted_counts}: an unreadable index drops that
-        # type from the manifest and the summary alike, so the two still agree.
-        type = File.basename(File.dirname(index_path))
-        Rails.logger.warn("[Woods] Skipping unreadable #{type}/_index.json in summary totals: #{e.message}")
-      end
+      stats = persisted_index_stats.reject { |_type, type_stats| type_stats[:count].zero? }
 
       stats.empty? ? nil : stats
     end
@@ -2352,6 +2576,10 @@ module Woods
       type_dir = payload_dir.join(type_key.to_s)
       return unless type_dir.directory?
 
+      # This run's counts and summary totals are read from the index files;
+      # rewriting one invalidates whatever was read before.
+      @persisted_index_stats = nil
+
       # Scan existing unit JSON files (exclude _index.json)
       index = Dir[type_dir.join('*.json')].filter_map do |file|
         next if File.basename(file) == '_index.json'
@@ -2371,7 +2599,8 @@ module Woods
 
       AtomicFile.write(
         type_dir.join('_index.json'),
-        json_serialize(index)
+        json_serialize(index),
+        durable: payload_writes_durable?
       )
     end
 
@@ -2806,6 +3035,11 @@ module Woods
       return Set.new if keys.empty?
 
       keys += ROUTE_CONSUMER_EXTRACTORS if keys.include?(:routes)
+      # A routes re-run replaces every controller, and a flow document
+      # carries the route itself, which no dependency edge connects to the
+      # controller. Nothing about that is reachable by a graph walk, so the
+      # run drops its flow scope and reassembles every touched controller.
+      @flow_scope = nil if keys.include?(:routes)
 
       keys.each_with_object(Set.new) do |key, touched|
         touched.merge(replace_type_wholesale(key, affected_types))
@@ -3282,7 +3516,7 @@ module Woods
 
       return if JSON.generate(data) == before
 
-      AtomicFile.write(path, json_serialize(data))
+      AtomicFile.write(path, json_serialize(data), durable: payload_writes_durable?)
       affected_types&.add(extractor_key)
     rescue JSON::ParserError => e
       Rails.logger.warn "[Woods] Could not finalize #{identifier}: #{e.message}"