paper_trail_diff 0.2.0 → 0.3.0

data/lib/paper_trail_diff.rb

@@ -5,27 +5,38 @@ 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'
@@ -36,11 +47,17 @@ 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'
 
@@ -53,6 +70,8 @@ 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
@@ -73,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
@@ -115,6 +176,7 @@ module PaperTrailDiff
         record,
         from: from,
         to: to,
+        within: within,
         activity: activity
       )
     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

data/sig/generated/paper_trail_diff/activity_range.rbs

@@ -3,6 +3,10 @@
 module PaperTrailDiff
   # Tests activity versions against a historical-version or wall-clock range end.
   class ActivityRange
+    attr_reader start_time: untyped
+
+    attr_reader end_time: untyped
+
     # : (untyped, untyped) -> void
     def initialize: (untyped, untyped) -> void
 
@@ -14,21 +18,26 @@ module PaperTrailDiff
     # : (untyped) -> untyped
     def scope: (untyped) -> untyped
 
+    # : () -> bool
+    def current_end?: () -> bool
+
     private
 
     @end_boundary: untyped
 
     @end_key: Array[untyped]?
 
-    @start_key: Array[untyped]
+    @start_boundary: untyped
+
+    @start_key: Array[untyped]?
 
-    @start_version: untyped
+    @start_time: untyped
 
     # : (untyped, Array[untyped]) -> bool
-    def before_end?: (untyped, Array[untyped]) -> bool
+    def after_start?: (untyped, Array[untyped]) -> bool
 
-    # : () -> untyped
-    def end_time: () -> untyped
+    # : (untyped, Array[untyped]) -> bool
+    def before_end?: (untyped, Array[untyped]) -> bool
 
     # : (Array[untyped], Array[untyped]) -> bool
     def key_before_or_equal?: (Array[untyped], Array[untyped]) -> bool

data/sig/generated/paper_trail_diff/activity_snapshot_delta.rbs

@@ -0,0 +1,33 @@
+# Generated from lib/paper_trail_diff/activity_snapshot_delta.rb with RBS::Inline
+
+module PaperTrailDiff
+  # Internal scalar transition for one isolated PaperTrail update event.
+  class ActivitySnapshotDelta
+    # : (before_attributes: Hash[untyped, untyped], after_attributes: Hash[untyped, untyped]) -> void
+    def initialize: (before_attributes: Hash[untyped, untyped], after_attributes: Hash[untyped, untyped]) -> void
+
+    # : (RecordSnapshot) -> RecordSnapshot
+    def apply: (RecordSnapshot) -> RecordSnapshot
+
+    # : (untyped) -> untyped
+    def before_value: (untyped) -> untyped
+
+    # : (untyped) -> untyped
+    def after_value: (untyped) -> untyped
+
+    # : (untyped) -> bool
+    def relationship_changed?: (untyped) -> bool
+
+    private
+
+    @after_attributes: Hash[String, untyped]
+
+    @before_attributes: Hash[String, untyped]
+
+    # : (Hash[untyped, untyped]) -> Hash[String, untyped]
+    def normalize_hash: (Hash[untyped, untyped]) -> Hash[String, untyped]
+
+    # : (untyped) -> Array[untyped]
+    def relationship_keys: (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]) -> void
-    def prepare: (untyped, Array[untyped]) -> void
+    # : (untyped, Array[untyped], ?start_at: untyped) -> void
+    def prepare: (untyped, Array[untyped], ?start_at: untyped) -> void
 
     # : (untyped, untyped) -> RecordSnapshot?
     def call: (untyped, untyped) -> RecordSnapshot?

data/sig/generated/paper_trail_diff/activity_timeline_builder.rbs

@@ -3,8 +3,8 @@
 module PaperTrailDiff
   # Compares adjacent root and selected-descendant activity boundaries.
   class ActivityTimelineBuilder
-    # : (untyped, from: untyped, to: untyped, tree: AssociationTree, snapshotter: untyped) -> void
-    def initialize: (untyped, from: untyped, to: untyped, tree: AssociationTree, snapshotter: untyped) -> void
+    # : (untyped, range: TimelineRange, tree: AssociationTree, snapshotter: untyped) -> void
+    def initialize: (untyped, range: TimelineRange, tree: AssociationTree, snapshotter: untyped) -> void
 
     # : () -> Array[ActivityStep]
     def build: () -> Array[ActivityStep]
@@ -17,6 +17,8 @@ module PaperTrailDiff
 
     @from: untyped
 
+    @range: TimelineRange
+
     @record: untyped
 
     @snapshotter: untyped
