paper_trail_diff 0.2.0 → 0.3.1

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_relationship.rbs

@@ -0,0 +1,23 @@
+# Generated from lib/paper_trail_diff/activity_relationship.rb with RBS::Inline
+
+module PaperTrailDiff
+  # Reads event-side foreign keys and matches them to an immutable snapshot owner.
+  class ActivityRelationship
+    # : (untyped, untyped, RecordSnapshot, ?state: Symbol) -> bool
+    def member_of_owner?: (untyped, untyped, RecordSnapshot, ?state: Symbol) -> bool
+
+    # : (untyped, untyped, state: Symbol) -> untyped
+    def owner_id: (untyped, untyped, state: Symbol) -> untyped
+
+    private
+
+    # : (untyped, untyped, state: Symbol) -> Array[String]
+    def relationship_owner_values: (untyped, untyped, state: Symbol) -> Array[String]
+
+    # : (untyped, untyped, state: Symbol) -> untyped
+    def event_attribute: (untyped, untyped, state: Symbol) -> untyped
+
+    # : (untyped, RecordSnapshot) -> Array[String]
+    def owner_types: (untyped, RecordSnapshot) -> Array[String]
+  end
+end

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

data/sig/generated/paper_trail_diff/collection_transition.rbs

@@ -0,0 +1,18 @@
+# Generated from lib/paper_trail_diff/collection_transition.rb with RBS::Inline
+
+module PaperTrailDiff
+  # One collection mutation between structurally adjacent snapshots.
+  class CollectionTransition
+    attr_reader before: RecordSnapshot?
+
+    attr_reader after: RecordSnapshot?
+
+    # : (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
+  end
+end

data/sig/generated/paper_trail_diff/comparison_batch.rbs

@@ -0,0 +1,65 @@
+# Generated from lib/paper_trail_diff/comparison_batch.rb with RBS::Inline
+
+module PaperTrailDiff
+  # Validates and executes independent comparisons with shared live endpoint loading.
+  class ComparisonBatch
+    # : (Array[comparison_input], live_loader: untyped, preparer: untyped, history_preparer: untyped, historical_snapshotter: untyped, live_normalizer: untyped) -> void
+    def initialize: (Array[comparison_input], live_loader: untyped, preparer: untyped, history_preparer: untyped, historical_snapshotter: untyped, live_normalizer: untyped) -> void
+
+    # : () -> comparison_results
+    def call: () -> comparison_results
+
+    private
+
+    @comparisons: Array[comparison_input]
+
+    @historical_snapshotter: untyped
+
+    @history_preparer: untyped
+
+    @live_loader: untyped
+
+    @live_normalizer: untyped
+
+    @preparer: untyped
+
+    # : (untyped, untyped, Hash[identity, RecordSnapshot]) -> Diff
+    def compare: (untyped, untyped, Hash[identity, RecordSnapshot]) -> Diff
+
+    # : (untyped, Hash[identity, RecordSnapshot]) -> RecordSnapshot?
+    def snapshot: (untyped, Hash[identity, RecordSnapshot]) -> RecordSnapshot?
+
+    # : (Array[untyped]) -> Hash[identity, untyped]
+    def load_live_records: (Array[untyped]) -> Hash[identity, untyped]
+
+    # : (Hash[identity, untyped]) -> Hash[identity, RecordSnapshot]
+    def normalize_live_records: (Hash[identity, untyped]) -> Hash[identity, RecordSnapshot]
+
+    # : (Array[[untyped, untyped]], Hash[identity, untyped]) -> void
+    def prepare_historical_batches!: (Array[[ untyped, untyped ]], Hash[identity, untyped]) -> void
+
+    # : (Array[[untyped, untyped]], Hash[identity, untyped]) -> Array[untyped]
+    def historical_versions: (Array[[ untyped, untyped ]], Hash[identity, untyped]) -> Array[untyped]
+
+    # : () -> Array[[untyped, untyped]]
+    def comparison_pairs: () -> Array[[ untyped, untyped ]]
+
+    # : (untyped, Integer) -> [untyped, untyped]
+    def comparison_pair: (untyped, Integer) -> [ untyped, untyped ]
+
+    # : (untyped, Integer) -> void
+    def valid_comparison!: (untyped, Integer) -> void
+
+    # : (Hash[untyped, untyped], Symbol) -> untyped
+    def endpoint: (Hash[untyped, untyped], Symbol) -> untyped
+
+    # : (Array[[untyped, untyped]]) -> void
+    def ensure_unique_identities!: (Array[[ untyped, untyped ]]) -> void
+
+    # : (Array[[untyped, untyped]]) -> void
+    def prepare_endpoint_classes!: (Array[[ untyped, untyped ]]) -> void
+
+    # : (Array[[untyped, untyped]]) -> Hash[untyped, bool]
+    def endpoint_requirements: (Array[[ untyped, untyped ]]) -> Hash[untyped, bool]
+  end
+end

