paper_trail_diff 0.14.0 → 0.15.0

data/lib/paper_trail_diff/live_endpoint_batch_loader.rb

@@ -46,9 +46,7 @@ module PaperTrailDiff
     def preload_model_tree(model_class, records, tree)
       reflections = selected_reflections(model_class, tree)
       resolve_polymorphic_targets(records, reflections)
-      batch, individual = reflections.partition do |reflection, _|
-        batch_safe?(records.fetch(0), reflection)
-      end
+      batch, individual = reflections.partition { |reflection, _| BatchPreload.safe?(reflection) }
       preload_batch(records, batch.map { |reflection, _| reflection.name })
       preload_subtrees(records, batch, individually: false)
       preload_subtrees(records, individual, individually: true)
@@ -101,38 +99,6 @@ module PaperTrailDiff
       active_record.const_get(:Associations).const_get(:Preloader)
     end
 
-    # The preloader applies a limit or offset to all owners' records at once,
-    # not to each owner's, so such an association is loaded per record. A
-    # has_one is no exception. Through a part with a limit, an offset or a
-    # has_one cut, the preloader keeps what the part alone would load, while
-    # the through's own query keeps the part's conditions only.
-    #: (untyped, untyped) -> bool
-    def batch_safe?(record, reflection)
-      scope = reflection.scope
-      return false if scope && !scope.arity.zero?
-      return true unless reflection.collection? || reflection.has_one?
-      return false if cut_part?(reflection)
-
-      relation = record.association(reflection.name).scope
-      relation.limit_value.nil? && relation.offset_value.nil?
-    end
-
-    #: (untyped) -> bool
-    def cut_part?(reflection)
-      reflection.collection? &&
-        (ScopeCondition.ranked_parts?(reflection) || through_parts(reflection).any?(&:has_one?))
-    end
-
-    # Every part a through passes, at any depth.
-    #: (untyped) -> Array[untyped]
-    def through_parts(reflection)
-      return [] unless reflection.through_reflection?
-
-      [reflection.through_reflection, reflection.source_reflection].flat_map do |part|
-        [part, *through_parts(part)]
-      end
-    end
-
     #: (Array[untyped], untyped) -> Array[untyped]
     def load_individually(records, reflection)
       unique_records(records.flat_map do |record|

data/lib/paper_trail_diff/nested_comparator.rb

@@ -52,13 +52,17 @@ module PaperTrailDiff
     # Returns the changed paths, or an empty hash when the pair is not two
     # structures this can look inside. An empty result therefore means "nothing
     # to report at this depth", and the caller still has the whole-value change.
+    # Two arrays at the top are one membership change, at the empty path.
     #: () -> nested_changes
     def call
-      from_structure, to_structure = structures
+      from, to = structures
       changes = {} #: nested_changes
-      return changes.freeze unless from_structure && to_structure
-
-      walk(from_structure, to_structure, [], changes)
+      if from.is_a?(Hash) && to.is_a?(Hash)
+        walk(from, to, [], changes)
+      elsif from.is_a?(Array) && to.is_a?(Array)
+        whole = [] #: Array[String]
+        changes[whole.freeze] = change_for(from, to) if from != to
+      end
       changes.freeze
     end
 
@@ -67,26 +71,23 @@ module PaperTrailDiff
     # @rbs @from_value: untyped
     # @rbs @to_value: untyped
 
-    # Both sides have to be readable as a Hash for a nested answer to mean
-    # anything. A column that held text on one side and JSON on the other
-    # changed wholesale, and saying so is the accurate report.
-    #: () -> [Hash[untyped, untyped]?, Hash[untyped, untyped]?]
+    # Both sides have to be readable as the same kind of structure for a
+    # nested answer to mean anything. A column that held text on one side and
+    # JSON on the other changed wholesale, and saying so is the accurate report.
+    #: () -> [untyped, untyped]
     def structures
       [structure(@from_value), structure(@to_value)]
     end
 
-    #: (untyped) -> Hash[untyped, untyped]?
+    # A string is read as JSON; anything else, or JSON that is neither an
+    # object nor an array, is left for #call to decline.
+    #: (untyped) -> untyped
     def structure(value)
-      return value if value.is_a?(Hash)
-      return unless value.is_a?(String)
+      return value unless value.is_a?(String)
 
-      parsed = begin
-        JSON.parse(value)
-      rescue JSON::ParserError
-        nil
-      end
-      # JSON parses objects into plain Hashes, never a subclass.
-      parsed if parsed.instance_of?(Hash)
+      JSON.parse(value)
+    rescue JSON::ParserError
+      nil
     end
 
     #: (Hash[untyped, untyped], Hash[untyped, untyped], Array[String], nested_changes) -> void

data/lib/paper_trail_diff/paper_trail_adapter.rb

@@ -7,16 +7,16 @@ module PaperTrailDiff
   # 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
-    # The only thing a wall-clock window can close on besides a later version.
-    CLOSE_ON_CURRENT = :current
-
-    #: (associations: Array[String | Symbol], ignore: ignore_option, ?reload_live_endpoints: bool, ?allow_expensive: bool) -> void
-    def initialize(associations:, ignore:, reload_live_endpoints: true, allow_expensive: false)
+    # `recorded_changes:` reads what each activity boundary's version recorded.
+    # `allow_approximate:` accepts association paths read with PT-AT.
+    #: (associations: association_option, ignore: ignore_option, ?reload_live_endpoints: bool, ?recorded_changes: bool, ?allow_approximate: bool) -> void
+    def initialize(associations:, ignore:, reload_live_endpoints: true, recorded_changes: false, allow_approximate: false) # rubocop:disable Metrics/MethodLength, Layout/LineLength
       @association_tree = AssociationTree.build(associations)
       @ignore_policy = IgnorePolicy.build(ignore, association_paths: @association_tree.paths)
+      @recorded = (@ignore_policy if recorded_changes)
       @traversal = AssociationTraversal.new(@association_tree)
-      @batch_safety = BatchSafety.new(@traversal, allow_expensive: allow_expensive)
-      @traversal_preparer = TraversalPreparer.new(tree: @association_tree, traversal: @traversal)
+      @traversal_preparer = TraversalPreparer.new(tree: @association_tree, traversal: @traversal,
+                                                  allow_approximate: allow_approximate)
       @live_endpoints = LiveEndpointProvider.new(
         tree: @association_tree, traversal: @traversal, reload: reload_live_endpoints
       )
@@ -53,12 +53,13 @@ module PaperTrailDiff
       count = comparisons.is_a?(Array) ? comparisons.length : 0
       payload = @instrumentation_payload.merge(comparison_count: count)
       Instrumentation.instrument('compare_many', payload) do
-        comparison_batch(comparisons, preparer: method(:prepare_batch_model)).call
+        comparison_batch(comparisons, preparer: @traversal_preparer.method(:call)).call
       end
     end
 
-    #: (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped, ?close_on: Symbol?) -> Array[Step]
-    def timeline(record, from:, to:, within:, version_scope: nil, close_on: nil) # rubocop:disable Metrics/ParameterLists
+    #: (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped) -> Array[Step]
+    def timeline(record, from:, to:, within:, version_scope: nil)
+      Endpoint.validate_root!(record)
       @traversal_preparer.call(record.class, historical: true)
       from, to = default_range(record, from, to, within)
       TimelineBuilder.new(
@@ -67,38 +68,40 @@ module PaperTrailDiff
         to: to,
         within: within,
         version_scope: version_scope,
-        live_endpoint: live_endpoint_for(record, close_on, within),
+        live_endpoint: live_endpoint_for(record, within),
         snapshotter: @timeline_snapshotter
       ).build
     end
 
-    #: (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool, ?group: Symbol?) -> Array[ActivityStep]
-    def activity_timeline(record, from:, to:, within:, version_scope: nil, close_on: nil, snapshots: false, group: nil) # rubocop:disable Metrics/ParameterLists, Layout/LineLength
-      payload = @instrumentation_payload.merge(model_type: record.class.base_class.name.to_s)
+    #: (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped, ?snapshots: bool, ?group: Symbol?) -> Array[ActivityStep]
+    def activity_timeline(record, from:, to:, within:, version_scope: nil, snapshots: false, group: nil) # rubocop:disable Metrics/ParameterLists, Layout/LineLength
+      Endpoint.validate_root!(record)
+      payload = model_payload(record)
       Instrumentation.instrument('activity_timeline', payload) do
         @traversal_preparer.call(record.class, historical: true)
         from, to = default_range(record, from, to, within)
-        live = live_endpoint_for(record, close_on, within)
+        live = live_endpoint_for(record, within)
         steps = activity_builder(
           record, from: from, to: to, within: within, version_scope: version_scope,
-                  live_endpoint: live, snapshots: snapshots, group: group
+                  live_endpoint: live, view: activity_view(true, snapshots, group)
         ).build
         payload[:step_count] = steps.length
         steps
       end
     end
 
-    #: (untyped, from: untyped, to: untyped, within: untyped, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool, ?group: Symbol?) -> Analysis
-    def analyze(record, from:, to:, within:, activity: false, version_scope: nil, close_on: nil, snapshots: false, group: nil) # rubocop:disable Metrics/ParameterLists, Layout/LineLength
-      ActivityGrouping.validate!(group, activity: activity, snapshots: snapshots)
+    #: (untyped, from: untyped, to: untyped, within: untyped, ?activity: bool, ?version_scope: untyped, ?snapshots: bool, ?group: Symbol?) -> Analysis
+    def analyze(record, from:, to:, within:, activity: false, version_scope: nil, snapshots: false, group: nil) # rubocop:disable Metrics/ParameterLists, Layout/LineLength
+      view = activity_view(activity, snapshots, group)
+      Endpoint.validate_root!(record)
       @traversal_preparer.call(record.class, historical: true)
       from, to = default_range(record, from, to, within)
-      live = live_endpoint_for(record, close_on, within)
+      live = live_endpoint_for(record, within)
       if activity
-        return analyze_activity(
+        return activity_builder(
           record, from: from, to: to, within: within, version_scope: version_scope,
-                  live_endpoint: live, snapshots: snapshots, group: group
-        )
+                  live_endpoint: live, view: view
+        ).analyze
       end
 
       TimelineBuilder.new(
@@ -108,40 +111,29 @@ module PaperTrailDiff
     end
 
     # Analyzes many roots over one shared range, preparing their history once.
-    #: (Array[untyped], within: untyped, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool, ?group: Symbol?) -> Hash[identity, Analysis]
-    def analyze_many(records, within:, activity: false, version_scope: nil, close_on: nil, snapshots: false, group: nil) # rubocop:disable Metrics/ParameterLists, Layout/LineLength
-      ActivityGrouping.validate!(group, activity: activity, snapshots: snapshots)
-      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), version_scope: version_scope,
-          close_on_current: close_on_current?(close_on, within) || within.nil?,
-          context_required: activity && !@association_tree.empty?,
-          live_loader: method(:load_batch_endpoints),
-          history_preparer: @historical_store.method(:prepare_batch),
-          analyzer: batched_root_analyzer(activity, within: within, snapshots: snapshots,
-                                                    group: group)
-        ).call
-      end
+    #: (Array[untyped], within: untyped, ?activity: bool, ?version_scope: untyped, ?snapshots: bool, ?group: Symbol?) -> Hash[identity, Analysis]
+    def analyze_many(records, within:, activity: false, version_scope: nil, snapshots: false, group: nil) # rubocop:disable Metrics/ParameterLists, Layout/LineLength
+      analyze_batch(records, within: within, activity: activity, version_scope: version_scope,
+                             view: activity_view(activity, snapshots, group))
     end
 
     # Selects the roots from a relation before running the ordinary batch, so a
     # caller reporting on a population does not have to rediscover which of its
     # members changed. The roots the relation could not reach come back named
     # rather than dropped -- see `PaperTrailDiff.analyze_scope`.
