paper_trail_diff 0.3.1 → 0.4.0

data/lib/paper_trail_diff/time_activity_timeline_builder.rb

@@ -14,17 +14,17 @@ module PaperTrailDiff
 
     #: () -> Array[ActivityStep]
     def build
-      history, = history_and_versions
-      history.steps
+      history, _root_versions, closing = history_and_versions
+      activity_steps(history, closing)
     end
 
     #: () -> Analysis
     def analyze
-      history, root_versions = history_and_versions
+      history, root_versions, closing = history_and_versions
       Analysis.new(
         diff: Engine.compare(history.first_snapshot, history.last_snapshot),
-        timeline: root_steps(root_versions, history.root_snapshots),
-        activity_timeline: history.steps
+        timeline: ActivityRootSteps.call(root_versions, history.root_snapshots),
+        activity_timeline: activity_steps(history, closing)
       )
     end
 
@@ -35,22 +35,61 @@ module PaperTrailDiff
     # @rbs @tree: AssociationTree
     # @rbs @snapshotter: untyped
 
-    #: () -> [ActivityHistory, Array[untyped]]
+    #: () -> [ActivityHistory, Array[untyped], ActivityStep?]
     def history_and_versions
       root_versions = @range.select(context_required: !@tree.empty?)
-      return [ActivityHistory.empty, root_versions] if root_versions.empty?
+      return [ActivityHistory.empty, root_versions, nil] if root_versions.empty?
 
       prepare_history(root_versions)
       events = collect_events(root_versions)
-      return [ActivityHistory.empty, root_versions] unless time_events?(events)
+      selected = selected_events(events)
+      return [ActivityHistory.empty, root_versions, nil] unless time_events?(selected, events)
 
-      history = ActivityHistoryBuilder.new(
+      history = build_history(root_versions, events)
+      [history, root_versions, closing_step(history, selected.last)]
+    end
+
+    #: (Array[untyped], Array[ActivityEvent]) -> ActivityHistory
+    def build_history(root_versions, events)
+      ActivityHistoryBuilder.new(
         root_versions,
         events,
         @snapshotter,
         include_step: ->(event) { @range.include?(event.version) }
       ).call
-      [history, root_versions]
+    end
+
+    #: (ActivityHistory, ActivityStep?) -> Array[ActivityStep]
+    def activity_steps(history, closing)
+      return history.steps unless closing
+
+      (history.steps + [closing]).freeze
+    end
+
+    #: (Array[ActivityEvent]) -> Array[ActivityEvent]
+    def selected_events(events)
+      events.select { |event| @range.include?(event.version) }
+    end
+
+    # The window's last selected mutation is the root's own destruction, so the
+    # timeline closes on the absence it leaves rather than on a later boundary.
+    #: (ActivityHistory, ActivityEvent?) -> ActivityStep?
+    def closing_step(history, event)
+      return unless event && terminal_destroy?(event)
+
+      version = event.version
+      ActivityStep.new(
+        from_boundary: ActivityBoundary.from_version(version),
+        to_boundary: ActivityBoundary.destroyed(version),
+        diff: Engine.compare(history.root_snapshots[ActivityRootSteps.version_key(version)], nil)
+      )
+    end
+
+    #: (ActivityEvent?) -> bool
+    def terminal_destroy?(event)
+      return false unless event
+
+      event.root? && event.version.event.to_s == 'destroy'
     end
 
     #: (Array[untyped]) -> void
@@ -72,11 +111,11 @@ module PaperTrailDiff
       ).call
     end
 
-    #: (Array[ActivityEvent]) -> bool
-    def time_events?(events)
-      selected = events.select { |event| @range.include?(event.version) }
+    #: (Array[ActivityEvent], Array[ActivityEvent]) -> bool
+    def time_events?(selected, events)
       return false if selected.empty?
       return true if later_event?(selected.last, events)
+      return true if terminal_destroy?(selected.last)
 
       message = 'time range requires a later activity boundary to reconstruct its final change'
       raise IncompleteTimeRangeError, message
@@ -88,24 +127,5 @@ module PaperTrailDiff
         Support.compare_versions(selected.version, event.version).negative?
       end
     end
