paper_trail_diff 0.1.0 → 0.3.0

data/lib/paper_trail_diff/traversal_emitter.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # Shared entry construction for internal traversal collaborators.
+  class TraversalEmitter
+    #: (^(TraversalEntry) -> void) -> void
+    def initialize(receiver)
+      @receiver = receiver
+    end
+
+    private
+
+    # @rbs @receiver: ^(TraversalEntry) -> void
+
+    #: (kind: Symbol, context: traversal_context, association_path: traversal_association_path, record_path: traversal_record_path, value: untyped, ?association_kind: Symbol?, ?state: traversal_state?, ?attribute: String?) -> void
+    def emit( # rubocop:disable Metrics/ParameterLists
+      kind:,
+      context:,
+      association_path:,
+      record_path:,
+      value:,
+      association_kind: nil,
+      state: nil,
+      attribute: nil
+    )
+      @receiver.call(
+        TraversalEntry.new(
+          kind: kind,
+          context: context,
+          association_path: association_path,
+          record_path: record_path,
+          association_kind: association_kind,
+          state: state,
+          attribute: attribute,
+          value: value
+        )
+      )
+    end
+  end
+  private_constant :TraversalEmitter
+end

data/lib/paper_trail_diff/traversal_entry.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # One immutable location and value emitted while walking a Diff tree.
+  class TraversalEntry
+    CONTEXTS = %i[change included_state].freeze
+    STATES = %i[before after].freeze
+    private_constant :CONTEXTS, :STATES
+
+    attr_reader :kind #: Symbol
+    attr_reader :context #: traversal_context
+    attr_reader :association_path #: traversal_association_path
+    attr_reader :record_path #: traversal_record_path
+    attr_reader :association_kind #: Symbol?
+    attr_reader :state #: traversal_state?
+    attr_reader :attribute #: String?
+    attr_reader :value #: untyped
+
+    #: (kind: Symbol, context: traversal_context, ?association_path: traversal_association_path, ?record_path: traversal_record_path, ?association_kind: Symbol?, ?state: traversal_state?, ?attribute: String?, ?value: untyped) -> void
+    def initialize( # rubocop:disable Metrics/ParameterLists
+      kind:,
+      context:,
+      association_path: [],
+      record_path: [],
+      association_kind: nil,
+      state: nil,
+      attribute: nil,
+      value: nil
+    )
+      validate!(context, state)
+      @kind = kind
+      @context = context
+      @association_path = immutable_names(association_path)
+      @record_path = Support.immutable_copy(record_path)
+      @association_kind = association_kind
+      @state = state
+      @attribute = Support.immutable_copy(attribute&.to_s)
+      @value = Support.immutable_copy(value)
+      freeze
+    end
+
+    #: () -> bool
+    def change?
+      context == :change
+    end
+
+    #: () -> bool
+    def included_state?
+      context == :included_state
+    end
+
+    #: () -> String?
+    def association
+      association_path.last
+    end
+
+    #: () -> RecordReference?
+    def record
+      record_path.last
+    end
+
+    #: () -> Hash[Symbol, untyped]
+    def to_h
+      {
+        kind: kind,
+        context: context,
+        association_path: Support.serialize(association_path),
+        record_path: Support.serialize(record_path),
+        association_kind: association_kind,
+        state: state,
+        attribute: attribute,
+        value: Support.serialize(value)
+      }
+    end
+
+    private
+
+    #: (Symbol, Symbol?) -> void
+    def validate!(candidate_context, candidate_state)
+      unless CONTEXTS.include?(candidate_context)
+        raise ArgumentError, "unsupported traversal context: #{candidate_context.inspect}"
+      end
+      return if candidate_state.nil? || STATES.include?(candidate_state)
+
+      raise ArgumentError, "unsupported traversal state: #{candidate_state.inspect}"
+    end
+
+    #: (traversal_association_path) -> traversal_association_path
+    def immutable_names(names)
+      names.map { |name| Support.immutable_copy(name.to_s) }.freeze
+    end
+  end
+end