-    #: (untyped, limit: Integer?, within: untyped, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool, ?group: Symbol?, ?historical_filter: untyped, ?max_filter_versions: Integer, ?include_deleted: bool) -> ScopedAnalysis
-    def analyze_scope(scope, limit:, within:, activity: false, version_scope: nil, close_on: nil, snapshots: false, group: nil, historical_filter: nil, max_filter_versions: HistoricalFilter::DEFAULT_VERSION_LIMIT, include_deleted: false) # rubocop:disable Metrics/ParameterLists, Layout/LineLength
-      ActivityGrouping.validate!(group, activity: activity, snapshots: snapshots)
-      check_scope(scope, activity)
+    #: (untyped, limit: Integer?, within: untyped, ?activity: bool, ?version_scope: untyped, ?snapshots: bool, ?group: Symbol?, ?historical_filter: untyped, ?max_filter_versions: Integer, ?include_deleted: bool) -> ScopedAnalysis
+    def analyze_scope(scope, limit:, within:, activity: false, version_scope: nil, snapshots: false, group: nil, historical_filter: nil, max_filter_versions: HistoricalFilter::DEFAULT_VERSION_LIMIT, include_deleted: false) # rubocop:disable Metrics/ParameterLists, Layout/LineLength
+      view = activity_view(activity, snapshots, group)
+      check_scope(scope)
       # @type var options: report_options
