paper_trail_diff 0.5.0 → 0.7.0

data/lib/paper_trail_diff/time_version_range.rb

@@ -4,34 +4,41 @@
 module PaperTrailDiff
   # Selects in-range root versions plus one later reconstruction boundary.
   class TimeVersionRange
-    #: (untyped, time_range: TimeRange) -> void
-    def initialize(record, time_range:)
+    #: (untyped, time_range: TimeRange, ?version_scope: untyped, ?live_endpoint: untyped) -> void
+    def initialize(record, time_range:, version_scope: nil, live_endpoint: nil)
       @record = record
       @time_range = time_range
+      @version_scope = version_scope
+      @live_endpoint = live_endpoint
     end
 
     #: (?context_required: bool) -> Array[untyped]
     def select(context_required: false)
-      relation = versions_relation
-      selected = ordered(@time_range.scope(relation).to_a)
-      empty = [] #: Array[untyped]
-      return empty.freeze if selected.empty? && !context_required
-
-      trailing = trailing_version(relation)
-      unless trailing
-        return selected.freeze if terminal_destroy?(selected)
-
-        message = 'time range requires a later root version to reconstruct its final change'
-        raise IncompleteTimeRangeError, message
-      end
+      select_plan(context_required: context_required).versions
+    end
 
-      (selected + [trailing]).freeze
+    #: (?context_required: bool) -> RootVersionPlan
+    def select_plan(context_required: false)
+      relation = versions_relation
+      in_range = ordered(@time_range.scope(relation).to_a)
+      RootVersionSelection.new(
+        in_range: in_range,
+        selected: VersionScopeFilter.new(@version_scope).call(@time_range.scope(relation),
+                                                              in_range),
+        after_range: trailing_version(relation),
+        windowed: true,
+        context_required: context_required,
+        filtered: !@version_scope.nil?,
+        live_endpoint: @live_endpoint
+      ).call
     end
 
     private
 
     # @rbs @record: untyped
     # @rbs @time_range: TimeRange
+    # @rbs @version_scope: untyped
+    # @rbs @live_endpoint: untyped
 
     #: () -> untyped
     def versions_relation
@@ -42,15 +49,6 @@ module PaperTrailDiff
       raise InvalidTimelineRangeError, message, cause: e
     end
 
-    # A window closing on the record's own destruction needs no later version:
-    # the destroy reveals the preceding mutation and nothing can follow it, so
-    # demanding a checkpoint that can never be written would reject the range
-    # permanently.
-    #: (Array[untyped]) -> bool
-    def terminal_destroy?(versions)
-      versions.last&.event.to_s == 'destroy'
-    end
-
     #: (untyped) -> untyped
     def trailing_version(relation)
       @time_range.trailing_scope(relation).reorder(created_at: :asc, id: :asc).first

data/lib/paper_trail_diff/timeline_builder.rb

@@ -4,10 +4,17 @@
 module PaperTrailDiff
   # Selects and compares a chronological slice of a record's version history.
   class TimelineBuilder
-    #: (untyped, from: untyped, to: untyped, snapshotter: untyped, ?within: untyped, ?versions: Array[untyped]?) -> void
-    def initialize(record, from:, to:, snapshotter:, within: nil, versions: nil) # rubocop:disable Metrics/ParameterLists
+    #: (untyped, from: untyped, to: untyped, snapshotter: untyped, ?within: untyped, ?versions: Array[untyped]?, ?version_scope: untyped, ?plan: RootVersionPlan?, ?live_endpoint: untyped) -> void
+    def initialize( # rubocop:disable Metrics/ParameterLists
+      record, from:, to:, snapshotter:, within: nil, versions: nil, version_scope: nil, plan: nil,
+      live_endpoint: nil
+    )
       @record = record
-      @range = TimelineRange.new(record, from: from, to: to, within: within, versions: versions)
+      @range = TimelineRange.new(
+        record, from: from, to: to, within: within,
+                versions: versions, version_scope: version_scope, plan: plan,
+                live_endpoint: live_endpoint
+      )
       @snapshotter = snapshotter
     end
 
