paper_trail_diff 0.4.0 → 0.5.0

data/lib/paper_trail_diff/paper_trail_adapter.rb

@@ -2,13 +2,17 @@
 # rbs_inline: enabled
 
 module PaperTrailDiff
-  # PaperTrail/ActiveRecord boundary that produces plain record snapshots.
-  class PaperTrailAdapter
+  # PaperTrail/ActiveRecord boundary that produces plain record snapshots. It is
+  # deliberately the widest class here: it fronts every public operation and is
+  # the only place allowed to know about both PaperTrail and the pure engine.
+  # Reconstruction logic lives in the collaborators it wires together.
+  class PaperTrailAdapter # rubocop:disable Metrics/ClassLength
     #: (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)
+      @traversal_preparer = TraversalPreparer.new(tree: @association_tree, traversal: @traversal)
       @live_endpoints = LiveEndpointProvider.new(
         tree: @association_tree, traversal: @traversal, reload: reload_live_endpoints
       )
@@ -18,9 +22,7 @@ module PaperTrailDiff
         tree: @association_tree, ignore_policy: @ignore_policy,
         traversal: @traversal, pool: @snapshot_pool
       )
-      @historical_store = build_historical_store
-      @timeline_snapshotter = TimelineSnapshotProvider.new(@historical_store)
-      @activity_snapshotter = build_activity_snapshotter
+      build_snapshotters
     end
 
     #: (untyped, untyped) -> Diff
