paper_trail_diff 0.3.1 → 0.5.0

data/lib/paper_trail_diff/activity_event_route_finder.rb

@@ -7,63 +7,43 @@ module PaperTrailDiff
     #: (AssociationTraversal) -> void
     def initialize(traversal)
       @traversal = traversal
-      @collection_model = nil
-      @collection_tree = nil #: AssociationTree?
-      @collection_type = nil #: String?
-      @collection_path = nil #: String?
-      @collection_routes = nil #: Array[Array[untyped]]?
-      @belongs_to_model = nil
-      @belongs_to_tree = nil #: AssociationTree?
-      @belongs_to_type = nil #: String?
-      @belongs_to_path = nil #: String?
-      @belongs_to_routes = nil #: Array[Array[untyped]]?
+      @collection_routes = {} #: Hash[Array[untyped], Array[Array[untyped]]]
+      @belongs_to_routes = {} #: Hash[Array[untyped], Array[Array[untyped]]]
     end
 
     #: (untyped, AssociationTree, String, ?path: String) -> Array[Array[untyped]]
     def collection_routes(model_class, tree, target_type, path: '')
-      cached = @collection_routes
-      if cached && @collection_model.equal?(model_class) && @collection_tree.equal?(tree) &&
-         @collection_type == target_type && @collection_path == path
-        return cached
-      end
-
-      computed = freeze_routes(routes(model_class, tree, target_type, :has_many, path: path))
-      @collection_model = model_class
-      @collection_tree = tree
-      @collection_type = Support.immutable_copy(target_type)
-      @collection_path = Support.immutable_copy(path)
-      @collection_routes = computed
+      cached(@collection_routes, model_class, tree, target_type, path, :has_many)
     end
 
     #: (untyped, AssociationTree, String, ?path: String) -> Array[Array[untyped]]
     def belongs_to_routes(model_class, tree, target_type, path: '')
-      cached = @belongs_to_routes
-      if cached && @belongs_to_model.equal?(model_class) && @belongs_to_tree.equal?(tree) &&
-         @belongs_to_type == target_type && @belongs_to_path == path
-        return cached
-      end
-
-      computed = freeze_routes(routes(model_class, tree, target_type, :belongs_to, path: path))
-      @belongs_to_model = model_class
-      @belongs_to_tree = tree
-      @belongs_to_type = Support.immutable_copy(target_type)
-      @belongs_to_path = Support.immutable_copy(path)
-      @belongs_to_routes = computed
+      cached(@belongs_to_routes, model_class, tree, target_type, path, :belongs_to)
     end
 
     private
 
     # @rbs @traversal: AssociationTraversal
-    # @rbs @collection_model: untyped
-    # @rbs @collection_tree: AssociationTree?
-    # @rbs @collection_type: String?
-    # @rbs @collection_path: String?
-    # @rbs @collection_routes: Array[Array[untyped]]?
-    # @rbs @belongs_to_model: untyped
-    # @rbs @belongs_to_tree: AssociationTree?
-    # @rbs @belongs_to_type: String?
-    # @rbs @belongs_to_path: String?
-    # @rbs @belongs_to_routes: Array[Array[untyped]]?
+    # @rbs @collection_routes: Hash[Array[untyped], Array[Array[untyped]]]
+    # @rbs @belongs_to_routes: Hash[Array[untyped], Array[Array[untyped]]]
+
+    # Timelines interleave event types, so every requested combination is
+    # retained. Model, tree, and path are fixed per adapter, leaving one entry
+    # per selected item type.
+    #: (Hash[Array[untyped], Array[Array[untyped]]], untyped, AssociationTree, String, String, Symbol) -> Array[Array[untyped]]
+    def cached(store, model_class, tree, target_type, path, macro) # rubocop:disable Metrics/ParameterLists
+      key = [model_class, tree, target_type, path]
+      existing = store[key]
+      return existing if existing
+
+      store[cache_key(key)] =
+        freeze_routes(routes(model_class, tree, target_type, macro, path: path))
+    end
+
+    #: (Array[untyped]) -> Array[untyped]
+    def cache_key(key)
+      key.map { |part| part.is_a?(String) ? -part : part }.freeze
+    end
 
     #: (Array[Array[untyped]]) -> Array[Array[untyped]]
     def freeze_routes(routes)

