paper_trail_diff 0.3.1 → 0.5.0

data/lib/paper_trail_diff/snapshot.rb

@@ -57,6 +57,30 @@ module PaperTrailDiff
     end
     private_constant :IdentityIndexCache
 
+    # Identifies one snapshot for internal carry-forward. A transition cannot
+    # hold its origin without retaining every earlier snapshot at that path,
+    # and `object_id` is only guaranteed unique among live objects, so Ruby may
+    # hand a collected snapshot's id to a later one.
+    class SerialSequence
+      #: () -> void
+      def initialize
+        @mutex = Mutex.new
+        @counter = 0
+      end
+
+      #: () -> Integer
+      def next_serial
+        @mutex.synchronize { @counter += 1 }
+      end
+
+      # @rbs @mutex: Thread::Mutex
+      # @rbs @counter: Integer
+    end
+    private_constant :SerialSequence
+
+    SERIALS = SerialSequence.new
+    private_constant :SERIALS
+
     class << self
       #: (Symbol) -> bool
       def collection_kind?(kind)
@@ -66,6 +90,7 @@ module PaperTrailDiff
 
     attr_reader :kind #: Symbol
     attr_reader :records #: Array[RecordSnapshot]
+    attr_reader :serial #: Integer
 
     #: (kind: Symbol, records: Array[RecordSnapshot], ?identity_index_cache: untyped, ?transition: CollectionTransition?) -> void
     def initialize(kind:, records:, identity_index_cache: nil, transition: nil)
@@ -80,6 +105,7 @@ module PaperTrailDiff
       @records = records.frozen? ? records : records.dup.freeze
       @identity_index_cache = identity_index_cache || IdentityIndexCache.new
       @transition = transition
+      @serial = SERIALS.next_serial
       freeze
     end
 

data/lib/paper_trail_diff/snapshot_normalizer.rb

@@ -53,6 +53,7 @@ module PaperTrailDiff
       @traversal = traversal
       @pool = pool
       @structural_columns = {} #: Hash[String, Array[String]]
+      @excluded_attributes = {} #: Hash[Array[untyped], Array[String]]
     end
 
     #: (untyped, reifier: untyped) -> RecordSnapshot?
@@ -86,6 +87,7 @@ module PaperTrailDiff
     # @rbs @traversal: AssociationTraversal
     # @rbs @pool: SnapshotPool
     # @rbs @structural_columns: Hash[String, Array[String]]
+    # @rbs @excluded_attributes: Hash[Array[untyped], Array[String]]
 
     #: (untyped, AssociationTree, String, untyped, Array[untyped]) -> RecordSnapshot?
     def normalize_record(record, tree, path, reifier, reflections)
@@ -107,15 +109,25 @@ module PaperTrailDiff
       attributes
     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]
     def excluded_attributes(record, reflections, path)
-      primary_key = record.class.primary_key #: untyped
+      model_class = record.class
+      @excluded_attributes[[model_class, path]] ||=
+        build_excluded_attributes(model_class, reflections, path)
+    end
+
+    #: (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
       ignored = @ignore_policy.attributes_for(path)
       structural = @structural_columns.fetch(path, [])
-      (primary_keys + ignored + relationship_columns(reflections) + structural).uniq
+      (primary_keys + ignored + relationship_columns(reflections) + structural).uniq.freeze
     end
 
     #: (Array[untyped]) -> Array[String]

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_builder.rb

@@ -4,10 +4,10 @@
 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) -> void
-    def initialize(record, from:, to:, snapshotter:, within: nil)
+    #: (untyped, from: untyped, to: untyped, snapshotter: untyped, ?within: untyped, ?versions: Array[untyped]?) -> void
+    def initialize(record, from:, to:, snapshotter:, within: nil, versions: nil) # rubocop:disable Metrics/ParameterLists
       @record = record
-      @range = TimelineRange.new(record, from: from, to: to, within: within)
+      @range = TimelineRange.new(record, from: from, to: to, within: within, versions: versions)
       @snapshotter = snapshotter
     end
 

data/lib/paper_trail_diff/timeline_range.rb

@@ -4,28 +4,46 @@
 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?
 
-    #: (untyped, from: untyped, to: untyped, within: untyped) -> void
-    def initialize(record, from:, to:, within:)
+    #: (untyped, from: untyped, to: untyped, within: untyped, ?versions: Array[untyped]?) -> void
+    def initialize(record, from:, to:, within:, versions: nil)
       @record = record
-      @from = from
-      @to = to
+      @versions = versions&.freeze
+      @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
+
+    # A batch may have selected these versions already, in which case reselecting
+    # them per record would undo the batching.
     #: (?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).select(
           context_required: context_required
         )
       end
+      return empty_versions if unresolved?
 
       VersionRange.new(@record, from: @from, to: @to).select
     end
@@ -49,9 +67,51 @@ module PaperTrailDiff
     private
 
     # @rbs @record: untyped
