paper_trail_diff 0.2.0 → 0.3.0

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

data/sig/generated/paper_trail_diff/live_graph_collector.rbs

@@ -0,0 +1,27 @@
+# Generated from lib/paper_trail_diff/live_graph_collector.rb with RBS::Inline
+
+module PaperTrailDiff
+  # Flattens an already-preloaded, explicitly bounded live association graph.
+  class LiveGraphCollector
+    # : (tree: AssociationTree, traversal: AssociationTraversal) -> void
+    def initialize: (tree: AssociationTree, traversal: AssociationTraversal) -> void
+
+    # : (Array[untyped]) -> Array[untyped]
+    def call: (Array[untyped]) -> Array[untyped]
+
+    private
+
+    @traversal: AssociationTraversal
+
+    @tree: AssociationTree
+
+    # : (Array[untyped], AssociationTree, path: String, into: Hash[Array[untyped], untyped]) -> void
+    def collect: (Array[untyped], AssociationTree, path: String, into: Hash[Array[untyped], untyped]) -> void
+
+    # : (untyped, Array[untyped], AssociationTree, path: String, into: Hash[Array[untyped], untyped]) -> void
+    def collect_group: (untyped, Array[untyped], AssociationTree, path: String, into: Hash[Array[untyped], untyped]) -> void
+
+    # : (Array[untyped], untyped) -> Array[untyped]
+    def children_for: (Array[untyped], untyped) -> Array[untyped]
+  end
+end

data/sig/generated/paper_trail_diff/paper_trail_adapter.rbs

@@ -3,20 +3,24 @@
 module PaperTrailDiff
   # PaperTrail/ActiveRecord boundary that produces plain record snapshots.
   class PaperTrailAdapter
-    # : (associations: Array[String | Symbol], ignore: ignore_option) -> void
-    def initialize: (associations: Array[String | Symbol], ignore: ignore_option) -> void
+    # : (associations: Array[String | Symbol], ignore: ignore_option, ?reload_live_endpoints: bool) -> void
+    def initialize: (associations: Array[String | Symbol], ignore: ignore_option, ?reload_live_endpoints: bool) -> void
 
     # : (untyped, untyped) -> Diff
     def compare: (untyped, untyped) -> Diff
 
-    # : (untyped, from: untyped, to: untyped) -> Array[Step]
-    def timeline: (untyped, from: untyped, to: untyped) -> Array[Step]
+    # Compares independent pairs and returns immutable results keyed by item identity.
+    # : (Array[comparison_input]) -> comparison_results
+    def compare_many: (Array[comparison_input]) -> comparison_results
 
-    # : (untyped, from: untyped, to: untyped) -> Array[ActivityStep]
-    def activity_timeline: (untyped, from: untyped, to: untyped) -> Array[ActivityStep]
+    # : (untyped, from: untyped, to: untyped, within: untyped) -> Array[Step]
+    def timeline: (untyped, from: untyped, to: untyped, within: untyped) -> Array[Step]
 
-    # : (untyped, from: untyped, to: untyped, ?activity: bool) -> Analysis
-    def analyze: (untyped, from: untyped, to: untyped, ?activity: bool) -> Analysis
+    # : (untyped, from: untyped, to: untyped, within: untyped) -> Array[ActivityStep]
+    def activity_timeline: (untyped, from: untyped, to: untyped, within: untyped) -> Array[ActivityStep]
+
+    # : (untyped, from: untyped, to: untyped, within: untyped, ?activity: bool) -> Analysis
+    def analyze: (untyped, from: untyped, to: untyped, within: untyped, ?activity: bool) -> Analysis
 
     private
 
@@ -28,6 +32,10 @@ module PaperTrailDiff
 
     @ignore_policy: IgnorePolicy
 
+    @instrumentation_payload: Hash[Symbol, untyped]
+
+    @live_endpoints: LiveEndpointProvider
+
     @normalizer: SnapshotNormalizer
 
     @snapshot_pool: SnapshotPool
@@ -42,8 +50,8 @@ module PaperTrailDiff
     # : () -> ActivitySnapshotProvider
     def build_activity_snapshotter: () -> ActivitySnapshotProvider
 