data/lib/paper_trail_diff/activity_root_steps.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+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
+    module_function
+
+    #: (Array[untyped], Hash[Array[untyped], RecordSnapshot?]) -> Array[Step]
+    def call(root_versions, root_snapshots)
+      snapshots = root_versions.map { |version| root_snapshots.fetch(version_key(version)) }
+      root_versions.each_cons(2).with_index.map do |versions, index|
+        Step.new(
+          from_version: versions.fetch(0),
+          to_version: versions.fetch(1),
+          diff: Engine.compare(snapshots.fetch(index), snapshots.fetch(index + 1))
+        )
+      end.freeze
+    end
+
+    #: (untyped) -> Array[untyped]
+    def version_key(version)
+      [version.class.name, version.id]
+    end
+  end
+end

data/lib/paper_trail_diff/activity_snapshot_sequence.rb

@@ -11,9 +11,14 @@ module PaperTrailDiff
       @preparer = preparer
     end
 
-    #: (untyped, Array[untyped], ?start_at: untyped) -> void
-    def prepare(record, root_versions, start_at: root_versions.first.created_at)
-      @preparer.call(record, root_versions, start_at: start_at)
+    #: (untyped, Array[untyped], ?start_at: untyped, ?end_at: untyped) -> void
+    def prepare(
+      record,
+      root_versions,
+      start_at: root_versions.first.created_at,
+      end_at: root_versions.last.created_at
+    )
+      @preparer.call(record, root_versions, start_at: start_at, end_at: end_at)
     end
 
     #: (untyped, untyped) -> RecordSnapshot?

data/lib/paper_trail_diff/activity_timeline_builder.rb

@@ -17,6 +17,7 @@ module PaperTrailDiff
     #: () -> Array[ActivityStep]
     def build
       return time_builder.build if @range.time?
+      return no_steps if @range.unresolved?
       return build_to_current if Endpoint.record?(@to)
 
       Endpoint.validate!(@to)
@@ -27,6 +28,7 @@ module PaperTrailDiff
     #: () -> Analysis
     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'
@@ -35,7 +37,7 @@ module PaperTrailDiff
       root_versions = @range.select
       prepare_history(root_versions)
       events = collect_events(root_versions)
-      build_analysis(root_versions, event_history(root_versions, events))
+      build_analysis(root_versions, events, event_history(root_versions, events))
     end
 
     private
@@ -47,6 +49,12 @@ module PaperTrailDiff
     # @rbs @tree: AssociationTree
     # @rbs @snapshotter: untyped
 
+    #: () -> Array[ActivityStep]
+    def no_steps
+      steps = [] #: Array[ActivityStep]
+      steps.freeze
+    end
+
     #: () -> Array[ActivityStep]
     def build_between_versions
       root_versions = @range.select
@@ -60,7 +68,9 @@ module PaperTrailDiff
       validate_current_range!
       current_snapshot, captured_at = capture_current
       root_versions = VersionRange.new(@record, from: @from, to: @from).select_through_latest
-      prepare_history(root_versions)
+      # 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,
@@ -102,15 +112,12 @@ module PaperTrailDiff
       ).call
     end
 
-    #: (Array[untyped], ?start_at: untyped) -> void
-    def prepare_history(root_versions, start_at: nil)
+    #: (Array[untyped], ?end_at: untyped) -> void
+    def prepare_history(root_versions, end_at: nil)
       return unless @snapshotter.respond_to?(:prepare)
+      return @snapshotter.prepare(@record, root_versions) unless end_at
 
-      if start_at
-        @snapshotter.prepare(@record, root_versions, start_at: start_at)
-      else
-        @snapshotter.prepare(@record, root_versions)
-      end
+      @snapshotter.prepare(@record, root_versions, end_at: end_at)
     end
 
     #: (Array[untyped], Array[ActivityEvent], ?current: untyped, ?final_boundary: ActivityBoundary?, ?final_snapshot: RecordSnapshot?) -> Array[ActivityStep]
