paper_trail_diff 0.14.0 → 0.15.0

data/lib/paper_trail_diff/prepared_record_index.rb

@@ -133,6 +133,17 @@ module PaperTrailDiff
       state_before(boundary)&.instantiate
     end
 
+    # A record created in the boundary's own transaction has no state before
+    # it, yet a HABTM checkpoint saved later in that transaction records it as
+    # a member. Such a member is read as it was created.
+    #: (untyped) -> untyped
+    def record_created_in(boundary)
+      index = transaction_index(boundary)
+      return unless index && versions.fetch(index).event == 'create'
+
+      state_after(index)&.instantiate
+    end
+
     #: (untyped) -> PreparedRecordState?
     def state_before(boundary)
       index = boundary_index(boundary)
@@ -179,7 +190,7 @@ module PaperTrailDiff
       [state_for(version), state_after(index)].compact
     end
 
-    #: (untyped) -> [Hash[untyped, untyped], Hash[untyped, untyped]]?
+    #: (untyped) -> [PreparedRecordState, PreparedRecordState]?
     def transition(version)
       index = @version_positions[version.id.to_s]
       return unless index
@@ -188,7 +199,7 @@ module PaperTrailDiff
       after = state_after(index)
       return unless before && after && before.model_class == after.model_class
 
-      [before.attributes, after.attributes]
+      [before, after]
     end
 
     private
@@ -228,7 +239,7 @@ module PaperTrailDiff
 
     #: (untyped) -> Integer?
     def transaction_index(boundary)
-      transaction_id = boundary.transaction_id if boundary.respond_to?(:transaction_id)
+      transaction_id = VersionBoundary.transaction_id(boundary)
       return unless transaction_id
 
       @transaction_positions[transaction_id]
@@ -238,9 +249,7 @@ module PaperTrailDiff
     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
+        transaction_id = VersionBoundary.transaction_id(version)
         positions[transaction_id] ||= index if transaction_id
       end
       positions.freeze
@@ -304,6 +313,11 @@ module PaperTrailDiff
       @series.fetch(identity(model_class, id)).record_before(boundary)
     end
 
+    #: (untyped, untyped, untyped) -> untyped
+    def record_created_in(model_class, id, boundary)
+      @series.fetch(identity(model_class, id)).record_created_in(boundary)
+    end
+
     #: (untyped, untyped, untyped) -> [bool, PreparedRecordState?]
     def snapshot_state_before(model_class, id, boundary)
       series = @series[identity(model_class, id)]
@@ -317,9 +331,15 @@ module PaperTrailDiff
       [!prepared.nil?, prepared]
     end
 
+    # Typed as a reified record's attributes are. A JSON or JSONB `object`
+    # column stores times and dates as strings, which PaperTrail does not cast
+    # back, and the transition is carried into snapshots built from records.
     #: (untyped, untyped, untyped) -> [Hash[untyped, untyped], Hash[untyped, untyped]]?
     def transition(model_class, id, version)
-      @series[identity(model_class, id)]&.transition(version)
+      states = @series[identity(model_class, id)]&.transition(version)
+      return unless states
+
+      [typed_attributes(states.fetch(0)), typed_attributes(states.fetch(1))]
     end
 
     #: (untyped, untyped, untyped, ?direct: bool) -> [bool, untyped]
@@ -370,6 +390,17 @@ module PaperTrailDiff
 
     private
 
+    # A model whose records need their own initialization is cast by
+    # instantiating it, as reify does.
+    #: (PreparedRecordState) -> Hash[untyped, untyped]
+    def typed_attributes(state)
+      @direct_states[state] = @direct_loader.complete(state) unless @direct_states.key?(state)
+      typed = @direct_states[state]
+      return typed.attributes if typed
+
+      PreparedRecordState.new(state.instantiate).attributes
+    end
+
     #: (untyped, String) -> bool
     def generated_reader?(model, name)
       model.define_attribute_methods