data/lib/paper_trail_diff/version.rb

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

data/lib/paper_trail_diff/version_association_candidate_scope.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # Selects association activity from a boundary forward plus the state at that boundary.
+  class VersionAssociationCandidateScope
+    #: (untyped, untyped, ?end_at: untyped) -> void
+    def initialize(version_class, start_at, end_at: nil)
+      @version_class = version_class
+      @start_at = start_at
+      @end_at = end_at
+    end
+
+    #: (untyped) -> untyped
+    def call(relation)
+      return relation unless @start_at
+
+      relation.where(candidate_condition)
+    end
+
+    private
+
+    # @rbs @version_class: untyped
+    # @rbs @start_at: untyped
+    # @rbs @end_at: untyped
+
+    #: () -> String
+    def candidate_condition # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+      connection = @version_class.connection
+      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)
+      compact_sql(<<~SQL)
+        (
+          #{activity}
+          OR (
+            #{column(outer, 'created_at')} < #{start_at}
+            AND #{column(outer, 'event')} != #{destroyed}
+            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')}
+            )
+          )
+        )
+      SQL
+    end
+
+    #: (String, String) -> String
+    def activity_condition(table, start_at)
+      condition = "#{column(table, '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})"
+    end
+
+    #: (String, String) -> String
+    def column(table, name)
+      "#{table}.#{@version_class.connection.quote_column_name(name)}"
+    end
+
+    #: (String) -> String
+    def compact_sql(sql)
+      sql.gsub(/\s+/, ' ').strip
+    end
+  end
+end

data/lib/paper_trail_diff.rb

@@ -5,37 +5,59 @@ require 'paper_trail'
 
 require_relative 'paper_trail_diff/version'
 require_relative 'paper_trail_diff/support'
+require_relative 'paper_trail_diff/instrumentation'
 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/association_discovery'
 require_relative 'paper_trail_diff/diagnostics'
+require_relative 'paper_trail_diff/collection_identity_index'
+require_relative 'paper_trail_diff/collection_transition'
 require_relative 'paper_trail_diff/snapshot'
+require_relative 'paper_trail_diff/activity_snapshot_delta'
 require_relative 'paper_trail_diff/value_objects'
+require_relative 'paper_trail_diff/traversal_entry'
+require_relative 'paper_trail_diff/traversal_emitter'
+require_relative 'paper_trail_diff/snapshot_traversal'
+require_relative 'paper_trail_diff/association_diff_traversal'
+require_relative 'paper_trail_diff/traversal'
+require_relative 'paper_trail_diff/collection_comparator'
 require_relative 'paper_trail_diff/engine'
 require_relative 'paper_trail_diff/historical_association_reifier'
 require_relative 'paper_trail_diff/prepared_record_index'
 require_relative 'paper_trail_diff/prepared_history'
+require_relative 'paper_trail_diff/version_association_candidate_scope'
 require_relative 'paper_trail_diff/prepared_edge_loader'
 require_relative 'paper_trail_diff/prepared_history_loader'
 require_relative 'paper_trail_diff/prepared_association_reifier'
 require_relative 'paper_trail_diff/live_association_reader'
+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/comparison_batch'
 require_relative 'paper_trail_diff/snapshot_normalizer'
 require_relative 'paper_trail_diff/historical_snapshot_store'
 require_relative 'paper_trail_diff/timeline_snapshot_provider'
 require_relative 'paper_trail_diff/activity_event_snapshot_refresher'
 require_relative 'paper_trail_diff/activity_root_snapshot_refresher'
 require_relative 'paper_trail_diff/branch_snapshot_refresher'
-require_relative 'paper_trail_diff/step'
 require_relative 'paper_trail_diff/activity_boundary'
+require_relative 'paper_trail_diff/step'
 require_relative 'paper_trail_diff/analysis'
 require_relative 'paper_trail_diff/version_range'