-    # : (untyped, from: untyped, to: untyped) -> ActivityTimelineBuilder
-    def activity_builder: (untyped, from: untyped, to: untyped) -> ActivityTimelineBuilder
+    # : (untyped, from: untyped, to: untyped, within: untyped) -> ActivityTimelineBuilder
+    def activity_builder: (untyped, from: untyped, to: untyped, within: untyped) -> ActivityTimelineBuilder
 
     # : (untyped) -> void
     def reject_live_habtm_activity!: (untyped) -> void
@@ -63,6 +71,9 @@ module PaperTrailDiff
     # : (untyped) -> RecordSnapshot
     def live_snapshot: (untyped) -> RecordSnapshot
 
+    # : (untyped) -> RecordSnapshot
+    def normalize_live_snapshot: (untyped) -> RecordSnapshot
+
     # : (untyped, historical: bool) -> void
     def prepare_traversal!: (untyped, historical: bool) -> void
 

data/sig/generated/paper_trail_diff/preloaded_endpoint_batch_loader.rbs

@@ -0,0 +1,24 @@
+# Generated from lib/paper_trail_diff/preloaded_endpoint_batch_loader.rb with RBS::Inline
+
+module PaperTrailDiff
+  # Validates and reuses caller-owned live records without issuing association queries.
+  class PreloadedEndpointBatchLoader
+    # : (tree: AssociationTree, traversal: AssociationTraversal) -> void
+    def initialize: (tree: AssociationTree, traversal: AssociationTraversal) -> void
+
+    # : (Array[untyped]) -> Hash[identity, untyped]
+    def call: (Array[untyped]) -> Hash[identity, untyped]
+
+    private
+
+    @traversal: AssociationTraversal
+
+    @tree: AssociationTree
+
+    # : (untyped, AssociationTree, path: String) -> void
+    def validate_record: (untyped, AssociationTree, path: String) -> void
+
+    # : (untyped, AssociationTree, String, untyped) -> void
+    def validate_association: (untyped, AssociationTree, String, untyped) -> void
+  end
+end

data/sig/generated/paper_trail_diff/prepared_edge_loader.rbs

@@ -5,8 +5,8 @@ module PaperTrailDiff
   class PreparedEdgeLoader
     EDGE_LOADERS: untyped
 
-    # : (PreparedRecordIndex, Array[untyped]) -> void
-    def initialize: (PreparedRecordIndex, Array[untyped]) -> void
+    # : (PreparedRecordIndex, Array[untyped], ?start_at: untyped) -> void
+    def initialize: (PreparedRecordIndex, Array[untyped], ?start_at: untyped) -> void
 
     # : (untyped, Array[untyped], untyped) -> [Hash[String, Hash[Symbol, untyped]], Hash[String, Array[untyped]]?]
     def call: (untyped, Array[untyped], untyped) -> [ Hash[String, Hash[Symbol, untyped]], Hash[String, Array[untyped]]? ]
@@ -15,6 +15,8 @@ module PaperTrailDiff
 
     @records: PreparedRecordIndex
 
+    @start_at: untyped
+
     @transaction_ids: Array[untyped]
 
     # : (untyped, Array[untyped], untyped) -> [Hash[String, Hash[Symbol, untyped]], nil]
@@ -41,11 +43,17 @@ module PaperTrailDiff
     # : (Array[untyped], untyped) -> Array[untyped]
     def membership_ids: (Array[untyped], untyped) -> Array[untyped]
 
-    # : (untyped, Array[untyped], untyped, String) -> Array[untyped]
-    def historical_child_ids: (untyped, Array[untyped], untyped, String) -> Array[untyped]
+    # : (untyped, Array[untyped], untyped, String) -> Hash[String, Array[untyped]]
+    def historical_child_ids: (untyped, Array[untyped], untyped, String) -> Hash[String, Array[untyped]]
+
+    # : (untyped, Array[untyped], untyped, String) -> untyped
+    def historical_child_relation: (untyped, Array[untyped], untyped, String) -> untyped
+
+    # : (untyped) -> VersionAssociationCandidateScope
+    def child_candidate_scope: (untyped) -> VersionAssociationCandidateScope
 