-
-    #: (Array[untyped], Hash[Array[untyped], RecordSnapshot?]) -> Array[Step]
-    def root_steps(root_versions, root_snapshots)
-      snapshots = root_versions.map do |version|
-        root_snapshots.fetch(version_key(version))
-      end
-      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/time_version_range.rb

@@ -19,6 +19,8 @@ module PaperTrailDiff
 
       trailing = trailing_version(relation)
       unless trailing
+        return selected.freeze if terminal_destroy?(selected)
+
         message = 'time range requires a later root version to reconstruct its final change'
         raise IncompleteTimeRangeError, message
       end
@@ -40,6 +42,15 @@ module PaperTrailDiff
       raise InvalidTimelineRangeError, message, cause: e
     end
 
+    # A window closing on the record's own destruction needs no later version:
+    # the destroy reveals the preceding mutation and nothing can follow it, so
+    # demanding a checkpoint that can never be written would reject the range
+    # permanently.
+    #: (Array[untyped]) -> bool
+    def terminal_destroy?(versions)
+      versions.last&.event.to_s == 'destroy'
+    end
+
     #: (untyped) -> untyped
     def trailing_version(relation)
       @time_range.trailing_scope(relation).reorder(created_at: :asc, id: :asc).first

data/lib/paper_trail_diff/timeline_range.rb

@@ -4,6 +4,8 @@
 module PaperTrailDiff
   # Chooses explicit-version or wall-clock selection for one timeline request.
   class TimelineRange
+    BOUNDARY_SYMBOLS = %i[first last].freeze
+
     attr_reader :from #: untyped
     attr_reader :to #: untyped
     attr_reader :time_range #: TimeRange?
@@ -11,13 +13,22 @@ module PaperTrailDiff
     #: (untyped, from: untyped, to: untyped, within: untyped) -> void
     def initialize(record, from:, to:, within:)
       @record = record
-      @from = from
-      @to = to
+      @requested_from = from
+      @requested_to = to
       @time_range = build_time_range(within)
       validate_mode!
+      @from = resolve(from)
+      @to = resolve(to)
       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.
+    #: () -> bool
+    def unresolved?
+      (symbolic?(@requested_from) && @from.nil?) || (symbolic?(@requested_to) && @to.nil?)
+    end
+
     #: (?context_required: bool) -> Array[untyped]
     def select(context_required: false)
       range = time_range
@@ -26,6 +37,7 @@ module PaperTrailDiff
           context_required: context_required
         )
       end
+      return empty_versions if unresolved?
 
       VersionRange.new(@record, from: @from, to: @to).select
     end
@@ -49,9 +61,50 @@ module PaperTrailDiff
     private
 
     # @rbs @record: untyped
+    # @rbs @requested_from: untyped
+    # @rbs @requested_to: untyped
     # @rbs @from: untyped
     # @rbs @to: untyped
 
+    #: () -> Array[untyped]
+    def empty_versions
+      versions = [] #: Array[untyped]
+      versions.freeze
+    end
+
+    #: (untyped) -> bool
+    def symbolic?(boundary)
+      boundary.is_a?(Symbol)
+    end
+
+    # Resolving `:first` and `:last` 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)
+
+      unless BOUNDARY_SYMBOLS.include?(boundary)
+        raise InvalidTimelineRangeError,
+              "unsupported boundary: #{boundary.inspect}; use :first, :last, a version, or a record"
+      end
+
+      boundary == :first ? ordered_versions.first : ordered_versions.last
+    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
+    end
+
     #: (untyped) -> TimeRange?
     def build_time_range(within)
       TimeRange.new(within) unless within.nil?
@@ -60,11 +113,11 @@ module PaperTrailDiff
     #: () -> void
     def validate_mode!
       if time?
-        return if @from.nil? && @to.nil?
+        return if @requested_from.nil? && @requested_to.nil?
 
         raise InvalidTimelineRangeError, '`within` cannot be combined with `from` or `to`'
       end
