paper_trail_diff 0.12.0 → 0.13.1

data/lib/paper_trail_diff/snapshot_normalizer.rb

@@ -21,9 +21,7 @@ module PaperTrailDiff
     #: (String, AssociationSnapshot) -> AssociationSnapshot
     def association(path, snapshot)
       previous = @associations[path]
-      if previous && previous.kind == snapshot.kind && previous.records == snapshot.records
-        return previous
-      end
+      return previous if previous && same_association?(previous, snapshot)
 
       @associations[path] = snapshot
     end
@@ -38,10 +36,14 @@ module PaperTrailDiff
       left.attributes == right.attributes &&
         left.associations.keys == right.associations.keys &&
         left.associations.all? do |name, association|
-          other = right.associations[name]
-          other && association.kind == other.kind && association.records == other.records
+          same_association?(association, right.associations.fetch(name))
         end
     end
+
+    #: (AssociationSnapshot, AssociationSnapshot) -> bool
+    def same_association?(left, right)
+      left.kind == right.kind && left.records == right.records
+    end
   end
 
   # Converts an ActiveRecord graph into immutable, persistence-independent snapshots.
@@ -53,11 +55,13 @@ module PaperTrailDiff
       @traversal = traversal
       @pool = pool
       @structural_columns = {} #: Hash[String, Array[String]]
-      @excluded_attributes = {} #: Hash[Array[untyped], Array[String]]
+      @excluded_attributes = {} #: Hash[Array[untyped], Array[String?]]
     end
 
     #: (untyped, reifier: untyped) -> RecordSnapshot?
     def call(record, reifier:)
+      return unless record
+
       reflections = reflections_for(record, @tree, '')
       normalize_record(record, @tree, '', reifier, reflections)
     end
@@ -76,23 +80,54 @@ module PaperTrailDiff
     # Normalizes scalar attributes without traversing or loading associations.
     #: (untyped, tree: AssociationTree, path: String) -> snapshot_attributes
     def attributes_for(record, tree:, path:)
+      if record.instance_of?(PreparedRecordState)
+        return from_state(record, tree: tree,
+                                  path: path).attributes
+      end
+
       reflections = reflections_for(record, tree, path)
       normalized_attributes(record, reflections, path)
     end
 
+    # Same exclusions as AR normalization, applied to an already typed state.
+    #: (PreparedRecordState, tree: AssociationTree, path: String, ?incoming: untyped, ?associations: snapshot_associations) -> RecordSnapshot
+    def from_state(state, tree:, path:, incoming: nil, associations: {})
+      model = state.model_class
+      @structural_columns[path] ||= @traversal.incoming_relationship_columns(incoming) if incoming
+      reflections = @traversal.reflections_for(model, tree, path: path)
+      excluded = @excluded_attributes[[model, path]] ||=
+        build_excluded_attributes(model, reflections, path)
+      snapshot = RecordSnapshot.new(
+        type: model.name, id: state_id(model, state),
+        attributes: state.attributes.except(*excluded), associations: associations
+      )
+      pool_state(path, snapshot)
+    end
+
     private
 
+    # The id a live record of the same row reports: one value, or one per
+    # column of a composite key.
+    #: (untyped, PreparedRecordState) -> untyped
+    def state_id(model, state)
+      key = model.primary_key
+      key.instance_of?(Array) ? state.attributes.fetch_values(*key) : state.attributes.fetch(key)
+    end
+
+    #: (String, RecordSnapshot) -> RecordSnapshot
+    def pool_state(path, snapshot)
+      path.empty? ? snapshot : @pool.record(path, snapshot)
+    end
+
     # @rbs @tree: AssociationTree
     # @rbs @ignore_policy: IgnorePolicy
     # @rbs @traversal: AssociationTraversal
     # @rbs @pool: SnapshotPool
     # @rbs @structural_columns: Hash[String, Array[String]]
-    # @rbs @excluded_attributes: Hash[Array[untyped], Array[String]]
+    # @rbs @excluded_attributes: Hash[Array[untyped], Array[String?]]
 
