paper_trail_diff 0.12.0 → 0.13.1

data/lib/paper_trail_diff/activity_timeline_builder.rb

@@ -8,6 +8,7 @@ module PaperTrailDiff
 
     #: (untyped, range: TimelineRange, tree: AssociationTree, snapshotter: untyped, ?snapshots: bool, ?group: Symbol?) -> void
     def initialize(record, range:, tree:, snapshotter:, snapshots: false, group: nil) # rubocop:disable Metrics/ParameterLists
+      ActivityGrouping.validate!(group)
       @snapshots = snapshots
       @group = group
       # Merging a group compares its outer states, so the snapshots must survive
@@ -36,10 +37,7 @@ module PaperTrailDiff
     def analyze
       return time_builder.analyze if @range.time?
       return Analysis.empty if @range.unresolved?
-
-      unless Endpoint.version?(@to)
-        raise InvalidTimelineRangeError, '`to` must be a root PaperTrail version'
-      end
+      return analyze_current if Endpoint.record?(@to)
 
       plan = @range.select_plan
       root_versions = plan.reconstruction_versions
@@ -73,27 +71,48 @@ module PaperTrailDiff
       root_versions = @range.select_plan.reconstruction_versions
       prepare_history(root_versions)
       events = collect_events(root_versions)
-      build_event_steps(root_versions, events)
+      history = event_history(root_versions, events)
+      activity_steps(history, events, destroyed_boundary(root_versions), nil)
     end
 
     #: () -> Array[ActivityStep]
     def build_to_current
-      validate_current_range!
-      current_snapshot, captured_at = capture_current
-      root_versions = VersionRange.new(@record, from: @from, to: @from).select_through_latest
-      # Descendants can move after the last root version, so the prepared range
-      # ends at the captured instant rather than at that version.
-      prepare_history(root_versions, end_at: captured_at)
-      events = collect_events(root_versions, range_end: captured_at)
-      build_event_steps(
-        root_versions,
-        events,
-        current: @to,
-        final_boundary: ActivityBoundary.current(@to, captured_at: captured_at),
-        final_snapshot: current_snapshot
+      _plan, events, history, snapshot, boundary = current_history
+      activity_steps(history, events, boundary, snapshot)
+    end
+
+    #: () -> Analysis
+    def analyze_current
+      plan, events, history, snapshot, boundary = current_history
+      final = boundary ? snapshot : history.last_snapshot
+      Analysis.new(
+        diff: Engine.compare(history.first_snapshot, final),
+        timeline: ActivityRootSteps.call(
+          plan, history.root_snapshots, closing_snapshot: snapshot,
+                                        captured_at: boundary&.recorded_at
+        ),
+        activity_timeline: activity_steps(history, events, boundary, snapshot),
+        from_snapshot: history.first_snapshot, to_snapshot: final
       )
     end
 
+    # The explicit live endpoint and a batch's live closing endpoint use the
+    # same selected plan. A version filter can close earlier, on its successor.
+    #: () -> [RootVersionPlan, Array[ActivityEvent], ActivityHistory, RecordSnapshot?, ActivityBoundary?]
+    def current_history
+      validate_current_range!
+      plan = @range.select_plan
+      return [plan, [], ActivityHistory.empty, nil, nil] if plan.empty?
+
+      snapshot, captured_at = capture_current if plan.closing_record
+      versions = plan.reconstruction_versions
+      prepare_history(versions, end_at: captured_at)
+      events = collect_events(versions, range_end: captured_at || versions.last)
+      history = event_history(versions, events, current: plan.closing_record)
+      boundary = ActivityBoundary.current(@to, captured_at: captured_at) if plan.closing_record
+      [plan, events, history, snapshot, boundary]
+    end
+
     #: () -> [RecordSnapshot?, untyped]
     def capture_current
       [@snapshotter.call(@to, @to), Time.now.utc]
@@ -107,6 +126,7 @@ module PaperTrailDiff
 
       Endpoint.validate_pair!(@from, @to)
       Endpoint.validate_pair!(@record, @to)
+      AssociationTraversal.new(@tree).reject_live_habtm_activity!(@record.class)
     end
 
     #: (Array[untyped], ?range_start: untyped, ?range_end: untyped) -> Array[ActivityEvent]
@@ -120,6 +140,7 @@ module PaperTrailDiff
         root_versions: root_versions,
         tree: @tree,
         traversal: AssociationTraversal.new(@tree),
+        prepared: (@snapshotter.activity_index if @snapshotter.respond_to?(:activity_index)),
         range_start: range_start,
         range_end: range_end
       ).call