-      return unless @from.nil? || @to.nil?
+      return unless @requested_from.nil? || @requested_to.nil?
 
       raise InvalidTimelineRangeError, 'provide both `from` and `to`, or provide `within`'
     end

data/lib/paper_trail_diff/version.rb

@@ -2,5 +2,5 @@
 # rbs_inline: enabled
 
 module PaperTrailDiff
-  VERSION = '0.3.1'
+  VERSION = '0.4.0'
 end

data/lib/paper_trail_diff/version_association_candidate_scope.rb

@@ -24,45 +24,72 @@ module PaperTrailDiff
     # @rbs @start_at: untyped
     # @rbs @end_at: untyped
 
+    # Only quoting helpers are needed, so the connection is borrowed for the
+    # duration of building the condition rather than checked out permanently,
+    # which Active Record 7.2 and newer can deprecate. Active Record 7.1 has no
+    # `with_connection` and reaches the same connection through the accessor.
+    #: () { (untyped) -> String } -> String
+    def with_connection(&block)
+      return @version_class.with_connection(&block) if @version_class.respond_to?(:with_connection)
+
+      block.call(@version_class.connection)
+    end
+
     #: () -> String
-    def candidate_condition # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
-      connection = @version_class.connection
+    def candidate_condition
+      with_connection { |connection| condition_sql(connection) }
+    end
+
+    #: (untyped) -> String
+    def condition_sql(connection) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
       outer = connection.quote_table_name(@version_class.table_name)
       later = connection.quote_table_name('paper_trail_diff_later_versions')
       start_at = connection.quote(@start_at)
-      destroyed = connection.quote('destroy')
-      activity = activity_condition(outer, start_at)
+      columns = quoted_columns(connection, outer, later)
       compact_sql(<<~SQL)
         (
-          #{activity}
+          #{activity_condition(columns, start_at, connection)}
           OR (
-            #{column(outer, 'created_at')} < #{start_at}
-            AND #{column(outer, 'event')} != #{destroyed}
+            #{columns.fetch(:outer_created_at)} < #{start_at}
+            AND #{columns.fetch(:outer_event)} != #{connection.quote('destroy')}
             AND NOT EXISTS (
               SELECT 1
                 FROM #{outer} #{later}
-               WHERE #{column(later, 'item_type')} = #{column(outer, 'item_type')}
-                 AND #{column(later, 'item_id')} = #{column(outer, 'item_id')}
-                 AND #{column(later, 'created_at')} < #{start_at}
-                 AND #{column(later, 'created_at')} > #{column(outer, 'created_at')}
+               WHERE #{columns.fetch(:later_item_type)} = #{columns.fetch(:outer_item_type)}
+                 AND #{columns.fetch(:later_item_id)} = #{columns.fetch(:outer_item_id)}
+                 AND #{columns.fetch(:later_created_at)} < #{start_at}
+                 AND #{columns.fetch(:later_created_at)} > #{columns.fetch(:outer_created_at)}
             )
           )
         )
       SQL
     end
 
-    #: (String, String) -> String
-    def activity_condition(table, start_at)
-      condition = "#{column(table, 'created_at')} >= #{start_at}"
+    #: (untyped, String, String) -> Hash[Symbol, String]
+    def quoted_columns(connection, outer, later)
+      {
+        outer_created_at: column(connection, outer, 'created_at'),
+        outer_event: column(connection, outer, 'event'),
+        outer_item_type: column(connection, outer, 'item_type'),
+        outer_item_id: column(connection, outer, 'item_id'),
+        later_created_at: column(connection, later, 'created_at'),
+        later_item_type: column(connection, later, 'item_type'),
+        later_item_id: column(connection, later, 'item_id')
+      }
+    end
+
+    #: (Hash[Symbol, String], String, untyped) -> String
+    def activity_condition(columns, start_at, connection)
+      created_at = columns.fetch(:outer_created_at)
+      condition = "#{created_at} >= #{start_at}"
       return condition unless @end_at
 
-      end_at = @version_class.connection.quote(@end_at)
-      "(#{condition} AND #{column(table, 'created_at')} <= #{end_at})"
+      "(#{condition} AND #{created_at} <= #{connection.quote(@end_at)})"
     end
 