@@ -122,6 +129,18 @@ module PaperTrailDiff
       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]
+    def activity_steps(history, events, final_boundary, final_snapshot)
       steps = history.steps.dup
       previous_event = events.last
       previous_boundary = ActivityBoundary.from_version(previous_event.version) if previous_event
@@ -135,6 +154,16 @@ module PaperTrailDiff
       steps.freeze
     end
 
+    # A destroyed root has no later version, but its own event states that
+    # nothing follows it, so the removal can still close the timeline.
+    #: (Array[untyped]) -> ActivityBoundary?
+    def destroyed_boundary(root_versions)
+      version = root_versions.last
+      return unless version && version.event.to_s == 'destroy'
+
+      ActivityBoundary.destroyed(version)
+    end
+
     #: (Array[untyped], Array[ActivityEvent], ?current: untyped) -> ActivityHistory
     def event_history(root_versions, events, current: nil)
       ActivityHistoryBuilder.new(
@@ -145,32 +174,18 @@ module PaperTrailDiff
       ).call
     end
 
-    #: (Array[untyped], ActivityHistory) -> Analysis
-    def build_analysis(root_versions, history)
-      snapshots = root_versions.map do |version|
-        history.root_snapshots.fetch(version_key(version))
-      end
+    # 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(root_versions, events, history)
       Analysis.new(
         diff: Engine.compare(history.first_snapshot, history.last_snapshot),
-        timeline: build_root_steps(root_versions, snapshots),
-        activity_timeline: history.steps
-      )
-    end
-
-    #: (Array[untyped], Array[RecordSnapshot?]) -> Array[Step]
-    def build_root_steps(root_versions, snapshots)
-      root_versions.each_cons(2).with_index.map do |versions, index|
-        Step.new(
-          from_version: versions.fetch(0),
-          to_version: versions.fetch(1),
-          diff: Engine.compare(snapshots.fetch(index), snapshots.fetch(index + 1))
+        timeline: ActivityRootSteps.call(root_versions, history.root_snapshots),
+        activity_timeline: activity_steps(
+          history, events, destroyed_boundary(root_versions), nil
         )
-      end.freeze
-    end
-
-    #: (untyped) -> Array[untyped]
-    def version_key(version)
-      [version.class.name, version.id]
+      )
     end
 
     #: () -> TimeActivityTimelineBuilder

data/lib/paper_trail_diff/analysis.rb

@@ -8,6 +8,15 @@ module PaperTrailDiff
     attr_reader :timeline #: Array[Step]
     attr_reader :activity_timeline #: Array[ActivityStep]?
 
+    # 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
+      timeline = [] #: Array[Step]
+      activity_timeline = [] #: Array[ActivityStep]
+      new(diff: Diff.new, timeline: timeline, activity_timeline: activity_timeline)
+    end
+
     #: (diff: Diff, timeline: Array[Step], ?activity_timeline: Array[ActivityStep]?) -> void
     def initialize(diff:, timeline:, activity_timeline: nil)
       @diff = diff

