paper_trail_diff 0.4.0 → 0.6.0

data/lib/paper_trail_diff/batched_root_versions.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # Selects each root's versions for a batched range in a fixed number of
+  # queries. Only the range forms that mean the same thing for every root are
+  # supported: a shared wall-clock window, or each root's own whole history.
+  class BatchedRootVersions
+    #: (Array[untyped], time_range: TimeRange?, ?version_scope: untyped) -> void
+    def initialize(records, time_range:, version_scope: nil)
+      @records = records
+      @time_range = time_range
+      @version_scope = version_scope
+    end
+
+    # Returns a plan per record identity.
+    #: () -> Hash[Array[String], RootVersionPlan]
+    def call
+      return {} if @records.empty?
+
+      selected = {} #: Hash[Array[String], RootVersionPlan]
+      @records.group_by(&:class).each do |model_class, records|
+        select_model(model_class, records, selected)
+      end
+      selected
+    end
+
+    private
+
+    # @rbs @records: Array[untyped]
+    # @rbs @time_range: TimeRange?
+    # @rbs @version_scope: untyped
+
+    #: (untyped, Array[untyped], Hash[Array[String], RootVersionPlan]) -> void
+    def select_model(model_class, records, selected)
+      ids = records.map(&:id)
+      in_range, chosen, trailing = model_versions(model_class, ids)
+      records.each do |record|
+        key = identity(model_class, record.id)
+        selected[key] = versions_for(
+          in_range.fetch(record.id.to_s, []), chosen, trailing[record.id.to_s]
+        )
+      end
+    end
+
+    #: (untyped, Array[untyped]) -> [Hash[String, Array[untyped]], Set[untyped]?, Hash[String, untyped]]
+    def model_versions(model_class, ids)
+      range = @time_range
+      empty = {} #: Hash[String, untyped]
+      [
+        grouped_versions(model_class, ids, range),
+        chosen_version_ids(model_class, ids, range),
+        range ? trailing_versions(model_class, ids, range) : empty
+      ]
+    end
+
+    #: (Array[untyped], Set[untyped]?, untyped) -> RootVersionPlan
+    def versions_for(in_range, chosen, after_range)
+      RootVersionSelection.new(
+        in_range: in_range,
+        selected: chosen ? in_range.select { |version| chosen.include?(version.id) } : in_range,
+        after_range: after_range,
+        windowed: !@time_range.nil?,
+        filtered: !@version_scope.nil?
+      ).call
+    end
+
+    # One extra query names the selected mutations without discarding the
+    # unfiltered versions the successor lookup still needs.
+    #: (untyped, Array[untyped], TimeRange?) -> Set[untyped]?
+    def chosen_version_ids(model_class, ids, range)
+      scope = @version_scope
+      return unless scope
+
+      # A narrowed relation is the expected return. Active Support also gives
+      # `pluck` to plain enumerables, so an array of versions works too.
+      filtered = scope.call(range_scope(model_class, ids, range))
+      Set.new(filtered.pluck(:id))
+    end
+
+    #: (untyped, Array[untyped], TimeRange?) -> Hash[String, Array[untyped]]
+    def grouped_versions(model_class, ids, range)
+      ordered(range_scope(model_class, ids, range)).group_by { |version| version.item_id.to_s }
+    end
+
+    #: (untyped, Array[untyped], TimeRange?) -> untyped
+    def range_scope(model_class, ids, range)
+      scope = base_scope(model_class, ids)
+      range ? range.scope(scope) : scope
+    end
+
+    # One row per root: the earliest version after the window, found without a
+    # window function so the query stays portable.
+    #: (untyped, Array[untyped], TimeRange) -> Hash[String, untyped]
+    def trailing_versions(model_class, ids, range)
+      table = model_class.paper_trail.version_class.arel_table
+      relation = range.trailing_scope(base_scope(model_class, ids))
+      ordered(relation.where(no_earlier_trailing(table, range)))
+        .to_h { |version| [version.item_id.to_s, version] }
+    end
+
+    #: (untyped, TimeRange) -> untyped
+    def no_earlier_trailing(table, range)
+      arel = Object.const_get(:Arel) #: untyped
+      later = table.alias('paper_trail_diff_later_roots')
+      arel.const_get(:SelectManager).new
+          .from(later)
+          .project(arel.sql('1'))
+          .where(preceding(table, later, range))
+          .exists
+          .not
+    end
+
+    # Mirrors the window's own end handling, so a version sitting exactly on an
+    # inclusive boundary stays inside the window instead of masking the trailing
+    # version that follows it.
+    #: (untyped, untyped, TimeRange) -> untyped
+    def preceding(table, later, range)
+      same_item = later[:item_type].eq(table[:item_type])
+                                   .and(later[:item_id].eq(table[:item_id]))
+      same_item.and(after_window(later, range)).and(later[:created_at].lt(table[:created_at]))
+    end
+
+    #: (untyped, TimeRange) -> untyped
+    def after_window(later, range)
+      return later[:created_at].gteq(range.end_time) if range.exclude_end?
+
+      later[:created_at].gt(range.end_time)
+    end
+
+    #: (untyped, Array[untyped]) -> untyped
+    def base_scope(model_class, ids)
+      model_class.paper_trail.version_class.where(
+        item_type: model_class.base_class.name.to_s,
+        item_id: ids
+      )
+    end
+
+    #: (untyped) -> Array[untyped]
+    def ordered(relation)
+      relation.reorder(created_at: :asc, id: :asc).to_a
+    end
+
+    #: (untyped, untyped) -> Array[String]
+    def identity(model_class, id)
+      [model_class.base_class.name.to_s, id.to_s]
+    end
+  end
+end

