paper_trail_diff 0.2.0 → 0.3.1

data/lib/paper_trail_diff/paper_trail_adapter.rb

@@ -4,17 +4,19 @@
 module PaperTrailDiff
   # PaperTrail/ActiveRecord boundary that produces plain record snapshots.
   class PaperTrailAdapter
-    #: (associations: Array[String | Symbol], ignore: ignore_option) -> void
-    def initialize(associations:, ignore:)
+    #: (associations: Array[String | Symbol], ignore: ignore_option, ?reload_live_endpoints: bool) -> void
+    def initialize(associations:, ignore:, reload_live_endpoints: true)
       @association_tree = AssociationTree.build(associations)
       @ignore_policy = IgnorePolicy.build(ignore, association_paths: @association_tree.paths)
       @traversal = AssociationTraversal.new(@association_tree)
+      @live_endpoints = LiveEndpointProvider.new(
+        tree: @association_tree, traversal: @traversal, reload: reload_live_endpoints
+      )
+      @instrumentation_payload = @live_endpoints.comparison_payload
       @snapshot_pool = SnapshotPool.new
       @normalizer = SnapshotNormalizer.new(
-        tree: @association_tree,
-        ignore_policy: @ignore_policy,
-        traversal: @traversal,
-        pool: @snapshot_pool
+        tree: @association_tree, ignore_policy: @ignore_policy,
+        traversal: @traversal, pool: @snapshot_pool
       )
       @historical_store = build_historical_store
       @timeline_snapshotter = TimelineSnapshotProvider.new(@historical_store)
@@ -23,40 +25,59 @@ module PaperTrailDiff
 
     #: (untyped, untyped) -> Diff
     def compare(from_endpoint, to_endpoint)
-      Endpoint.validate_pair!(from_endpoint, to_endpoint)
-      Engine.compare(snapshot_for_endpoint(from_endpoint), snapshot_for_endpoint(to_endpoint))
+      payload = @instrumentation_payload.merge(comparison_count: 1)
+      Instrumentation.instrument('compare', payload) do
+        Endpoint.validate_pair!(from_endpoint, to_endpoint)
+        Engine.compare(snapshot_for_endpoint(from_endpoint), snapshot_for_endpoint(to_endpoint))
+      end
+    end
+
+    # Compares independent pairs and returns immutable results keyed by item identity.
+    #: (Array[comparison_input]) -> comparison_results
+    def compare_many(comparisons)
+      count = comparisons.is_a?(Array) ? comparisons.length : 0
+      payload = @instrumentation_payload.merge(comparison_count: count)
+      Instrumentation.instrument('compare_many', payload) do
+        ComparisonBatch.new(
+          comparisons,
+          live_loader: @live_endpoints.method(:call), preparer: method(:prepare_traversal!),
+          history_preparer: @historical_store.method(:prepare_batch),
+          historical_snapshotter: method(:historical_snapshot),
+          live_normalizer: method(:normalize_live_snapshot)
+        ).call
+      end
     end
 
-    #: (untyped, from: untyped, to: untyped) -> Array[Step]
-    def timeline(record, from:, to:)
+    #: (untyped, from: untyped, to: untyped, within: untyped) -> Array[Step]
+    def timeline(record, from:, to:, within:)
       prepare_traversal!(record.class, historical: true)
       builder = TimelineBuilder.new(
         record,
         from: from,
         to: to,
+        within: within,
         snapshotter: @timeline_snapshotter
       )
       builder.build
     end
 
-    #: (untyped, from: untyped, to: untyped) -> Array[ActivityStep]
-    def activity_timeline(record, from:, to:)
-      prepare_traversal!(record.class, historical: true)
-      reject_live_habtm_activity!(record.class) if Endpoint.record?(to)
-      ActivityTimelineBuilder.new(
-        record,
-        from: from,
-        to: to,
-        tree: @association_tree,
-        snapshotter: @activity_snapshotter
-      ).build
+    #: (untyped, from: untyped, to: untyped, within: untyped) -> Array[ActivityStep]
+    def activity_timeline(record, from:, to:, within:)
+      payload = @instrumentation_payload.merge(model_type: record.class.base_class.name.to_s)
+      Instrumentation.instrument('activity_timeline', payload) do
+        prepare_traversal!(record.class, historical: true)
+        reject_live_habtm_activity!(record.class) if Endpoint.record?(to)
+        steps = activity_builder(record, from: from, to: to, within: within).build
+        payload[:step_count] = steps.length
+        steps
+      end
     end
 