data/lib/paper_trail_diff/analysis_batch.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # Builds one Analysis per root over a shared range, selecting every root's
+  # 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(records, time_range:, live_loader:, history_preparer:, analyzer:)
+      @records = records
+      @time_range = time_range
+      @live_loader = live_loader
+      @history_preparer = history_preparer
+      @analyzer = analyzer
+    end
+
+    #: () -> Hash[identity, Analysis]
+    def call
+      records = validated_records
+      selected = BatchedRootVersions.new(records, time_range: @time_range).call
+      prepare(records, selected)
+      records.to_h do |record|
+        key = Endpoint.identity(record)
+        [Support.immutable_copy(key), analysis_for(record, selected.fetch(key, []))]
+      end.freeze
+    end
+
+    private
+
+    # @rbs @records: Array[untyped]
+    # @rbs @time_range: TimeRange?
+    # @rbs @live_loader: untyped
+    # @rbs @history_preparer: untyped
+    # @rbs @analyzer: untyped
+
+    #: () -> Array[untyped]
+    def validated_records
+      raise ConfigurationError, 'records: must be an array' unless @records.is_a?(Array)
+
+      @records.each { |record| Endpoint.validate!(record) }
+      identities = @records.map { |record| Endpoint.identity(record) }
+      return @records if identities.uniq.length == identities.length
+
+      raise ConfigurationError, 'records: identities must be unique'
+    end
+
+    # Association history is prepared per model class across every selected root
+    # version, which is the work that would otherwise repeat for each record.
+    # 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(records, selected)
+      loaded = @live_loader.call(records)
+      records.group_by(&:class).each_value do |grouped|
+        versions = grouped.flat_map { |record| selected.fetch(Endpoint.identity(record), []) }
+        next if versions.empty?
+
+        roots = grouped.map { |record| loaded.fetch(Endpoint.identity(record), record) }
+        @history_preparer.call(roots, versions)
+      end
+    end
+
+    # 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(record, versions)
+      return Analysis.empty if versions.empty?
+
+      @analyzer.call(record, versions)
+    end
+  end
+end

data/lib/paper_trail_diff/batch_boundary_resolver.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # Resolves `:first` and `:last` endpoints for a whole batch in two 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
+
+    class << self
+      #: (untyped) -> bool
+      def symbolic?(endpoint)
+        endpoint.is_a?(Symbol)
+      end
+    end
+
+    #: (Array[[untyped, untyped]]) -> void
+    def initialize(pairs)
+      @pairs = pairs
+    end
+
+    # Returns the pairs with every resolvable symbol replaced. A symbol that
+    # names history the record does not have is left in place, so the caller can
+    # decide what an absent history means rather than being handed nil.
+    #: () -> Array[[untyped, untyped]]
+    def call
+      return @pairs unless @pairs.flatten(1).any? { |endpoint| symbolic?(endpoint) }
+
+      index = boundary_index
+      @pairs.map do |from, to|
+        [resolve(from, to, index), resolve(to, from, index)]
+      end
+    end
+
+    private
+
+    # @rbs @pairs: Array[[untyped, untyped]]
+
+    #: (untyped) -> bool
+    def symbolic?(endpoint)
+      self.class.symbolic?(endpoint)
+    end
+
+    #: (untyped, untyped, Hash[Array[String], Hash[Symbol, untyped]]) -> untyped
+    def resolve(endpoint, other, index)
+      return endpoint unless symbolic?(endpoint)
+
+      unless BOUNDARIES.include?(endpoint)
+        raise ConfigurationError,
+              "unsupported boundary: #{endpoint.inspect}; use :first, :last, 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'
+      end
+
+      index.dig(identity, endpoint) || endpoint
+    end
+
+    # A symbol carries no identity of its own, so the pair's other endpoint has
+    # to say which record is meant.
+    #: (untyped) -> Array[String]?
+    def anchor_identity(endpoint)
+      return if endpoint.nil? || symbolic?(endpoint)
+
+      Endpoint.identity(endpoint)
+    rescue InvalidEndpointError
+      nil
+    end
+
+    #: () -> Hash[Array[String], Hash[Symbol, untyped]]
+    def boundary_index
+      index = {} #: Hash[Array[String], Hash[Symbol, untyped]]
+      anchors.group_by { |model_class, _id| model_class }.each do |model_class, entries|
+        add_model_boundaries(index, model_class, entries.map { |_klass, id| id }.uniq)
+      end
+      index
+    end
+
+    #: () -> Array[[untyped, untyped]]
+    def anchors
+      @pairs.flatten(1).filter_map { |endpoint| anchor(endpoint) }.uniq
+    end
+
+    #: (untyped) -> [untyped, untyped]?
+    def anchor(endpoint)
+      return if endpoint.nil? || symbolic?(endpoint)
+
+      if Endpoint.version?(endpoint)
+        [Endpoint.model_class(endpoint), endpoint.item_id]
+      elsif Endpoint.record?(endpoint)
+        [endpoint.class, endpoint.id]
+      end
+    rescue InvalidEndpointError
+      nil
+    end
+
+    #: (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)
+      ids.each do |id|
+        index[identity_key(model_class, id)] = {
+          first: versions[boundary_key(first_ids, id)],
+          last: versions[boundary_key(last_ids, id)]
+        }
+      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)
+      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]
+    end
+
+    #: (untyped, untyped) -> Array[String]
+    def identity_key(model_class, id)
+      [model_class.base_class.name.to_s, id.to_s]
+    end
+  end
+end