data/lib/paper_trail_diff/comparison_batch.rb

@@ -23,18 +23,10 @@ module PaperTrailDiff
 
     #: () -> comparison_results
     def call
-      pairs = comparison_pairs
-      pairs.each { |from, to| Endpoint.validate_pair!(from, to) }
-      ensure_unique_identities!(pairs)
-      prepare_endpoint_classes!(pairs)
-      live_records = load_live_records(pairs.flatten)
-      prepare_historical_batches!(pairs, live_records)
-      live_snapshots = normalize_live_records(live_records)
-
-      pairs.to_h do |from, to|
-        identity = Support.immutable_copy(Endpoint.identity(from))
-        [identity, compare(from, to, live_snapshots)]
-      end.freeze
+      resolved = BatchBoundaryResolver.new(comparison_pairs).call
+      pairs = resolved.reject { |pair| pair.any? { |endpoint| symbolic?(endpoint) } }
+      ensure_unique_identities!(resolved)
+      results(resolved, prepared_live_snapshots(pairs)).freeze
     end
 
     private
@@ -46,6 +38,38 @@ module PaperTrailDiff
     # @rbs @historical_snapshotter: untyped
     # @rbs @live_normalizer: untyped
 
+    #: (Array[[untyped, untyped]]) -> Hash[identity, RecordSnapshot]
+    def prepared_live_snapshots(pairs)
+      pairs.each { |from, to| Endpoint.validate_pair!(from, to) }
+      prepare_endpoint_classes!(pairs)
+      live_records = load_live_records(pairs.flatten)
+      prepare_historical_batches!(pairs, live_records)
+      normalize_live_records(live_records)
+    end
+
+    #: (untyped) -> bool
+    def symbolic?(endpoint)
+      BatchBoundaryResolver.symbolic?(endpoint)
+    end
+
+    # A boundary symbol that stayed unresolved means the root has no recorded
+    # history. An absent history is an empty result rather than a failed
+    # request, matching how the timeline APIs answer the same question.
+    #: (Array[[untyped, untyped]], Hash[identity, RecordSnapshot]) -> comparison_results
+    def results(resolved, live_snapshots)
+      resolved.to_h do |from, to|
+        identity = Support.immutable_copy(entry_identity(from, to))
+        next [identity, Diff.new] if symbolic?(from) || symbolic?(to)
+
+        [identity, compare(from, to, live_snapshots)]
+      end
+    end
+
+    #: (untyped, untyped) -> identity
+    def entry_identity(from, to)
+      Endpoint.identity(symbolic?(from) ? to : from)
+    end
+
     #: (untyped, untyped, Hash[identity, RecordSnapshot]) -> Diff
     def compare(from, to, live_snapshots)
       Engine.compare(snapshot(from, live_snapshots), snapshot(to, live_snapshots))