@@ -37,25 +39,28 @@ module PaperTrailDiff
     # : () -> void
     def validate_current_range!: () -> void
 
-    # : (Array[untyped], ?range_end: untyped) -> Array[ActivityEvent]
-    def collect_events: (Array[untyped], ?range_end: untyped) -> Array[ActivityEvent]
+    # : (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]) -> void
-    def prepare_history: (Array[untyped]) -> void
+    # : (Array[untyped], ?start_at: untyped) -> void
+    def prepare_history: (Array[untyped], ?start_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) -> [Array[ActivityStep], Hash[Array[untyped], RecordSnapshot?], RecordSnapshot?]
-    def event_history: (Array[untyped], Array[ActivityEvent], ?current: untyped) -> [ Array[ActivityStep], Hash[Array[untyped], RecordSnapshot?], RecordSnapshot? ]
+    # : (Array[untyped], Array[ActivityEvent], ?current: untyped) -> ActivityHistory
+    def event_history: (Array[untyped], Array[ActivityEvent], ?current: untyped) -> ActivityHistory
 
-    # : (Array[untyped], Hash[Array[untyped], RecordSnapshot?], Array[ActivityStep]) -> Analysis
-    def build_analysis: (Array[untyped], Hash[Array[untyped], RecordSnapshot?], Array[ActivityStep]) -> Analysis
+    # : (Array[untyped], ActivityHistory) -> Analysis
+    def build_analysis: (Array[untyped], ActivityHistory) -> Analysis
 
     # : (Array[untyped], Array[RecordSnapshot?]) -> Array[Step]
     def build_root_steps: (Array[untyped], Array[RecordSnapshot?]) -> Array[Step]
 
     # : (untyped) -> Array[untyped]
     def version_key: (untyped) -> Array[untyped]
+
+    # : () -> TimeActivityTimelineBuilder
+    def time_builder: () -> TimeActivityTimelineBuilder
   end
 end

data/sig/generated/paper_trail_diff/activity_version_collector.rbs

@@ -3,8 +3,8 @@
 module PaperTrailDiff
   # Collects root and selected-descendant versions relevant to one root history range.
   class ActivityVersionCollector
-    # : (untyped, root_versions: Array[untyped], tree: AssociationTree, traversal: AssociationTraversal, ?range_end: untyped) -> void
-    def initialize: (untyped, root_versions: Array[untyped], tree: AssociationTree, traversal: AssociationTraversal, ?range_end: untyped) -> void
+    # : (untyped, root_versions: Array[untyped], tree: AssociationTree, traversal: AssociationTraversal, ?range_start: untyped, ?range_end: untyped) -> void
+    def initialize: (untyped, root_versions: Array[untyped], tree: AssociationTree, traversal: AssociationTraversal, ?range_start: untyped, ?range_end: untyped) -> void
 
     # : () -> Array[ActivityEvent]
     def call: () -> Array[ActivityEvent]
@@ -59,9 +59,6 @@ module PaperTrailDiff
     # : (untyped, untyped) -> untyped
     def target_class: (untyped, untyped) -> untyped
 
-    # : (untyped) -> Array[String?]
-    def related_parent_types: (untyped) -> Array[String?]
-
     # : (untyped) -> bool
     def in_range?: (untyped) -> bool
 

data/sig/generated/paper_trail_diff/branch_snapshot_refresher.rbs

@@ -3,8 +3,8 @@
 module PaperTrailDiff
   # Reconstructs selected root branches and merges them into a prior immutable snapshot.
   class BranchSnapshotRefresher
-    # : (tree: AssociationTree, ignore_policy: IgnorePolicy, traversal: AssociationTraversal, pool: SnapshotPool, normalizer: SnapshotNormalizer, full_snapshotter: untyped, partial_snapshotter: untyped, association_reader: untyped) -> void
-    def initialize: (tree: AssociationTree, ignore_policy: IgnorePolicy, traversal: AssociationTraversal, pool: SnapshotPool, normalizer: SnapshotNormalizer, full_snapshotter: untyped, partial_snapshotter: untyped, association_reader: untyped) -> void
+    # : (tree: AssociationTree, ignore_policy: IgnorePolicy, traversal: AssociationTraversal, pool: SnapshotPool, normalizer: SnapshotNormalizer, full_snapshotter: untyped, partial_snapshotter: untyped, association_reader: untyped, record_transition: untyped) -> void
+    def initialize: (tree: AssociationTree, ignore_policy: IgnorePolicy, traversal: AssociationTraversal, pool: SnapshotPool, normalizer: SnapshotNormalizer, full_snapshotter: untyped, partial_snapshotter: untyped, association_reader: untyped, record_transition: untyped) -> void
 
     # : (untyped, untyped, RecordSnapshot?, event: ActivityEvent) -> RecordSnapshot?
     def advance_root: (untyped, untyped, RecordSnapshot?, event: ActivityEvent) -> RecordSnapshot?