data/lib/paper_trail_diff/batched_root_analyzer.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+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 = tree
+      @timeline_snapshotter = timeline_snapshotter
+      @activity_snapshotter = activity_snapshotter
+      @preparer = preparer
+      @activity = activity
+    end
+
+    #: (untyped, Array[untyped]) -> Analysis
+    def call(record, versions)
+      @preparer.call(record.class, historical: true)
+      return activity_analysis(record, versions) if @activity
+
+      TimelineBuilder.new(
+        record,
+        from: versions.first,
+        to: versions.last,
+        within: nil,
+        versions: versions,
+        snapshotter: @timeline_snapshotter
+      ).analyze
+    end
+
+    private
+
+    # @rbs @tree: AssociationTree
+    # @rbs @timeline_snapshotter: untyped
+    # @rbs @activity_snapshotter: untyped
+    # @rbs @preparer: untyped
+    # @rbs @activity: bool
+
+    #: (untyped, Array[untyped]) -> Analysis
+    def activity_analysis(record, versions)
+      range = TimelineRange.new(
+        record, from: versions.first, to: versions.last, within: nil, versions: versions
+      )
+      ActivityTimelineBuilder.new(
+        record, range: range, tree: @tree, snapshotter: @activity_snapshotter
+      ).analyze
+    end
+  end
+end

data/lib/paper_trail_diff/batched_root_versions.rb

@@ -0,0 +1,131 @@
+# 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?) -> void
+    def initialize(records, time_range:)
+      @records = records
+      @time_range = time_range
+    end
+
+    # Returns root versions per record identity, in chronological order.
+    #: () -> Hash[Array[String], Array[untyped]]
+    def call
+      return {} if @records.empty?
+
+      selected = {} #: Hash[Array[String], Array[untyped]]
+      @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?
+
+    #: (untyped, Array[untyped], Hash[Array[String], Array[untyped]]) -> void
+    def select_model(model_class, records, selected)
+      ids = records.map(&:id)
+      range = @time_range
+      grouped = grouped_versions(model_class, ids, range)
+      empty = {} #: Hash[String, untyped]
+      trailing = range ? trailing_versions(model_class, ids, range) : empty
+      records.each do |record|
+        key = identity(model_class, record.id)
+        selected[key] = versions_for(grouped.fetch(record.id.to_s, []), trailing[record.id.to_s])
+      end
+    end
+
+    # The window's own versions plus, when it has one, the later version needed
+    # to reveal the last mutation inside it. A window closing on the root's own
+    # destruction needs no later version, because none can exist.
+    #: (Array[untyped], untyped) -> Array[untyped]
+    def versions_for(in_range, trailing)
+      return in_range if @time_range.nil?
+      return in_range.freeze if in_range.empty?
+      return in_range.freeze if trailing.nil? && terminal_destroy?(in_range)
+
+      unless trailing
+        raise IncompleteTimeRangeError,
+              'time range requires a later root version to reconstruct its final change'
+      end
+
+      (in_range + [trailing]).freeze
+    end
+
+    #: (Array[untyped]) -> bool
+    def terminal_destroy?(versions)
+      versions.last&.event.to_s == 'destroy'
+    end
+
+    #: (untyped, Array[untyped], TimeRange?) -> Hash[String, Array[untyped]]
+    def grouped_versions(model_class, ids, range)
+      scope = base_scope(model_class, ids)
+      scope = range.scope(scope) if range
+      ordered(scope).group_by { |version| version.item_id.to_s }
+    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