data/lib/paper_trail_diff/root_version_selection.rb

@@ -14,9 +14,11 @@ module PaperTrailDiff
     # An error is a specification, so it names the way out as well as the wall.
     # A window ending at the present can never gain a later version, which makes
     # "write a checkpoint afterwards" impossible advice on its own.
+    # A window closes on the current record when it reaches the present, so
+    # this is raised only when there is none to read.
     INCOMPLETE = 'time range requires a later root version to reconstruct its ' \
-                 'final change: pass close_on: :current to end at current state, ' \
-                 'or narrow the window to end before the last recorded version'
+                 'final change, and there is no current record to end at: narrow ' \
+                 'the window to end before the last recorded version'
 
     #: (in_range: Array[untyped], selected: Array[untyped], after_range: untyped, windowed: bool, ?context_required: bool, ?filtered: bool, ?live_endpoint: untyped) -> void
     def initialize( # rubocop:disable Metrics/ParameterLists

data/lib/paper_trail_diff/scope_condition.rb

@@ -14,6 +14,8 @@ module PaperTrailDiff
     # ranking alone.
     RELATION_VALUES = %i[where order reordering limit offset readonly strict_loading
                          extending].freeze
+    # Relation parts that load or shape rows without choosing them.
+    LOADING_VALUES = %i[includes preload select distinct].freeze
     # Types whose stored values compare in Ruby as the database compares them,
     # named rather than referenced so that loading needs no Active Model.
     VALUE_TYPES = %w[ActiveModel::Type::Integer ActiveModel::Type::Boolean
@@ -63,6 +65,23 @@ module PaperTrailDiff
       nil
     end
 
+    # A relation's own where clause, default scope included, read as
+    # conditions on stored attributes; nil when it cannot be. Its order,
+    # limit, and offset choose a page of current rows rather than membership,
+    # and loading or selecting columns changes neither, so they are left out.
+    # A single-table subclass's type condition is left to the caller, as for
+    # an association.
+    #: (untyped, untyped) -> ScopeCondition?
+    def self.for_relation(relation, model_class)
+      extra = relation.values.except(*RELATION_VALUES, *LOADING_VALUES).values
+      return unless extra.all? { |value| value.respond_to?(:empty?) && value.empty? }
+
+      clause = relation.where_clause - model_class.unscoped.where_clause
+      new(model_class, Reader.new(model_class).call(clause.ast))
+    rescue Unreadable
+      nil
+    end
+
     # nil when the relation picks its members by conditions alone.
     #: (untyped, untyped, untyped) -> ScopeRanking?
     def self.ranking(relation, reflection, model_class)
@@ -132,9 +151,11 @@ module PaperTrailDiff
       freeze
     end
 
+    # SQL admits a row only when its condition is true, not when it is
+    # unknown.
     #: (Hash[String, untyped]) -> bool
     def matches?(attributes)
-      evaluate(@predicate, attributes)
+      evaluate(@predicate, attributes) == true
     end
 
     # The members among records that are each the owner's by key: those that
@@ -152,13 +173,15 @@ module PaperTrailDiff
       ranking ? ranking.call(records) : records
     end
 
-    # SQL compares NULL with nothing, so only an IS NULL test, an equality
-    # with nil, matches it.
+    # SQL's three values: a comparison with NULL is unknown (nil) rather than
+    # false, except an IS NULL or IS NOT NULL test, an equality with nil, which
+    # is always known. Unknown matters only under NOT, which leaves it
+    # unknown where false would become true.
     COMPARISONS = {
-      eq: ->(value, expected) { value == expected },
-      not_eq: ->(value, expected) { !value.nil? && value != expected },
-      in: ->(value, expected) { !value.nil? && expected.include?(value) },
-      not_in: ->(value, expected) { !value.nil? && !expected.include?(value) }
+      eq: ->(value, expected) { expected.nil? || !value.nil? ? value == expected : nil },
+      not_eq: ->(value, expected) { expected.nil? || !value.nil? ? value != expected : nil },
+      in: ->(value, expected) { expected.include?(value) unless value.nil? },
+      not_in: ->(value, expected) { !expected.include?(value) unless value.nil? }
     }.freeze
     private_constant :COMPARISONS
 
@@ -168,16 +191,39 @@ module PaperTrailDiff
     # @rbs @predicate: Array[untyped]
     # @rbs @ranking: ScopeRanking?
 
-    #: (Array[untyped], Hash[String, untyped]) -> bool
+    # true, false, or nil for unknown.
+    #: (Array[untyped], Hash[String, untyped]) -> bool?
     def evaluate(predicate, attributes)
       operator, first, second = predicate
       case operator
-      when :and then first.all? { |part| evaluate(part, attributes) }
-      when :or then first.any? { |part| evaluate(part, attributes) }
+      when :and then all(first.map { |part| evaluate(part, attributes) })
+      when :or then any(first.map { |part| evaluate(part, attributes) })
+      when :not then negate(evaluate(first, attributes))
       else COMPARISONS.fetch(operator).call(stored(first, attributes), second)
       end
     end
 
+    # False if any part is, otherwise unknown if any part is.
+    #: (Array[bool?]) -> bool?
+    def all(values)
+      return false if values.include?(false)
+
+      true unless values.include?(nil)
+    end
+
+    # True if any part is, otherwise unknown if any part is.
+    #: (Array[bool?]) -> bool?
+    def any(values)
+      return true if values.include?(true)
+
+      false unless values.include?(nil)
+    end
+
+    #: (bool?) -> bool?
+    def negate(value)
+      !value unless value.nil?
+    end
+
     # The form the database holds, as the scope's own values were cast.
     #: (String, Hash[String, untyped]) -> untyped
     def stored(name, attributes)
@@ -224,6 +270,7 @@ module PaperTrailDiff
         when 'Arel::Nodes::And' then [:and, node.children.map { |child| call(child) }]
         when 'Arel::Nodes::Or' then [:or, either(node).map { |child| call(child) }]
         when 'Arel::Nodes::Grouping' then call(node.expr)
+        when 'Arel::Nodes::Not' then [:not, call(node.expr)]
         else comparison(node)
         end
       end
@@ -250,9 +297,11 @@ module PaperTrailDiff
         end
       end
 
+      # Whether a value is NULL compares alike on every type.
       #: (Symbol, untyped) -> Array[untyped]
       def binary(operator, node)
-        [operator, column(node.left), value(node.right)]
+        expected = value(node.right)
+        [operator, column(node.left, null_test: expected.nil?), expected]
       end
 
       #: (untyped) -> Array[untyped]
@@ -272,29 +321,35 @@ module PaperTrailDiff
       end
 
       # Ruby comparison stands in for SQL only on the record's own column of
-      # a type both compare alike.
-      #: (untyped) -> String
-      def column(attribute)
+      # a type both compare alike. Whether a value is NULL, any column's
+      # type compares alike.
+      #: (untyped, ?null_test: bool) -> String
+      def column(attribute, null_test: false)
         raise Unreadable unless ATTRIBUTE.eql?(attribute.class.name)
 
         table = attribute.relation
         raise Unreadable unless table.name == @model_class.table_name && table.table_alias.nil?
 
         name = attribute.name
-        raise Unreadable unless comparable?(name)
+        column = @model_class.columns_hash[name]
+        raise Unreadable unless column && (null_test || comparable?(name, column))
 
         name
       end
 
-      #: (String) -> bool
-      def comparable?(name)
-        column = @model_class.columns_hash[name]
+      #: (String, untyped) -> bool
+      def comparable?(name, column)
         kinds = value_type(@model_class.type_for_attribute(name)).class.ancestors.map(&:name)
-        return false unless column && VALUE_TYPES.intersect?(kinds)
-        return true unless kinds.include?(TEXT_TYPE)
+        return false unless VALUE_TYPES.intersect?(kinds)
+
+        !kinds.include?(TEXT_TYPE) || exact_text?(column)
+      end
 
+      # PostgreSQL's citext is text that compares without regard to case.
+      #: (untyped) -> bool
+      def exact_text?(column)
         EXACT_TEXT_ADAPTERS.include?(@model_class.connection_db_config.adapter) &&
-          column.collation.nil?
+          column.collation.nil? && !column.sql_type.casecmp?('citext')
       end
 
       # An enum compares the values it stores, which its subtype describes. A

data/lib/paper_trail_diff/scope_ranking.rb

@@ -11,6 +11,9 @@ module PaperTrailDiff
     DIRECTIONS = { 'Arel::Nodes::Ascending' => false, 'Arel::Nodes::Descending' => true }.freeze
     ATTRIBUTE = 'Arel::Attributes::Attribute'
     ENUM_TYPE = 'ActiveRecord::Enum::EnumType'
+    # Rails wraps a time-zone-aware attribute's type, by default every
+    # datetime's, in this delegator; the time it stores is the wrapped type's.
+    TIME_ZONE_TYPE = 'ActiveRecord::AttributeMethods::TimeZoneConversion::TimeZoneConverter'
     # Integers, booleans and dates sort alike everywhere. Strings follow a
     # collation, so they are not read.
     ORDER_TYPES = %w[ActiveModel::Type::Integer ActiveModel::Type::Boolean
@@ -107,14 +110,21 @@ module PaperTrailDiff
     def self.orderable?(model_class, name)
       return false unless model_class.columns_hash.key?(name)
 
-      type = model_class.type_for_attribute(name)
-      type = type.subtype if ENUM_TYPE.eql?(type.class.name)
+      type = stored_type(model_class.type_for_attribute(name))
       kinds = type.class.ancestors.map(&:name)
       ORDER_TYPES.intersect?(kinds) ||
         (kinds.include?(DATETIME_TYPE) && exact_time?(model_class, type))
     end
     private_class_method :orderable?
 
+    # The type of the value a column stores, under an enum or time zone wrapper.
+    #: (untyped) -> untyped
+    def self.stored_type(type)
+      type = type.subtype if ENUM_TYPE.eql?(type.class.name)
+      TIME_ZONE_TYPE.eql?(type.class.name) ? type.__getobj__ : type
+    end
+    private_class_method :stored_type
+
     # Active Record truncates a time to its column's precision before writing
     # it, so history holds the stored value when it keeps that many digits.
     # Times the type stores in UTC sort as the instants they name; local

data/lib/paper_trail_diff/scoped_analysis.rb

@@ -36,6 +36,17 @@ module PaperTrailDiff
       freeze
     end
 
+    # Each root's change rows, keyed as `analyses` is: the roots that still
+    # exist, then the deleted ones that have history to report. A deleted root
+    # without destroy history has no rows and is left out.
+    #: () -> Hash[Array[String], Array[ChangeRow]]
+    def change_rows
+      rows = {} #: Hash[Array[String], Array[ChangeRow]]
+      analyses.each { |identity, analysis| rows[identity] = analysis.change_rows }
+      deleted.each { |identity, analysis| rows[identity] = analysis.change_rows if analysis }
+      rows.freeze
+    end
+
     # Two elements, not three: `roots` is reached by name so that existing
     # destructuring keeps working.
     #: () -> [Hash[Array[String], Analysis], Array[Array[String]]]

data/lib/paper_trail_diff/scoped_analysis_builder.rb

@@ -19,8 +19,8 @@ module PaperTrailDiff
                historical_filter: historical_filter, max_filter_versions: max_filter_versions,
                activity_tree: activity_tree
       )
+      @deleted_filter = DeletedRootFilter.new(scope.all) if include_deleted
       @limit = limit
-      @include_deleted = include_deleted
       @analyzer = analyzer
       @deleted_analyzer = deleted_analyzer
     end
@@ -28,20 +28,28 @@ module PaperTrailDiff
     #: () -> ScopedAnalysis
     def call
       selection = @selection.call
-      if @include_deleted && selection.records.length + selection.unreachable.length > @limit
+      deleted_filter = @deleted_filter
+      return analysis(selection, selection.unreachable, {}) unless deleted_filter
+
+      unreachable = deleted_filter.call(selection.unreachable)
+      if selection.records.length + unreachable.length > @limit
         raise BatchLimitExceededError, 'include_deleted: live and missing roots exceed limit:'
       end
 
-      ScopedAnalysis.new(
-        analyses: @analyzer.call(selection.records), roots: selection.records,
-        unreachable: selection.unreachable,
-        deleted: @include_deleted ? @deleted_analyzer.call(selection.unreachable) : {}
-      )
+      analysis(selection, unreachable, @deleted_analyzer.call(unreachable))
+    end
+
+    private
+
+    #: (ScopedRootSelection::Result, Array[Array[String]], Hash[Array[String], Analysis?]) -> ScopedAnalysis
+    def analysis(selection, unreachable, deleted)
+      ScopedAnalysis.new(analyses: @analyzer.call(selection.records), roots: selection.records,
+                         unreachable: unreachable, deleted: deleted)
     end
 
     # @rbs @selection: ScopedRootSelection
+    # @rbs @deleted_filter: DeletedRootFilter?
     # @rbs @limit: Integer
-    # @rbs @include_deleted: bool
     # @rbs @analyzer: untyped
     # @rbs @deleted_analyzer: untyped
   end

data/lib/paper_trail_diff/scoped_root_selection.rb

@@ -106,14 +106,22 @@ module PaperTrailDiff
       matching if matching.length == related.length
     end
 
+    # Which candidates still have a row is asked without the relation's
+    # conditions, so that "filtered out" and "no longer exists" stay
+    # separable. A filter then reads the history of the relation's records
+    # only, whose order and page choose among those that match, and of the
+    # deleted ones, which no relation can test. Those it lists, as without a
+    # filter, but does not count toward `limit:`.
     #: (Array[String]) -> Result
     def plucked_selection(candidates)
-      candidates = @historical_filter.call(candidates) if @historical_filter
-      live = live_ids(candidates)
-      Result.new(
-        records: selected_records([live]),
-        unreachable: (candidates - live).sort.map { |id| identity(id) }.freeze
-      )
+      live = ids_in(base_class.unscoped, candidates)
+      missing = candidates - live
+      if (filter = @historical_filter)
+        live = filter.call(ids_in(@scope.except(:order, :limit, :offset), live).uniq)
+        missing = filter.call(missing, counted: false)
+      end
+      Result.new(records: selected_records([live]),
+                 unreachable: missing.sort.map { |id| identity(id) }.freeze)
     end
 
     # Comparing the two columns in SQL needs them to share a type: PostgreSQL
@@ -144,7 +152,7 @@ module PaperTrailDiff
 
     #: () -> untyped
     def window_versions
-      relation = version_class.where(item_type: item_type)
+      relation = VersionQuery.for_model(model)
       range = @time_range
       range ? range.scope(relation) : relation
     end
@@ -185,12 +193,10 @@ module PaperTrailDiff
       window_versions.distinct.pluck(:item_id).map(&:to_s)
     end
 
-    # Which of those candidates still have a row, asked without the relation's
-    # conditions so that "filtered out" and "no longer exists" stay separable.
-    #: (Array[String]) -> Array[String]
-    def live_ids(candidates)
+    #: (untyped, Array[String]) -> Array[String]
+    def ids_in(relation, candidates)
       candidates.each_slice(PAGE_SIZE).flat_map do |slice|
-        base_class.unscoped.where(primary_key => slice).pluck(primary_key).map(&:to_s)
+        relation.where(primary_key => slice).pluck(primary_key).map(&:to_s)
       end
     end
 

data/lib/paper_trail_diff/snapshot.rb

@@ -102,7 +102,7 @@ module PaperTrailDiff
       end
 
       @kind = kind
-      @records = records.frozen? ? records : records.dup.freeze
+      @records = ordered(records)
       @identity_index_cache = identity_index_cache || IdentityIndexCache.new
       @transition = transition
       @serial = SERIALS.next_serial
@@ -124,6 +124,21 @@ module PaperTrailDiff
       )
     end
 
+    # Collections are documented in record type, then ID, order wherever they
+    # were read from. Most arrive sorted, so they are checked before sorting.
+    #: (Array[RecordSnapshot]) -> Array[RecordSnapshot]
+    def ordered(records)
+      keys = records.map { |record| Support.sortable_identity(record.type, record.id) }
+      return records.sort_by.with_index { |_, index| keys.fetch(index) }.freeze unless sorted?(keys)
+
+      records.frozen? ? records : records.dup.freeze
+    end
+
+    #: (Array[Array[untyped]]) -> bool
+    def sorted?(keys)
+      keys.each_cons(2).all? { |left, right| (left <=> right).to_i <= 0 }
+    end
+
     #: (AssociationSnapshot) -> CollectionTransition?
     def transition_from(association)
       @transition if @transition&.from?(association)

data/lib/paper_trail_diff/support.rb

@@ -44,6 +44,20 @@ module PaperTrailDiff
       end
     end
 
+    # Records 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.
+    #: (untyped, untyped) -> Array[untyped]
+    def sortable_identity(type, id)
+      key = case id
+            when Numeric then [0, id]
+            when String, Symbol then [1, id.to_s]
+            else [2, id.inspect]
+            end
+      [type.to_s, key]
+    end
+
     #: (untyped) -> Array[untyped]
     def chronological_version_key(version)
       version_key(version.created_at, version.id)
@@ -70,11 +84,24 @@ module PaperTrailDiff
     #: (Array[untyped]) -> Array[untyped]?
     def ambiguous_pair(sorted)
       sorted.each_cons(2).find do |left, right|
-        left.created_at == right.created_at &&
-          !(sequential_id?(left.id) && sequential_id?(right.id))
+        left.created_at == right.created_at && !orderable_tie?(left, right)
       end
     end
 
+    # Ids order versions saved in one instant only when they count up in one
+    # table. Two version tables count separately, so ids there say nothing.
+    #: (untyped, untyped) -> bool
+    def orderable_tie?(left, right)
+      version_table(left) == version_table(right) &&
+        sequential_id?(left.id) && sequential_id?(right.id)
+    end
+
+    #: (untyped) -> untyped
+    def version_table(version)
+      version.class.respond_to?(:table_name) ? version.class.table_name : version.class.name
+    end
+    private_class_method :version_table
+
     # Versions sharing a timestamp, whether or not their ids order them. PT-AT
     # indexes association membership per version but resolves it by timestamp,
     # so association state cannot be told apart across such a pair even when the

data/lib/paper_trail_diff/time_range.rb

@@ -3,6 +3,10 @@
 
 module PaperTrailDiff
   # Validates and applies a finite wall-clock range without loading model state.
+  #
+  # A Date is a whole day and a String a local time, both in Time.zone, as
+  # Rails reads them, or in UTC without one: never the server's own zone. An
+  # inclusive Date end runs through that day.
   class TimeRange
     attr_reader :begin_time #: Time
     attr_reader :end_time #: Time
@@ -14,8 +18,8 @@ module PaperTrailDiff
       end
 
       @begin_time = coerce_time(value.begin, boundary: :begin)
-      @end_time = coerce_time(value.end, boundary: :end)
-      @exclude_end = value.exclude_end?
+      @exclude_end = value.exclude_end? || calendar_date?(value.end)
+      @end_time = coerce_time(end_value(value), boundary: :end)
       validate_order!
       freeze
     end
@@ -79,16 +83,34 @@ module PaperTrailDiff
       raise InvalidTimeRangeError, "`within` #{boundary} must be time-like"
     end
 
-    # Active Support 8.0 and older warn, once per process, that `to_time` will
-    # change on a zoned time, so read zoned values without it. Every branch
-    # gives the same instant, so no spec (and no mutation) can tell them apart.
-    # mutant:disable
-    #: (untyped) -> Time
+    # Anything else names its instant, and `getutc` reads it without
+    # `to_time`, which Active Support 8.0 and older warn will change on a
+    # zoned time, and without changing the caller's own value as `utc` does.
+    #: (untyped) -> untyped
     def time_value(value)
-      return value if value.is_a?(Time)
+      return zone.parse(value) || raise(ArgumentError) if value.is_a?(String)
+      return zone.local(value.year, value.month, value.day) if calendar_date?(value)
+
+      value
+    end
+
+    # An inclusive date end runs through the day: to the next one's start.
+    #: (Range[untyped]) -> untyped
+    def end_value(range)
+      last = range.end
+      calendar_date?(last) && !range.exclude_end? ? last.next_day : last
+    end
+
+    # A DateTime is a Date too, but names its instant.
+    #: (untyped) -> bool
+    def calendar_date?(value)
+      value.instance_of?(Date)
+    end
 
-      utc = value.utc if value.respond_to?(:utc)
-      utc.is_a?(Time) ? utc : value.to_time
+    #: () -> untyped
+    def zone
+      time = Time #: untyped
+      time.zone || time.find_zone!('UTC')
     end
 
     #: () -> void

data/lib/paper_trail_diff/timeline_builder.rb

@@ -46,21 +46,21 @@ module PaperTrailDiff
       return empty_history if plan.empty?
 
       versions = plan.versions
-      @snapshotter.prepare(@record, versions) if @snapshotter.respond_to?(:prepare)
-      steps = build_steps(plan)
-      final = plan.closes_on_destroy ? nil : @snapshotter.call(plan.final_endpoint)
-      [steps, @snapshotter.call(versions.first), final]
+      snapshots = @snapshotter.prepare(@record, versions)
+      steps = build_steps(plan, snapshots)
+      final = plan.closes_on_destroy ? nil : snapshots.call(plan.final_endpoint)
+      [steps, snapshots.call(versions.first), final]
     end
 
-    #: (RootVersionPlan) -> Array[Step]
-    def build_steps(plan)
+    #: (RootVersionPlan, untyped) -> Array[Step]
+    def build_steps(plan, snapshots)
       captured_at = Time.now.utc if plan.closing_record
       plan.steps.map do |from_endpoint, to_endpoint|
         Step.new(
           from_version: from_endpoint,
           to_version: to_endpoint,
           captured_at: captured_at,
-          diff: Engine.compare(@snapshotter.call(from_endpoint), @snapshotter.call(to_endpoint))
+          diff: Engine.compare(snapshots.call(from_endpoint), snapshots.call(to_endpoint))
         )
       end.freeze
     end

data/lib/paper_trail_diff/timeline_range.rb

@@ -122,9 +122,17 @@ module PaperTrailDiff
       VersionQuery.chronological(Endpoint.versions(@record))
     end
 
+    # A batch passes each root the window it already moved to transaction
+    # edges; a single record's window is moved here.
     #: (untyped) -> TimeRange?
     def build_time_range(within)
-      TimeRange.new(within) unless within.nil?
+      return if within.nil?
+      return within if within.instance_of?(TimeRange)
+
+      range = TimeRange.new(within)
+      return range unless Support.versioned?(@record.class)
+
+      TransactionCut.windows(@record.class, [@record], range).fetch(@record.id.to_s, range)
     end
 
     #: () -> void