data/sig/generated/paper_trail_diff/collection_comparator.rbs

@@ -0,0 +1,59 @@
+# Generated from lib/paper_trail_diff/collection_comparator.rb with RBS::Inline
+
+module PaperTrailDiff
+  # Compares collection snapshots with a low-allocation path for stable membership.
+  class CollectionComparator
+    # : (AssociationSnapshot, AssociationSnapshot, record_comparer: untyped) -> void
+    def initialize: (AssociationSnapshot, AssociationSnapshot, record_comparer: untyped) -> void
+
+    # : () -> CollectionAssociationDiff
+    def call: () -> CollectionAssociationDiff
+
+    private
+
+    @from: AssociationSnapshot
+
+    @record_comparer: untyped
+
+    @to: AssociationSnapshot
+
+    # : (CollectionTransition) -> CollectionAssociationDiff
+    def transition_difference: (CollectionTransition) -> CollectionAssociationDiff
+
+    # : (RecordSnapshot?, RecordSnapshot?) -> RecordChange?
+    def compare_transition_records: (RecordSnapshot?, RecordSnapshot?) -> RecordChange?
+
+    # : () -> Array[RecordChange]?
+    def aligned_changes: () -> Array[RecordChange]?
+
+    # : () -> Array[[RecordSnapshot, RecordSnapshot]]?
+    def aligned_changed_pairs: () -> Array[[ RecordSnapshot, RecordSnapshot ]]?
+
+    # : (Array[RecordSnapshot], Array[RecordSnapshot]) -> Array[[RecordSnapshot, RecordSnapshot]]?
+    def collect_aligned_pairs: (Array[RecordSnapshot], Array[RecordSnapshot]) -> Array[[ RecordSnapshot, RecordSnapshot ]]?
+
+    # : () -> CollectionAssociationDiff
+    def indexed_difference: () -> CollectionAssociationDiff
+
+    # : (added: Array[RecordSnapshot], removed: Array[RecordSnapshot], changed: Array[RecordChange]) -> CollectionAssociationDiff
+    def difference: (added: Array[RecordSnapshot], removed: Array[RecordSnapshot], changed: Array[RecordChange]) -> CollectionAssociationDiff
+
+    # : (Hash[identity, RecordSnapshot], Hash[identity, RecordSnapshot]) -> Array[RecordSnapshot]
+    def records_missing_from: (Hash[identity, RecordSnapshot], Hash[identity, RecordSnapshot]) -> Array[RecordSnapshot]
+
+    # : (Hash[identity, RecordSnapshot], Hash[identity, RecordSnapshot]) -> Array[RecordChange]
+    def changed_records: (Hash[identity, RecordSnapshot], Hash[identity, RecordSnapshot]) -> Array[RecordChange]
+
+    # : (Array[RecordSnapshot]) -> Hash[identity, RecordSnapshot]
+    def index_records: (Array[RecordSnapshot]) -> Hash[identity, RecordSnapshot]
+
+    # : (Array[identity]) -> Array[identity]
+    def sorted_identities: (Array[identity]) -> Array[identity]
+
+    # : (identity) -> Array[untyped]
+    def sortable_identity: (identity) -> Array[untyped]
+
+    # : (identity) -> void
+    def raise_duplicate_identity!: (identity) -> void
+  end
+end

data/sig/generated/paper_trail_diff/collection_identity_index.rbs

@@ -0,0 +1,29 @@
+# Generated from lib/paper_trail_diff/collection_identity_index.rb with RBS::Inline
+
+module PaperTrailDiff
+  # Immutable positions for one collection membership and ordering.
+  class CollectionIdentityIndex
+    # : (Array[untyped]) -> void
+    def initialize: (Array[untyped]) -> void
+
+    # : (untyped, untyped) -> Integer?
+    def position: (untyped, untyped) -> Integer?
+
+    # : (untyped) -> Integer?
+    def position_for_id: (untyped) -> Integer?
+
+    private
+
+    @id_positions: Hash[String, Integer?]
+
+    @positions: Hash[Array[untyped], Integer]
+
+    @serialized_positions: Hash[Array[String], Integer]
+
+    # : (untyped, Integer) -> void
+    def register: (untyped, Integer) -> void
+
+    # : (untyped, Integer) -> void
+    def register_id: (untyped, Integer) -> void
+  end
+end