-      options = { within: within, activity: activity, version_scope: version_scope,
-                  close_on: close_on, snapshots: snapshots, group: group }
+      options = { within: within, activity: activity, version_scope: version_scope, view: view }
       ScopedAnalysisBuilder.new(
         scope, limit: limit, within: within, historical_filter: historical_filter,
                max_filter_versions: max_filter_versions, include_deleted: include_deleted,
-               analyzer: ->(records) { analyze_many(records, **options, within: within) },
+               analyzer: lambda { |records|
+                 analyze_batch(records, within: within, activity: activity,
+                                        version_scope: version_scope, view: view)
+               },
                deleted_analyzer: lambda { |identities|
                  analyze_deleted(scope.all.model, identities, options)
                },
@@ -153,14 +145,40 @@ module PaperTrailDiff
 
     private
 
-    # Selecting by activity reads association history, so it must be available
-    # before the first selection query rather than once analysis starts.
-    #: (untyped, bool) -> void
-    def check_scope(scope, activity)
+    #: (bool, bool, Symbol?) -> ActivityView
+    def activity_view(activity, snapshots, group)
+      ActivityView.build(activity: activity, snapshots: snapshots, group: group,
+                         recorded: @recorded)
+    end
+
+    #: (untyped) -> Hash[Symbol, untyped]
+    def model_payload(record)
+      @instrumentation_payload.merge(model_type: record.class.base_class.name.to_s)
+    end
+
+    #: (Array[untyped], within: untyped, activity: bool, version_scope: untyped, view: ActivityView) -> Hash[identity, Analysis]
+    def analyze_batch(records, within:, activity:, version_scope:, view:)
+      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), version_scope: version_scope,
+          context_required: activity && !@association_tree.empty?,
+          live_loader: method(:load_batch_endpoints),
+          history_preparer: @historical_store.method(:prepare_batch),
+          analyzer: batched_root_analyzer(activity, within: within, view: view)
+        ).call
+      end
+    end
+
+    # Analysis reads association history, so a request it would refuse is
+    # refused before the first selection query rather than once analysis starts.
+    #: (untyped) -> void
+    def check_scope(scope)
       return unless scope.respond_to?(:all) && scope.respond_to?(:where)
 