-    #: (untyped, AssociationTree, String, untyped, Array[untyped]) -> RecordSnapshot?
+    #: (untyped, AssociationTree, String, untyped, Array[untyped]) -> RecordSnapshot
     def normalize_record(record, tree, path, reifier, reflections)
-      return unless record
-
       snapshot = RecordSnapshot.new(
         type: record.class.name,
         id: record.id,
@@ -104,38 +139,48 @@ module PaperTrailDiff
 
     #: (untyped, Array[untyped], String) -> snapshot_attributes
     def normalized_attributes(record, reflections, path)
-      attributes = record.attributes.dup
+      attributes = record.attributes
       excluded_attributes(record, reflections, path).each { |name| attributes.delete(name) }
-      attributes
+      StoredTimePrecision.apply(attributes, StoredTimePrecision.digits(record.class))
     end
 
     # Every input is fixed for one model class at one selected path, and the
     # path's structural columns are recorded before its records normalize, so
     # this is resolved once instead of per record per boundary.
-    #: (untyped, Array[untyped], String) -> Array[String]
+    #: (untyped, Array[untyped], String) -> Array[String?]
     def excluded_attributes(record, reflections, path)
       model_class = record.class
       @excluded_attributes[[model_class, path]] ||=
         build_excluded_attributes(model_class, reflections, path)
     end
 
-    #: (untyped, Array[untyped], String) -> Array[String]
+    #: (untyped, Array[untyped], String) -> Array[String?]
     def build_excluded_attributes(model_class, reflections, path)
-      primary_key = model_class.primary_key #: untyped
-      primary_keys = primary_key.is_a?(Array) ? primary_key : [primary_key]
-      # @type var primary_keys: Array[untyped]
-      primary_keys = primary_keys.map { |key| key.to_s } # rubocop:disable Style/SymbolProc
+      primary_keys = Array(model_class.primary_key) #: Array[String]
       ignored = @ignore_policy.attributes_for(path)
       structural = @structural_columns.fetch(path, [])
-      (primary_keys + ignored + relationship_columns(reflections) + structural).uniq.freeze
+      primary_keys + ignored + skipped_columns(model_class) +
+        relationship_columns(reflections) + structural
+    end
+
+    # `has_paper_trail skip:` columns are never written to a version, so history
+    # holds only their defaults. Compared with a live row they would report a
+    # change nobody recorded.
+    #: (untyped) -> Array[String]
+    def skipped_columns(model_class)
+      return [] unless Support.versioned?(model_class)
+
+      # PaperTrail stores these as strings, or hashes keyed by strings.
+      entries = model_class.paper_trail_options.fetch(:skip) #: Array[untyped]
+      entries.flat_map { |entry| entry.instance_of?(Hash) ? entry.keys : entry }
     end
 
-    #: (Array[untyped]) -> Array[String]
+    # A non-polymorphic reflection has no foreign type, so it adds nil, which
+    # excludes nothing.
+    #: (Array[untyped]) -> Array[String?]
     def relationship_columns(reflections)
       reflections.select { |reflection| reflection.macro == :belongs_to }.flat_map do |reflection|
-        columns = [reflection.foreign_key.to_s]
-        columns << reflection.foreign_type.to_s if reflection.polymorphic?
-        columns
+        [reflection.foreign_key, reflection.foreign_type]
       end
     end
 
@@ -143,27 +188,20 @@ module PaperTrailDiff
     def normalize_associations(record, tree, path, reifier, reflections)
       reflections.to_h do |reflection|
         name = reflection.name.to_s
-        subtree = tree.child(name)
-        raise ConfigurationError, "missing traversal subtree: #{name}" unless subtree
-
-        [name, association_snapshot(record, reflection, subtree, path, reifier)]
+        [name, association_snapshot(record, reflection, tree.children.fetch(name), path, reifier)]
       end
     end
 
     #: (untyped, untyped, AssociationTree, String, untyped) -> AssociationSnapshot
-    def association_snapshot( # rubocop:disable Metrics/AbcSize
+    def association_snapshot(
       record,
       reflection,
       subtree,
       path,
       reifier
     )
-      associated = record.public_send(reflection.name)
-      records = if AssociationSnapshot.collection_kind?(reflection.macro)
-                  associated.to_a
-                else
-                  Array(associated).compact
-                end
+      # A reified history can hold a member PaperTrail could not rebuild.
+      records = Array(record.public_send(reflection.name)).compact
       child_path = Support.association_path(path, reflection.name.to_s)
       @structural_columns[child_path] ||= @traversal.incoming_relationship_columns(reflection)
       snapshot = AssociationSnapshot.new(
@@ -175,10 +213,9 @@ module PaperTrailDiff
 
     #: (Array[untyped], AssociationTree, String, untyped) -> Array[RecordSnapshot]
     def normalize_children(records, tree, path, reifier)
-      reflections_by_class = {} #: Hash[String, Array[untyped]]
-      records.filter_map do |child|
-        type = child.class.name
-        reflections = reflections_by_class[type] ||= reflections_for(child, tree, path)
+      reflections_by_class = {} #: Hash[untyped, Array[untyped]]
+      records.map do |child|
+        reflections = reflections_by_class[child.class] ||= reflections_for(child, tree, path)
         reifier.reify(child, reflections) unless reflections.empty?
         normalize_record(child, tree, path, reifier, reflections)
       end
@@ -186,8 +223,6 @@ module PaperTrailDiff
 
     #: (untyped, AssociationTree, String) -> Array[untyped]
     def reflections_for(record, tree, path)
-      return [] unless record
-
       @traversal.reflections_for(record.class, tree, path: path)
     end
   end

data/lib/paper_trail_diff/step.rb

@@ -33,12 +33,17 @@ module PaperTrailDiff
       diff.empty?
     end
 
-    #: () -> Hash[Symbol, untyped]
-    def to_h
+    # The root event whose change this step reports.
+    #: () -> ActivityBoundary
+    def source_boundary = from_boundary
+
+    # The same shape as `ActivityStep#to_h`, so a consumer reads both step
+    # types alike; each boundary carries its own `version_id`.
+    #: (?metadata: bool) -> Hash[Symbol, untyped]
+    def to_h(metadata: false)
       {
-        from_version_id: from_version.id,
-        to_version_id: to_version&.id,
-        to_boundary: to_boundary.to_h,
+        from: from_boundary.to_h(metadata: metadata),
+        to: to_boundary.to_h(metadata: metadata),
         diff: diff.to_h
       }
     end

data/lib/paper_trail_diff/stored_time_precision.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # Matches time values to the precision PaperTrail actually stored.
+  #
+  # PaperTrail's JSON serializer, and a `json` or `jsonb` object column, write
+  # times through ActiveSupport's JSON encoder, which keeps only
+  # `ActiveSupport::JSON::Encoding.time_precision` fractional digits
+  # (milliseconds by default). The live row keeps the database's precision, so
+  # comparing the two would report every timestamp as changed even though
+  # nothing was edited. Truncating every side to the stored precision is
+  # idempotent, so values that came from history are unaffected and only the
+  # digits history could never have held are dropped.
+  module StoredTimePrecision
+    NANOSECOND_DIGITS = 9
+    JSON_COLUMN_TYPES = %i[json jsonb].freeze
+    private_constant :NANOSECOND_DIGITS, :JSON_COLUMN_TYPES
+
+    module_function
+
+    # Fractional digits a model's history keeps for times, or nil when the
+    # history is stored losslessly.
+    #: (untyped) -> Integer?
+    def digits(model_class)
+      return unless Support.versioned?(model_class)
+      return unless json_history?(model_class.paper_trail.version_class)
+
+      active_support = Object.const_get(:ActiveSupport) #: untyped
+      active_support.const_get(:JSON).const_get(:Encoding).time_precision
+    end
+
+    #: (Hash[untyped, untyped], Integer?) -> Hash[untyped, untyped]
+    def apply(attributes, digits)
+      return attributes unless digits
+
+      attributes.transform_values { |value| truncate(value, digits) }
+    end
+
+    #: (untyped, Integer) -> untyped
+    def truncate(value, digits)
+      return value unless value.is_a?(Time) && digits < NANOSECOND_DIGITS
+
+      # ActiveSupport's Time#change, which also serves TimeWithZone.
+      time = value #: untyped
+      step = 10**(NANOSECOND_DIGITS - [digits, 0].max) #: Integer
+      remainder = time.nsec % step
+      remainder.zero? ? time : time.change(nsec: time.nsec - remainder)
+    end
+
+    #: (untyped) -> bool
+    def json_history?(version_class)
+      columns = version_class.columns_hash
+      json_column = %w[object object_changes].any? do |name|
+        JSON_COLUMN_TYPES.include?(columns[name]&.type)
+      end
+      json_column || json_serializer?
+    end
+    private_class_method :json_history?
+
+    #: () -> bool
+    def json_serializer?
+      paper_trail = Object.const_get(:PaperTrail) #: untyped
+      paper_trail.serializer.equal?(paper_trail.const_get(:Serializers).const_get(:JSON))
+    end
+    private_class_method :json_serializer?
+  end
+end

data/lib/paper_trail_diff/support.rb

@@ -8,15 +8,13 @@ module PaperTrailDiff
 
     #: (untyped) -> untyped
     def immutable_copy(value)
-      return value if value.frozen?
-
       case value
       when Hash
         immutable_hash(value)
       when Array
         value.map { |item| immutable_copy(item) }.freeze
       else
-        duplicate_and_freeze(value)
+        value.frozen? ? value : duplicate_and_freeze(value)
       end
     end
 
@@ -94,6 +92,18 @@ module PaperTrailDiff
       model_class.respond_to?(:paper_trail_options) && !model_class.paper_trail_options.nil?
     end
 
+    # `versions.item_id` is often a string column -- PaperTrail's setup for UUID
+    # keys -- while the model's own key is an integer. An id read from history
+    # is cast to the key's type, or the same record read once from history and
+    # once from its live row would count as two.
+    #: (untyped, untyped) -> untyped
+    def record_id(model_class, id)
+      key = model_class.primary_key
+      return id if id.nil? || !key.is_a?(String)
+
+      model_class.type_for_attribute(key).cast(id)
+    end
+
     #: (untyped) -> bool
     def sequential_id?(id)
       id.is_a?(Integer) || id.to_s.match?(/\A\d+\z/)

data/lib/paper_trail_diff/time_activity_timeline_builder.rb

@@ -28,7 +28,7 @@ module PaperTrailDiff
     #: () -> Analysis
     def analyze
       history, plan, closing, closing_snapshot, captured_at = history_and_versions
-      final = closing_snapshot || history.last_snapshot
+      final = plan.closes_on_destroy ? nil : closing_snapshot || history.last_snapshot
       Analysis.new(
         diff: Engine.compare(history.first_snapshot, final),
         timeline: ActivityRootSteps.call(
@@ -52,7 +52,10 @@ module PaperTrailDiff
     #: () -> [ActivityHistory, RootVersionPlan, ActivityStep?, RecordSnapshot?, untyped]
     def history_and_versions
       plan = @range.select_plan(context_required: !@tree.empty?)
-      return [ActivityHistory.empty, plan, nil, nil, nil] if plan.reconstruction_versions.empty?
+      reject_live_habtm! if plan.closing_record
+      if plan.reconstruction_versions.empty? && !plan.closing_record
+        return [ActivityHistory.empty, plan, nil, nil, nil]
+      end
 
       # A window closing on current state runs to the instant it is captured,
       # not to the last root version, or descendants that moved after that
@@ -60,6 +63,11 @@ module PaperTrailDiff
       history_for(plan, plan.closing_record ? Time.now.utc : nil)
     end
 
+    #: () -> void
+    def reject_live_habtm!
+      AssociationTraversal.new(@tree).reject_live_habtm_activity!(@record.class)
+    end
+
     #: (RootVersionPlan, untyped) -> [ActivityHistory, RootVersionPlan, ActivityStep?, RecordSnapshot?, untyped]
     def history_for(plan, captured_at)
       root_versions = plan.reconstruction_versions
@@ -69,7 +77,7 @@ module PaperTrailDiff
         return [ActivityHistory.empty, plan, nil, nil, nil]
       end
 
-      history = build_history(root_versions, events)
+      history = build_history(root_versions, events, current: plan.closing_record)
       snapshot = current_snapshot(plan)
       closing = closing_step(history, selected.last, plan, captured_at, snapshot)
       [history, plan, closing, snapshot, captured_at]
@@ -91,12 +99,15 @@ module PaperTrailDiff
       collect_events(root_versions, range_end: captured_at)
     end
 
-    #: (Array[untyped], Array[ActivityEvent]) -> ActivityHistory
-    def build_history(root_versions, events)
+    # Events after the last root version read the root from the live record
+    # when the window closes on it, as an explicit `to: record` range does.
+    #: (Array[untyped], Array[ActivityEvent], ?current: untyped) -> ActivityHistory
+    def build_history(root_versions, events, current: nil)
       ActivityHistoryBuilder.new(
         root_versions,
         events,
         @snapshotter,
+        current: current,
         include_step: ->(event) { @range.include?(event.version) },
         snapshots: @retain
       ).call
@@ -150,13 +161,13 @@ module PaperTrailDiff
     # have moved since it.
     #: (ActivityHistory, untyped, untyped, RecordSnapshot?) -> ActivityStep?
     def current_step(history, record, captured_at, snapshot)
-      previous = history.steps.last&.to_boundary
+      previous = history.last_boundary
       return unless previous
 
       ActivityStep.between(
         from_boundary: previous,
         to_boundary: ActivityBoundary.current(record, captured_at: captured_at),
-        from_snapshot: history.last_snapshot, to_snapshot: snapshot, retain: @retain
+        from_snapshot: history.last_event_snapshot, to_snapshot: snapshot, retain: @retain
       )
     end
 
@@ -184,6 +195,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.begin_time,
         range_end: range_end || root_versions.last
       ).call

data/lib/paper_trail_diff/time_range.rb

@@ -41,14 +41,33 @@ module PaperTrailDiff
     #: (untyped) -> untyped
     def trailing_scope(relation)
       column = relation.klass.arel_table[:created_at]
-      predicate = exclude_end? ? column.gteq(end_time) : column.gt(end_time)
-      relation.where(predicate)
+      relation.where(after_end(column))
+    end
+
+    # Each item's earliest version after the range, keyed by item id. One row
+    # per item comes back from a NOT EXISTS rather than a window function, so
+    # the query stays portable; a timestamp tie keeps the lower id.
+    #: (untyped) -> Hash[String, untyped]
+    def first_trailing_versions(relation)
+      table = relation.klass.arel_table
+      first_after = VersionQuery.no_earlier_version(table) do |earlier|
+        after_end(earlier[:created_at])
+      end
+      versions = VersionQuery.chronological(trailing_scope(relation).where(first_after)).to_a
+      first = {} #: Hash[String, untyped]
+      versions.each { |version| first[version.item_id.to_s] ||= version }
+      first
     end
 
     private
 
     # @rbs @exclude_end: bool
 
+    #: (untyped) -> untyped
+    def after_end(column)
+      exclude_end? ? column.gteq(end_time) : column.gt(end_time)
+    end
+
     #: () -> Range[Time]
     def query_range
       exclude_end? ? (begin_time...end_time) : (begin_time..end_time)

data/lib/paper_trail_diff/time_version_range.rb

@@ -12,14 +12,9 @@ module PaperTrailDiff
       @live_endpoint = live_endpoint
     end
 
-    #: (?context_required: bool) -> Array[untyped]
-    def select(context_required: false)
-      select_plan(context_required: context_required).versions
-    end
-
     #: (?context_required: bool) -> RootVersionPlan
     def select_plan(context_required: false)
-      relation = versions_relation
+      relation = Endpoint.versions(@record)
       in_range = ordered(@time_range.scope(relation).to_a)
       RootVersionSelection.new(
         in_range: in_range,
@@ -40,18 +35,9 @@ module PaperTrailDiff
     # @rbs @version_scope: untyped
     # @rbs @live_endpoint: untyped
 
-    #: () -> untyped
-    def versions_relation
-      association_name = @record.class.versions_association_name
-      @record.public_send(association_name)
-    rescue NoMethodError => e
-      message = 'record does not expose a PaperTrail version history'
-      raise InvalidTimelineRangeError, message, cause: e
-    end
-
     #: (untyped) -> untyped
     def trailing_version(relation)
-      @time_range.trailing_scope(relation).reorder(created_at: :asc, id: :asc).first
+      VersionQuery.chronological(@time_range.trailing_scope(relation)).first
     end
 
     #: (Array[untyped]) -> Array[untyped]

data/lib/paper_trail_diff/timeline_builder.rb

@@ -4,15 +4,15 @@
 module PaperTrailDiff
   # Selects and compares a chronological slice of a record's version history.
   class TimelineBuilder
-    #: (untyped, from: untyped, to: untyped, snapshotter: untyped, ?within: untyped, ?versions: Array[untyped]?, ?version_scope: untyped, ?plan: RootVersionPlan?, ?live_endpoint: untyped) -> void
+    #: (untyped, from: untyped, to: untyped, snapshotter: untyped, ?within: untyped, ?version_scope: untyped, ?plan: RootVersionPlan?, ?live_endpoint: untyped) -> void
     def initialize( # rubocop:disable Metrics/ParameterLists
-      record, from:, to:, snapshotter:, within: nil, versions: nil, version_scope: nil, plan: nil,
+      record, from:, to:, snapshotter:, within: nil, version_scope: nil, plan: nil,
       live_endpoint: nil
     )
       @record = record
       @range = TimelineRange.new(
         record, from: from, to: to, within: within,
-                versions: versions, version_scope: version_scope, plan: plan,
+                version_scope: version_scope, plan: plan,
                 live_endpoint: live_endpoint
       )
       @snapshotter = snapshotter
@@ -48,7 +48,8 @@ module PaperTrailDiff
       versions = plan.versions
       @snapshotter.prepare(@record, versions) if @snapshotter.respond_to?(:prepare)
       steps = build_steps(plan)
-      [steps, @snapshotter.call(versions.first), @snapshotter.call(plan.final_endpoint)]
+      final = plan.closes_on_destroy ? nil : @snapshotter.call(plan.final_endpoint)
+      [steps, @snapshotter.call(versions.first), final]
     end
 
     #: (RootVersionPlan) -> Array[Step]

data/lib/paper_trail_diff/timeline_range.rb

@@ -4,18 +4,21 @@
 module PaperTrailDiff
   # Chooses explicit-version or wall-clock selection for one timeline request.
   class TimelineRange
-    BOUNDARY_SYMBOLS = %i[first last].freeze
+    BOUNDARY_SYMBOLS = %i[first].freeze
+    # `:last` once named the last version, whose recorded state is the one
+    # *before* the latest change, so a range ending there silently dropped it.
+    LAST_REMOVED = '`:last` was removed because it left out the latest change: omit `to:` ' \
+                   'to end at current state, or pass a version'
 
     attr_reader :from #: untyped
     attr_reader :to #: untyped
     attr_reader :time_range #: TimeRange?
 
-    #: (untyped, from: untyped, to: untyped, within: untyped, ?versions: Array[untyped]?, ?version_scope: untyped, ?plan: RootVersionPlan?, ?live_endpoint: untyped) -> void
-    def initialize(record, from:, to:, within:, versions: nil, version_scope: nil, plan: nil, live_endpoint: nil) # rubocop:disable Metrics/ParameterLists, Layout/LineLength
+    #: (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped, ?plan: RootVersionPlan?, ?live_endpoint: untyped) -> void
+    def initialize(record, from:, to:, within:, version_scope: nil, plan: nil, live_endpoint: nil) # rubocop:disable Metrics/ParameterLists
       @record = record
       @plan = plan
       @live_endpoint = live_endpoint
-      @versions = (plan ? plan.versions : versions)&.freeze
       @version_scope = version_scope
       @requested_from = from
       @requested_to = to
@@ -26,11 +29,12 @@ module PaperTrailDiff
       freeze
     end
 
-    # A record with no versions has no first or last boundary to resolve, which
-    # is an empty history rather than a bad request.
+    # A record with no versions has no first boundary to resolve, which
+    # is an empty history rather than a bad request. Both endpoints are
+    # required, so only `:first` can resolve to nothing; a window has none.
     #: () -> bool
     def unresolved?
-      (symbolic?(@requested_from) && @from.nil?) || (symbolic?(@requested_to) && @to.nil?)
+      !time? && (@from.nil? || @to.nil?)
     end
 
     # A batch may have selected these versions already, in which case reselecting
@@ -49,27 +53,7 @@ module PaperTrailDiff
                    live_endpoint: @live_endpoint
         ).select_plan(context_required: context_required)
       end
-      return RootVersionPlan.empty if unresolved?
-
-      VersionRange.new(
-        @record, from: @from, to: @to, version_scope: @version_scope
-      ).select_plan_for_range
-    end
-
-    #: (?context_required: bool) -> Array[untyped]
-    def select(context_required: false)
-      preselected = @versions
-      return preselected if preselected
-
-      range = time_range
-      if range
-        return TimeVersionRange.new(
-          @record, time_range: range, version_scope: @version_scope
-        ).select(context_required: context_required)
-      end
-      return empty_versions if unresolved?
-
-      VersionRange.new(@record, from: @from, to: @to, version_scope: @version_scope).select
+      explicit_plan
     end
 
     #: () -> bool
@@ -91,7 +75,6 @@ module PaperTrailDiff
     private
 
     # @rbs @record: untyped
-    # @rbs @versions: Array[untyped]?
     # @rbs @plan: RootVersionPlan?
     # @rbs @version_scope: untyped
     # @rbs @live_endpoint: untyped
@@ -100,43 +83,43 @@ module PaperTrailDiff
     # @rbs @from: untyped
     # @rbs @to: untyped
 
-    #: () -> Array[untyped]
-    def empty_versions
-      versions = [] #: Array[untyped]
-      versions.freeze
+    #: () -> RootVersionPlan
+    def explicit_plan
+      return RootVersionPlan.empty if unresolved?
+      if Endpoint.record?(@to)
+        return VersionRange.new(@record, from: @from, to: @from, version_scope: @version_scope)
+                           .select_plan_through_current(@to)
+      end
+
+      VersionRange.new(
+        @record, from: @from, to: @to, version_scope: @version_scope
+      ).select_plan_for_range
     end
 
     #: (untyped) -> bool
     def symbolic?(boundary)
-      boundary.is_a?(Symbol)
+      boundary.instance_of?(Symbol)
     end
 
-    # Resolving `:first` and `:last` here keeps callers from depending on the
+    # Resolving `:first` here keeps callers from depending on the
     # order PaperTrail happens to give its versions association, which a caller
     # is also free to reorder.
     #: (untyped) -> untyped
     def resolve(boundary)
       return boundary unless symbolic?(boundary)
+      raise InvalidTimelineRangeError, LAST_REMOVED if boundary == :last
 
       unless BOUNDARY_SYMBOLS.include?(boundary)
         raise InvalidTimelineRangeError,
-              "unsupported boundary: #{boundary.inspect}; use :first, :last, a version, or a record"
+              "unsupported boundary: #{boundary.inspect}; use :first, a version, or a record"
       end
 
-      boundary == :first ? ordered_versions.first : ordered_versions.last
+      ordered_versions.first
     end
 
     #: () -> untyped
     def ordered_versions
-      versions_relation.reorder(created_at: :asc, id: :asc)
-    end
-
-    #: () -> untyped
-    def versions_relation
-      @record.public_send(@record.class.versions_association_name)
-    rescue NoMethodError => e
-      message = 'record does not expose a PaperTrail version history'
-      raise InvalidTimelineRangeError, message, cause: e
+      VersionQuery.chronological(Endpoint.versions(@record))
     end
 
     #: (untyped) -> TimeRange?