@@ -133,23 +154,6 @@ module PaperTrailDiff
       @snapshotter.prepare(@record, root_versions, end_at: end_at)
     end
 
-    #: (Array[untyped], Array[ActivityEvent], ?current: untyped, ?final_boundary: ActivityBoundary?, ?final_snapshot: RecordSnapshot?) -> Array[ActivityStep]
-    def build_event_steps(
-      root_versions,
-      events,
-      current: nil,
-      final_boundary: nil,
-      final_snapshot: nil
-    )
-      history = event_history(root_versions, events, current: current)
-      activity_steps(
-        history,
-        events,
-        final_boundary || destroyed_boundary(root_versions),
-        final_snapshot
-      )
-    end
-
     # Appends the transition into an explicit closing boundary, which is either
     # a requested current record or the absence a final root destroy leaves.
     #: (ActivityHistory, Array[ActivityEvent], ActivityBoundary?, RecordSnapshot?) -> Array[ActivityStep]

data/lib/paper_trail_diff/activity_version_collector.rb

@@ -4,15 +4,17 @@
 module PaperTrailDiff
   # Collects root and selected-descendant versions relevant to one root history range.
   class ActivityVersionCollector
-    #: (untyped, root_versions: Array[untyped], tree: AssociationTree, traversal: AssociationTraversal, ?range_start: untyped, ?range_end: untyped) -> void
+    #: (untyped, root_versions: Array[untyped], tree: AssociationTree, traversal: AssociationTraversal, ?range_start: untyped, ?range_end: untyped, ?prepared: PreparedActivityIndex?) -> void
     def initialize( # rubocop:disable Metrics/ParameterLists
       record,
       root_versions:,
       tree:,
       traversal:,
       range_start: root_versions.first,
-      range_end: root_versions.last
+      range_end: root_versions.last,
+      prepared: nil
     )
+      @prepared = prepared
       @record = record
       @root_versions = root_versions
       @tree = tree
@@ -32,6 +34,7 @@ module PaperTrailDiff
 
     private
 
+    # @rbs @prepared: PreparedActivityIndex?
     # @rbs @record: untyped
     # @rbs @root_versions: Array[untyped]
     # @rbs @tree: AssociationTree
@@ -59,7 +62,7 @@ module PaperTrailDiff
         @registry.add(group.fetch(:versions), branch: branch)
         next if subtree.empty?
 
-        child_path = join_path(path, reflection.name.to_s)
+        child_path = Support.association_path(path, reflection.name.to_s)
         collect_tree(group.fetch(:model), group.fetch(:ids), subtree,
                      path: child_path, branch: branch)
       end
@@ -97,6 +100,10 @@ module PaperTrailDiff
 
     #: (untyped, Array[untyped], untyped) -> Hash[String, untyped]
     def belongs_to_groups(parent_class, parent_versions, reflection)
+      if (prepared = @prepared)
+        rows = prepared.association_rows(parent_class, parent_versions, reflection)
+        return identity_groups(rows, reflection)
+      end
       rows = parent_class.paper_trail.version_association_class.where(
         version_id: parent_versions.map(&:id),
         foreign_key_name: reflection.foreign_key.to_s
@@ -106,9 +113,12 @@ module PaperTrailDiff
 
     #: (untyped, Array[untyped], untyped) -> Hash[String, untyped]
     def direct_child_groups(parent_class, parent_ids, reflection)
-      item_ids = ActivityChildCandidateLoader.new(
-        parent_class, parent_ids, reflection, @range
-      ).call
+      item_ids = if (prepared = @prepared)
+                   prepared.child_ids(parent_class, parent_ids, reflection, @range)
+                 else
+                   ActivityChildCandidateLoader.new(parent_class, parent_ids, reflection,
+                                                    @range).call
+                 end
       return {} if item_ids.empty?
 
       { reflection.klass.name => group(reflection.klass, item_ids) }
@@ -116,6 +126,11 @@ module PaperTrailDiff
 
     #: (untyped, Array[untyped], untyped) -> Hash[String, untyped]
     def habtm_groups(parent_class, parent_versions, reflection)
+      if (prepared = @prepared)
+        rows = prepared.association_rows(parent_class, parent_versions, reflection,
+                                         transactions: true)
+        return identity_groups(rows, reflection)
+      end
       transaction_ids = parent_versions.filter_map do |version|
         version.transaction_id if version.respond_to?(:transaction_id)
       end
@@ -133,7 +148,7 @@ module PaperTrailDiff
       identities.each do |model_class, class_rows|
         next unless model_class
 
-        ids = class_rows.map(&:foreign_key_id).compact.uniq
+        ids = class_rows.filter_map(&:foreign_key_id).uniq
         groups[model_class.name] = group(model_class, ids)
       end
       groups
@@ -162,13 +177,17 @@ module PaperTrailDiff
     def versions_for(model_class, ids)
       return [] if ids.empty?
 
+      if (prepared = @prepared)
+        return prepared.versions(model_class, ids).select { |version| @range.include?(version) }
+      end
+
       version_class = model_class.paper_trail.version_class
       @range.scope(
         version_class.where(
           item_type: model_class.base_class.name,
           item_id: ids
         )
-      ).to_a.select { |version| in_range?(version) }
+      ).to_a.select { |version| @range.include?(version) }
     end
 
     #: (untyped, untyped) -> untyped