+    # @rbs @versions: Array[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 +120,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/traversal_preparer.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # Checks that a model can be traversed before any reconstruction starts, and
+  # that association tracking is actually available when history is involved.
+  class TraversalPreparer
+    #: (tree: AssociationTree, traversal: AssociationTraversal) -> void
+    def initialize(tree:, traversal:)
+      @tree = tree
+      @traversal = traversal
+    end
+
+    #: (untyped, historical: bool) -> void
+    def call(model_class, historical:)
+      return if @tree.empty?
+
+      ensure_association_tracking! if historical
+      @traversal.validate!(model_class)
+    end
+
+    private
+
+    # @rbs @tree: AssociationTree
+    # @rbs @traversal: AssociationTraversal
+
+    #: () -> 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/version.rb

@@ -2,5 +2,5 @@
 # rbs_inline: enabled
 
 module PaperTrailDiff
-  VERSION = '0.3.1'
+  VERSION = '0.5.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

@@ -10,6 +10,7 @@ require_relative 'paper_trail_diff/errors'
 require_relative 'paper_trail_diff/configuration'
 require_relative 'paper_trail_diff/endpoint'
 require_relative 'paper_trail_diff/association_traversal'
+require_relative 'paper_trail_diff/traversal_preparer'
 require_relative 'paper_trail_diff/association_discovery'
 require_relative 'paper_trail_diff/diagnostics'
 require_relative 'paper_trail_diff/collection_identity_index'
@@ -36,7 +37,9 @@ require_relative 'paper_trail_diff/live_endpoint_batch_loader'
 require_relative 'paper_trail_diff/preloaded_endpoint_batch_loader'
 require_relative 'paper_trail_diff/live_endpoint_provider'
 require_relative 'paper_trail_diff/live_graph_collector'
+require_relative 'paper_trail_diff/batch_boundary_resolver'
 require_relative 'paper_trail_diff/comparison_batch'
+require_relative 'paper_trail_diff/batched_root_versions'
 require_relative 'paper_trail_diff/snapshot_normalizer'
 require_relative 'paper_trail_diff/historical_snapshot_store'
 require_relative 'paper_trail_diff/timeline_snapshot_provider'
@@ -55,6 +58,9 @@ 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/analysis_batch'
+require_relative 'paper_trail_diff/batched_root_analyzer'
 require_relative 'paper_trail_diff/version_range'
 require_relative 'paper_trail_diff/time_range'
 require_relative 'paper_trail_diff/time_version_range'
@@ -89,8 +95,9 @@ require_relative 'paper_trail_diff/paper_trail_adapter'
 #     type traversal_record_path = Array[RecordReference]
 #   end
 
-# Structured version comparison for PaperTrail.
-module PaperTrailDiff
+# Structured version comparison for PaperTrail. Each method is a thin,
+# documented entry point, so this reads as an API listing rather than logic.
+module PaperTrailDiff # rubocop:disable Metrics/ModuleLength
   DEFAULT_IGNORED_ATTRIBUTES = ['updated_at'].freeze
   SUPPORTED_ASSOCIATION_MACROS = %i[
     belongs_to
@@ -153,16 +160,23 @@ module PaperTrailDiff
     end
 
     # Compares adjacent root and selected-descendant activity boundaries.
-    #: (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option) -> Array[ActivityStep]
+    # `reload_live_endpoints:` applies only when `to:` is a current record; the
+    # other range forms never read live state.
+    #: (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?reload_live_endpoints: bool) -> Array[ActivityStep]
     def activity_timeline( # rubocop:disable Metrics/ParameterLists
       record,
       from: nil,
       to: nil,
       within: nil,
       associations: [],
-      ignore: DEFAULT_IGNORED_ATTRIBUTES
+      ignore: DEFAULT_IGNORED_ATTRIBUTES,
+      reload_live_endpoints: true
     )
-      PaperTrailAdapter.new(associations: associations, ignore: ignore).activity_timeline(
+      PaperTrailAdapter.new(
+        associations: associations,
+        ignore: ignore,
+        reload_live_endpoints: reload_live_endpoints
+      ).activity_timeline(
         record,
         from: from,
         to: to,
@@ -190,6 +204,24 @@ module PaperTrailDiff
       )
     end
 
+    # Analyzes many roots over one shared time window, preparing their selected
+    # history once for the batch instead of once per record. Roots with no
+    # versions in the window return an empty `Analysis`.
+    #: (Array[untyped], ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?activity: bool) -> Hash[identity, Analysis]
+    def analyze_many(
+      records,
+      within: nil,
+      associations: [],
+      ignore: DEFAULT_IGNORED_ATTRIBUTES,
+      activity: false
+    )
+      PaperTrailAdapter.new(associations: associations, ignore: ignore).analyze_many(
+        records,
+        within: within,
+        activity: activity
+      )
+    end
+
     # Returns the association macros this release can normalize.
     #: () -> Array[Symbol]
     def supported_association_macros

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]]