-    #: (String, String) -> String
-    def column(table, name)
-      "#{table}.#{@version_class.connection.quote_column_name(name)}"
+    #: (untyped, String, String) -> String
+    def column(connection, table, name)
+      "#{table}.#{connection.quote_column_name(name)}"
     end
 
     #: (String) -> String

data/lib/paper_trail_diff.rb

@@ -55,6 +55,7 @@ require_relative 'paper_trail_diff/branch_snapshot_refresher'
 require_relative 'paper_trail_diff/activity_boundary'
 require_relative 'paper_trail_diff/step'
 require_relative 'paper_trail_diff/analysis'
+require_relative 'paper_trail_diff/activity_root_steps'
 require_relative 'paper_trail_diff/version_range'
 require_relative 'paper_trail_diff/time_range'
 require_relative 'paper_trail_diff/time_version_range'

data/sig/generated/paper_trail_diff/activity_boundary.rbs

@@ -25,6 +25,12 @@ module PaperTrailDiff
     # : (untyped, captured_at: untyped) -> ActivityBoundary
     def self.current: (untyped, captured_at: untyped) -> ActivityBoundary
 
+    # The state a `destroy` version leaves behind. A version records the state
+    # before its own event, so the boundary built from a destroy version still
+    # holds the record; this one is the absence that follows it.
+    # : (untyped) -> ActivityBoundary
+    def self.destroyed: (untyped) -> ActivityBoundary
+
     # : (kind: Symbol, version_id: untyped, item_type: untyped, item_id: untyped, recorded_at: untyped, ?event: untyped, ?whodunnit: untyped) -> void
     def initialize: (kind: Symbol, version_id: untyped, item_type: untyped, item_id: untyped, recorded_at: untyped, ?event: untyped, ?whodunnit: untyped) -> void
 
@@ -34,6 +40,9 @@ module PaperTrailDiff
     # : () -> bool
     def current?: () -> bool
 
+    # : () -> bool
+    def destroyed?: () -> bool
+
     # : () -> Hash[Symbol, untyped]
     def to_h: () -> Hash[Symbol, untyped]
   end

data/sig/generated/paper_trail_diff/activity_event_route_finder.rbs

@@ -14,27 +14,20 @@ module PaperTrailDiff
 
     private
 
-    @belongs_to_model: untyped
+    @belongs_to_routes: Hash[Array[untyped], Array[Array[untyped]]]
 
-    @belongs_to_path: String?
+    @collection_routes: Hash[Array[untyped], Array[Array[untyped]]]
 
-    @belongs_to_routes: Array[Array[untyped]]?
-
-    @belongs_to_tree: AssociationTree?
-
-    @belongs_to_type: String?
-
-    @collection_model: untyped
-
-    @collection_path: String?
-
-    @collection_routes: Array[Array[untyped]]?
-
-    @collection_tree: AssociationTree?
+    @traversal: AssociationTraversal
 
-    @collection_type: String?
+    # 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: (Hash[Array[untyped], Array[Array[untyped]]], untyped, AssociationTree, String, String, Symbol) -> Array[Array[untyped]]
 
-    @traversal: AssociationTraversal
+    # : (Array[untyped]) -> Array[untyped]
+    def cache_key: (Array[untyped]) -> Array[untyped]
 
     # : (Array[Array[untyped]]) -> Array[Array[untyped]]
     def freeze_routes: (Array[Array[untyped]]) -> Array[Array[untyped]]

data/sig/generated/paper_trail_diff/activity_root_steps.rbs

@@ -0,0 +1,13 @@
+# Generated from lib/paper_trail_diff/activity_root_steps.rb with RBS::Inline
+
+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
+    # : (Array[untyped], Hash[Array[untyped], RecordSnapshot?]) -> Array[Step]
+    def self?.call: (Array[untyped], Hash[Array[untyped], RecordSnapshot?]) -> Array[Step]
+
+    # : (untyped) -> Array[untyped]
+    def self?.version_key: (untyped) -> Array[untyped]
+  end
+end

data/sig/generated/paper_trail_diff/activity_snapshot_sequence.rbs