-      @batch_safety.call(scope.all.model)
-      @traversal_preparer.call(scope.all.model, historical: true) if activity
+      @traversal_preparer.call(scope.all.model, historical: true)
     end
 
     #: (Array[comparison_input], preparer: untyped) -> ComparisonBatch
@@ -175,27 +193,18 @@ module PaperTrailDiff
       )
     end
 
+    # Refused before the current records load, rather than once analysis starts.
     #: (Array[untyped]) -> Hash[identity, untyped]
     def load_batch_endpoints(records)
-      records.map(&:class).uniq.each { |model| @batch_safety.call(model) }
+      records.map(&:class).uniq.each { |model| @traversal_preparer.call(model, historical: true) }
       @live_endpoints.call(records)
     end
 
-    #: (untyped, historical: bool) -> void
-    def prepare_batch_model(model, historical:)
-      @batch_safety.call(model)
-      @traversal_preparer.call(model, historical: historical)
-    end
-
-    # @rbs @batch_safety: BatchSafety
-
     #: (untyped, Array[Array[String]], Hash[Symbol, untyped]) -> Hash[Array[String], Analysis?]
     def analyze_deleted(model, identities, options)
       within = options.fetch(:within)
-      analyzer = batched_root_analyzer(
-        options.fetch(:activity), within: within, snapshots: options.fetch(:snapshots),
-                                  group: options.fetch(:group)
-      )
+      analyzer = batched_root_analyzer(options.fetch(:activity), within: within,
+                                                                 view: options.fetch(:view))
       DeletedAnalysisBatch.new(
         model, identities: identities, time_range: within.nil? ? nil : TimeRange.new(within),
                version_scope: options.fetch(:version_scope),
@@ -209,6 +218,7 @@ module PaperTrailDiff
     # @rbs @live_endpoints: LiveEndpointProvider
     # @rbs @instrumentation_payload: Hash[Symbol, untyped]
     # @rbs @ignore_policy: IgnorePolicy
+    # @rbs @recorded: IgnorePolicy?
     # @rbs @traversal: AssociationTraversal
     # @rbs @traversal_preparer: TraversalPreparer
     # @rbs @snapshot_pool: SnapshotPool
@@ -217,24 +227,13 @@ module PaperTrailDiff
     # @rbs @timeline_snapshotter: TimelineSnapshotProvider
     # @rbs @activity_snapshotter: ActivitySnapshotProvider
 
-    #: (untyped, from: untyped, to: untyped, within: untyped, version_scope: untyped, live_endpoint: untyped, ?snapshots: bool, ?group: Symbol?) -> Analysis
-    def analyze_activity(record, from:, to:, within:, version_scope:, live_endpoint:, snapshots: false, group: nil) # rubocop:disable Metrics/ParameterLists, Layout/LineLength
-      activity_builder(
-        record, from: from, to: to, within: within, version_scope: version_scope,
-                live_endpoint: live_endpoint, snapshots: snapshots, group: group
-      ).analyze
-    end
-
-    # Association membership is resolved by timestamp, so endpoints sharing one
-    # cannot be told apart and any association change between them is invisible.
-    # The result may still be correct -- nothing associated may have changed --
-    # and the gem cannot tell which, since not seeing the change is the symptom.
-    # So it reports the condition and leaves the judgement to the application.
+    # The result may still be correct -- nothing the path reaches may have
+    # changed -- and the gem cannot tell which, since not seeing the change is
+    # the symptom. So it reports the condition and leaves the judgement to the
+    # application.
     #: (untyped, untyped) -> void
     def notify_ambiguous_association_boundary(from_endpoint, to_endpoint)
-      return if @association_tree.empty?
-      return unless Endpoint.version?(from_endpoint) && Endpoint.version?(to_endpoint)
-      return unless from_endpoint.created_at == to_endpoint.created_at
+      return unless ambiguous_association_boundary?(from_endpoint, to_endpoint)
 
       Instrumentation.notify(
         'ambiguous_association_boundary',
@@ -246,19 +245,19 @@ module PaperTrailDiff
       )
     end
 
-    # A window with nothing recorded after its last change ends at the live
-    # record, which holds the state that change produced -- whether the window
-    # ended a moment ago or long before. `close_on: :current` asked for this
-    # before it was the default and is still accepted. It names what ends a
-    # wall-clock window, so it is meaningless for explicit endpoints.
-    #: (Symbol?, untyped) -> bool
-    def close_on_current?(close_on, within)
-      unless close_on.nil? || close_on == CLOSE_ON_CURRENT
-        raise ConfigurationError, "close_on: must be #{CLOSE_ON_CURRENT.inspect} or nil"
-      end
-      raise ConfigurationError, 'close_on: requires `within`' if close_on && within.nil?
-
-      !within.nil?
+    # Loaded history orders two versions that share a timestamp by id, but
+    # PT-AT places association changes by timestamp alone, so only a path it
+    # reads can lose a change between them. A request the preparer refuses
+    # raises here, before anything is reported.
+    #: (untyped, untyped) -> bool
+    def ambiguous_association_boundary?(from_endpoint, to_endpoint)
+      return false if @association_tree.empty?
+      return false unless Endpoint.version?(from_endpoint) && Endpoint.version?(to_endpoint)
+      return false unless from_endpoint.created_at == to_endpoint.created_at
+
+      model_class = RecordedClass.for(from_endpoint)
+      @traversal_preparer.call(model_class, historical: true)
+      FallbackPaths.any?(@traversal, model_class, approximate: true)
     end
 
     # With neither a window nor endpoints, a range is the record's whole
@@ -271,12 +270,15 @@ module PaperTrailDiff
       [from.nil? ? :first : from, to.nil? ? record : to]
     end
 
+    # A window with nothing recorded after its last change ends at the live
+    # record, which holds the state that change produced -- whether the window
+    # ended a moment ago or long before. Explicit endpoints name their own end.
     # Only a saved row has current state to close on. A destroyed root's own
     # destroy version already terminates its history, and a reified or unsaved
     # instance stands for a state that is not in the table.
-    #: (untyped, Symbol?, untyped) -> untyped
-    def live_endpoint_for(record, close_on, within)
-      return unless close_on_current?(close_on, within)
+    #: (untyped, untyped) -> untyped
+    def live_endpoint_for(record, within)
+      return if within.nil?
       return unless Endpoint.record?(record) && record.persisted?
 
       record
@@ -288,17 +290,20 @@ module PaperTrailDiff
       @timeline_snapshotter = TimelineSnapshotProvider.new(
         @historical_store, live_snapshotter: method(:live_snapshot)
       )
-      @activity_snapshotter = build_activity_snapshotter
+      @activity_snapshotter = ActivitySnapshotProvider.new(
+        store: @historical_store, snapshotter: method(:snapshot_at),
+        refresher: method(:branch_refresher)
+      )
     end
 
-    #: (bool, within: untyped, snapshots: bool, group: Symbol?) -> BatchedRootAnalyzer
-    def batched_root_analyzer(activity, within:, snapshots:, group:)
+    #: (bool, within: untyped, view: ActivityView) -> BatchedRootAnalyzer
+    def batched_root_analyzer(activity, within:, view:)
       BatchedRootAnalyzer.new(
         tree: @association_tree,
         timeline_snapshotter: @timeline_snapshotter,
         activity_snapshotter: @activity_snapshotter,
         preparer: @traversal_preparer.method(:call),
-        activity: activity, within: within, snapshots: snapshots, group: group
+        activity: activity, within: within, view: view
       )
     end
 
@@ -312,27 +317,23 @@ module PaperTrailDiff
       )
     end
 