@@ -125,7 +149,7 @@ module PaperTrailDiff
 
     #: (Array[[untyped, untyped]]) -> void
     def ensure_unique_identities!(pairs)
-      identities = pairs.map { |from, _to| Endpoint.identity(from) }
+      identities = pairs.map { |from, to| entry_identity(from, to) }
       return if identities.uniq.length == identities.length
 
       raise ConfigurationError, 'comparisons: root identities must be unique'

data/lib/paper_trail_diff/historical_snapshot_store.rb

@@ -24,6 +24,8 @@ module PaperTrailDiff
       end_at: root_versions.last.created_at
     )
       return if @tree.empty?
+      # A batched preparation already covers these roots.
+      return if root_versions.any? { |v| @prepared_histories.key?(context_key(v)) }
 
       @prepared_history = PreparedHistoryLoader.new(
         record,
@@ -35,7 +37,6 @@ module PaperTrailDiff
       ).call
     end
 
-    # Prepares selected history for several roots of the same model class.
     #: (Array[untyped], Array[untyped]) -> void
     def prepare_batch(records, root_versions)
       return if @tree.empty? || records.empty? || root_versions.empty?
@@ -50,12 +51,7 @@ module PaperTrailDiff
       key = snapshot_key(root_endpoint, context_endpoint)
       return @snapshots[key] if @snapshots.key?(key)
 
-      @snapshots[key] = custom(
-        root_endpoint,
-        context_endpoint,
-        tree: @tree,
-        normalizer: @normalizer
-      )
+      @snapshots[key] = uncached(root_endpoint, context_endpoint)
     end
 
     #: (untyped, untyped) -> RecordSnapshot?

data/lib/paper_trail_diff/paper_trail_adapter.rb

@@ -2,13 +2,17 @@
 # rbs_inline: enabled
 
 module PaperTrailDiff
-  # PaperTrail/ActiveRecord boundary that produces plain record snapshots.
-  class PaperTrailAdapter
+  # PaperTrail/ActiveRecord boundary that produces plain record snapshots. It is
+  # deliberately the widest class here: it fronts every public operation and is
+  # the only place allowed to know about both PaperTrail and the pure engine.
+  # Reconstruction logic lives in the collaborators it wires together.
+  class PaperTrailAdapter # rubocop:disable Metrics/ClassLength
     #: (associations: Array[String | Symbol], ignore: ignore_option, ?reload_live_endpoints: bool) -> void
     def initialize(associations:, ignore:, reload_live_endpoints: true)
       @association_tree = AssociationTree.build(associations)
       @ignore_policy = IgnorePolicy.build(ignore, association_paths: @association_tree.paths)
       @traversal = AssociationTraversal.new(@association_tree)
+      @traversal_preparer = TraversalPreparer.new(tree: @association_tree, traversal: @traversal)
       @live_endpoints = LiveEndpointProvider.new(
         tree: @association_tree, traversal: @traversal, reload: reload_live_endpoints
       )
@@ -18,9 +22,7 @@ module PaperTrailDiff
         tree: @association_tree, ignore_policy: @ignore_policy,
         traversal: @traversal, pool: @snapshot_pool
       )