-    # : (untyped, Array[untyped], untyped, String) -> Array[untyped]
-    def live_child_ids: (untyped, Array[untyped], untyped, String) -> Array[untyped]
+    # : (untyped, Array[untyped], untyped, String) -> Hash[String, Array[untyped]]
+    def live_child_ids: (untyped, Array[untyped], untyped, String) -> Hash[String, Array[untyped]]
 
     # : (untyped, untyped) -> untyped
     def target_class: (untyped, untyped) -> untyped
@@ -53,8 +61,14 @@ module PaperTrailDiff
     # : (Hash[String, Hash[Symbol, untyped]], untyped, untyped) -> void
     def add_identity: (Hash[String, Hash[Symbol, untyped]], untyped, untyped) -> void
 
-    # : (untyped, Array[untyped]) -> Hash[String, Hash[Symbol, untyped]]
-    def group_for: (untyped, Array[untyped]) -> Hash[String, Hash[Symbol, untyped]]
+    # : (untyped, Array[untyped], ?owners: Hash[String, Array[untyped]]?) -> Hash[String, Hash[Symbol, untyped]]
+    def group_for: (untyped, Array[untyped], ?owners: Hash[String, Array[untyped]]?) -> Hash[String, Hash[Symbol, untyped]]
+
+    # : (Array[Array[untyped]]) -> Hash[String, Array[untyped]]
+    def group_ids_by_owner: (Array[Array[untyped]]) -> Hash[String, Array[untyped]]
+
+    # : (Hash[String, Array[untyped]], Hash[String, Array[untyped]]) -> Hash[String, Array[untyped]]
+    def merge_owners: (Hash[String, Array[untyped]], Hash[String, Array[untyped]]) -> Hash[String, Array[untyped]]
 
     # : (untyped) -> String?
     def scalar_foreign_key: (untyped) -> String?

data/sig/generated/paper_trail_diff/prepared_history.rbs

@@ -20,6 +20,9 @@ module PaperTrailDiff
     # : (untyped, untyped, Hash[String, Array[untyped]]) -> void
     def register_habtm: (untyped, untyped, Hash[String, Array[untyped]]) -> void
 
+    # : (untyped, untyped, untyped) -> [Hash[untyped, untyped], Hash[untyped, untyped]]?
+    def record_transition: (untyped, untyped, untyped) -> [ Hash[untyped, untyped], Hash[untyped, untyped] ]?
+
     # : (untyped, untyped, untyped, habtm_boundary: untyped) -> [bool, Array[untyped]]
     def resolve: (untyped, untyped, untyped, habtm_boundary: untyped) -> [ bool, Array[untyped] ]
 
@@ -57,6 +60,9 @@ module PaperTrailDiff
     # : (untyped, untyped, untyped) -> Array[untyped]
     def child_records: (untyped, untyped, untyped) -> Array[untyped]
 
+    # : (Hash[Symbol, untyped], untyped) -> Array[untyped]
+    def child_ids_for: (Hash[Symbol, untyped], untyped) -> Array[untyped]
+
     # : (untyped, untyped, untyped, untyped) -> Array[untyped]?
     def habtm_records: (untyped, untyped, untyped, untyped) -> Array[untyped]?
 

data/sig/generated/paper_trail_diff/prepared_history_loader.rbs

@@ -3,8 +3,8 @@
 module PaperTrailDiff
   # Expands the explicit association tree into a request-scoped PreparedHistory.
   class PreparedHistoryLoader
-    # : (untyped, root_versions: Array[untyped], tree: AssociationTree, traversal: AssociationTraversal) -> void
-    def initialize: (untyped, root_versions: Array[untyped], tree: AssociationTree, traversal: AssociationTraversal) -> void
+    # : (untyped, root_versions: Array[untyped], tree: AssociationTree, traversal: AssociationTraversal, ?root_ids: Array[untyped], ?start_at: untyped, ?live_records: Array[untyped]) -> void
+    def initialize: (untyped, root_versions: Array[untyped], tree: AssociationTree, traversal: AssociationTraversal, ?root_ids: Array[untyped], ?start_at: untyped, ?live_records: Array[untyped]) -> void
 
     # : () -> PreparedHistory
     def call: () -> PreparedHistory