@@ -6,8 +6,8 @@ module PaperTrailDiff
     # : (snapshotter: untyped, refresher: untyped, preparer: untyped) -> void
     def initialize: (snapshotter: untyped, refresher: untyped, preparer: untyped) -> void
 
-    # : (untyped, Array[untyped], ?start_at: untyped) -> void
-    def prepare: (untyped, Array[untyped], ?start_at: untyped) -> void
+    # : (untyped, Array[untyped], ?start_at: untyped, ?end_at: untyped) -> void
+    def prepare: (untyped, Array[untyped], ?start_at: untyped, ?end_at: untyped) -> void
 
     # : (untyped, untyped) -> RecordSnapshot?
     def call: (untyped, untyped) -> RecordSnapshot?

data/sig/generated/paper_trail_diff/activity_timeline_builder.rbs

@@ -27,6 +27,9 @@ module PaperTrailDiff
 
     @tree: AssociationTree
 
+    # : () -> Array[ActivityStep]
+    def no_steps: () -> Array[ActivityStep]
+
     # : () -> Array[ActivityStep]
     def build_between_versions: () -> Array[ActivityStep]
 
@@ -42,23 +45,30 @@ module PaperTrailDiff
     # : (Array[untyped], ?range_start: untyped, ?range_end: untyped) -> Array[ActivityEvent]
     def collect_events: (Array[untyped], ?range_start: untyped, ?range_end: untyped) -> Array[ActivityEvent]
 
-    # : (Array[untyped], ?start_at: untyped) -> void
-    def prepare_history: (Array[untyped], ?start_at: untyped) -> void
+    # : (Array[untyped], ?end_at: untyped) -> void
+    def prepare_history: (Array[untyped], ?end_at: untyped) -> void
 
     # : (Array[untyped], Array[ActivityEvent], ?current: untyped, ?final_boundary: ActivityBoundary?, ?final_snapshot: RecordSnapshot?) -> Array[ActivityStep]
     def build_event_steps: (Array[untyped], Array[ActivityEvent], ?current: untyped, ?final_boundary: ActivityBoundary?, ?final_snapshot: RecordSnapshot?) -> Array[ActivityStep]
 
-    # : (Array[untyped], Array[ActivityEvent], ?current: untyped) -> ActivityHistory
-    def event_history: (Array[untyped], Array[ActivityEvent], ?current: untyped) -> ActivityHistory
+    # 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: (ActivityHistory, Array[ActivityEvent], ActivityBoundary?, RecordSnapshot?) -> Array[ActivityStep]
 
-    # : (Array[untyped], ActivityHistory) -> Analysis
-    def build_analysis: (Array[untyped], ActivityHistory) -> Analysis
+    # 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: (Array[untyped]) -> ActivityBoundary?
 
-    # : (Array[untyped], Array[RecordSnapshot?]) -> Array[Step]
-    def build_root_steps: (Array[untyped], Array[RecordSnapshot?]) -> Array[Step]
+    # : (Array[untyped], Array[ActivityEvent], ?current: untyped) -> ActivityHistory
+    def event_history: (Array[untyped], Array[ActivityEvent], ?current: untyped) -> ActivityHistory
 
-    # : (untyped) -> Array[untyped]
-    def version_key: (untyped) -> Array[untyped]
+    # 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: (Array[untyped], Array[ActivityEvent], ActivityHistory) -> Analysis
 
     # : () -> TimeActivityTimelineBuilder
     def time_builder: () -> TimeActivityTimelineBuilder

data/sig/generated/paper_trail_diff/analysis.rbs

@@ -9,6 +9,11 @@ module PaperTrailDiff
 
     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: () -> Analysis
+
     # : (diff: Diff, timeline: Array[Step], ?activity_timeline: Array[ActivityStep]?) -> void
     def initialize: (diff: Diff, timeline: Array[Step], ?activity_timeline: Array[ActivityStep]?) -> void
 

data/sig/generated/paper_trail_diff/collection_comparator.rbs

@@ -50,9 +50,16 @@ module PaperTrailDiff
     # : (Array[identity]) -> Array[identity]
     def sorted_identities: (Array[identity]) -> Array[identity]
 