-      @historical_store = build_historical_store
-      @timeline_snapshotter = TimelineSnapshotProvider.new(@historical_store)
-      @activity_snapshotter = build_activity_snapshotter
+      build_snapshotters
     end
 
     #: (untyped, untyped) -> Diff
@@ -40,7 +42,7 @@ module PaperTrailDiff
       Instrumentation.instrument('compare_many', payload) do
         ComparisonBatch.new(
           comparisons,
-          live_loader: @live_endpoints.method(:call), preparer: method(:prepare_traversal!),
+          live_loader: @live_endpoints.method(:call), preparer: @traversal_preparer.method(:call),
           history_preparer: @historical_store.method(:prepare_batch),
           historical_snapshotter: method(:historical_snapshot),
           live_normalizer: method(:normalize_live_snapshot)
@@ -48,48 +50,69 @@ module PaperTrailDiff
       end
     end
 
-    #: (untyped, from: untyped, to: untyped, within: untyped) -> Array[Step]
-    def timeline(record, from:, to:, within:)
-      prepare_traversal!(record.class, historical: true)
-      builder = TimelineBuilder.new(
+    #: (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped) -> Array[Step]
+    def timeline(record, from:, to:, within:, version_scope: nil)
+      @traversal_preparer.call(record.class, historical: true)
+      TimelineBuilder.new(
         record,
         from: from,
         to: to,
         within: within,
+        version_scope: version_scope,
         snapshotter: @timeline_snapshotter
-      )
-      builder.build
+      ).build
     end
 
-    #: (untyped, from: untyped, to: untyped, within: untyped) -> Array[ActivityStep]
-    def activity_timeline(record, from:, to:, within:)
+    #: (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped) -> Array[ActivityStep]
+    def activity_timeline(record, from:, to:, within:, version_scope: nil)
       payload = @instrumentation_payload.merge(model_type: record.class.base_class.name.to_s)
       Instrumentation.instrument('activity_timeline', payload) do
-        prepare_traversal!(record.class, historical: true)
+        @traversal_preparer.call(record.class, historical: true)
         reject_live_habtm_activity!(record.class) if Endpoint.record?(to)
-        steps = activity_builder(record, from: from, to: to, within: within).build
+        steps = activity_builder(
+          record, from: from, to: to, within: within, version_scope: version_scope
+        ).build
         payload[:step_count] = steps.length
         steps
       end
     end
 
-    #: (untyped, from: untyped, to: untyped, within: untyped, ?activity: bool) -> Analysis
-    def analyze(record, from:, to:, within:, activity: false)
+    #: (untyped, from: untyped, to: untyped, within: untyped, ?activity: bool, ?version_scope: untyped) -> Analysis
+    def analyze(record, from:, to:, within:, activity: false, version_scope: nil) # rubocop:disable Metrics/ParameterLists
+      @traversal_preparer.call(record.class, historical: true)
       if activity
-        prepare_traversal!(record.class, historical: true)
-        return activity_builder(record, from: from, to: to, within: within).analyze
+        return activity_builder(
+          record, from: from, to: to, within: within, version_scope: version_scope
+        ).analyze
       end
 
-      prepare_traversal!(record.class, historical: true)
       TimelineBuilder.new(
         record,
         from: from,
         to: to,
         within: within,
+        version_scope: version_scope,
         snapshotter: @timeline_snapshotter
       ).analyze
     end
 
+    # Analyzes many roots over one shared range, preparing their history once.
+    #: (Array[untyped], within: untyped, ?activity: bool, ?version_scope: untyped) -> Hash[identity, Analysis]
+    def analyze_many(records, within:, activity: false, version_scope: nil)
+      count = records.is_a?(Array) ? records.length : 0
+      payload = @instrumentation_payload.merge(comparison_count: count)
+      Instrumentation.instrument('analyze_many', payload) do
+        AnalysisBatch.new(
+          records,
+          time_range: within.nil? ? nil : TimeRange.new(within),
+          version_scope: version_scope,
+          live_loader: @live_endpoints.method(:call),
+          history_preparer: @historical_store.method(:prepare_batch),
+          analyzer: batched_root_analyzer(activity)
+        ).call
+      end
+    end
+
     private
 
     # @rbs @association_tree: AssociationTree
@@ -97,19 +120,38 @@ module PaperTrailDiff
     # @rbs @instrumentation_payload: Hash[Symbol, untyped]
     # @rbs @ignore_policy: IgnorePolicy
     # @rbs @traversal: AssociationTraversal
+    # @rbs @traversal_preparer: TraversalPreparer
     # @rbs @snapshot_pool: SnapshotPool
     # @rbs @normalizer: SnapshotNormalizer
     # @rbs @historical_store: HistoricalSnapshotStore
     # @rbs @timeline_snapshotter: TimelineSnapshotProvider
     # @rbs @activity_snapshotter: ActivitySnapshotProvider
 
+    #: () -> void
+    def build_snapshotters
+      @historical_store = build_historical_store
+      @timeline_snapshotter = TimelineSnapshotProvider.new(@historical_store)
+      @activity_snapshotter = build_activity_snapshotter
+    end
+
+    #: (bool) -> BatchedRootAnalyzer
+    def batched_root_analyzer(activity)
+      BatchedRootAnalyzer.new(
+        tree: @association_tree,
+        timeline_snapshotter: @timeline_snapshotter,
+        activity_snapshotter: @activity_snapshotter,
+        preparer: @traversal_preparer.method(:call),
+        activity: activity
+      )
+    end
+
     #: () -> HistoricalSnapshotStore
     def build_historical_store
       HistoricalSnapshotStore.new(
         tree: @association_tree,
         traversal: @traversal,
         normalizer: @normalizer,
-        preparer: method(:prepare_traversal!)
+        preparer: @traversal_preparer.method(:call)
       )
     end
 
@@ -131,11 +173,13 @@ module PaperTrailDiff
       )
     end
 