@@ -179,15 +198,5 @@ module PaperTrailDiff
     rescue NameError
       nil
     end
-
-    #: (untyped) -> bool
-    def in_range?(version)
-      @range.include?(version)
-    end
-
-    #: (String, String) -> String
-    def join_path(parent, name)
-      parent.empty? ? name : "#{parent}.#{name}"
-    end
   end
 end

data/lib/paper_trail_diff/analysis.rb

@@ -34,10 +34,15 @@ module PaperTrailDiff
     # 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: false)
-      value = { diff: diff.to_h, timeline: Support.serialize(timeline) }
-      value[:activity_timeline] = Support.serialize(activity_timeline) if activity_timeline
+    #: (?snapshots: bool, ?metadata: bool) -> Hash[Symbol, untyped]
+    def to_h(snapshots: false, metadata: false)
+      value = { diff: diff.to_h, timeline: timeline.map { |step| step.to_h(metadata: metadata) } }
+      activity = activity_timeline
+      if activity
+        value[:activity_timeline] = activity.map do |step|
+          step.to_h(metadata: metadata, snapshots: snapshots)
+        end
+      end
       return value unless snapshots
 
       value.merge(

data/lib/paper_trail_diff/analysis_batch.rb

@@ -6,12 +6,13 @@ 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, ?version_scope: untyped, ?close_on_current: bool) -> void
+    #: (Array[untyped], time_range: TimeRange?, live_loader: untyped, history_preparer: untyped, analyzer: untyped, ?version_scope: untyped, ?close_on_current: bool, ?context_required: bool) -> void
     def initialize( # rubocop:disable Metrics/ParameterLists
       records, time_range:, live_loader:, history_preparer:, analyzer:, version_scope: nil,
-      close_on_current: false
+      close_on_current: false, context_required: false
     )
       @records = records
+      @context_required = context_required
       @time_range = time_range
       @version_scope = validated_scope(version_scope)
       @close_on_current = close_on_current
@@ -26,7 +27,8 @@ module PaperTrailDiff
       loaded = @live_loader.call(records)
       selected = BatchedRootVersions.new(
         records, time_range: @time_range, version_scope: @version_scope,
-                 live_endpoints: (loaded if @close_on_current)
+                 live_endpoints: (loaded if @close_on_current),
+                 context_required: @context_required
       ).call
       prepare(records, selected, loaded)
       records.to_h do |record|
@@ -42,6 +44,7 @@ module PaperTrailDiff
     # @rbs @time_range: TimeRange?
     # @rbs @version_scope: untyped
     # @rbs @close_on_current: bool
+    # @rbs @context_required: bool
     # @rbs @live_loader: untyped
     # @rbs @history_preparer: untyped
     # @rbs @analyzer: untyped
@@ -75,20 +78,38 @@ module PaperTrailDiff
     def prepare(records, selected, loaded)
       records.group_by(&:class).each_value do |grouped|
         versions = grouped.flat_map do |record|
-          selected.fetch(Endpoint.identity(record), RootVersionPlan.empty).versions
+          selected.fetch(Endpoint.identity(record), RootVersionPlan.empty).reconstruction_versions
         end
         next if versions.empty?
 
         roots = grouped.map { |record| loaded.fetch(Endpoint.identity(record), record) }
