paper_trail_diff 0.3.1 → 0.5.0

data/lib/paper_trail_diff/collection_comparator.rb

@@ -142,9 +142,22 @@ module PaperTrailDiff
       identities.sort_by { |identity| sortable_identity(identity) }
     end
 
+    # Identities sort by type first so that mixed id types stay comparable, then
+    # naturally within one type. Ordering by the printed form instead would put
+    # id 10 before id 2, which is deterministic but reads as unsorted wherever a
+    # result is rendered.
     #: (identity) -> Array[untyped]
     def sortable_identity(identity)
-      [identity.fetch(0), identity.fetch(1).inspect]
+      [identity.fetch(0), *sortable_id(identity.fetch(1))]
+    end
+
+    #: (untyped) -> Array[untyped]
+    def sortable_id(id)
+      case id
+      when Numeric then [0, id, '']
+      when String, Symbol then [1, 0, id.to_s]
+      else [2, 0, id.inspect]
+      end
     end
 
     #: (identity) -> void

data/lib/paper_trail_diff/collection_transition.rb

@@ -7,9 +7,12 @@ module PaperTrailDiff
     attr_reader :before #: RecordSnapshot?
     attr_reader :after #: RecordSnapshot?
 
+    # The origin is recorded by serial rather than by reference, because
+    # holding it would retain every earlier snapshot at the same path for the
+    # whole timeline.
     #: (from: AssociationSnapshot, before: RecordSnapshot?, after: RecordSnapshot?) -> void
     def initialize(from:, before:, after:)
-      @from_object_id = from.object_id
+      @from_serial = from.serial
       @before = before
       @after = after
       freeze
@@ -17,9 +20,9 @@ module PaperTrailDiff
 
     #: (AssociationSnapshot) -> bool
     def from?(association)
-      @from_object_id == association.object_id
+      @from_serial == association.serial
     end
 
-    # @rbs @from_object_id: Integer
+    # @rbs @from_serial: Integer
   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/endpoint.rb

@@ -10,10 +10,35 @@ module PaperTrailDiff
     def validate_pair!(from_endpoint, to_endpoint)
       validate!(from_endpoint)
       validate!(to_endpoint)
-      return if identity(from_endpoint) == identity(to_endpoint)
+      unless identity(from_endpoint) == identity(to_endpoint)
+        raise VersionMismatchError, 'endpoints must belong to the same PaperTrail item'
+      end
+
+      validate_order!(from_endpoint, to_endpoint)
+    end
+
+    # Two versions carry no visible cue about which is earlier, so transposing
+    # them is easy to do by accident and impossible to detect afterwards: the
+    # result is a valid inverse diff and carries no direction of its own. It is
+    # also redundant, because the two orders differ only in which side of each
+    # change is `from`. A current-record endpoint is exempt: it is self-evidently
+    # the live state, so putting it first is a deliberate reverse comparison.
+    #: (untyped, untyped) -> void
+    def validate_order!(from_endpoint, to_endpoint)
+      return unless reversed_versions?(from_endpoint, to_endpoint)
+
+      raise ReversedEndpointsError,
+            'version endpoints must be given in chronological order; ' \
+            'swap them to read the same difference in the other direction'
+    end
+
+    #: (untyped, untyped) -> bool
+    def reversed_versions?(from_endpoint, to_endpoint)
+      return false unless version?(from_endpoint) && version?(to_endpoint)
 
-      raise VersionMismatchError, 'endpoints must belong to the same PaperTrail item'
+      Support.compare_versions(from_endpoint, to_endpoint).positive?
     end
+    private_class_method :reversed_versions?
 
     #: (untyped) -> void
     def validate!(endpoint)

data/lib/paper_trail_diff/errors.rb

@@ -11,6 +11,9 @@ module PaperTrailDiff
   # Raised when compare endpoints do not belong to the same PaperTrail item.
   class VersionMismatchError < Error; end
 
+  # Raised when comparison endpoints are given in reverse chronological order.
+  class ReversedEndpointsError < Error; end
+
   # Raised when a live endpoint is not a clean, persisted ActiveRecord record.
   class InvalidEndpointError < Error; end
 

data/lib/paper_trail_diff/historical_association_reifier.rb

@@ -11,7 +11,10 @@ module PaperTrailDiff
         @habtm_transaction_id = habtm_version.transaction_id
       end
       @version_at = version.created_at
-      @reified_associations = {} #: Hash[Array[untyped], bool]
+      # Keyed on record identity rather than `object_id`, which Ruby may reuse
+      # once an earlier record in the same pass has been collected.
+      reified = {} #: Hash[untyped, Hash[untyped, bool]]
+      @reified_associations = reified.compare_by_identity
     end
 
     #: (untyped, Array[untyped]) -> void