-    #: () -> ActivitySnapshotProvider
-    def build_activity_snapshotter
-      refresher = BranchSnapshotRefresher.new(
+    # Refreshes one root's snapshots, reading with the history prepared for it.
+    #: (PreparedActivitySnapshots) -> BranchSnapshotRefresher
+    def branch_refresher(snapshots)
+      BranchSnapshotRefresher.new(
         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),
-        record_transition: @historical_store.method(:record_transition),
-        prepared_record_after: @historical_store.method(:record_after)
-      )
-      ActivitySnapshotProvider.new(
-        snapshotter: method(:snapshot_at), refresher: refresher,
-        preparer: @historical_store.method(:prepare),
-        activity_index: @historical_store.method(:activity_index)
+        full_snapshotter: snapshots.method(:call),
+        partial_snapshotter: snapshots.method(:custom),
+        association_reader: snapshots.method(:association_reader),
+        record_transition: snapshots.method(:record_transition),
+        prepared_record_after: snapshots.method(:record_after)
       )
     end
 
-    #: (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped, ?live_endpoint: untyped, ?snapshots: bool, ?group: Symbol?) -> ActivityTimelineBuilder
-    def activity_builder(record, from:, to:, within:, version_scope: nil, live_endpoint: nil, snapshots: false, group: nil) # rubocop:disable Metrics/ParameterLists, Layout/LineLength
+    #: (untyped, from: untyped, to: untyped, within: untyped, version_scope: untyped, live_endpoint: untyped, view: ActivityView) -> ActivityTimelineBuilder
+    def activity_builder(record, from:, to:, within:, version_scope:, live_endpoint:, view:) # rubocop:disable Metrics/ParameterLists
       ActivityTimelineBuilder.new(
         record,
         range: TimelineRange.new(
@@ -341,8 +342,7 @@ module PaperTrailDiff
         ),
         tree: @association_tree,
         snapshotter: @activity_snapshotter,
-        snapshots: snapshots,
-        group: group
+        view: view
       )
     end
 