-        @history_preparer.call(roots, versions)
+        live = closes_live?(grouped, selected)
+        @history_preparer.call(roots, versions, **preparation_range(versions, live: live))
       end
     end
 
+    #: (Array[untyped], Hash[Array[String], RootVersionPlan]) -> bool
+    def closes_live?(records, selected)
+      records.any? do |record|
+        !selected.fetch(Endpoint.identity(record), RootVersionPlan.empty).closing_record.nil?
+      end
+    end
+
+    # A plan closing on the live record reads history up to now; the others
+    # stop at the window, so a past window does not load everything since.
+    #: (Array[untyped], ?live: bool) -> Hash[Symbol, untyped]
+    def preparation_range(versions, live: @close_on_current)
+      last = versions.map(&:created_at).max
+      end_at = [last, @time_range&.end_time, (Time.now.utc if live)].compact.max
+      { start_at: @time_range&.begin_time || versions.map(&:created_at).min, end_at: end_at }
+    end
+
     # A root with no versions in range has nothing to report, which is an empty
-    # result rather than a failed request.
+    # result rather than a failed request -- unless an activity view closes it
+    # on current state, where its descendants may still have moved.
     #: (untyped, RootVersionPlan) -> Analysis
     def analysis_for(record, plan)
-      return Analysis.empty if plan.empty?
+      return Analysis.empty if plan.empty? && !plan.closing_record
 
       @analyzer.call(record, plan)
     end

data/lib/paper_trail_diff/association_traversal.rb

@@ -4,6 +4,17 @@
 module PaperTrailDiff
   # Resolves and validates ActiveRecord reflections for a bounded association tree.
   class AssociationTraversal
+    # The class a `belongs_to` points at for this record, reading a polymorphic
+    # type column when there is one. Nil when that type names no class.
+    #: (untyped, untyped) -> untyped
+    def self.belongs_to_target(reflection, record)
+      return reflection.klass unless reflection.polymorphic?
+
+      Object.const_get(record.public_send(reflection.foreign_type).to_s)
+    rescue NameError
+      nil
+    end
+
     #: (AssociationTree) -> void
     def initialize(tree)
       @tree = tree
@@ -37,6 +48,18 @@ module PaperTrailDiff
       end.freeze
     end
 
+    # HABTM join rows have no versions of their own, so membership changes
+    # cannot be split into events once a range runs past the last root version
+    # into live state.
+    #: (untyped) -> void
+    def reject_live_habtm_activity!(model_class)
+      paths = habtm_paths(model_class)
+      return if paths.empty?
+
+      message = "live-ended activity cannot reconstruct HABTM event boundaries: #{paths.join(', ')}"
+      raise UnsupportedLiveActivityError, message
+    end
+
     #: (untyped, AssociationTree, path: String) -> Array[untyped]
     def reflections_for(model_class, tree, path:)
       key = [model_class.name.to_s, path, tree.object_id]

data/lib/paper_trail_diff/batch_boundary_resolver.rb

@@ -2,11 +2,11 @@
 # rbs_inline: enabled
 
 module PaperTrailDiff
-  # Resolves `:first` and `:last` endpoints for a whole batch in two queries per
+  # Resolves `:first` endpoints for a whole batch in a fixed number of queries per
   # model class. Left to the caller this is a per-root lookup, which reintroduces
   # exactly the queries a batched comparison exists to remove.
   class BatchBoundaryResolver
-    BOUNDARIES = %i[first last].freeze
+    BOUNDARIES = %i[first].freeze
 
     class << self
       #: (untyped) -> bool
@@ -45,16 +45,17 @@ module PaperTrailDiff
     #: (untyped, untyped, Hash[Array[String], Hash[Symbol, untyped]]) -> untyped
     def resolve(endpoint, other, index)
       return endpoint unless symbolic?(endpoint)
+      raise ConfigurationError, TimelineRange::LAST_REMOVED if endpoint == :last
 
       unless BOUNDARIES.include?(endpoint)
         raise ConfigurationError,
-              "unsupported boundary: #{endpoint.inspect}; use :first, :last, a version, or a record"
+              "unsupported boundary: #{endpoint.inspect}; use :first, a version, or a record"
       end
 
       identity = anchor_identity(other)
       unless identity
         raise ConfigurationError,
-              'a :first or :last endpoint needs the other endpoint to name a record'
+              'a :first endpoint needs the other endpoint to name a record'
       end
 
       index.dig(identity, endpoint) || endpoint