+require_relative 'paper_trail_diff/time_range'
+require_relative 'paper_trail_diff/time_version_range'
+require_relative 'paper_trail_diff/timeline_range'
 require_relative 'paper_trail_diff/timeline_builder'
 require_relative 'paper_trail_diff/activity_range'
 require_relative 'paper_trail_diff/activity_event'
+require_relative 'paper_trail_diff/activity_child_candidate_loader'
 require_relative 'paper_trail_diff/activity_version_collector'
 require_relative 'paper_trail_diff/activity_snapshot_sequence'
+require_relative 'paper_trail_diff/activity_history'
+require_relative 'paper_trail_diff/time_activity_timeline_builder'
 require_relative 'paper_trail_diff/activity_timeline_builder'
 require_relative 'paper_trail_diff/paper_trail_adapter'
 
@@ -48,8 +70,14 @@ require_relative 'paper_trail_diff/paper_trail_adapter'
 #     type association_diffs = Hash[String, association_diff]
 #     type association_snapshots = Hash[String, AssociationSnapshot]
 #     type identity = Array[untyped]
+#     type comparison_input = Hash[String | Symbol, untyped]
+#     type comparison_results = Hash[identity, Diff]
 #     type ignore_option = Array[String | Symbol] | Hash[String | Symbol, untyped]
 #     type reference_key = :type | :id | "type" | "id"
+#     type traversal_context = :change | :included_state
+#     type traversal_state = :before | :after
+#     type traversal_association_path = Array[String]
+#     type traversal_record_path = Array[RecordReference]
 #   end
 
 # Structured version comparison for PaperTrail.
@@ -64,40 +92,82 @@ module PaperTrailDiff
 
   class << self
     # Compares net state between explicit PaperTrail-version or current-record endpoints.