-    #: (untyped, from: untyped, to: untyped, ?activity: bool) -> Analysis
-    def analyze(record, from:, to:, activity: false)
+    #: (untyped, from: untyped, to: untyped, within: untyped, ?activity: bool) -> Analysis
+    def analyze(record, from:, to:, within:, activity: false)
       if activity
         prepare_traversal!(record.class, historical: true)
-        return activity_builder(record, from: from, to: to).analyze
+        return activity_builder(record, from: from, to: to, within: within).analyze
       end
 
       prepare_traversal!(record.class, historical: true)
@@ -64,6 +85,7 @@ module PaperTrailDiff
         record,
         from: from,
         to: to,
+        within: within,
         snapshotter: @timeline_snapshotter
       ).analyze
     end
@@ -71,6 +93,8 @@ module PaperTrailDiff
     private
 
     # @rbs @association_tree: AssociationTree
+    # @rbs @live_endpoints: LiveEndpointProvider
+    # @rbs @instrumentation_payload: Hash[Symbol, untyped]
     # @rbs @ignore_policy: IgnorePolicy
     # @rbs @traversal: AssociationTraversal
     # @rbs @snapshot_pool: SnapshotPool
@@ -92,14 +116,13 @@ module PaperTrailDiff
     #: () -> ActivitySnapshotProvider
     def build_activity_snapshotter
       refresher = BranchSnapshotRefresher.new(
-        tree: @association_tree,
-        ignore_policy: @ignore_policy,
-        traversal: @traversal,
-        pool: @snapshot_pool,
+        tree: @association_tree, ignore_policy: @ignore_policy,
+        traversal: @traversal, pool: @snapshot_pool,
         normalizer: @normalizer,
         full_snapshotter: method(:snapshot_at),
         partial_snapshotter: @historical_store.method(:custom),
-        association_reader: @historical_store.method(:association_reader)
+        association_reader: @historical_store.method(:association_reader),
+        record_transition: @historical_store.method(:record_transition)
       )
       ActivitySnapshotProvider.new(
         snapshotter: method(:snapshot_at),
@@ -108,12 +131,11 @@ module PaperTrailDiff
       )
     end
 
-    #: (untyped, from: untyped, to: untyped) -> ActivityTimelineBuilder
-    def activity_builder(record, from:, to:)
+    #: (untyped, from: untyped, to: untyped, within: untyped) -> ActivityTimelineBuilder
+    def activity_builder(record, from:, to:, within:)
       ActivityTimelineBuilder.new(
         record,
-        from: from,
-        to: to,
+        range: TimelineRange.new(record, from: from, to: to, within: within),
         tree: @association_tree,
         snapshotter: @activity_snapshotter
       )
@@ -152,7 +174,12 @@ module PaperTrailDiff
 
     #: (untyped) -> RecordSnapshot
     def live_snapshot(record)
-      current = Endpoint.reload_record(record)
+      current = @live_endpoints.call([record]).fetch(Endpoint.identity(record))
+      normalize_live_snapshot(current)
+    end
+
+    #: (untyped) -> RecordSnapshot
+    def normalize_live_snapshot(current)
       prepare_traversal!(current.class, historical: false)
       @normalizer.call(current, reifier: LiveAssociationReader.new) ||
         raise(InvalidEndpointError, 'current record endpoint could not be normalized')