@@ -100,33 +101,24 @@ module PaperTrailDiff
 
     #: (Hash[Array[String], Hash[Symbol, untyped]], untyped, Array[untyped]) -> void
     def add_model_boundaries(index, model_class, ids)
-      first_ids, last_ids, versions = boundary_versions(model_class, ids)
+      firsts = first_versions(model_class, ids)
       ids.each do |id|
-        index[identity_key(model_class, id)] = {
-          first: versions[boundary_key(first_ids, id)],
-          last: versions[boundary_key(last_ids, id)]
-        }
+        index[identity_key(model_class, id)] = { first: firsts[id.to_s] }
       end
     end
 
-    # Two grouped queries name each root's outermost versions, and one more
-    # loads them, whatever the size of the batch.
-    #: (untyped, Array[untyped]) -> [Hash[untyped, untyped], Hash[untyped, untyped], Hash[untyped, untyped]]
-    def boundary_versions(model_class, ids)
+    # Each root's earliest version by time, in one query whatever the size of
+    # the batch. The lowest id is not the earliest version when ids are not
+    # sequential, as with UUIDs, so time decides and the usual ordering breaks
+    # a tie -- refusing one that ids cannot order.
+    #: (untyped, Array[untyped]) -> Hash[String, untyped]
+    def first_versions(model_class, ids)
       version_class = model_class.paper_trail.version_class
-      scope = version_class.where(item_type: model_class.base_class.name.to_s, item_id: ids)
-      first_ids = scope.group(:item_id).minimum(:id)
-      last_ids = scope.group(:item_id).maximum(:id)
-      loaded = version_class.where(id: (first_ids.values + last_ids.values).uniq).index_by(&:id)
-      [first_ids, last_ids, loaded]
-    end
-
-    # Grouped keys come back with whatever type the column uses, so match on the
-    # string form rather than assuming integers.
-    #: (Hash[untyped, untyped], untyped) -> untyped
-    def boundary_key(grouped, id)
-      key = grouped.keys.find { |candidate| candidate.to_s == id.to_s }
-      grouped[key]
+      table = version_class.arel_table
+      candidates = version_class.where(item_type: model_class.base_class.name.to_s, item_id: ids)
+                                .where(VersionQuery.no_earlier_version(table)).to_a
+      candidates.group_by { |version| version.item_id.to_s }
+                .transform_values { |versions| Support.chronological_sort(versions).first }
     end
 
     #: (untyped, untyped) -> Array[String]

data/lib/paper_trail_diff/batch_safety.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # Refuses known per-record association loading before a batch reconstructs it.
+  class BatchSafety
+    #: (AssociationTraversal, allow_expensive: bool) -> void
+    def initialize(traversal, allow_expensive:)
+      unless [true, false].include?(allow_expensive)
+        raise ConfigurationError, 'allow_expensive: must be true or false'
+      end
+
+      @traversal = traversal
+      @allow_expensive = allow_expensive
+    end
+
+    #: (untyped, ?historical: bool) -> void
+    def call(model, historical: true)
+      return if @allow_expensive
+
+      @traversal.selected_reflections(model).each do |path, reflection|
+        check(reflection, path, historical)
+      end
+    end
+
+    private
+
+    # @rbs @traversal: AssociationTraversal
+    # @rbs @allow_expensive: bool
+
+    #: (untyped, String, bool) -> void
+    def check(reflection, path, historical)
+      reason = reason_for(reflection, historical)
+      if reason
+        raise UnsupportedBatchPathError,
+              "association #{path} requires per-record reconstruction (#{reason}); " \
+              'remove this path or explicitly pass allow_expensive: true'
+      end
+      return unless reflection.options[:through]
+
+      check(reflection.through_reflection, path, historical)
+      check(reflection.source_reflection, path, historical)
+    end
+
+    #: (untyped, bool) -> String?
+    def reason_for(reflection, historical)
+      return 'association scope' if reflection.scope
+      return 'default-scoped target' if !reflection.polymorphic? && reflection.klass.default_scopes?
+      return unless historical && reflection.options[:through]
+      return if reflection.source_reflection.belongs_to?
+
+      'through source is not belongs_to'
+    end
+  end
+end

data/lib/paper_trail_diff/batched_root_analyzer.rb

@@ -5,13 +5,16 @@ module PaperTrailDiff
   # Builds one root's Analysis inside a batch, from versions the batch already
   # selected and history it already prepared.
   class BatchedRootAnalyzer