-    #: (untyped, from: untyped, to: untyped, within: untyped) -> ActivityTimelineBuilder
-    def activity_builder(record, from:, to:, within:)
+    #: (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped) -> ActivityTimelineBuilder
+    def activity_builder(record, from:, to:, within:, version_scope: nil)
       ActivityTimelineBuilder.new(
         record,
-        range: TimelineRange.new(record, from: from, to: to, within: within),
+        range: TimelineRange.new(
+          record, from: from, to: to, within: within, version_scope: version_scope
+        ),
         tree: @association_tree,
         snapshotter: @activity_snapshotter
       )
@@ -180,30 +224,9 @@ module PaperTrailDiff
 
     #: (untyped) -> RecordSnapshot
     def normalize_live_snapshot(current)
-      prepare_traversal!(current.class, historical: false)
+      @traversal_preparer.call(current.class, historical: false)
       @normalizer.call(current, reifier: LiveAssociationReader.new) ||
         raise(InvalidEndpointError, 'current record endpoint could not be normalized')
     end
-
-    #: (untyped, historical: bool) -> void
-    def prepare_traversal!(model_class, historical:)
-      return if @association_tree.empty?
-
-      ensure_association_tracking! if historical
-      @traversal.validate!(model_class)
-    end
-
-    #: () -> void
-    def ensure_association_tracking!
-      paper_trail = Object.const_get(:PaperTrail) #: untyped
-      config = paper_trail.config #: untyped
-      available = defined?(::PaperTrailAssociationTracking) &&
-                  config.respond_to?(:track_associations?) &&
-                  config.track_associations?
-      return if available
-
-      message = 'association tracking must be loaded and enabled to compare historical associations'
-      raise AssociationTrackingUnavailableError, message
-    end
   end
 end