@@ -21,6 +21,8 @@ module PaperTrailDiff
 
     @records: PreparedRecordIndex
 
+    @root_ids: Array[untyped]
+
     @traversal: AssociationTraversal
 
     @tree: AssociationTree

data/sig/generated/paper_trail_diff/prepared_record_index.rbs

@@ -3,23 +3,58 @@
 module PaperTrailDiff
   # Immutable scalar state from a PaperTrail version or live-record fallback.
   class PreparedRecordState
+    attr_reader model_class: untyped
+
+    attr_reader attributes: Hash[untyped, untyped]
+
     # : (untyped) -> void
     def initialize: (untyped) -> void
 
+    # : (untyped, Hash[untyped, untyped]) -> PreparedRecordState
+    def self.from_attributes: (untyped, Hash[untyped, untyped]) -> PreparedRecordState
+
     # : () -> untyped
     def instantiate: () -> untyped
 
-    @attributes: Hash[untyped, untyped]
+    private
+
+    # : (untyped, Hash[untyped, untyped]) -> void
+    def initialize_attributes: (untyped, Hash[untyped, untyped]) -> void
+  end
+
+  # Extracts a version's scalar state without constructing a disposable AR object.
+  class PreparedVersionStateLoader
+    # : () -> void
+    def initialize: () -> void
+
+    # : (untyped) -> PreparedRecordState?
+    def call: (untyped) -> PreparedRecordState?
+
+    private
+
+    @attribute_names: Hash[untyped, Array[String]]
+
+    @serializers: Hash[untyped, untyped]
+
+    # : (Hash[untyped, untyped]) -> Hash[String, untyped]
+    def stringify_keys: (Hash[untyped, untyped]) -> Hash[String, untyped]
 
-    @model_class: untyped
+    # : (untyped, Hash[String, untyped]) -> untyped
+    def reification_class: (untyped, Hash[String, untyped]) -> untyped
+
+    # : (untyped, Hash[String, untyped]) -> bool
+    def direct_attributes?: (untyped, Hash[String, untyped]) -> bool
+
+    # : (untyped) -> untyped
+    def object_attribute_serializer: (untyped) -> untyped
   end
 
   # Versions and live fallback for one model identity.
   class PreparedRecordSeries
     attr_reader versions: Array[untyped]
 
-    # : (versions: Array[untyped], live: PreparedRecordState?) -> void
-    def initialize: (versions: Array[untyped], live: PreparedRecordState?) -> void
+    # : (versions: Array[untyped], live: PreparedRecordState?, ?state_loader: PreparedVersionStateLoader) -> void
+    def initialize: (versions: Array[untyped], live: PreparedRecordState?, ?state_loader: PreparedVersionStateLoader) -> void
 
     # : (untyped) -> untyped
     def record_before: (untyped) -> untyped
@@ -27,12 +62,22 @@ module PaperTrailDiff
     # : () -> Array[untyped]
     def records: () -> Array[untyped]
 
+    # : (untyped) -> [Hash[untyped, untyped], Hash[untyped, untyped]]?
+    def transition: (untyped) -> [ Hash[untyped, untyped], Hash[untyped, untyped] ]?
+
     private
 
     @live: PreparedRecordState?
 
+    @state_loader: PreparedVersionStateLoader
+
     @states: Hash[untyped, PreparedRecordState?]
 
+    @version_positions: Hash[String, Integer]
+
+    # : (Integer) -> PreparedRecordState?
+    def state_after: (Integer) -> PreparedRecordState?
+
     # : (untyped, untyped) -> bool
     def eligible?: (untyped, untyped) -> bool
 
@@ -45,8 +90,8 @@ module PaperTrailDiff
 
   # Request-scoped scalar history loaded once per model identity.
   class PreparedRecordIndex
-    # : (untyped) -> void
-    def initialize: (untyped) -> void
+    # : (untyped, ?live_records: Array[untyped]) -> void
+    def initialize: (untyped, ?live_records: Array[untyped]) -> void
 
     # : (untyped, Array[untyped]) -> void
     def load: (untyped, Array[untyped]) -> void