@@ -22,7 +29,9 @@ module PaperTrailDiff
       steps, first_snapshot, last_snapshot = compare_history(selected_versions)
       Analysis.new(
         diff: Engine.compare(first_snapshot, last_snapshot),
-        timeline: steps
+        timeline: steps,
+        from_snapshot: first_snapshot,
+        to_snapshot: last_snapshot
       )
     end
 
@@ -32,24 +41,27 @@ module PaperTrailDiff
     # @rbs @range: TimelineRange
     # @rbs @snapshotter: untyped
 
-    #: (Array[untyped]) -> [Array[Step], RecordSnapshot?, RecordSnapshot?]
-    def compare_history(versions)
-      return empty_history if versions.empty?
+    #: (RootVersionPlan) -> [Array[Step], RecordSnapshot?, RecordSnapshot?]
+    def compare_history(plan)
+      return empty_history if plan.empty?
 
+      versions = plan.versions
       @snapshotter.prepare(@record, versions) if @snapshotter.respond_to?(:prepare)
-      first_snapshot = @snapshotter.call(versions.first)
-      previous_snapshot = first_snapshot
-      steps = versions.each_cons(2).map do |from_version, to_version|
-        current_snapshot = @snapshotter.call(to_version)
-        step = Step.new(
-          from_version: from_version,
-          to_version: to_version,
-          diff: Engine.compare(previous_snapshot, current_snapshot)
+      steps = build_steps(plan)
+      [steps, @snapshotter.call(versions.first), @snapshotter.call(plan.final_endpoint)]
+    end
+
+    #: (RootVersionPlan) -> Array[Step]
+    def build_steps(plan)
+      captured_at = Time.now.utc if plan.closing_record
+      plan.steps.map do |from_endpoint, to_endpoint|
+        Step.new(
+          from_version: from_endpoint,
+          to_version: to_endpoint,
+          captured_at: captured_at,
+          diff: Engine.compare(@snapshotter.call(from_endpoint), @snapshotter.call(to_endpoint))
         )
-        previous_snapshot = current_snapshot
-        step
       end.freeze
-      [steps, first_snapshot, previous_snapshot]
     end
 
     #: () -> [Array[Step], nil, nil]
@@ -58,9 +70,9 @@ module PaperTrailDiff
       [steps.freeze, nil, nil]
     end
 
-    #: () -> Array[untyped]
+    #: () -> RootVersionPlan
     def selected_versions
-      @range.select
+      @range.select_plan
     end
   end
 end

data/lib/paper_trail_diff/timeline_range.rb

@@ -10,10 +10,13 @@ module PaperTrailDiff
     attr_reader :to #: untyped
     attr_reader :time_range #: TimeRange?
 
-    #: (untyped, from: untyped, to: untyped, within: untyped, ?versions: Array[untyped]?) -> void
-    def initialize(record, from:, to:, within:, versions: nil)
+    #: (untyped, from: untyped, to: untyped, within: untyped, ?versions: Array[untyped]?, ?version_scope: untyped, ?plan: RootVersionPlan?, ?live_endpoint: untyped) -> void
+    def initialize(record, from:, to:, within:, versions: nil, version_scope: nil, plan: nil, live_endpoint: nil) # rubocop:disable Metrics/ParameterLists, Layout/LineLength
       @record = record
-      @versions = versions&.freeze
+      @plan = plan
+      @live_endpoint = live_endpoint
+      @versions = (plan ? plan.versions : versions)&.freeze
+      @version_scope = version_scope
       @requested_from = from
       @requested_to = to
       @time_range = build_time_range(within)
@@ -32,6 +35,27 @@ module PaperTrailDiff
 
     # A batch may have selected these versions already, in which case reselecting
     # them per record would undo the batching.
+    # The plan says which pairs of versions become steps, which a filter can
+    # make different from adjacent pairs of the selected versions.
+    #: (?context_required: bool) -> RootVersionPlan
+    def select_plan(context_required: false)
+      preselected = @plan
+      return preselected if preselected
+
+      range = time_range
+      if range
+        return TimeVersionRange.new(
+          @record, time_range: range, version_scope: @version_scope,
+                   live_endpoint: @live_endpoint
+        ).select_plan(context_required: context_required)
+      end
+      return RootVersionPlan.empty if unresolved?
+
+      VersionRange.new(
+        @record, from: @from, to: @to, version_scope: @version_scope
+      ).select_plan_for_range
+    end
+
     #: (?context_required: bool) -> Array[untyped]
     def select(context_required: false)
       preselected = @versions
@@ -39,13 +63,13 @@ module PaperTrailDiff
 
       range = time_range
       if range
-        return TimeVersionRange.new(@record, time_range: range).select(
-          context_required: context_required
-        )
+        return TimeVersionRange.new(
+          @record, time_range: range, version_scope: @version_scope
+        ).select(context_required: context_required)
       end
       return empty_versions if unresolved?
 
-      VersionRange.new(@record, from: @from, to: @to).select
+      VersionRange.new(@record, from: @from, to: @to, version_scope: @version_scope).select
     end
 
     #: () -> bool
@@ -68,6 +92,9 @@ module PaperTrailDiff
 
     # @rbs @record: untyped
     # @rbs @versions: Array[untyped]?
+    # @rbs @plan: RootVersionPlan?
+    # @rbs @version_scope: untyped
+    # @rbs @live_endpoint: untyped
     # @rbs @requested_from: untyped
     # @rbs @requested_to: untyped
     # @rbs @from: untyped

data/lib/paper_trail_diff/timeline_snapshot_provider.rb

@@ -4,9 +4,10 @@
 module PaperTrailDiff
   # Gives TimelineBuilder one-argument access to a range-prepared snapshot store.
   class TimelineSnapshotProvider
-    #: (HistoricalSnapshotStore) -> void
-    def initialize(store)
+    #: (HistoricalSnapshotStore, ?live_snapshotter: untyped) -> void
+    def initialize(store, live_snapshotter: nil)
       @store = store
+      @live_snapshotter = live_snapshotter
     end
 
     #: (untyped, Array[untyped]) -> void
@@ -14,11 +15,26 @@ module PaperTrailDiff
       @store.prepare(record, versions)
     end
 
+    # A window closing on current state ends at the live record rather than at a
+    # version, which is the one endpoint no version history can reconstruct.
     #: (untyped) -> RecordSnapshot?
-    def call(version)
-      @store.uncached(version, version)
+    def call(endpoint)
+      return live_snapshot(endpoint) if Endpoint.record?(endpoint)
+
+      @store.uncached(endpoint, endpoint)
+    end
+
+    private
+
+    #: (untyped) -> RecordSnapshot?
+    def live_snapshot(record)
+      snapshotter = @live_snapshotter
+      raise InvalidTimelineRangeError, 'live endpoints are unavailable here' unless snapshotter
+
+      snapshotter.call(record)
     end
 
     # @rbs @store: HistoricalSnapshotStore
+    # @rbs @live_snapshotter: untyped
   end
 end

data/lib/paper_trail_diff/version.rb

@@ -2,5 +2,5 @@
 # rbs_inline: enabled
 
 module PaperTrailDiff
-  VERSION = '0.5.0'
+  VERSION = '0.7.0'
 end

data/lib/paper_trail_diff/version_range.rb

@@ -4,11 +4,34 @@
 module PaperTrailDiff
   # Selects an inclusive, chronological range from a record's root versions.
   class VersionRange
-    #: (untyped, from: untyped, to: untyped) -> void
-    def initialize(record, from:, to:)
+    #: (untyped, from: untyped, to: untyped, ?version_scope: untyped) -> void
+    def initialize(record, from:, to:, version_scope: nil)
       @record = record
       @from = from
       @to = to
+      @version_scope = version_scope
+    end
+
+    # Same selection as `select`, but keeping the step pairs a filter implies.
+    #: () -> RootVersionPlan
+    def select_plan_for_range
+      relation = validated_relation
+      select_plan(
+        relation.where(created_at: @from.created_at..@to.created_at),
+        through: @to
+      )
+    end
+
+    #: () -> untyped
+    def validated_relation
+      relation = versions_relation
+      validate_boundary!(@from, relation, boundary: :from)
+      validate_boundary!(@to, relation, boundary: :to)
+      if Support.compare_versions(@from, @to).positive?
+        raise InvalidTimelineRangeError, '`from` version must not follow `to` version'
+      end
+
+      relation
     end
 
     #: () -> Array[untyped]
@@ -38,6 +61,7 @@ module PaperTrailDiff
     # @rbs @record: untyped
     # @rbs @from: untyped
     # @rbs @to: untyped
+    # @rbs @version_scope: untyped
 
     #: () -> untyped
     def versions_relation
@@ -50,13 +74,29 @@ module PaperTrailDiff
 
     #: (untyped, ?through: untyped) -> Array[untyped]
     def select_relation(relation, through: nil)
-      selected = relation.to_a.select do |version|
+      select_plan(relation, through: through).versions
+    end
+
+    #: (untyped, ?through: untyped) -> RootVersionPlan
+    def select_plan(relation, through: nil)
+      in_range = ordered(relation.to_a.select do |version|
         next false if Support.compare_versions(@from, version).positive?
         next true unless through
 
         Support.compare_versions(version, through) <= 0
-      end
-      selected.sort_by { |version| Support.chronological_version_key(version) }
+      end)
+      RootVersionSelection.new(
+        in_range: in_range,
+        selected: VersionScopeFilter.new(@version_scope).call(relation, in_range),
+        after_range: nil,
+        windowed: false,
+        filtered: !@version_scope.nil?
+      ).call
+    end
+
+    #: (Array[untyped]) -> Array[untyped]
+    def ordered(versions)
+      versions.sort_by { |version| Support.chronological_version_key(version) }
     end
 
     #: (untyped, untyped, boundary: Symbol) -> void

data/lib/paper_trail_diff/version_scope_filter.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # Applies a caller's version filter to a range, naming which of its versions
+  # count as selected mutations. The unfiltered versions stay available to the
+  # caller, because the one that reveals the last selected mutation is drawn
+  # from them.
+  class VersionScopeFilter
+    #: (untyped) -> void
+    def initialize(scope)
+      @scope = validated(scope)
+    end
+
+    #: (untyped, Array[untyped]) -> Array[untyped]
+    def call(relation, in_range)
+      scope = @scope
+      return in_range unless scope
+
+      # A narrowed relation is the expected return. Active Support also gives
+      # `pluck` to plain enumerables, so an array of versions works too.
+      chosen = Set.new(scope.call(relation).pluck(:id))
+      in_range.select { |version| chosen.include?(version.id) }
+    end
+
+    private
+
+    # @rbs @scope: untyped
+
+    #: (untyped) -> untyped
+    def validated(scope)
+      return scope if scope.nil? || scope.respond_to?(:call)
+
+      raise ConfigurationError, 'version_scope: must respond to call'
+    end
+  end
+end

data/lib/paper_trail_diff.rb

@@ -39,6 +39,9 @@ require_relative 'paper_trail_diff/live_endpoint_provider'
 require_relative 'paper_trail_diff/live_graph_collector'
 require_relative 'paper_trail_diff/batch_boundary_resolver'
 require_relative 'paper_trail_diff/comparison_batch'
+require_relative 'paper_trail_diff/root_version_plan'
+require_relative 'paper_trail_diff/version_scope_filter'
+require_relative 'paper_trail_diff/root_version_selection'
 require_relative 'paper_trail_diff/batched_root_versions'
 require_relative 'paper_trail_diff/snapshot_normalizer'
 require_relative 'paper_trail_diff/historical_snapshot_store'
@@ -142,27 +145,31 @@ module PaperTrailDiff # rubocop:disable Metrics/ModuleLength
     end
 
     # Compares every adjacent reconstructed state in an inclusive version range.
-    #: (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option) -> Array[Step]
+    #: (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?version_scope: untyped, ?close_on: Symbol?) -> Array[Step]
     def timeline( # rubocop:disable Metrics/ParameterLists
       record,
       from: nil,
       to: nil,
       within: nil,
       associations: [],
-      ignore: DEFAULT_IGNORED_ATTRIBUTES
+      ignore: DEFAULT_IGNORED_ATTRIBUTES,
+      version_scope: nil,
+      close_on: nil
     )
       PaperTrailAdapter.new(associations: associations, ignore: ignore).timeline(
         record,
         from: from,
         to: to,
-        within: within
+        within: within,
+        version_scope: version_scope,
+        close_on: close_on
       )
     end
 
     # Compares adjacent root and selected-descendant activity boundaries.
     # `reload_live_endpoints:` applies only when `to:` is a current record; the
     # other range forms never read live state.
-    #: (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?reload_live_endpoints: bool) -> Array[ActivityStep]
+    #: (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?reload_live_endpoints: bool, ?version_scope: untyped, ?close_on: Symbol?) -> Array[ActivityStep]
     def activity_timeline( # rubocop:disable Metrics/ParameterLists
       record,
       from: nil,
@@ -170,7 +177,9 @@ module PaperTrailDiff # rubocop:disable Metrics/ModuleLength
       within: nil,
       associations: [],
       ignore: DEFAULT_IGNORED_ATTRIBUTES,
-      reload_live_endpoints: true
+      reload_live_endpoints: true,
+      version_scope: nil,
+      close_on: nil
     )
       PaperTrailAdapter.new(
         associations: associations,
@@ -180,12 +189,14 @@ module PaperTrailDiff # rubocop:disable Metrics/ModuleLength
         record,
         from: from,
         to: to,
-        within: within
+        within: within,
+        version_scope: version_scope,
+        close_on: close_on
       )
     end
 
     # Builds an endpoint diff and root-checkpoint timeline while normalizing each version once.
-    #: (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?activity: bool) -> Analysis
+    #: (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?) -> Analysis
     def analyze( # rubocop:disable Metrics/ParameterLists
       record,
       from: nil,
@@ -193,32 +204,40 @@ module PaperTrailDiff # rubocop:disable Metrics/ModuleLength
       within: nil,
       associations: [],
       ignore: DEFAULT_IGNORED_ATTRIBUTES,
-      activity: false
+      activity: false,
+      version_scope: nil,
+      close_on: nil
     )
       PaperTrailAdapter.new(associations: associations, ignore: ignore).analyze(
         record,
         from: from,
         to: to,
         within: within,
-        activity: activity
+        activity: activity,
+        version_scope: version_scope,
+        close_on: close_on
       )
     end
 
     # Analyzes many roots over one shared time window, preparing their selected
     # history once for the batch instead of once per record. Roots with no
     # versions in the window return an empty `Analysis`.
-    #: (Array[untyped], ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?activity: bool) -> Hash[identity, Analysis]
-    def analyze_many(
+    #: (Array[untyped], ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?) -> Hash[identity, Analysis]
+    def analyze_many( # rubocop:disable Metrics/ParameterLists
       records,
       within: nil,
       associations: [],
       ignore: DEFAULT_IGNORED_ATTRIBUTES,
-      activity: false
+      activity: false,
+      version_scope: nil,
+      close_on: nil
     )
       PaperTrailAdapter.new(associations: associations, ignore: ignore).analyze_many(
         records,
         within: within,
-        activity: activity
+        activity: activity,
+        version_scope: version_scope,
+        close_on: close_on
       )
     end
 

data/sig/generated/paper_trail_diff/activity_root_steps.rbs

@@ -4,8 +4,13 @@ module PaperTrailDiff
   # Root checkpoint steps recovered from the snapshots an activity pass retained,
   # so a combined result does not reconstruct the same boundaries twice.
   module ActivityRootSteps
-    # : (Array[untyped], Hash[Array[untyped], RecordSnapshot?]) -> Array[Step]
-    def self?.call: (Array[untyped], Hash[Array[untyped], RecordSnapshot?]) -> Array[Step]
+    # A window closing on current state ends at the live record, which no
+    # version-keyed snapshot can supply, so that endpoint is passed in.
+    # : (RootVersionPlan, Hash[Array[untyped], RecordSnapshot?], ?closing_snapshot: RecordSnapshot?, ?captured_at: untyped) -> Array[Step]
+    def self?.call: (RootVersionPlan, Hash[Array[untyped], RecordSnapshot?], ?closing_snapshot: RecordSnapshot?, ?captured_at: untyped) -> Array[Step]
+
+    # : (untyped, Hash[Array[untyped], RecordSnapshot?], RecordSnapshot?) -> RecordSnapshot?
+    def self?.snapshot_for: (untyped, Hash[Array[untyped], RecordSnapshot?], RecordSnapshot?) -> RecordSnapshot?
 
     # : (untyped) -> Array[untyped]
     def self?.version_key: (untyped) -> Array[untyped]

data/sig/generated/paper_trail_diff/activity_timeline_builder.rbs

@@ -30,6 +30,10 @@ module PaperTrailDiff
     # : () -> Array[ActivityStep]
     def no_steps: () -> Array[ActivityStep]
 
+    # Every boundary in the span, filtered out or not. A filter narrows where the
+    # span starts and ends, but the sequence inside it stays complete: dropping
+    # boundaries would fold the changes they carried into a neighbouring step and
+    # credit them to whoever made that one.
     # : () -> Array[ActivityStep]
     def build_between_versions: () -> Array[ActivityStep]
 
@@ -67,8 +71,8 @@ module PaperTrailDiff
     # Only the activity view gains the closing removal. The endpoint diff and
     # the root timeline keep their `compare` and `timeline` semantics, under
     # which the state at a destroy version is the state before the deletion.
-    # : (Array[untyped], Array[ActivityEvent], ActivityHistory) -> Analysis
-    def build_analysis: (Array[untyped], Array[ActivityEvent], ActivityHistory) -> Analysis
+    # : (RootVersionPlan, Array[ActivityEvent], ActivityHistory) -> Analysis
+    def build_analysis: (RootVersionPlan, Array[ActivityEvent], ActivityHistory) -> Analysis
 
     # : () -> TimeActivityTimelineBuilder
     def time_builder: () -> TimeActivityTimelineBuilder

data/sig/generated/paper_trail_diff/analysis.rbs

@@ -9,15 +9,24 @@ module PaperTrailDiff
 
     attr_reader activity_timeline: Array[ActivityStep]?
 
+    attr_reader from_snapshot: RecordSnapshot?
+
+    attr_reader to_snapshot: RecordSnapshot?
+
     # The result for a record whose requested history contains no versions,
     # which is an empty history rather than a failed request.
     # : () -> Analysis
     def self.empty: () -> Analysis
 
-    # : (diff: Diff, timeline: Array[Step], ?activity_timeline: Array[ActivityStep]?) -> void
-    def initialize: (diff: Diff, timeline: Array[Step], ?activity_timeline: Array[ActivityStep]?) -> void
+    # The reconstructed states the diff was taken between. A report that has to
+    # render unchanged columns needs the whole final state, not only what moved.
+    # : (diff: Diff, timeline: Array[Step], ?activity_timeline: Array[ActivityStep]?, ?from_snapshot: RecordSnapshot?, ?to_snapshot: RecordSnapshot?) -> void
+    def initialize: (diff: Diff, timeline: Array[Step], ?activity_timeline: Array[ActivityStep]?, ?from_snapshot: RecordSnapshot?, ?to_snapshot: RecordSnapshot?) -> void
 
-    # : () -> Hash[Symbol, untyped]
-    def to_h: () -> Hash[Symbol, untyped]
+    # Reconstructed endpoint states are opt-in, because they carry the whole
+    # selected graph whether or not anything changed, which dwarfs the rest of
+    # the payload for a wide graph.
+    # : (?snapshots: bool) -> Hash[Symbol, untyped]
+    def to_h: (?snapshots: bool) -> Hash[Symbol, untyped]
   end
 end

data/sig/generated/paper_trail_diff/analysis_batch.rbs

@@ -5,8 +5,8 @@ module PaperTrailDiff
   # versions and preparing their association history once for the whole batch
   # rather than once per root.
   class AnalysisBatch
-    # : (Array[untyped], time_range: TimeRange?, live_loader: untyped, history_preparer: untyped, analyzer: untyped) -> void
-    def initialize: (Array[untyped], time_range: TimeRange?, live_loader: untyped, history_preparer: untyped, analyzer: untyped) -> void
+    # : (Array[untyped], time_range: TimeRange?, live_loader: untyped, history_preparer: untyped, analyzer: untyped, ?version_scope: untyped, ?close_on_current: bool) -> void
+    def initialize: (Array[untyped], time_range: TimeRange?, live_loader: untyped, history_preparer: untyped, analyzer: untyped, ?version_scope: untyped, ?close_on_current: bool) -> void
 
     # : () -> Hash[identity, Analysis]
     def call: () -> Hash[identity, Analysis]
@@ -15,6 +15,8 @@ module PaperTrailDiff
 
     @analyzer: untyped
 
+    @close_on_current: bool
+
     @history_preparer: untyped
 
     @live_loader: untyped
@@ -23,6 +25,13 @@ module PaperTrailDiff
 
     @time_range: TimeRange?
 
+    @version_scope: untyped
+
+    # A filter is a callable that narrows the version relation, so it is checked
+    # up front rather than failing partway through a batch.
+    # : (untyped) -> untyped
+    def validated_scope: (untyped) -> untyped
+
     # : () -> Array[untyped]
     def validated_records: () -> Array[untyped]
 
@@ -31,12 +40,12 @@ module PaperTrailDiff
     # The roots are preloaded first, because preparation reads their current
     # association state as a fallback and would otherwise walk it one root at a
     # time.
-    # : (Array[untyped], Hash[Array[String], Array[untyped]]) -> void
-    def prepare: (Array[untyped], Hash[Array[String], Array[untyped]]) -> void
+    # : (Array[untyped], Hash[Array[String], RootVersionPlan], Hash[Array[String], untyped]) -> void
+    def prepare: (Array[untyped], Hash[Array[String], RootVersionPlan], Hash[Array[String], untyped]) -> void
 
     # A root with no versions in range has nothing to report, which is an empty
     # result rather than a failed request.
-    # : (untyped, Array[untyped]) -> Analysis
-    def analysis_for: (untyped, Array[untyped]) -> Analysis
+    # : (untyped, RootVersionPlan) -> Analysis
+    def analysis_for: (untyped, RootVersionPlan) -> Analysis
   end
 end

data/sig/generated/paper_trail_diff/batched_root_analyzer.rbs

@@ -7,8 +7,8 @@ module PaperTrailDiff
     # : (tree: AssociationTree, timeline_snapshotter: untyped, activity_snapshotter: untyped, preparer: untyped, activity: bool) -> void
     def initialize: (tree: AssociationTree, timeline_snapshotter: untyped, activity_snapshotter: untyped, preparer: untyped, activity: bool) -> void
 
-    # : (untyped, Array[untyped]) -> Analysis
-    def call: (untyped, Array[untyped]) -> Analysis
+    # : (untyped, RootVersionPlan) -> Analysis
+    def call: (untyped, RootVersionPlan) -> Analysis
 
     private
 
@@ -22,7 +22,7 @@ module PaperTrailDiff
 
     @tree: AssociationTree
 
-    # : (untyped, Array[untyped]) -> Analysis
-    def activity_analysis: (untyped, Array[untyped]) -> Analysis
+    # : (untyped, RootVersionPlan) -> Analysis
+    def activity_analysis: (untyped, RootVersionPlan) -> Analysis
   end
 end