-    #: (tree: AssociationTree, timeline_snapshotter: untyped, activity_snapshotter: untyped, preparer: untyped, activity: bool) -> void
-    def initialize(tree:, timeline_snapshotter:, activity_snapshotter:, preparer:, activity:)
+    #: (tree: AssociationTree, timeline_snapshotter: untyped, activity_snapshotter: untyped, preparer: untyped, activity: bool, ?within: untyped, ?snapshots: bool, ?group: Symbol?) -> void
+    def initialize(tree:, timeline_snapshotter:, activity_snapshotter:, preparer:, activity:, within: nil, snapshots: false, group: nil) # rubocop:disable Metrics/ParameterLists, Layout/LineLength
       @tree = tree
       @timeline_snapshotter = timeline_snapshotter
       @activity_snapshotter = activity_snapshotter
       @preparer = preparer
       @activity = activity
+      @within = within
+      @snapshots = snapshots
+      @group = group
     end
 
     #: (untyped, RootVersionPlan) -> Analysis
@@ -22,7 +25,7 @@ module PaperTrailDiff
       TimelineBuilder.new(
         record,
         from: plan.versions.first,
-        to: plan.versions.last,
+        to: plan.closing_record || plan.versions.last,
         within: nil,
         plan: plan,
         snapshotter: @timeline_snapshotter
@@ -36,14 +39,20 @@ module PaperTrailDiff
     # @rbs @activity_snapshotter: untyped
     # @rbs @preparer: untyped
     # @rbs @activity: bool
+    # @rbs @within: untyped
+    # @rbs @snapshots: bool
+    # @rbs @group: Symbol?
 
     #: (untyped, RootVersionPlan) -> Analysis
     def activity_analysis(record, plan)
       range = TimelineRange.new(
-        record, from: plan.versions.first, to: plan.versions.last, within: nil, plan: plan
+        record, from: (@within ? nil : plan.versions.first),
+                to: (@within ? nil : plan.closing_record || plan.versions.last),
+                within: @within, plan: plan
       )
       ActivityTimelineBuilder.new(
-        record, range: range, tree: @tree, snapshotter: @activity_snapshotter
+        record, range: range, tree: @tree, snapshotter: @activity_snapshotter,
+                snapshots: @snapshots, group: @group
       ).analyze
     end
   end

data/lib/paper_trail_diff/batched_root_versions.rb

@@ -6,9 +6,13 @@ module PaperTrailDiff
   # 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, ?live_endpoints: Hash[Array[String], untyped]?) -> void
-    def initialize(records, time_range:, version_scope: nil, live_endpoints: nil)
+    #: (Array[untyped], time_range: TimeRange?, ?version_scope: untyped, ?live_endpoints: Hash[Array[String], untyped]?, ?context_required: bool) -> void
+    def initialize(records, time_range:, version_scope: nil, live_endpoints: nil,
+                   context_required: false)
       @records = records
+      # An activity view needs a root to reconstruct from even in a window with
+      # no root version, exactly as a single-record activity timeline does.
+      @context_required = context_required
       @time_range = time_range
       @version_scope = version_scope
       @live_endpoints = live_endpoints
@@ -32,6 +36,7 @@ module PaperTrailDiff
     # @rbs @time_range: TimeRange?
     # @rbs @version_scope: untyped
     # @rbs @live_endpoints: Hash[Array[String], untyped]?
+    # @rbs @context_required: bool
 
     #: (untyped, Array[untyped], Hash[Array[String], RootVersionPlan]) -> void
     def select_model(model_class, records, selected)
@@ -64,6 +69,7 @@ module PaperTrailDiff
         selected: chosen ? in_range.select { |version| chosen.include?(version.id) } : in_range,
         after_range: after_range,
         windowed: !@time_range.nil?,
+        context_required: @context_required,
         filtered: !@version_scope.nil?,
         live_endpoint: live_endpoint
       ).call
@@ -104,43 +110,9 @@ module PaperTrailDiff
       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)
+      range.first_trailing_versions(base_scope(model_class, ids))
     end
 
     #: (untyped, Array[untyped]) -> untyped
@@ -153,7 +125,7 @@ module PaperTrailDiff
 
     #: (untyped) -> Array[untyped]
     def ordered(relation)
-      relation.reorder(created_at: :asc, id: :asc).to_a
+      VersionQuery.chronological(relation).to_a
     end
 
     #: (untyped, untyped) -> Array[String]