@@ -54,6 +99,9 @@ module PaperTrailDiff
     # : (untyped, untyped, untyped) -> untyped
     def record_before: (untyped, untyped, untyped) -> untyped
 
+    # : (untyped, untyped, untyped) -> [Hash[untyped, untyped], Hash[untyped, untyped]]?
+    def transition: (untyped, untyped, untyped) -> [ Hash[untyped, untyped], Hash[untyped, untyped] ]?
+
     # : (untyped, Array[untyped]) -> Array[untyped]
     def records_for: (untyped, Array[untyped]) -> Array[untyped]
 
@@ -62,10 +110,14 @@ module PaperTrailDiff
 
     private
 
+    @seeded_live_records: Hash[Array[String], untyped]
+
     @series: Hash[Array[String], PreparedRecordSeries]
 
     @start_time: untyped
 
+    @state_loader: PreparedVersionStateLoader
+
     # : (untyped, untyped) -> Array[String]
     def identity: (untyped, untyped) -> Array[String]
 
@@ -78,6 +130,9 @@ module PaperTrailDiff
     # : (untyped, Array[untyped]) -> Array[untyped]
     def versions_for: (untyped, Array[untyped]) -> Array[untyped]
 
+    # : (untyped, Array[untyped]) -> Array[untyped]
+    def available_live_records: (untyped, Array[untyped]) -> Array[untyped]
+
     # : (untyped, Array[untyped]) -> Array[untyped]
     def live_records_for: (untyped, Array[untyped]) -> Array[untyped]
   end

data/sig/generated/paper_trail_diff/snapshot.rbs

@@ -26,6 +26,16 @@ module PaperTrailDiff
 
     SUPPORTED_KINDS: untyped
 
+    # Non-semantic memoization shared by structurally adjacent snapshots. The
+    # cached value is derived only from frozen records and is itself immutable.
+    class IdentityIndexCache
+      # : () -> void
+      def initialize: () -> void
+
+      # : (Array[RecordSnapshot]) -> CollectionIdentityIndex
+      def index: (Array[RecordSnapshot]) -> CollectionIdentityIndex
+    end
+
     # : (Symbol) -> bool
     def self.collection_kind?: (Symbol) -> bool
 
@@ -33,11 +43,36 @@ module PaperTrailDiff
 
     attr_reader records: Array[RecordSnapshot]
 
-    # : (kind: Symbol, records: Array[RecordSnapshot]) -> void
-    def initialize: (kind: Symbol, records: Array[RecordSnapshot]) -> void
+    # : (kind: Symbol, records: Array[RecordSnapshot], ?identity_index_cache: untyped, ?transition: CollectionTransition?) -> void
+    def initialize: (kind: Symbol, records: Array[RecordSnapshot], ?identity_index_cache: untyped, ?transition: CollectionTransition?) -> void
+
+    # Builds a structurally adjacent collection snapshot for internal activity carry-forward.
+    # : (Array[RecordSnapshot], before: RecordSnapshot?, after: RecordSnapshot?, membership_preserved: bool) -> AssociationSnapshot
+    def transition_to: (Array[RecordSnapshot], before: RecordSnapshot?, after: RecordSnapshot?, membership_preserved: bool) -> AssociationSnapshot
+
+    # : (AssociationSnapshot) -> CollectionTransition?
+    def transition_from: (AssociationSnapshot) -> CollectionTransition?
+
+    # : (untyped, untyped) -> Integer?
+    def position: (untyped, untyped) -> Integer?
+
+    # : (untyped) -> Integer?
+    def position_for_id: (untyped) -> Integer?
+
+    # : () -> void
+    def validate_unique_identities!: () -> void
 
     # : () -> Hash[Symbol, untyped]
     def to_h: () -> Hash[Symbol, untyped]
+
+    private
+
+    @identity_index_cache: untyped
+
+    @transition: CollectionTransition?
+
+    # : () -> CollectionIdentityIndex
+    def identity_index: () -> CollectionIdentityIndex
   end
 
   # An immutable, ActiveRecord-independent representation of a reified record.