@@ -24,14 +27,14 @@ module PaperTrailDiff
     # @rbs @transaction_id: untyped
     # @rbs @habtm_transaction_id: untyped
     # @rbs @version_at: untyped
-    # @rbs @reified_associations: Hash[Array[untyped], bool]
+    # @rbs @reified_associations: Hash[untyped, Hash[untyped, bool]]
 
     #: (untyped, untyped) -> void
     def reify_association(record, reflection)
-      key = [record.object_id, reflection.name]
-      return if @reified_associations[key]
+      reified = @reified_associations[record] ||= {} #: Hash[untyped, bool]
+      return if reified[reflection.name]
 
-      @reified_associations[key] = true
+      reified[reflection.name] = true
       case reflection.macro
       when :belongs_to
         reifier(:BelongsTo).reify(reflection, record, options, @transaction_id)

data/lib/paper_trail_diff/historical_snapshot_store.rb

@@ -16,20 +16,27 @@ module PaperTrailDiff
       @prepared_histories = {} #: Hash[Array[untyped], PreparedHistory]
     end
 
-    #: (untyped, Array[untyped], ?start_at: untyped) -> void
-    def prepare(record, root_versions, start_at: root_versions.first.created_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
+    )
       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,
         root_versions: root_versions,
         start_at: start_at,
+        end_at: end_at,
         tree: @tree,
         traversal: @traversal
       ).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?
@@ -44,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?
@@ -139,6 +141,7 @@ module PaperTrailDiff
         root_ids: records.map(&:id),
         root_versions: root_versions,
         start_at: root_versions.map(&:created_at).min,
+        end_at: root_versions.map(&:created_at).max,
         tree: @tree,
         traversal: @traversal,
         live_records: @live_graph_collector.call(records)

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)
@@ -50,7 +52,7 @@ module PaperTrailDiff
 
     #: (untyped, from: untyped, to: untyped, within: untyped) -> Array[Step]
     def timeline(record, from:, to:, within:)
-      prepare_traversal!(record.class, historical: true)
+      @traversal_preparer.call(record.class, historical: true)
       builder = TimelineBuilder.new(
         record,
         from: from,
@@ -65,7 +67,7 @@ module PaperTrailDiff
     def activity_timeline(record, from:, to:, within:)
       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
         payload[:step_count] = steps.length
@@ -76,11 +78,11 @@ module PaperTrailDiff
     #: (untyped, from: untyped, to: untyped, within: untyped, ?activity: bool) -> Analysis
     def analyze(record, from:, to:, within:, activity: false)
       if activity
-        prepare_traversal!(record.class, historical: true)
+        @traversal_preparer.call(record.class, historical: true)
         return activity_builder(record, from: from, to: to, within: within).analyze
       end
 
-      prepare_traversal!(record.class, historical: true)
+      @traversal_preparer.call(record.class, historical: true)
       TimelineBuilder.new(
         record,
         from: from,
@@ -90,6 +92,22 @@ module PaperTrailDiff
       ).analyze
     end
 
+    # Analyzes many roots over one shared range, preparing their history once.
+    #: (Array[untyped], within: untyped, ?activity: bool) -> Hash[identity, Analysis]
+    def analyze_many(records, within:, activity: false)
+      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),
+          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 +115,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
 
@@ -180,30 +217,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/prepared_association_reifier.rb

@@ -10,7 +10,10 @@ module PaperTrailDiff
       @boundary = boundary
       @habtm_boundary = habtm_boundary
       @fallback = fallback
-      @reified = {} #: Hash[Array[untyped], bool]
+      # Keyed on record identity rather than `object_id`, which Ruby may reuse
+      # once an earlier record in the same pass has been collected.
+      reified = {} #: Hash[untyped, Hash[untyped, bool]]
+      @reified = reified.compare_by_identity
     end
 
     #: (untyped, Array[untyped]) -> void
@@ -24,14 +27,14 @@ module PaperTrailDiff
     # @rbs @boundary: untyped
     # @rbs @habtm_boundary: untyped
     # @rbs @fallback: HistoricalAssociationReifier
-    # @rbs @reified: Hash[Array[untyped], bool]
+    # @rbs @reified: Hash[untyped, Hash[untyped, bool]]
 
     #: (untyped, untyped) -> void
     def reify_association(record, reflection)
-      key = [record.object_id, reflection.name]
-      return if @reified[key]
+      reified = @reified[record] ||= {} #: Hash[untyped, bool]
+      return if reified[reflection.name]
 