@@ -356,16 +356,11 @@ module PaperTrailDiff
       snapshot_at(version, version)
     end
 
-    #: (untyped) -> RecordSnapshot?
-    def uncached_historical_snapshot(version)
-      @historical_store.uncached(version, version)
-    end
-
-    #: (untyped, untyped) -> RecordSnapshot?
-    def snapshot_at(root_endpoint, context_endpoint)
+    #: (untyped, untyped, ?history: PreparedHistory?) -> RecordSnapshot?
+    def snapshot_at(root_endpoint, context_endpoint, history: nil)
       return live_snapshot(root_endpoint) if Endpoint.record?(context_endpoint)
 
-      @historical_store.call(root_endpoint, context_endpoint)
+      @historical_store.call(root_endpoint, context_endpoint, history: history)
     end
 
     #: (untyped) -> RecordSnapshot

data/lib/paper_trail_diff/preloaded_endpoint_batch_loader.rb

@@ -2,7 +2,8 @@
 # rbs_inline: enabled
 
 module PaperTrailDiff
-  # Validates and reuses caller-owned live records without issuing association queries.
+  # Validates and reuses caller-owned live records, reading again only the
+  # associations a preload of many records cannot have loaded correctly.
   class PreloadedEndpointBatchLoader
     #: (tree: AssociationTree, traversal: AssociationTraversal) -> void
     def initialize(tree:, traversal:)