data/lib/paper_trail_diff/root_version_plan.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # Which versions a range reconstructs, and which pairs of them become steps.
+  #
+  # Without a filter those are the same thing: every selected version is a
+  # boundary and adjacent ones bound each other. A filter separates them, because
+  # each selected mutation then has to be bounded by the version that actually
+  # reveals it rather than by the next mutation that happened to be selected.
+  #
+  # A filter also separates what is *reported* from what has to be *replayed*.
+  # The activity view rebuilds state by carrying one snapshot forward across
+  # every event in order, so skipping a filtered-out version would leave that
+  # snapshot holding a state the record had already moved past. `versions` are
+  # the boundaries the steps refer to; `reconstruction_versions` are every root
+  # version the span passes through, which is what any forward replay must walk.
+  class RootVersionPlan
+    attr_reader :versions #: Array[untyped]
+    attr_reader :reconstruction_versions #: Array[untyped]
+    attr_reader :steps #: Array[[untyped, untyped]]
+    attr_reader :context_version #: untyped
+    # The root versions this plan reports as mutations, which excludes any
+    # version present only to reveal what the last of them produced.
+    attr_reader :mutations #: Array[untyped]
+
+    class << self
+      # Adjacent boundaries, which is what an unfiltered range reports.
+      #: (Array[untyped], ?context_version: untyped) -> RootVersionPlan
+      def contiguous(versions, context_version: nil)
+        new(
+          versions: versions,
+          steps: versions.each_cons(2).map { |from, to| [from, to] },
+          context_version: context_version
+        )
+      end
+
+      #: () -> RootVersionPlan
+      def empty
+        versions = [] #: Array[untyped]
+        steps = [] #: Array[[untyped, untyped]]
+        new(versions: versions, steps: steps)
+      end
+    end
+
+    #: (versions: Array[untyped], steps: Array[[untyped, untyped]], ?context_version: untyped, ?reconstruction_versions: Array[untyped]?, ?mutations: Array[untyped]?) -> void
+    def initialize(
+      versions:, steps:, context_version: nil, reconstruction_versions: nil, mutations: nil
+    )
+      @versions = versions.freeze
+      @reconstruction_versions = (reconstruction_versions || versions).freeze
+      @steps = steps.freeze
+      @context_version = context_version
+      @mutations = (mutations || default_mutations).freeze
+      @mutation_keys = Set.new(@mutations.map { |version| key(version) }).freeze
+      freeze
+    end
+
+    #: () -> bool
+    def empty?
+      versions.empty?
+    end
+
+    #: (untyped) -> bool
+    def mutation?(version)
+      @mutation_keys.include?(key(version))
+    end
+
+    private
+
+    # @rbs @mutation_keys: Set[Array[untyped]]
+
+    #: () -> Array[untyped]
+    def default_mutations
+      return @versions unless @context_version
+
+      context = key(@context_version)
+      @versions.reject { |version| key(version) == context }
+    end
+
+    #: (untyped) -> Array[untyped]
+    def key(version)
+      [version.class.name, version.id]
+    end
+  end
+end