-      @reified[key] = true
+      reified[reflection.name] = true
       handled, records = @history.resolve(
         record,
         reflection,

data/lib/paper_trail_diff/prepared_edge_loader.rb

@@ -164,13 +164,15 @@ module PaperTrailDiff
       { model_class.name.to_s => group }
     end
 
+    # Keyed rather than scanned so that a wide edge stays linear in its width.
     #: (Array[Array[untyped]]) -> Hash[String, Array[untyped]]
     def group_ids_by_owner(pairs)
-      grouped = {} #: Hash[String, Array[untyped]]
-      pairs.each_with_object(grouped) do |(owner_id, child_id), result|
-        ids = result[owner_id.to_s] ||= []
-        ids << child_id unless ids.include?(child_id)
+      grouped = {} #: Hash[String, Hash[untyped, true]]
+      pairs.each do |owner_id, child_id|
+        ids = grouped[owner_id.to_s] ||= {} #: Hash[untyped, true]
+        ids[child_id] = true
       end
+      grouped.transform_values(&:keys)
     end
 
     #: (Hash[String, Array[untyped]], Hash[String, Array[untyped]]) -> Hash[String, Array[untyped]]

data/lib/paper_trail_diff/prepared_history_loader.rb

@@ -4,7 +4,7 @@
 module PaperTrailDiff
   # Expands the explicit association tree into a request-scoped PreparedHistory.
   class PreparedHistoryLoader
-    #: (untyped, root_versions: Array[untyped], tree: AssociationTree, traversal: AssociationTraversal, ?root_ids: Array[untyped], ?start_at: untyped, ?live_records: Array[untyped]) -> void
+    #: (untyped, root_versions: Array[untyped], tree: AssociationTree, traversal: AssociationTraversal, ?root_ids: Array[untyped], ?start_at: untyped, ?end_at: untyped, ?live_records: Array[untyped]) -> void
     def initialize( # rubocop:disable Metrics/ParameterLists
       record,
       root_versions:,
@@ -12,13 +12,14 @@ module PaperTrailDiff
       traversal:,
       root_ids: [record.id],
       start_at: root_versions.first.created_at,
+      end_at: nil,
       live_records: []
     )
       @record = record
       @root_ids = root_ids
       @tree = tree
       @traversal = traversal
-      @records = PreparedRecordIndex.new(start_at, live_records: live_records)
+      @records = PreparedRecordIndex.new(start_at, end_at: end_at, live_records: live_records)
       @history = PreparedHistory.new(@records)
       @edges = PreparedEdgeLoader.new(@records, root_versions, start_at: start_at)
       @prepared = {} #: Hash[Array[String], Array[String]]

data/lib/paper_trail_diff/prepared_record_index.rb

@@ -21,9 +21,14 @@ module PaperTrailDiff
       state
     end
 
+    # Mirrors PaperTrail's reifier, which writes attributes directly. Mass
+    # assignment would route reconstructed state through application-defined
+    # attribute writers and reify a different record than the version stored.
     #: () -> untyped
     def instantiate
-      @model_class.new(@attributes)
+      record = @model_class.new
+      @attributes.each { |name, value| record[name] = value }
+      record
     end
 
     private
@@ -108,6 +113,7 @@ module PaperTrailDiff
       @version_positions = @versions.each_with_index.to_h do |version, index|
         [version.id.to_s, index]
       end.freeze
+      @transaction_positions = build_transaction_positions
       @live = live
       @state_loader = state_loader
       @states = {} #: Hash[untyped, PreparedRecordState?]
@@ -115,8 +121,8 @@ module PaperTrailDiff
 
     #: (untyped) -> untyped
     def record_before(boundary)
-      version = versions.find { |candidate| eligible?(candidate, boundary) }
-      return state_for(version)&.instantiate if version
+      index = boundary_index(boundary)
+      return state_for(versions.fetch(index))&.instantiate if index
 
       @live&.instantiate
     end
@@ -146,6 +152,7 @@ module PaperTrailDiff
     # @rbs @state_loader: PreparedVersionStateLoader
     # @rbs @states: Hash[untyped, PreparedRecordState?]
     # @rbs @version_positions: Hash[String, Integer]
+    # @rbs @transaction_positions: Hash[untyped, Integer]
 
     #: (Integer) -> PreparedRecordState?
     def state_after(index)
@@ -153,16 +160,41 @@ module PaperTrailDiff
       successor ? state_for(successor) : @live
     end
 
-    #: (untyped, untyped) -> bool
-    def eligible?(version, boundary)
-      version.created_at >= boundary.created_at || same_transaction?(version, boundary)
+    # A version is eligible when it is at or after the boundary, or shares the
+    # boundary's transaction. The first is monotonic over the chronological
+    # list and the second is indexed, so neither rescans a long history once
+    # per boundary.
+    #: (untyped) -> Integer?
+    def boundary_index(boundary)
+      created_at = boundary.created_at
+      chronological = versions.bsearch_index do |candidate|
+        candidate.created_at >= created_at
+      end
+      transactional = transaction_index(boundary)
+      return chronological unless transactional
+      return transactional unless chronological
+
+      [chronological, transactional].min
     end
 
-    #: (untyped, untyped) -> bool
-    def same_transaction?(version, boundary)
+    #: (untyped) -> Integer?
+    def transaction_index(boundary)
       transaction_id = boundary.transaction_id if boundary.respond_to?(:transaction_id)
-      transaction_id && version.respond_to?(:transaction_id) &&
-        version.transaction_id == transaction_id
+      return unless transaction_id
+
+      @transaction_positions[transaction_id]
+    end
+
+    #: () -> Hash[untyped, Integer]
+    def build_transaction_positions
+      positions = {} #: Hash[untyped, Integer]
+      @versions.each_with_index do |version, index|
+        next unless version.respond_to?(:transaction_id)
+
+        transaction_id = version.transaction_id
+        positions[transaction_id] ||= index if transaction_id
+      end
+      positions.freeze
     end
 
     #: (untyped) -> PreparedRecordState?
@@ -185,9 +217,10 @@ module PaperTrailDiff
 
   # Request-scoped scalar history loaded once per model identity.
   class PreparedRecordIndex
-    #: (untyped, ?live_records: Array[untyped]) -> void
-    def initialize(start_at, live_records: [])
-      @start_time = start_at
+    #: (untyped, ?end_at: untyped, ?live_records: Array[untyped]) -> void
+    def initialize(start_at, end_at: nil, live_records: [])
+      @start_time = boundary_time(start_at)
+      @end_time = boundary_time(end_at)
       @seeded_live_records = live_records.to_h do |record|
         [identity(record.class, record.id), record]
       end
@@ -230,10 +263,17 @@ module PaperTrailDiff
     private
 
     # @rbs @start_time: untyped
+    # @rbs @end_time: untyped
     # @rbs @seeded_live_records: Hash[Array[String], untyped]
     # @rbs @state_loader: PreparedVersionStateLoader
     # @rbs @series: Hash[Array[String], PreparedRecordSeries]
 
+    # Callers bound the range with either a version or a bare timestamp.
+    #: (untyped) -> untyped
+    def boundary_time(value)
+      value.respond_to?(:created_at) ? value.created_at : value
+    end
+
     #: (untyped, untyped) -> Array[String]
     def identity(model_class, id)
       [model_class.base_class.name.to_s, id.to_s]
@@ -254,12 +294,47 @@ module PaperTrailDiff
       )
     end
 