+    # 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) -> Array[untyped]
 
+    # : (untyped) -> Array[untyped]
+    def sortable_id: (untyped) -> Array[untyped]
+
     # : (identity) -> void
     def raise_duplicate_identity!: (identity) -> void
   end

data/sig/generated/paper_trail_diff/collection_transition.rbs

@@ -7,12 +7,15 @@ module PaperTrailDiff
 
     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: AssociationSnapshot, before: RecordSnapshot?, after: RecordSnapshot?) -> void
 
     # : (AssociationSnapshot) -> bool
     def from?: (AssociationSnapshot) -> bool
 
-    @from_object_id: Integer
+    @from_serial: Integer
   end
 end

data/sig/generated/paper_trail_diff/endpoint.rbs

@@ -6,6 +6,18 @@ module PaperTrailDiff
     # : (untyped, untyped) -> void
     def self?.validate_pair!: (untyped, untyped) -> void
 
+    # 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 self?.validate_order!: (untyped, untyped) -> void
+
+    # : (untyped, untyped) -> bool
+    def self?.reversed_versions?: (untyped, untyped) -> bool
+
     # : (untyped) -> void
     def self?.validate!: (untyped) -> void
 

data/sig/generated/paper_trail_diff/errors.rbs

@@ -13,6 +13,10 @@ module PaperTrailDiff
   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/sig/generated/paper_trail_diff/historical_association_reifier.rbs

@@ -13,7 +13,7 @@ module PaperTrailDiff
 
     @habtm_transaction_id: untyped
 
-    @reified_associations: Hash[Array[untyped], bool]
+    @reified_associations: Hash[untyped, Hash[untyped, bool]]
 
     @transaction_id: untyped
 

data/sig/generated/paper_trail_diff/historical_snapshot_store.rbs

@@ -6,8 +6,8 @@ module PaperTrailDiff
     # : (tree: AssociationTree, traversal: AssociationTraversal, normalizer: SnapshotNormalizer, preparer: untyped) -> void
     def initialize: (tree: AssociationTree, traversal: AssociationTraversal, normalizer: SnapshotNormalizer, preparer: untyped) -> void
 
-    # : (untyped, Array[untyped], ?start_at: untyped) -> void
-    def prepare: (untyped, Array[untyped], ?start_at: untyped) -> void
+    # : (untyped, Array[untyped], ?start_at: untyped, ?end_at: untyped) -> void
+    def prepare: (untyped, Array[untyped], ?start_at: untyped, ?end_at: untyped) -> void
 
     # Prepares selected history for several roots of the same model class.
     # : (Array[untyped], Array[untyped]) -> void

data/sig/generated/paper_trail_diff/prepared_association_reifier.rbs

@@ -19,7 +19,7 @@ module PaperTrailDiff
 
     @history: PreparedHistory
 
-    @reified: Hash[Array[untyped], bool]
+    @reified: Hash[untyped, Hash[untyped, bool]]
 
     # : (untyped, untyped) -> void
     def reify_association: (untyped, untyped) -> void

data/sig/generated/paper_trail_diff/prepared_edge_loader.rbs

@@ -64,6 +64,7 @@ module PaperTrailDiff
     # : (untyped, Array[untyped], ?owners: Hash[String, Array[untyped]]?) -> Hash[String, Hash[Symbol, untyped]]
     def group_for: (untyped, Array[untyped], ?owners: Hash[String, Array[untyped]]?) -> Hash[String, Hash[Symbol, untyped]]
 
+    # 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: (Array[Array[untyped]]) -> Hash[String, Array[untyped]]
 

data/sig/generated/paper_trail_diff/prepared_history_loader.rbs

@@ -3,8 +3,8 @@
 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
-    def initialize: (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: (untyped, root_versions: Array[untyped], tree: AssociationTree, traversal: AssociationTraversal, ?root_ids: Array[untyped], ?start_at: untyped, ?end_at: untyped, ?live_records: Array[untyped]) -> void
 
     # : () -> PreparedHistory
     def call: () -> PreparedHistory