data/sig/generated/paper_trail_diff/engine.rbs

@@ -36,18 +36,6 @@ module PaperTrailDiff
     # : (AssociationSnapshot, AssociationSnapshot) -> CollectionAssociationDiff
     private def self.compare_collection: (AssociationSnapshot, AssociationSnapshot) -> CollectionAssociationDiff
 
-    # : (Hash[identity, RecordSnapshot], Hash[identity, RecordSnapshot]) -> Array[RecordSnapshot]
-    private def self.records_missing_from: (Hash[identity, RecordSnapshot], Hash[identity, RecordSnapshot]) -> Array[RecordSnapshot]
-
-    # : (Hash[identity, RecordSnapshot], Hash[identity, RecordSnapshot]) -> Array[RecordChange]
-    private def self.changed_records: (Hash[identity, RecordSnapshot], Hash[identity, RecordSnapshot]) -> Array[RecordChange]
-
-    # : (Array[RecordSnapshot]) -> Hash[Array[untyped], RecordSnapshot]
-    private def self.index_records: (Array[RecordSnapshot]) -> Hash[Array[untyped], RecordSnapshot]
-
-    # : (Array[Array[untyped]]) -> Array[Array[untyped]]
-    private def self.sorted_identities: (Array[Array[untyped]]) -> Array[Array[untyped]]
-
     # : (RecordSnapshot?, RecordSnapshot?) -> bool
     private def self.same_identity?: (RecordSnapshot?, RecordSnapshot?) -> bool
   end

data/sig/generated/paper_trail_diff/errors.rbs

@@ -17,10 +17,22 @@ module PaperTrailDiff
   class InvalidEndpointError < Error
   end
 
+  # Raised when reload opt-out encounters an association that was not preloaded.
+  class UnloadedAssociationError < InvalidEndpointError
+  end
+
   # Raised when a timeline boundary is absent or the requested range is reversed.
   class InvalidTimelineRangeError < Error
   end
 
+  # Raised when `within` is not a finite, chronological range of time-like values.
+  class InvalidTimeRangeError < InvalidTimelineRangeError
+  end
+
+  # Raised when an in-range mutation has no later root boundary for reconstruction.
+  class IncompleteTimeRangeError < InvalidTimelineRangeError
+  end
+
   # Raised when a requested ActiveRecord association does not exist.
   class UnknownAssociationError < Error
   end

data/sig/generated/paper_trail_diff/historical_snapshot_store.rbs

@@ -6,8 +6,12 @@ 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]) -> void
-    def prepare: (untyped, Array[untyped]) -> void
+    # : (untyped, Array[untyped], ?start_at: untyped) -> void
+    def prepare: (untyped, Array[untyped], ?start_at: untyped) -> void
+
+    # Prepares selected history for several roots of the same model class.
+    # : (Array[untyped], Array[untyped]) -> void
+    def prepare_batch: (Array[untyped], Array[untyped]) -> void
 
     # : (untyped, untyped) -> RecordSnapshot?
     def call: (untyped, untyped) -> RecordSnapshot?
@@ -21,10 +25,17 @@ module PaperTrailDiff
     # : (untyped, habtm_version: untyped) -> untyped
     def association_reader: (untyped, habtm_version: untyped) -> untyped
 
+    # : (untyped) -> [Hash[untyped, untyped], Hash[untyped, untyped]]?
+    def record_transition: (untyped) -> [ Hash[untyped, untyped], Hash[untyped, untyped] ]?
+
     private
 
+    @live_graph_collector: LiveGraphCollector
+
     @normalizer: SnapshotNormalizer
 
+    @prepared_histories: Hash[Array[untyped], PreparedHistory]
+
     @prepared_history: PreparedHistory?
 
     @preparer: untyped
@@ -35,6 +46,15 @@ module PaperTrailDiff
 
     @tree: AssociationTree
 
+    # : (untyped) -> Array[untyped]
+    def context_key: (untyped) -> Array[untyped]
+
+    # : (Array[untyped], Array[untyped]) -> Hash[Symbol, untyped]
+    def batch_payload: (Array[untyped], Array[untyped]) -> Hash[Symbol, untyped]
+
+    # : (Array[untyped], Array[untyped]) -> void
+    def register_batch: (Array[untyped], Array[untyped]) -> void
+
     # : (untyped, untyped, tree: AssociationTree, normalizer: SnapshotNormalizer) -> RecordSnapshot?
     def snapshot_from_version: (untyped, untyped, tree: AssociationTree, normalizer: SnapshotNormalizer) -> RecordSnapshot?
 