@@ -40,7 +42,7 @@ module PaperTrailDiff
       Instrumentation.instrument('compare_many', payload) do
         ComparisonBatch.new(
           comparisons,
-          live_loader: @live_endpoints.method(:call), preparer: method(:prepare_traversal!),
+          live_loader: @live_endpoints.method(:call), preparer: @traversal_preparer.method(:call),
           history_preparer: @historical_store.method(:prepare_batch),
           historical_snapshotter: method(:historical_snapshot),
           live_normalizer: method(:normalize_live_snapshot)
@@ -50,7 +52,7 @@ module PaperTrailDiff
 
     #: (untyped, from: untyped, to: untyped, within: untyped) -> Array[Step]
     def timeline(record, from:, to:, within:)
-      prepare_traversal!(record.class, historical: true)
+      @traversal_preparer.call(record.class, historical: true)
       builder = TimelineBuilder.new(
         record,
         from: from,
@@ -65,7 +67,7 @@ module PaperTrailDiff
     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)
+        @traversal_preparer.call(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
@@ -76,11 +78,11 @@ module PaperTrailDiff
     #: (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)
+        @traversal_preparer.call(record.class, historical: true)
         return activity_builder(record, from: from, to: to, within: within).analyze
       end
 
-      prepare_traversal!(record.class, historical: true)
+      @traversal_preparer.call(record.class, historical: true)
       TimelineBuilder.new(
         record,
         from: from,
@@ -90,6 +92,22 @@ module PaperTrailDiff
       ).analyze
     end
 
+    # Analyzes many roots over one shared range, preparing their history once.
+    #: (Array[untyped], within: untyped, ?activity: bool) -> Hash[identity, Analysis]
+    def analyze_many(records, within:, activity: false)
+      count = records.is_a?(Array) ? records.length : 0
+      payload = @instrumentation_payload.merge(comparison_count: count)
+      Instrumentation.instrument('analyze_many', payload) do
+        AnalysisBatch.new(
+          records,
+          time_range: within.nil? ? nil : TimeRange.new(within),
+          live_loader: @live_endpoints.method(:call),
+          history_preparer: @historical_store.method(:prepare_batch),
+          analyzer: batched_root_analyzer(activity)
+        ).call
+      end
+    end
+
     private
 
     # @rbs @association_tree: AssociationTree
@@ -97,19 +115,38 @@ module PaperTrailDiff
     # @rbs @instrumentation_payload: Hash[Symbol, untyped]
     # @rbs @ignore_policy: IgnorePolicy
     # @rbs @traversal: AssociationTraversal
+    # @rbs @traversal_preparer: TraversalPreparer
     # @rbs @snapshot_pool: SnapshotPool
     # @rbs @normalizer: SnapshotNormalizer
     # @rbs @historical_store: HistoricalSnapshotStore
     # @rbs @timeline_snapshotter: TimelineSnapshotProvider
     # @rbs @activity_snapshotter: ActivitySnapshotProvider
 
+    #: () -> void
+    def build_snapshotters
+      @historical_store = build_historical_store
+      @timeline_snapshotter = TimelineSnapshotProvider.new(@historical_store)
+      @activity_snapshotter = build_activity_snapshotter
+    end
+
+    #: (bool) -> BatchedRootAnalyzer
+    def batched_root_analyzer(activity)
+      BatchedRootAnalyzer.new(
+        tree: @association_tree,
+        timeline_snapshotter: @timeline_snapshotter,
+        activity_snapshotter: @activity_snapshotter,
+        preparer: @traversal_preparer.method(:call),
+        activity: activity
+      )
+    end
+
     #: () -> HistoricalSnapshotStore
     def build_historical_store
       HistoricalSnapshotStore.new(
         tree: @association_tree,
         traversal: @traversal,
         normalizer: @normalizer,
-        preparer: method(:prepare_traversal!)
+        preparer: @traversal_preparer.method(:call)
       )
     end
 
@@ -180,30 +217,9 @@ module PaperTrailDiff
 
     #: (untyped) -> RecordSnapshot
     def normalize_live_snapshot(current)
-      prepare_traversal!(current.class, historical: false)
+      @traversal_preparer.call(current.class, historical: false)
       @normalizer.call(current, reifier: LiveAssociationReader.new) ||
         raise(InvalidEndpointError, 'current record endpoint could not be normalized')
     end
-
-    #: (untyped, historical: bool) -> void
-    def prepare_traversal!(model_class, historical:)
-      return if @association_tree.empty?
-
-      ensure_association_tracking! if historical
-      @traversal.validate!(model_class)
-    end
-
-    #: () -> void
-    def ensure_association_tracking!
-      paper_trail = Object.const_get(:PaperTrail) #: untyped
-      config = paper_trail.config #: untyped
-      available = defined?(::PaperTrailAssociationTracking) &&
-                  config.respond_to?(:track_associations?) &&
-                  config.track_associations?
-      return if available
-
-      message = 'association tracking must be loaded and enabled to compare historical associations'
-      raise AssociationTrackingUnavailableError, message
-    end
   end
 end

data/lib/paper_trail_diff/timeline_builder.rb

@@ -4,10 +4,10 @@
 module PaperTrailDiff
   # Selects and compares a chronological slice of a record's version history.
   class TimelineBuilder
-    #: (untyped, from: untyped, to: untyped, snapshotter: untyped, ?within: untyped) -> void
-    def initialize(record, from:, to:, snapshotter:, within: nil)
+    #: (untyped, from: untyped, to: untyped, snapshotter: untyped, ?within: untyped, ?versions: Array[untyped]?) -> void
+    def initialize(record, from:, to:, snapshotter:, within: nil, versions: nil) # rubocop:disable Metrics/ParameterLists
       @record = record
-      @range = TimelineRange.new(record, from: from, to: to, within: within)
+      @range = TimelineRange.new(record, from: from, to: to, within: within, versions: versions)
       @snapshotter = snapshotter
     end
 

data/lib/paper_trail_diff/timeline_range.rb

@@ -10,9 +10,10 @@ module PaperTrailDiff
     attr_reader :to #: untyped
     attr_reader :time_range #: TimeRange?
 
-    #: (untyped, from: untyped, to: untyped, within: untyped) -> void
-    def initialize(record, from:, to:, within:)
+    #: (untyped, from: untyped, to: untyped, within: untyped, ?versions: Array[untyped]?) -> void
+    def initialize(record, from:, to:, within:, versions: nil)
       @record = record
+      @versions = versions&.freeze
       @requested_from = from
       @requested_to = to
       @time_range = build_time_range(within)
@@ -29,8 +30,13 @@ module PaperTrailDiff
       (symbolic?(@requested_from) && @from.nil?) || (symbolic?(@requested_to) && @to.nil?)
     end
 
+    # A batch may have selected these versions already, in which case reselecting
+    # them per record would undo the batching.
     #: (?context_required: bool) -> Array[untyped]
     def select(context_required: false)
+      preselected = @versions
+      return preselected if preselected
+
       range = time_range
       if range
         return TimeVersionRange.new(@record, time_range: range).select(
@@ -61,6 +67,7 @@ module PaperTrailDiff
     private
 
     # @rbs @record: untyped
+    # @rbs @versions: Array[untyped]?
     # @rbs @requested_from: untyped
     # @rbs @requested_to: untyped
     # @rbs @from: untyped

data/lib/paper_trail_diff/traversal_preparer.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # Checks that a model can be traversed before any reconstruction starts, and
+  # that association tracking is actually available when history is involved.
+  class TraversalPreparer
+    #: (tree: AssociationTree, traversal: AssociationTraversal) -> void
+    def initialize(tree:, traversal:)
+      @tree = tree
+      @traversal = traversal
+    end
+
+    #: (untyped, historical: bool) -> void
+    def call(model_class, historical:)
+      return if @tree.empty?
+
+      ensure_association_tracking! if historical
+      @traversal.validate!(model_class)
+    end
+
+    private
+
+    # @rbs @tree: AssociationTree
+    # @rbs @traversal: AssociationTraversal
+
+    #: () -> void
+    def ensure_association_tracking!
+      paper_trail = Object.const_get(:PaperTrail) #: untyped
+      config = paper_trail.config #: untyped
+      available = defined?(::PaperTrailAssociationTracking) &&
+                  config.respond_to?(:track_associations?) &&
+                  config.track_associations?
+      return if available
+
+      message = 'association tracking must be loaded and enabled to compare historical associations'
+      raise AssociationTrackingUnavailableError, message
+    end
+  end
+end

data/lib/paper_trail_diff/version.rb

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

data/lib/paper_trail_diff.rb

@@ -10,6 +10,7 @@ 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/traversal_preparer'
 require_relative 'paper_trail_diff/association_discovery'
 require_relative 'paper_trail_diff/diagnostics'
 require_relative 'paper_trail_diff/collection_identity_index'
@@ -36,7 +37,9 @@ 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/batch_boundary_resolver'
 require_relative 'paper_trail_diff/comparison_batch'
+require_relative 'paper_trail_diff/batched_root_versions'
 require_relative 'paper_trail_diff/snapshot_normalizer'
 require_relative 'paper_trail_diff/historical_snapshot_store'
 require_relative 'paper_trail_diff/timeline_snapshot_provider'
@@ -56,6 +59,8 @@ require_relative 'paper_trail_diff/activity_boundary'
 require_relative 'paper_trail_diff/step'
 require_relative 'paper_trail_diff/analysis'
 require_relative 'paper_trail_diff/activity_root_steps'
+require_relative 'paper_trail_diff/analysis_batch'
+require_relative 'paper_trail_diff/batched_root_analyzer'
 require_relative 'paper_trail_diff/version_range'
 require_relative 'paper_trail_diff/time_range'
 require_relative 'paper_trail_diff/time_version_range'
@@ -90,8 +95,9 @@ require_relative 'paper_trail_diff/paper_trail_adapter'
 #     type traversal_record_path = Array[RecordReference]
 #   end
 
-# Structured version comparison for PaperTrail.
-module PaperTrailDiff
+# Structured version comparison for PaperTrail. Each method is a thin,
+# documented entry point, so this reads as an API listing rather than logic.
+module PaperTrailDiff # rubocop:disable Metrics/ModuleLength
   DEFAULT_IGNORED_ATTRIBUTES = ['updated_at'].freeze
   SUPPORTED_ASSOCIATION_MACROS = %i[
     belongs_to
@@ -154,16 +160,23 @@ module PaperTrailDiff
     end
 
     # Compares adjacent root and selected-descendant activity boundaries.
-    #: (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option) -> Array[ActivityStep]
+    # `reload_live_endpoints:` applies only when `to:` is a current record; the
+    # other range forms never read live state.
+    #: (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?reload_live_endpoints: bool) -> Array[ActivityStep]
     def activity_timeline( # rubocop:disable Metrics/ParameterLists
       record,
       from: nil,
       to: nil,
       within: nil,
       associations: [],
-      ignore: DEFAULT_IGNORED_ATTRIBUTES
+      ignore: DEFAULT_IGNORED_ATTRIBUTES,
+      reload_live_endpoints: true
     )
-      PaperTrailAdapter.new(associations: associations, ignore: ignore).activity_timeline(
+      PaperTrailAdapter.new(
+        associations: associations,
+        ignore: ignore,
+        reload_live_endpoints: reload_live_endpoints
+      ).activity_timeline(
         record,
         from: from,
         to: to,
@@ -191,6 +204,24 @@ module PaperTrailDiff
       )
     end
 
+    # Analyzes many roots over one shared time window, preparing their selected
+    # history once for the batch instead of once per record. Roots with no
+    # versions in the window return an empty `Analysis`.
+    #: (Array[untyped], ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?activity: bool) -> Hash[identity, Analysis]
+    def analyze_many(
+      records,
+      within: nil,
+      associations: [],
+      ignore: DEFAULT_IGNORED_ATTRIBUTES,
+      activity: false
+    )
+      PaperTrailAdapter.new(associations: associations, ignore: ignore).analyze_many(
+        records,
+        within: within,
+        activity: activity
+      )
+    end
+
     # Returns the association macros this release can normalize.
     #: () -> Array[Symbol]
     def supported_association_macros

data/sig/generated/paper_trail_diff/analysis_batch.rbs

@@ -0,0 +1,42 @@
+# Generated from lib/paper_trail_diff/analysis_batch.rb with RBS::Inline
+
+module PaperTrailDiff
+  # Builds one Analysis per root over a shared range, selecting every root's
+  # versions and preparing their association history once for the whole batch
+  # rather than once per root.
+  class AnalysisBatch
+    # : (Array[untyped], time_range: TimeRange?, live_loader: untyped, history_preparer: untyped, analyzer: untyped) -> void
+    def initialize: (Array[untyped], time_range: TimeRange?, live_loader: untyped, history_preparer: untyped, analyzer: untyped) -> void
+
+    # : () -> Hash[identity, Analysis]
+    def call: () -> Hash[identity, Analysis]
+
+    private
+
+    @analyzer: untyped
+
+    @history_preparer: untyped
+
+    @live_loader: untyped
+
+    @records: Array[untyped]
+
+    @time_range: TimeRange?
+
+    # : () -> Array[untyped]
+    def validated_records: () -> Array[untyped]
+
+    # Association history is prepared per model class across every selected root
+    # version, which is the work that would otherwise repeat for each record.
+    # The roots are preloaded first, because preparation reads their current
+    # association state as a fallback and would otherwise walk it one root at a
+    # time.
+    # : (Array[untyped], Hash[Array[String], Array[untyped]]) -> void
+    def prepare: (Array[untyped], Hash[Array[String], Array[untyped]]) -> void
+
+    # A root with no versions in range has nothing to report, which is an empty
+    # result rather than a failed request.
+    # : (untyped, Array[untyped]) -> Analysis
+    def analysis_for: (untyped, Array[untyped]) -> Analysis
+  end
+end

data/sig/generated/paper_trail_diff/batch_boundary_resolver.rbs

@@ -0,0 +1,62 @@
+# Generated from lib/paper_trail_diff/batch_boundary_resolver.rb with RBS::Inline
+
+module PaperTrailDiff
+  # Resolves `:first` and `:last` endpoints for a whole batch in two queries per
+  # model class. Left to the caller this is a per-root lookup, which reintroduces
+  # exactly the queries a batched comparison exists to remove.
+  class BatchBoundaryResolver
+    BOUNDARIES: untyped
+
+    # : (untyped) -> bool
+    def self.symbolic?: (untyped) -> bool
+
+    # : (Array[[untyped, untyped]]) -> void
+    def initialize: (Array[[ untyped, untyped ]]) -> void
+
+    # Returns the pairs with every resolvable symbol replaced. A symbol that
+    # names history the record does not have is left in place, so the caller can
+    # decide what an absent history means rather than being handed nil.
+    # : () -> Array[[untyped, untyped]]
+    def call: () -> Array[[ untyped, untyped ]]
+
+    private
+
+    @pairs: Array[[ untyped, untyped ]]
+
+    # : (untyped) -> bool
+    def symbolic?: (untyped) -> bool
+
+    # : (untyped, untyped, Hash[Array[String], Hash[Symbol, untyped]]) -> untyped
+    def resolve: (untyped, untyped, Hash[Array[String], Hash[Symbol, untyped]]) -> untyped
+
+    # A symbol carries no identity of its own, so the pair's other endpoint has
+    # to say which record is meant.
+    # : (untyped) -> Array[String]?
+    def anchor_identity: (untyped) -> Array[String]?
+
+    # : () -> Hash[Array[String], Hash[Symbol, untyped]]
+    def boundary_index: () -> Hash[Array[String], Hash[Symbol, untyped]]
+
+    # : () -> Array[[untyped, untyped]]
+    def anchors: () -> Array[[ untyped, untyped ]]
+
+    # : (untyped) -> [untyped, untyped]?
+    def anchor: (untyped) -> [ untyped, untyped ]?
+
+    # : (Hash[Array[String], Hash[Symbol, untyped]], untyped, Array[untyped]) -> void
+    def add_model_boundaries: (Hash[Array[String], Hash[Symbol, untyped]], untyped, Array[untyped]) -> void
+
+    # Two grouped queries name each root's outermost versions, and one more
+    # loads them, whatever the size of the batch.
+    # : (untyped, Array[untyped]) -> [Hash[untyped, untyped], Hash[untyped, untyped], Hash[untyped, untyped]]
+    def boundary_versions: (untyped, Array[untyped]) -> [ Hash[untyped, untyped], Hash[untyped, untyped], Hash[untyped, untyped] ]
+
+    # Grouped keys come back with whatever type the column uses, so match on the
+    # string form rather than assuming integers.
+    # : (Hash[untyped, untyped], untyped) -> untyped
+    def boundary_key: (Hash[untyped, untyped], untyped) -> untyped
+
+    # : (untyped, untyped) -> Array[String]
+    def identity_key: (untyped, untyped) -> Array[String]
+  end
+end

data/sig/generated/paper_trail_diff/batched_root_analyzer.rbs

@@ -0,0 +1,28 @@
+# Generated from lib/paper_trail_diff/batched_root_analyzer.rb with RBS::Inline
+
+module PaperTrailDiff
+  # Builds one root's Analysis inside a batch, from versions the batch already
+  # selected and history it already prepared.
+  class BatchedRootAnalyzer
+    # : (tree: AssociationTree, timeline_snapshotter: untyped, activity_snapshotter: untyped, preparer: untyped, activity: bool) -> void
+    def initialize: (tree: AssociationTree, timeline_snapshotter: untyped, activity_snapshotter: untyped, preparer: untyped, activity: bool) -> void
+
+    # : (untyped, Array[untyped]) -> Analysis
+    def call: (untyped, Array[untyped]) -> Analysis
+
+    private
+
+    @activity: bool
+
+    @activity_snapshotter: untyped
+
+    @preparer: untyped
+
+    @timeline_snapshotter: untyped
+
+    @tree: AssociationTree
+
+    # : (untyped, Array[untyped]) -> Analysis
+    def activity_analysis: (untyped, Array[untyped]) -> Analysis
+  end
+end

data/sig/generated/paper_trail_diff/batched_root_versions.rbs

@@ -0,0 +1,62 @@
+# Generated from lib/paper_trail_diff/batched_root_versions.rb with RBS::Inline
+
+module PaperTrailDiff
+  # Selects each root's versions for a batched range in a fixed number of
+  # queries. Only the range forms that mean the same thing for every root are
+  # supported: a shared wall-clock window, or each root's own whole history.
+  class BatchedRootVersions
+    # : (Array[untyped], time_range: TimeRange?) -> void
+    def initialize: (Array[untyped], time_range: TimeRange?) -> void
+
+    # Returns root versions per record identity, in chronological order.
+    # : () -> Hash[Array[String], Array[untyped]]
+    def call: () -> Hash[Array[String], Array[untyped]]
+
+    private
+
+    @records: Array[untyped]
+
+    @time_range: TimeRange?
+
+    # : (untyped, Array[untyped], Hash[Array[String], Array[untyped]]) -> void
+    def select_model: (untyped, Array[untyped], Hash[Array[String], Array[untyped]]) -> void
+
+    # The window's own versions plus, when it has one, the later version needed
+    # to reveal the last mutation inside it. A window closing on the root's own
+    # destruction needs no later version, because none can exist.
+    # : (Array[untyped], untyped) -> Array[untyped]
+    def versions_for: (Array[untyped], untyped) -> Array[untyped]
+
+    # : (Array[untyped]) -> bool
+    def terminal_destroy?: (Array[untyped]) -> bool
+
+    # : (untyped, Array[untyped], TimeRange?) -> Hash[String, Array[untyped]]
+    def grouped_versions: (untyped, Array[untyped], TimeRange?) -> Hash[String, Array[untyped]]
+
+    # One row per root: the earliest version after the window, found without a
+    # window function so the query stays portable.
+    # : (untyped, Array[untyped], TimeRange) -> Hash[String, untyped]
+    def trailing_versions: (untyped, Array[untyped], TimeRange) -> Hash[String, untyped]
+
+    # : (untyped, TimeRange) -> untyped
+    def no_earlier_trailing: (untyped, TimeRange) -> untyped
+
+    # Mirrors the window's own end handling, so a version sitting exactly on an
+    # inclusive boundary stays inside the window instead of masking the trailing
+    # version that follows it.
+    # : (untyped, untyped, TimeRange) -> untyped
+    def preceding: (untyped, untyped, TimeRange) -> untyped
+
+    # : (untyped, TimeRange) -> untyped
+    def after_window: (untyped, TimeRange) -> untyped
+
+    # : (untyped, Array[untyped]) -> untyped
+    def base_scope: (untyped, Array[untyped]) -> untyped
+
+    # : (untyped) -> Array[untyped]
+    def ordered: (untyped) -> Array[untyped]
+
+    # : (untyped, untyped) -> Array[String]
+    def identity: (untyped, untyped) -> Array[String]
+  end
+end

data/sig/generated/paper_trail_diff/comparison_batch.rbs

@@ -23,6 +23,21 @@ module PaperTrailDiff
 
     @preparer: untyped
 
+    # : (Array[[untyped, untyped]]) -> Hash[identity, RecordSnapshot]
+    def prepared_live_snapshots: (Array[[ untyped, untyped ]]) -> Hash[identity, RecordSnapshot]
+
+    # : (untyped) -> bool
+    def symbolic?: (untyped) -> bool
+
+    # A boundary symbol that stayed unresolved means the root has no recorded
+    # history. An absent history is an empty result rather than a failed
+    # request, matching how the timeline APIs answer the same question.
+    # : (Array[[untyped, untyped]], Hash[identity, RecordSnapshot]) -> comparison_results
+    def results: (Array[[ untyped, untyped ]], Hash[identity, RecordSnapshot]) -> comparison_results
+
+    # : (untyped, untyped) -> identity
+    def entry_identity: (untyped, untyped) -> identity
+
     # : (untyped, untyped, Hash[identity, RecordSnapshot]) -> Diff
     def compare: (untyped, untyped, Hash[identity, RecordSnapshot]) -> Diff
 

data/sig/generated/paper_trail_diff/historical_snapshot_store.rbs

@@ -9,7 +9,6 @@ module PaperTrailDiff
     # : (untyped, Array[untyped], ?start_at: untyped, ?end_at: untyped) -> void
     def prepare: (untyped, Array[untyped], ?start_at: untyped, ?end_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
 

data/sig/generated/paper_trail_diff/paper_trail_adapter.rbs

@@ -1,7 +1,10 @@
 # Generated from lib/paper_trail_diff/paper_trail_adapter.rb with RBS::Inline
 
 module PaperTrailDiff
-  # PaperTrail/ActiveRecord boundary that produces plain record snapshots.
+  # PaperTrail/ActiveRecord boundary that produces plain record snapshots. It is
+  # deliberately the widest class here: it fronts every public operation and is
+  # the only place allowed to know about both PaperTrail and the pure engine.
+  # Reconstruction logic lives in the collaborators it wires together.
   class PaperTrailAdapter
     # : (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
@@ -22,6 +25,10 @@ module PaperTrailDiff
     # : (untyped, from: untyped, to: untyped, within: untyped, ?activity: bool) -> Analysis
     def analyze: (untyped, from: untyped, to: untyped, within: untyped, ?activity: bool) -> Analysis
 
+    # Analyzes many roots over one shared range, preparing their history once.
+    # : (Array[untyped], within: untyped, ?activity: bool) -> Hash[identity, Analysis]
+    def analyze_many: (Array[untyped], within: untyped, ?activity: bool) -> Hash[identity, Analysis]
+
     private
 
     @activity_snapshotter: ActivitySnapshotProvider
@@ -44,6 +51,14 @@ module PaperTrailDiff
 
     @traversal: AssociationTraversal
 
+    @traversal_preparer: TraversalPreparer
+
+    # : () -> void
+    def build_snapshotters: () -> void
+
+    # : (bool) -> BatchedRootAnalyzer
+    def batched_root_analyzer: (bool) -> BatchedRootAnalyzer
+
     # : () -> HistoricalSnapshotStore
     def build_historical_store: () -> HistoricalSnapshotStore
 
@@ -73,11 +88,5 @@ module PaperTrailDiff
 
     # : (untyped) -> RecordSnapshot
     def normalize_live_snapshot: (untyped) -> RecordSnapshot
-
-    # : (untyped, historical: bool) -> void
-    def prepare_traversal!: (untyped, historical: bool) -> void
-
-    # : () -> void
-    def ensure_association_tracking!: () -> void
   end
 end

data/sig/generated/paper_trail_diff/timeline_builder.rbs

@@ -3,8 +3,8 @@
 module PaperTrailDiff
   # Selects and compares a chronological slice of a record's version history.
   class TimelineBuilder
-    # : (untyped, from: untyped, to: untyped, snapshotter: untyped, ?within: untyped) -> void
-    def initialize: (untyped, from: untyped, to: untyped, snapshotter: untyped, ?within: untyped) -> void
+    # : (untyped, from: untyped, to: untyped, snapshotter: untyped, ?within: untyped, ?versions: Array[untyped]?) -> void
+    def initialize: (untyped, from: untyped, to: untyped, snapshotter: untyped, ?within: untyped, ?versions: Array[untyped]?) -> void
 
     # : () -> Array[Step]
     def build: () -> Array[Step]

data/sig/generated/paper_trail_diff/timeline_range.rbs

@@ -11,14 +11,16 @@ module PaperTrailDiff
 
     attr_reader time_range: TimeRange?
 
-    # : (untyped, from: untyped, to: untyped, within: untyped) -> void
-    def initialize: (untyped, from: untyped, to: untyped, within: untyped) -> void
+    # : (untyped, from: untyped, to: untyped, within: untyped, ?versions: Array[untyped]?) -> void
+    def initialize: (untyped, from: untyped, to: untyped, within: untyped, ?versions: Array[untyped]?) -> void
 
     # A record with no versions has no first or last boundary to resolve, which
     # is an empty history rather than a bad request.
     # : () -> bool
     def unresolved?: () -> bool
 
+    # A batch may have selected these versions already, in which case reselecting
+    # them per record would undo the batching.
     # : (?context_required: bool) -> Array[untyped]
     def select: (?context_required: bool) -> Array[untyped]
 
@@ -43,6 +45,8 @@ module PaperTrailDiff
 
     @to: untyped
 
+    @versions: Array[untyped]?
+
     # : () -> Array[untyped]
     def empty_versions: () -> Array[untyped]