data/lib/paper_trail_diff/preloaded_endpoint_batch_loader.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # Validates and reuses caller-owned live records without issuing association queries.
+  class PreloadedEndpointBatchLoader
+    #: (tree: AssociationTree, traversal: AssociationTraversal) -> void
+    def initialize(tree:, traversal:)
+      @tree = tree
+      @traversal = traversal
+    end
+
+    #: (Array[untyped]) -> Hash[identity, untyped]
+    def call(records)
+      records.each { |record| validate_record(record, @tree, path: '') }
+      records.to_h { |record| [Endpoint.identity(record), record] }
+    end
+
+    private
+
+    # @rbs @tree: AssociationTree
+    # @rbs @traversal: AssociationTraversal
+
+    #: (untyped, AssociationTree, path: String) -> void
+    def validate_record(record, tree, path:)
+      @traversal.reflections_for(record.class, tree, path: path).each do |reflection|
+        validate_association(record, tree, path, reflection)
+      end
+    end
+
+    #: (untyped, AssociationTree, String, untyped) -> void
+    def validate_association(record, tree, path, reflection)
+      association_path = Support.association_path(path, reflection.name.to_s)
+      association = record.association(reflection.name)
+      unless association.loaded?
+        message = "current endpoint association is not preloaded: #{association_path}"
+        raise UnloadedAssociationError, message
+      end
+
+      subtree = tree.child(reflection.name)
+      return unless subtree
+
+      Array(association.target).compact.each do |child|
+        validate_record(child, subtree, path: association_path)
+      end
+    end
+  end
+end

data/lib/paper_trail_diff/prepared_edge_loader.rb

@@ -12,10 +12,11 @@ module PaperTrailDiff
     }.freeze
     private_constant :EDGE_LOADERS
 
-    #: (PreparedRecordIndex, Array[untyped]) -> void
-    def initialize(records, root_versions)
+    #: (PreparedRecordIndex, Array[untyped], ?start_at: untyped) -> void
+    def initialize(records, root_versions, start_at: root_versions.first&.created_at)
       @records = records
       @transaction_ids = root_versions.filter_map(&:transaction_id).uniq.freeze
+      @start_at = start_at
     end
 
     #: (untyped, Array[untyped], untyped) -> [Hash[String, Hash[Symbol, untyped]], Hash[String, Array[untyped]]?]
@@ -28,6 +29,7 @@ module PaperTrailDiff
 
     # @rbs @records: PreparedRecordIndex
     # @rbs @transaction_ids: Array[untyped]
+    # @rbs @start_at: untyped
 
     #: (untyped, Array[untyped], untyped) -> [Hash[String, Hash[Symbol, untyped]], nil]
     def belongs_to_edge(owner_class, owner_ids, reflection)
@@ -63,9 +65,10 @@ module PaperTrailDiff
       key = scalar_foreign_key(reflection)
       return {} unless key
 
-      ids = historical_child_ids(owner_class, owner_ids, reflection, key)
-      ids.concat(live_child_ids(owner_class, owner_ids, reflection, key))
-      group_for(reflection.klass, ids)
+      historical = historical_child_ids(owner_class, owner_ids, reflection, key)
+      live = live_child_ids(owner_class, owner_ids, reflection, key)
+      owners = merge_owners(historical, live)
+      group_for(reflection.klass, owners.values.flatten, owners: owners)
     end
 
     #: (untyped, untyped) -> [Hash[String, Hash[Symbol, untyped]], Hash[String, Array[untyped]]]
@@ -92,30 +95,48 @@ module PaperTrailDiff
       end.uniq
     end
 