@@ -36,6 +37,7 @@ module PaperTrailDiff
         message = "current endpoint association is not preloaded: #{association_path}"
         raise UnloadedAssociationError, message
       end
+      read_alone(association) unless BatchPreload.safe?(reflection)
 
       subtree = tree.child(reflection.name)
       return unless subtree
@@ -44,5 +46,15 @@ module PaperTrailDiff
         validate_record(child, subtree, path: association_path)
       end
     end
+
+    # Preloading many records applies a limit or offset to all of them
+    # together, so what a caller preloaded cannot be trusted: one record keeps
+    # another's share, or none. Such an association is read again for each
+    # record, as reloading reads it.
+    #: (untyped) -> void
+    def read_alone(association)
+      association.reset
+      association.load_target
+    end
   end
 end

data/lib/paper_trail_diff/prepared_activity_index.rb

@@ -189,7 +189,7 @@ module PaperTrailDiff
     # A version without a transaction id names no rows, so it can stay in.
     #: (Array[untyped]) -> Array[untyped]
     def transaction_ids(versions)
-      versions.map { |version| version.transaction_id if version.respond_to?(:transaction_id) }.uniq
+      versions.map { |version| VersionBoundary.transaction_id(version) }.uniq
     end
   end
 end

data/lib/paper_trail_diff/prepared_edge_loader.rb

@@ -111,7 +111,8 @@ module PaperTrailDiff
     #: (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(
+      associations = owner_class.paper_trail.version_association_class
+      VersionTable.joined(associations, version_class).where(
         foreign_key_name: foreign_key,
         foreign_key_id: owner_ids,
         foreign_type: parent_types(owner_class)

data/lib/paper_trail_diff/prepared_history.rb

@@ -146,6 +146,11 @@ module PaperTrailDiff
       owners ? owners.fetch(owner.id.to_s, empty) : group.fetch(:ids)
     end
 
+    # PT-AT records a checkpoint's membership as it is when the checkpoint is
+    # saved, so a tag attached earlier in the checkpoint's own transaction is a
+    # member there, unlike other associations, which a version reads as they
+    # were before its transaction. A member created in that transaction has no
+    # earlier state, so it is read as it was created.
     #: (untyped, untyped, untyped, untyped, bool) -> Array[untyped]?
     def habtm_records(record, reflection, boundary, habtm_boundary, ranked)
       transaction_id = transaction_id_for(habtm_boundary)
@@ -155,7 +160,10 @@ module PaperTrailDiff
       ids = @habtm.fetch(edge_key(record.class, reflection), empty)[transaction_id.to_s]
       return unless ids
 
-      members = ids.filter_map { |id| @records.record_before(reflection.klass, id, boundary) }
+      members = ids.filter_map do |id|
+        @records.record_before(reflection.klass, id, boundary) ||
+          @records.record_created_in(reflection.klass, id, habtm_boundary)
+      end
       @conditions.select(reflection, members, ranked: ranked)
     end
 

data/lib/paper_trail_diff/prepared_history_loader.rb

@@ -21,6 +21,7 @@ module PaperTrailDiff
       @root_versions = root_versions
       @tree = tree
       @traversal = traversal
+      start_at = VersionBoundary.transaction_start(root_versions, start_at)
       @records = PreparedRecordIndex.new(start_at, end_at: end_at, live_records: live_records)
       @activity = PreparedActivityIndex.new(
         @records, root_versions, start_at: start_at, end_at: end_at || root_versions.last.created_at