+    # A PaperTrail version is a pre-change snapshot, so the state at the last
+    # selected boundary can only live in the next version after it. One
+    # trailing version per identity is retained, rather than every version
+    # recorded between the requested range and the present.
     #: (untyped, Array[untyped]) -> Array[untyped]
     def versions_for(model_class, ids)
-      model_class.paper_trail.version_class.where(
+      version_class = model_class.paper_trail.version_class
+      scope = version_class.where(
         item_type: model_class.base_class.name,
         item_id: ids
-      ).where('created_at >= ?', @start_time).order(:id).to_a
+      ).where(created_at: @start_time..)
+      scope = scope.where(window_condition(version_class)) if @end_time
+      scope.order(:id).to_a
+    end
+
+    # In range, or the earliest version after it, resolved in the same query
+    # rather than with a window function or one query per identity.
+    #: (untyped) -> untyped
+    def window_condition(version_class)
+      table = version_class.arel_table
+      table[:created_at].lteq(@end_time).or(first_after_range(table))
+    end
+
+    #: (untyped) -> untyped
+    def first_after_range(table)
+      arel = Object.const_get(:Arel) #: untyped
+      later = table.alias('paper_trail_diff_later_versions')
+      arel.const_get(:SelectManager).new
+          .from(later)
+          .project(arel.sql('1'))
+          .where(preceding_trailing_version(table, later))
+          .exists
+          .not
+    end
+
+    #: (untyped, untyped) -> untyped
+    def preceding_trailing_version(table, later)
+      later[:item_type].eq(table[:item_type])
+                       .and(later[:item_id].eq(table[:item_id]))
+                       .and(later[:created_at].gt(@end_time))
+                       .and(later[:created_at].lt(table[:created_at]))
     end
 
     #: (untyped, Array[untyped]) -> Array[untyped]