-    #: (untyped, Array[untyped], untyped, String) -> Array[untyped]
-    def historical_child_ids( # rubocop:disable Metrics/AbcSize
+    #: (untyped, Array[untyped], untyped, String) -> Hash[String, Array[untyped]]
+    def historical_child_ids(
       owner_class,
       owner_ids,
       reflection,
       foreign_key
     )
       version_class = owner_class.paper_trail.version_class
-      relation = owner_class.paper_trail.version_association_class.joins(:version).where(
+      association_class = owner_class.paper_trail.version_association_class
+      relation = historical_child_relation(owner_class, owner_ids, reflection, foreign_key)
+      pairs = child_candidate_scope(version_class).call(relation).distinct.pluck(
+        association_class.arel_table[:foreign_key_id],
+        version_class.arel_table[:item_id]
+      )
+      group_ids_by_owner(pairs)
+    end
+
+    #: (untyped, Array[untyped], untyped, String) -> untyped
+    def historical_child_relation(owner_class, owner_ids, reflection, foreign_key)
+      version_class = owner_class.paper_trail.version_class
+      owner_class.paper_trail.version_association_class.joins(:version).where(
         foreign_key_name: foreign_key,
-        foreign_key_id: owner_ids
-      ).where(foreign_type: parent_types(owner_class)).where(
-        version_class.table_name => { item_type: reflection.klass.base_class.name }
+        foreign_key_id: owner_ids,
+        foreign_type: parent_types(owner_class)
+      ).where(version_class.table_name => { item_type: reflection.klass.base_class.name })
+    end
+
+    #: (untyped) -> VersionAssociationCandidateScope
+    def child_candidate_scope(version_class)
+      VersionAssociationCandidateScope.new(
+        version_class,
+        @start_at
       )
-      relation.distinct.pluck(version_class.arel_table[:item_id])
     end
 
-    #: (untyped, Array[untyped], untyped, String) -> Array[untyped]
+    #: (untyped, Array[untyped], untyped, String) -> Hash[String, Array[untyped]]
     def live_child_ids(owner_class, owner_ids, reflection, foreign_key)
       relation = reflection.klass.base_class.unscoped.where(foreign_key => owner_ids)
       if reflection.options[:as]
         relation = relation.where(reflection.type => parent_types(owner_class))
       end
-      relation.pluck(reflection.klass.primary_key)
+      group_ids_by_owner(relation.pluck(foreign_key, reflection.klass.primary_key))
     end
 
     #: (untyped, untyped) -> untyped
@@ -133,12 +154,28 @@ module PaperTrailDiff
       group.fetch(:ids) << id unless group.fetch(:ids).include?(id)
     end
 
-    #: (untyped, Array[untyped]) -> Hash[String, Hash[Symbol, untyped]]
-    def group_for(model_class, ids)
+    #: (untyped, Array[untyped], ?owners: Hash[String, Array[untyped]]?) -> Hash[String, Hash[Symbol, untyped]]
+    def group_for(model_class, ids, owners: nil)
       unique = ids.compact.uniq
       return {} if unique.empty?
 
-      { model_class.name.to_s => { model: model_class, ids: unique } }
+      group = { model: model_class, ids: unique } #: Hash[Symbol, untyped]
+      group[:owners] = owners if owners
+      { model_class.name.to_s => group }
+    end
+
+    #: (Array[Array[untyped]]) -> Hash[String, Array[untyped]]
+    def group_ids_by_owner(pairs)
+      grouped = {} #: Hash[String, Array[untyped]]
+      pairs.each_with_object(grouped) do |(owner_id, child_id), result|
+        ids = result[owner_id.to_s] ||= []
+        ids << child_id unless ids.include?(child_id)
+      end
+    end
+
+    #: (Hash[String, Array[untyped]], Hash[String, Array[untyped]]) -> Hash[String, Array[untyped]]
+    def merge_owners(left, right)
+      left.merge(right) { |_owner, first, second| first | second }
     end
 
     #: (untyped) -> String?

data/lib/paper_trail_diff/prepared_history.rb

@@ -43,6 +43,11 @@ module PaperTrailDiff
       @habtm[edge_key(owner_class, reflection)] = memberships.transform_keys(&:to_s)
     end
 
+    #: (untyped, untyped, untyped) -> [Hash[untyped, untyped], Hash[untyped, untyped]]?
+    def record_transition(model_class, id, version)
+      @records.transition(model_class, id, version)
+    end
+
     #: (untyped, untyped, untyped, habtm_boundary: untyped) -> [bool, Array[untyped]]
     def resolve(record, reflection, boundary, habtm_boundary:)
       return [false, []] unless supported?(record.class, reflection)
@@ -112,13 +117,20 @@ module PaperTrailDiff
     def child_records(record, reflection, boundary)
       edge(record.class, reflection).values.flat_map do |group|
         model_class = group.fetch(:model)
-        group.fetch(:ids).filter_map do |id|
+        child_ids_for(group, record).filter_map do |id|
           child = @records.record_before(model_class, id, boundary)
           child if child && member_of?(child, reflection, record)
         end
       end
     end
 
+    #: (Hash[Symbol, untyped], untyped) -> Array[untyped]
+    def child_ids_for(group, owner)
+      owners = group[:owners]
+      empty = [] #: Array[untyped]
+      owners ? owners.fetch(owner.id.to_s, empty) : group.fetch(:ids)
+    end
+
     #: (untyped, untyped, untyped, untyped) -> Array[untyped]?
     def habtm_records(record, reflection, boundary, habtm_boundary)
       transaction_id = transaction_id_for(habtm_boundary)
@@ -209,9 +221,7 @@ module PaperTrailDiff
 
     #: (Hash[String, Hash[Symbol, untyped]], Hash[String, Hash[Symbol, untyped]]) -> Hash[String, Hash[Symbol, untyped]]
     def merge_groups(existing, incoming)
-      existing.merge(incoming) do |_name, left, right|
-        left.merge(ids: (left.fetch(:ids) | right.fetch(:ids)))
-      end
+      Support.merge_record_groups(existing, incoming)
     end
   end
 end

data/lib/paper_trail_diff/prepared_history_loader.rb

@@ -4,26 +4,36 @@
 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(record, root_versions:, tree:, traversal:)
+    #: (untyped, root_versions: Array[untyped], tree: AssociationTree, traversal: AssociationTraversal, ?root_ids: Array[untyped], ?start_at: untyped, ?live_records: Array[untyped]) -> void
+    def initialize( # rubocop:disable Metrics/ParameterLists
+      record,
+      root_versions:,
+      tree:,
+      traversal:,
+      root_ids: [record.id],
+      start_at: root_versions.first.created_at,
+      live_records: []
+    )
       @record = record
+      @root_ids = root_ids
       @tree = tree
       @traversal = traversal
-      @records = PreparedRecordIndex.new(root_versions.first)
+      @records = PreparedRecordIndex.new(start_at, live_records: live_records)
       @history = PreparedHistory.new(@records)
-      @edges = PreparedEdgeLoader.new(@records, root_versions)
+      @edges = PreparedEdgeLoader.new(@records, root_versions, start_at: start_at)
       @prepared = {} #: Hash[Array[String], Array[String]]
     end
 
     #: () -> PreparedHistory
     def call
-      load_node(@record.class, [@record.id], @tree, path: '')
+      load_node(@record.class, @root_ids, @tree, path: '')
       @history
     end
 
     private
 
     # @rbs @record: untyped
+    # @rbs @root_ids: Array[untyped]
     # @rbs @tree: AssociationTree
     # @rbs @traversal: AssociationTraversal
     # @rbs @records: PreparedRecordIndex
@@ -33,7 +43,6 @@ module PaperTrailDiff
 
     #: (untyped, Array[untyped], AssociationTree, path: String) -> void
     def load_node(model_class, ids, tree, path:)
-      load_records(model_class, ids)
       @traversal.reflections_for(model_class, tree, path: path).each do |reflection|
         subtree = tree.child(reflection.name)
         next unless subtree
@@ -73,6 +82,7 @@ module PaperTrailDiff
       missing = unprepared_ids(owner_class, owner_ids, reflection)
       return @history.edge(owner_class, reflection) if missing.empty?
 
+      load_records(owner_class, missing) if reflection.macro == :belongs_to
       groups, memberships = @edges.call(owner_class, missing, reflection)
       @history.merge_edge(owner_class, reflection, groups)
       @history.register_habtm(owner_class, reflection, memberships) if memberships
@@ -128,9 +138,7 @@ module PaperTrailDiff
 
     #: (Hash[String, Hash[Symbol, untyped]], Hash[String, Hash[Symbol, untyped]]) -> Hash[String, Hash[Symbol, untyped]]
     def merge_groups(left, right)
-      left.merge(right) do |_name, first, second|
-        first.merge(ids: (first.fetch(:ids) | second.fetch(:ids)))
-      end
+      Support.merge_record_groups(left, right)
     end
   end
 end

data/lib/paper_trail_diff/prepared_record_index.rb

@@ -4,6 +4,9 @@
 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(record)
       @model_class = record.class
@@ -11,23 +14,102 @@ module PaperTrailDiff
       freeze
     end
 
+    #: (untyped, Hash[untyped, untyped]) -> PreparedRecordState
+    def self.from_attributes(model_class, attributes)
+      state = allocate
+      state.send(:initialize_attributes, model_class, attributes)
+      state
+    end
+
     #: () -> untyped
     def instantiate
       @model_class.new(@attributes)
     end
 
-    # @rbs @model_class: untyped
-    # @rbs @attributes: Hash[untyped, untyped]
+    private
+
+    #: (untyped, Hash[untyped, untyped]) -> void
+    def initialize_attributes(model_class, attributes)
+      @model_class = model_class
+      @attributes = Support.immutable_copy(attributes)
+      freeze
+    end
+  end
+
+  # Extracts a version's scalar state without constructing a disposable AR object.
+  class PreparedVersionStateLoader
+    #: () -> void
+    def initialize
+      @serializers = {} #: Hash[untyped, untyped]
+      @attribute_names = {} #: Hash[untyped, Array[String]]
+    end
+
+    #: (untyped) -> PreparedRecordState?
+    def call(version)
+      return unless version.object
+
+      attributes = version.object_deserialized
+      return unless attributes.is_a?(Hash)
+
+      attributes = stringify_keys(attributes)
+      model_class = reification_class(version, attributes)
+      return unless direct_attributes?(model_class, attributes)
+
+      object_attribute_serializer(model_class).deserialize(attributes)
+      PreparedRecordState.from_attributes(model_class, attributes)
+    rescue StandardError
+      nil
+    end
+
+    private
+
+    # @rbs @serializers: Hash[untyped, untyped]
+    # @rbs @attribute_names: Hash[untyped, Array[String]]
+
+    #: (Hash[untyped, untyped]) -> Hash[String, untyped]
+    def stringify_keys(attributes)
+      attributes.to_h { |name, value| [name.to_s, value] }
+    end
+
+    #: (untyped, Hash[String, untyped]) -> untyped
+    def reification_class(version, attributes)
+      model_class = Endpoint.model_class(version)
+      inheritance_value = attributes[model_class.inheritance_column]
+      return model_class if inheritance_value.nil? || inheritance_value.to_s.empty?
+
+      model_class.sti_class_for(inheritance_value)
+    end
+
+    #: (untyped, Hash[String, untyped]) -> bool
+    def direct_attributes?(model_class, attributes)
+      encrypted = model_class.encrypted_attributes if model_class.respond_to?(:encrypted_attributes)
+      return false if encrypted&.any?
+
+      names = @attribute_names[model_class] ||= model_class.attribute_names
+      (attributes.keys - names).empty?
+    end
+
+    #: (untyped) -> untyped
+    def object_attribute_serializer(model_class)
+      paper_trail = Object.const_get(:PaperTrail)
+      serializers = paper_trail.const_get(:AttributeSerializers)
+      serializer_class = serializers.const_get(:ObjectAttribute)
+      @serializers[model_class] ||= serializer_class.new(model_class)
+    end
   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:, live:)
-      @versions = versions.freeze
+    #: (versions: Array[untyped], live: PreparedRecordState?, ?state_loader: PreparedVersionStateLoader) -> void
+    def initialize(versions:, live:, state_loader: PreparedVersionStateLoader.new)
+      @versions = versions.sort_by { |version| Support.chronological_version_key(version) }.freeze
+      @version_positions = @versions.each_with_index.to_h do |version, index|
+        [version.id.to_s, index]
+      end.freeze
       @live = live
+      @state_loader = state_loader
       @states = {} #: Hash[untyped, PreparedRecordState?]
     end
 
@@ -46,10 +128,30 @@ module PaperTrailDiff
       live ? [*version_records, live.instantiate] : version_records
     end
 
+    #: (untyped) -> [Hash[untyped, untyped], Hash[untyped, untyped]]?
+    def transition(version)
+      index = @version_positions[version.id.to_s]
+      return unless index
+
+      before = state_for(versions.fetch(index))
+      after = state_after(index)
+      return unless before && after && before.model_class == after.model_class
+
+      [before.attributes, after.attributes]
+    end
+
     private
 
     # @rbs @live: PreparedRecordState?
+    # @rbs @state_loader: PreparedVersionStateLoader
     # @rbs @states: Hash[untyped, PreparedRecordState?]
+    # @rbs @version_positions: Hash[String, Integer]
+
+    #: (Integer) -> PreparedRecordState?
+    def state_after(index)
+      successor = versions[index + 1]
+      successor ? state_for(successor) : @live
+    end
 
     #: (untyped, untyped) -> bool
     def eligible?(version, boundary)
@@ -67,6 +169,9 @@ module PaperTrailDiff
     def state_for(version)
       return @states[version.id] if @states.key?(version.id)
 
+      prepared = @state_loader.call(version)
+      return @states[version.id] = prepared if prepared
+
       record = version.reify(
         dup: true,
         has_many: false,
@@ -80,9 +185,13 @@ module PaperTrailDiff
 
   # Request-scoped scalar history loaded once per model identity.
   class PreparedRecordIndex
-    #: (untyped) -> void
-    def initialize(start_version)
-      @start_time = start_version.created_at
+    #: (untyped, ?live_records: Array[untyped]) -> void
+    def initialize(start_at, live_records: [])
+      @start_time = start_at
+      @seeded_live_records = live_records.to_h do |record|
+        [identity(record.class, record.id), record]
+      end
+      @state_loader = PreparedVersionStateLoader.new
       @series = {} #: Hash[Array[String], PreparedRecordSeries]
     end
 
@@ -92,7 +201,9 @@ module PaperTrailDiff
       return if missing.empty?
 
       versions = versions_for(model_class, missing).group_by { |version| version.item_id.to_s }
-      live = live_records_for(model_class, missing).to_h { |record| [record.id.to_s, record] }
+      live = available_live_records(model_class, missing).to_h do |record|
+        [record.id.to_s, record]
+      end
       missing.each { |id| add_series(model_class, id, versions, live) }
     end
 
@@ -101,6 +212,11 @@ module PaperTrailDiff
       @series.fetch(identity(model_class, id)).record_before(boundary)
     end
 
+    #: (untyped, untyped, untyped) -> [Hash[untyped, untyped], Hash[untyped, untyped]]?
+    def transition(model_class, id, version)
+      @series[identity(model_class, id)]&.transition(version)
+    end
+
     #: (untyped, Array[untyped]) -> Array[untyped]
     def records_for(model_class, ids)
       ids.flat_map { |id| @series.fetch(identity(model_class, id)).records }
@@ -114,6 +230,8 @@ module PaperTrailDiff
     private
 
     # @rbs @start_time: untyped
+    # @rbs @seeded_live_records: Hash[Array[String], untyped]
+    # @rbs @state_loader: PreparedVersionStateLoader
     # @rbs @series: Hash[Array[String], PreparedRecordSeries]
 
     #: (untyped, untyped) -> Array[String]
@@ -131,7 +249,8 @@ module PaperTrailDiff
       record = live[id.to_s]
       @series[identity(model_class, id)] = PreparedRecordSeries.new(
         versions: versions.fetch(id.to_s, []),
-        live: record && PreparedRecordState.new(record)
+        live: record && PreparedRecordState.new(record),
+        state_loader: @state_loader
       )
     end
 
@@ -143,8 +262,17 @@ module PaperTrailDiff
       ).where('created_at >= ?', @start_time).order(:id).to_a
     end
 
+    #: (untyped, Array[untyped]) -> Array[untyped]
+    def available_live_records(model_class, ids)
+      seeded = ids.filter_map { |id| @seeded_live_records[identity(model_class, id)] }
+      missing = ids.reject { |id| @seeded_live_records.key?(identity(model_class, id)) }
+      seeded.concat(live_records_for(model_class, missing))
+    end
+
     #: (untyped, Array[untyped]) -> Array[untyped]
     def live_records_for(model_class, ids)
+      return [] if ids.empty?
+
       primary_key = model_class.primary_key
       return [] if primary_key.is_a?(Array)