data/sig/generated/paper_trail_diff/instrumentation.rbs

@@ -0,0 +1,12 @@
+# Generated from lib/paper_trail_diff/instrumentation.rb with RBS::Inline
+
+module PaperTrailDiff
+  # Emits quiet, namespaced runtime events for application-owned diagnostics.
+  module Instrumentation
+    # : (String | Symbol, Hash[Symbol, untyped]) { () -> untyped } -> untyped
+    def self?.instrument: (String | Symbol, Hash[Symbol, untyped]) { () -> untyped } -> untyped
+
+    # : (association_paths: Array[String], reload_live_endpoints: bool) -> Hash[Symbol, untyped]
+    def self?.comparison_payload: (association_paths: Array[String], reload_live_endpoints: bool) -> Hash[Symbol, untyped]
+  end
+end

data/sig/generated/paper_trail_diff/live_endpoint_batch_loader.rbs

@@ -0,0 +1,52 @@
+# Generated from lib/paper_trail_diff/live_endpoint_batch_loader.rb with RBS::Inline
+
+module PaperTrailDiff
+  # Reloads current-record endpoints and their explicitly selected associations in batches.
+  class LiveEndpointBatchLoader
+    # : (tree: AssociationTree) -> void
+    def initialize: (tree: AssociationTree) -> void
+
+    # : (Array[untyped]) -> Hash[identity, untyped]
+    def call: (Array[untyped]) -> Hash[identity, untyped]
+
+    private
+
+    @tree: AssociationTree
+
+    # : (untyped, Array[untyped]) -> Array[untyped]
+    def load_group: (untyped, Array[untyped]) -> Array[untyped]
+
+    # : (Array[untyped], AssociationTree) -> void
+    def preload_tree: (Array[untyped], AssociationTree) -> void
+
+    # : (untyped, Array[untyped], AssociationTree) -> void
+    def preload_model_tree: (untyped, Array[untyped], AssociationTree) -> void
+
+    # : (untyped, AssociationTree) -> Array[[untyped, AssociationTree]]
+    def selected_reflections: (untyped, AssociationTree) -> Array[[ untyped, AssociationTree ]]
+
+    # : (Array[untyped], Array[[untyped, AssociationTree]], individually: bool) -> void
+    def preload_subtrees: (Array[untyped], Array[[ untyped, AssociationTree ]], individually: bool) -> void
+
+    # : (Array[untyped], Array[Symbol]) -> void
+    def preload_batch: (Array[untyped], Array[Symbol]) -> void
+
+    # : () -> untyped
+    def active_record_preloader: () -> untyped
+
+    # : (untyped, untyped) -> bool
+    def batch_safe?: (untyped, untyped) -> bool
+
+    # : (Array[untyped], untyped) -> Array[untyped]
+    def load_individually: (Array[untyped], untyped) -> Array[untyped]
+
+    # : (Array[untyped], untyped) -> Array[untyped]
+    def targets: (Array[untyped], untyped) -> Array[untyped]
+
+    # : (Array[untyped]) -> Array[untyped]
+    def unique_records: (Array[untyped]) -> Array[untyped]
+
+    # : (Array[untyped], Hash[identity, untyped]) -> void
+    def ensure_all_loaded!: (Array[untyped], Hash[identity, untyped]) -> void
+  end
+end

data/sig/generated/paper_trail_diff/live_endpoint_provider.rbs

@@ -0,0 +1,23 @@
+# Generated from lib/paper_trail_diff/live_endpoint_provider.rb with RBS::Inline
+
+module PaperTrailDiff
+  # Selects safe reload or validated caller-owned loading for current endpoints.
+  class LiveEndpointProvider
+    attr_reader reload: bool
+
+    attr_reader comparison_payload: Hash[Symbol, untyped]
+
+    # : (tree: AssociationTree, traversal: AssociationTraversal, reload: bool) -> void
+    def initialize: (tree: AssociationTree, traversal: AssociationTraversal, reload: bool) -> void
+
+    # : (Array[untyped]) -> Hash[identity, untyped]
+    def call: (Array[untyped]) -> Hash[identity, untyped]
+
+    private
+
+    @loader: untyped
+
+    # : (Array[untyped]) -> Hash[Symbol, untyped]
+    def payload: (Array[untyped]) -> Hash[Symbol, untyped]
+  end
+end