data/lib/paper_trail_diff/root_version_selection.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # Decides which versions a range reports, and which one reveals the last of
+  # them. A version records the state before its own event, so whatever follows
+  # the final selected mutation is the only thing that can show what it produced.
+  # That successor is reconstruction context rather than a reported mutation, so
+  # a filter must never remove it.
+  #
+  # Both the single-record and the batched selectors resolve this here, because
+  # the rule is subtle enough that two copies of it would drift apart.
+  class RootVersionSelection
+    INCOMPLETE = 'time range requires a later root version to reconstruct its final change'
+
+    #: (in_range: Array[untyped], selected: Array[untyped], after_range: untyped, windowed: bool, ?context_required: bool, ?filtered: bool) -> void
+    def initialize( # rubocop:disable Metrics/ParameterLists
+      in_range:, selected:, after_range:, windowed:, context_required: false, filtered: false
+    )
+      @in_range = in_range
+      @selected = selected
+      @after_range = after_range
+      @windowed = windowed
+      @context_required = context_required
+      @filtered = filtered
+    end
+
+    #: () -> RootVersionPlan
+    def call
+      return without_selection if @selected.empty?
+
+      revealing = revealing_version
+      raise IncompleteTimeRangeError, INCOMPLETE if !revealing && @windowed && !terminal_destroy?
+      return filtered_plan(revealing) if @filtered
+
+      versions = revealing ? (@selected + [revealing]) : @selected
+      RootVersionPlan.contiguous(versions, context_version: revealing)
+    end
+
+    private
+
+    # @rbs @in_range: Array[untyped]
+    # @rbs @selected: Array[untyped]
+    # @rbs @after_range: untyped
+    # @rbs @windowed: bool
+    # @rbs @context_required: bool
+    # @rbs @filtered: bool
+
+    # An activity view still needs a root to reconstruct from even when no root
+    # version falls inside the window, because descendants may have moved.
+    #: () -> RootVersionPlan
+    def without_selection
+      return RootVersionPlan.empty unless @context_required
+      if @after_range
+        return RootVersionPlan.contiguous([@after_range], context_version: @after_range)
+      end
+
+      raise IncompleteTimeRangeError, INCOMPLETE
+    end
+
+    # Each selected mutation is bounded by the version that reveals it, not by
+    # the next mutation that happened to be selected. Bounding by the next
+    # selection would fold anything filtered out in between into it, so the same
+    # edit would read differently depending on what followed it.
+    #: (untyped) -> RootVersionPlan
+    def filtered_plan(revealing)
+      steps = @selected.filter_map do |version|
+        successor = version.equal?(@selected.last) ? revealing : immediate_successor(version)
+        [version, successor] if successor
+      end #: Array[[untyped, untyped]]
+      versions = chronological(steps.flatten(1) + closing_versions)
+      RootVersionPlan.new(
+        versions: versions,
+        steps: steps,
+        context_version: revealing,
+        reconstruction_versions: spanned(versions),
+        mutations: @selected
+      )
+    end
+
+    # Nothing can follow a destroy, so it never pairs into a step. It is still a
+    # selected mutation, and the activity view closes on the absence it leaves,
+    # so it has to stay a boundary or a filtered report loses the deletion
+    # entirely — the one event it can least afford to drop.
+    #: () -> Array[untyped]
+    def closing_versions
+      terminal_destroy? ? [@selected.last] : []
+    end
+
+    # Everything the span passes through, filtered out or not. A replay that
+    # skipped the excluded versions would carry a stale state into the next
+    # reported step, so the two selected mutations either side of a gap would
+    # disagree about what the record looked like between them.
+    #: (Array[untyped]) -> Array[untyped]
+    def spanned(versions)
+      first = versions.first
+      last = versions.last
+      return versions unless first && last
+
+      @in_range.select do |candidate|
+        !Support.compare_versions(first, candidate).positive? &&
+          !Support.compare_versions(candidate, last).positive?
+      end
+    end
+
+    #: (Array[untyped]) -> Array[untyped]
+    def chronological(versions)
+      versions.uniq { |version| [version.class.name, version.id] }
+              .sort_by { |version| Support.chronological_version_key(version) }
+    end
+
+    #: (untyped) -> untyped
+    def immediate_successor(version)
+      @in_range.find { |candidate| Support.compare_versions(version, candidate).negative? }
+    end
+
+    # A version left out by a filter is still the state the last selected change
+    # produced, so it is preferred over anything after the range.
+    #: () -> untyped
+    def revealing_version
+      immediate_successor(@selected.last) || @after_range
+    end
+
+    # A range closing on the record's own destruction needs no later version:
+    # nothing can follow it, so demanding one would reject the range forever.
+    #: () -> bool
+    def terminal_destroy?
+      @selected.last&.event.to_s == 'destroy'
+    end
+  end
+end