-    #: (untyped, untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option) -> Diff
-    def compare(from_version, to_version, associations: [], ignore: DEFAULT_IGNORED_ATTRIBUTES)
-      PaperTrailAdapter.new(associations: associations, ignore: ignore).compare(
+    #: (untyped, untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?reload_live_endpoints: bool) -> Diff
+    def compare(
+      from_version,
+      to_version,
+      associations: [],
+      ignore: DEFAULT_IGNORED_ATTRIBUTES,
+      reload_live_endpoints: true
+    )
+      PaperTrailAdapter.new(
+        associations: associations,
+        ignore: ignore,
+        reload_live_endpoints: reload_live_endpoints
+      ).compare(
         from_version,
         to_version
       )
     end
 
+    # Compares many independent endpoint pairs while batching current-record loading.
+    #: (Array[comparison_input], ?associations: Array[String | Symbol], ?ignore: ignore_option, ?reload_live_endpoints: bool) -> comparison_results
+    def compare_many(
+      comparisons,
+      associations: [],
+      ignore: DEFAULT_IGNORED_ATTRIBUTES,
+      reload_live_endpoints: true
+    )
+      PaperTrailAdapter.new(
+        associations: associations,
+        ignore: ignore,
+        reload_live_endpoints: reload_live_endpoints
+      ).compare_many(comparisons)
+    end
+
     # Compares every adjacent reconstructed state in an inclusive version range.
-    #: (untyped, from: untyped, to: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option) -> Array[Step]
-    def timeline(record, from:, to:, associations: [], ignore: DEFAULT_IGNORED_ATTRIBUTES)
+    #: (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option) -> Array[Step]
+    def timeline( # rubocop:disable Metrics/ParameterLists
+      record,
+      from: nil,
+      to: nil,
+      within: nil,
+      associations: [],
+      ignore: DEFAULT_IGNORED_ATTRIBUTES
+    )
       PaperTrailAdapter.new(associations: associations, ignore: ignore).timeline(
         record,
         from: from,
-        to: to
+        to: to,
+        within: within
       )
     end
 
     # Compares adjacent root and selected-descendant activity boundaries.
-    #: (untyped, from: untyped, to: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option) -> Array[ActivityStep]
-    def activity_timeline(record, from:, to:, associations: [], ignore: DEFAULT_IGNORED_ATTRIBUTES)
+    #: (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option) -> Array[ActivityStep]
+    def activity_timeline( # rubocop:disable Metrics/ParameterLists
+      record,
+      from: nil,
+      to: nil,
+      within: nil,
+      associations: [],
+      ignore: DEFAULT_IGNORED_ATTRIBUTES
+    )
       PaperTrailAdapter.new(associations: associations, ignore: ignore).activity_timeline(
         record,
         from: from,
-        to: to
+        to: to,
+        within: within
       )
     end
 
     # Builds an endpoint diff and root-checkpoint timeline while normalizing each version once.
-    #: (untyped, from: untyped, to: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?activity: bool) -> Analysis
+    #: (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?activity: bool) -> Analysis
     def analyze( # rubocop:disable Metrics/ParameterLists
       record,
-      from:,
-      to:,
+      from: nil,
+      to: nil,
+      within: nil,
       associations: [],
       ignore: DEFAULT_IGNORED_ATTRIBUTES,
       activity: false
@@ -106,6 +176,7 @@ module PaperTrailDiff
         record,
         from: from,
         to: to,
+        within: within,
         activity: activity
       )
     end

data/sig/generated/paper_trail_diff/activity_boundary.rbs

@@ -13,14 +13,26 @@ module PaperTrailDiff
 
     attr_reader recorded_at: untyped
 
+    attr_reader event: String?
+
+    attr_reader whodunnit: untyped
+
+    attr_reader record: RecordReference
+
     # : (untyped) -> ActivityBoundary
     def self.from_version: (untyped) -> ActivityBoundary
 
     # : (untyped, captured_at: untyped) -> ActivityBoundary
     def self.current: (untyped, captured_at: untyped) -> ActivityBoundary
 
-    # : (kind: Symbol, version_id: untyped, item_type: untyped, item_id: untyped, recorded_at: untyped) -> void
-    def initialize: (kind: Symbol, version_id: untyped, item_type: untyped, item_id: untyped, recorded_at: untyped) -> void
+    # : (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
+
+    # : () -> bool
+    def version?: () -> bool
+
+    # : () -> bool
+    def current?: () -> bool
 
     # : () -> Hash[Symbol, untyped]
     def to_h: () -> Hash[Symbol, untyped]
@@ -37,6 +49,9 @@ module PaperTrailDiff
     # : (from_boundary: ActivityBoundary, to_boundary: ActivityBoundary, diff: Diff) -> void
     def initialize: (from_boundary: ActivityBoundary, to_boundary: ActivityBoundary, diff: Diff) -> void
 
+    # : () -> bool
+    def empty?: () -> bool
+
     # : () -> Hash[Symbol, untyped]
     def to_h: () -> Hash[Symbol, untyped]
   end

data/sig/generated/paper_trail_diff/activity_child_candidate_loader.rbs

@@ -0,0 +1,40 @@
+# Generated from lib/paper_trail_diff/activity_child_candidate_loader.rb with RBS::Inline
+
+module PaperTrailDiff
+  # Loads direct-child identities active at or after one activity boundary.
+  class ActivityChildCandidateLoader
+    # : (untyped, Array[untyped], untyped, ActivityRange) -> void
+    def initialize: (untyped, Array[untyped], untyped, ActivityRange) -> void
+
+    # : () -> Array[untyped]
+    def call: () -> Array[untyped]
+
+    private
+
+    @parent_class: untyped
+
+    @parent_ids: Array[untyped]
+
+    @range: ActivityRange
+
+    @reflection: untyped
+
+    # : () -> Array[untyped]
+    def historical_ids: () -> Array[untyped]
+
+    # : (untyped) -> untyped
+    def historical_relation: (untyped) -> untyped
+
+    # : (untyped) -> VersionAssociationCandidateScope
+    def candidate_scope: (untyped) -> VersionAssociationCandidateScope
+
+    # : () -> Array[untyped]
+    def current_ids: () -> Array[untyped]
+
+    # : () -> String
+    def child_item_type: () -> String
+
+    # : () -> Array[String?]
+    def parent_types: () -> Array[String?]
+  end
+end

data/sig/generated/paper_trail_diff/activity_event_snapshot_refresher.rbs

@@ -6,8 +6,8 @@ module PaperTrailDiff
   class ActivityEventSnapshotRefresher
     RECORD_AFTER_HANDLERS: untyped
 
-    # : (traversal: AssociationTraversal, pool: SnapshotPool, components: untyped, ?association_reader: untyped) -> void
-    def initialize: (traversal: AssociationTraversal, pool: SnapshotPool, components: untyped, ?association_reader: untyped) -> void
+    # : (traversal: AssociationTraversal, pool: SnapshotPool, components: untyped, ?association_reader: untyped, ?record_transition: untyped) -> void
+    def initialize: (traversal: AssociationTraversal, pool: SnapshotPool, components: untyped, ?association_reader: untyped, ?record_transition: untyped) -> void
 
     # : (untyped, untyped, RecordSnapshot, Array[String], ActivityEvent?) -> [bool, RecordSnapshot?]
     def call: (untyped, untyped, RecordSnapshot, Array[String], ActivityEvent?) -> [ bool, RecordSnapshot? ]
@@ -20,13 +20,30 @@ module PaperTrailDiff
 
     @pool: SnapshotPool
 
+    @record_transition: untyped
+
     @traversal: AssociationTraversal
 
     # : (Array[Array[untyped]], untyped) -> bool
     def unsafe_through_membership_event?: (Array[Array[untyped]], untyped) -> bool
 
-    # : (untyped, untyped, RecordSnapshot, SnapshotNormalizer, Array[Array[untyped]], untyped) -> [bool, RecordSnapshot]
-    def collection_target_snapshot: (untyped, untyped, RecordSnapshot, SnapshotNormalizer, Array[Array[untyped]], untyped) -> [ bool, RecordSnapshot ]
+    # : (Array[Array[untyped]], ActivitySnapshotDelta?) -> bool
+    def unsafe_nested_membership_delta?: (Array[Array[untyped]], ActivitySnapshotDelta?) -> bool
+
+    # : (untyped, untyped, RecordSnapshot, SnapshotNormalizer, Array[Array[untyped]], untyped, ActivitySnapshotDelta?) -> [bool, RecordSnapshot]
+    def collection_target_snapshot: (untyped, untyped, RecordSnapshot, SnapshotNormalizer, Array[Array[untyped]], untyped, ActivitySnapshotDelta?) -> [ bool, RecordSnapshot ]
+
+    # : (RecordSnapshot, Array[untyped], untyped, ActivitySnapshotDelta?, Array[untyped], SnapshotNormalizer, untyped, untyped) -> [untyped, RecordSnapshot?]
+    def collection_route_event_state: (RecordSnapshot, Array[untyped], untyped, ActivitySnapshotDelta?, Array[untyped], SnapshotNormalizer, untyped, untyped) -> [ untyped, RecordSnapshot? ]
+
+    # : (untyped, Array[untyped], SnapshotNormalizer, untyped, untyped) -> RecordSnapshot?
+    def normalized_collection_event_record: (untyped, Array[untyped], SnapshotNormalizer, untyped, untyped) -> RecordSnapshot?
+
+    # : (RecordSnapshot, Array[untyped], untyped, ActivitySnapshotDelta?) -> RecordSnapshot?
+    def existing_delta_record: (RecordSnapshot, Array[untyped], untyped, ActivitySnapshotDelta?) -> RecordSnapshot?
+
+    # : (RecordSnapshot, Array[untyped], ActivitySnapshotDelta) -> RecordSnapshot?
+    def nested_delta_owner: (RecordSnapshot, Array[untyped], ActivitySnapshotDelta) -> RecordSnapshot?
 
     # : (untyped, AssociationTree, String, ?path: String) -> Array[Array[untyped]]
     def direct_collection_routes: (untyped, AssociationTree, String, ?path: String) -> Array[Array[untyped]]
@@ -34,6 +51,18 @@ module PaperTrailDiff
     # : (RecordSnapshot, Array[untyped], untyped, untyped, RecordSnapshot?, ?depth: Integer) -> [RecordSnapshot, bool]
     def replace_collection_route: (RecordSnapshot, Array[untyped], untyped, untyped, RecordSnapshot?, ?depth: Integer) -> [ RecordSnapshot, bool ]
 
+    # : (AssociationSnapshot, untyped, untyped, untyped, RecordSnapshot, RecordSnapshot?) -> RecordSnapshot?
+    def collection_event_child: (AssociationSnapshot, untyped, untyped, untyped, RecordSnapshot, RecordSnapshot?) -> RecordSnapshot?
+
+    # : (AssociationSnapshot, Array[untyped], untyped, untyped, RecordSnapshot?, Integer) -> [Array[RecordSnapshot], RecordSnapshot?, RecordSnapshot?, bool]?
+    def replace_targeted_collection_parent: (AssociationSnapshot, Array[untyped], untyped, untyped, RecordSnapshot?, Integer) -> [ Array[RecordSnapshot], RecordSnapshot?, RecordSnapshot?, bool ]?
+
+    # : (Array[RecordSnapshot], Integer, RecordSnapshot, RecordSnapshot, bool) -> [Array[RecordSnapshot], RecordSnapshot?, RecordSnapshot?, bool]
+    def targeted_parent_replacement: (Array[RecordSnapshot], Integer, RecordSnapshot, RecordSnapshot, bool) -> [ Array[RecordSnapshot], RecordSnapshot?, RecordSnapshot?, bool ]
+
+    # : (AssociationSnapshot, untyped, untyped, untyped) -> Integer?
+    def nested_owner_position: (AssociationSnapshot, untyped, untyped, untyped) -> Integer?
+
     # : (untyped, untyped, RecordSnapshot, AssociationTree, SnapshotNormalizer, untyped) -> [bool, RecordSnapshot?]
     def belongs_to_target_snapshot: (untyped, untyped, RecordSnapshot, AssociationTree, SnapshotNormalizer, untyped) -> [ bool, RecordSnapshot? ]
 
@@ -77,8 +106,17 @@ module PaperTrailDiff
     # : (untyped, untyped, untyped) -> untyped
     def standard_changeset: (untyped, untyped, untyped) -> untyped
 
-    # : (untyped, untyped, RecordSnapshot) -> bool
-    def member_of_owner?: (untyped, untyped, RecordSnapshot) -> bool
+    # : (untyped) -> ActivitySnapshotDelta?
+    def activity_snapshot_delta: (untyped) -> ActivitySnapshotDelta?
+
+    # : (untyped, untyped, RecordSnapshot, ?state: Symbol) -> bool
+    def member_of_owner?: (untyped, untyped, RecordSnapshot, ?state: Symbol) -> bool
+
+    # : (untyped, untyped, state: Symbol) -> untyped
+    def event_attribute: (untyped, untyped, state: Symbol) -> untyped
+
+    # : (untyped, untyped, state: Symbol) -> untyped
+    def relationship_owner_id: (untyped, untyped, state: Symbol) -> untyped
 
     # : (untyped, untyped, AssociationTree, String, SnapshotNormalizer, untyped, untyped) -> RecordSnapshot?
     def normalize_event_record: (untyped, untyped, AssociationTree, String, SnapshotNormalizer, untyped, untyped) -> RecordSnapshot?
@@ -86,8 +124,11 @@ module PaperTrailDiff
     # : (untyped, habtm_version: untyped) -> HistoricalAssociationReifier
     def historical_reader: (untyped, habtm_version: untyped) -> HistoricalAssociationReifier
 
-    # : (Array[RecordSnapshot], untyped, RecordSnapshot?) -> Array[RecordSnapshot]
-    def replace_collection_record: (Array[RecordSnapshot], untyped, RecordSnapshot?) -> Array[RecordSnapshot]
+    # : (AssociationSnapshot, untyped, RecordSnapshot?) -> [Array[RecordSnapshot], RecordSnapshot?, RecordSnapshot?, bool]
+    def replace_collection_record: (AssociationSnapshot, untyped, RecordSnapshot?) -> [ Array[RecordSnapshot], RecordSnapshot?, RecordSnapshot?, bool ]
+
+    # : (Array[RecordSnapshot], Integer?, RecordSnapshot?) -> Array[RecordSnapshot]
+    def replacement_collection_records: (Array[RecordSnapshot], Integer?, RecordSnapshot?) -> Array[RecordSnapshot]
 
     # : (untyped, RecordSnapshot?) -> String
     def replacement_type: (untyped, RecordSnapshot?) -> String

data/sig/generated/paper_trail_diff/activity_history.rbs

@@ -0,0 +1,79 @@
+# Generated from lib/paper_trail_diff/activity_history.rb with RBS::Inline
+
+module PaperTrailDiff
+  # Immutable snapshots and steps produced by one activity-history pass.
+  class ActivityHistory
+    attr_reader steps: Array[ActivityStep]
+
+    attr_reader root_snapshots: Hash[Array[untyped], RecordSnapshot?]
+
+    attr_reader first_snapshot: RecordSnapshot?
+
+    attr_reader last_snapshot: RecordSnapshot?
+
+    # : (steps: Array[ActivityStep], root_snapshots: Hash[Array[untyped], RecordSnapshot?], first_snapshot: RecordSnapshot?, last_snapshot: RecordSnapshot?) -> void
+    def initialize: (steps: Array[ActivityStep], root_snapshots: Hash[Array[untyped], RecordSnapshot?], first_snapshot: RecordSnapshot?, last_snapshot: RecordSnapshot?) -> void
+
+    # : () -> ActivityHistory
+    def self.empty: () -> ActivityHistory
+  end
+
+  # Builds activity steps while retaining root snapshots for combined analysis.
+  class ActivityHistoryBuilder
+    # : (Array[untyped], Array[ActivityEvent], untyped, ?current: untyped, ?include_step: untyped) -> void
+    def initialize: (Array[untyped], Array[ActivityEvent], untyped, ?current: untyped, ?include_step: untyped) -> void
+
+    # : () -> ActivityHistory
+    def call: () -> ActivityHistory
+
+    private
+
+    @current: untyped
+
+    @events: Array[ActivityEvent]
+
+    @first_snapshot: RecordSnapshot?
+
+    @include_step: untyped
+
+    @previous_boundary: ActivityBoundary?
+
+    @previous_event: ActivityEvent?
+
+    @previous_snapshot: RecordSnapshot?
+
+    @root_snapshots: Hash[Array[untyped], RecordSnapshot?]
+
+    @root_versions: Array[untyped]
+
+    @selected_last_snapshot: RecordSnapshot?
+
+    @snapshotter: untyped
+
+    @steps: Array[ActivityStep]
+
+    # : () -> void
+    def reset: () -> void
+
+    # : () -> ActivitySnapshotSequence
+    def sequence: () -> ActivitySnapshotSequence
+
+    # : (ActivityEvent, RecordSnapshot?) -> void
+    def consume: (ActivityEvent, RecordSnapshot?) -> void
+
+    # : (RecordSnapshot?) -> void
+    def capture_first: (RecordSnapshot?) -> void
+
+    # : (ActivityBoundary, RecordSnapshot?) -> void
+    def append_step: (ActivityBoundary, RecordSnapshot?) -> void
+
+    # : () -> bool
+    def include_previous_step?: () -> bool
+
+    # : () -> RecordSnapshot?
+    def final_snapshot: () -> RecordSnapshot?
+
+    # : (untyped) -> Array[untyped]
+    def version_key: (untyped) -> Array[untyped]
+  end
+end