paper_trail_diff 0.10.0 → 0.12.0

data/lib/paper_trail_diff/paper_trail_adapter.rb

@@ -68,8 +68,8 @@ module PaperTrailDiff
       ).build
     end
 
-    #: (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool) -> Array[ActivityStep]
-    def activity_timeline(record, from:, to:, within:, version_scope: nil, close_on: nil, snapshots: false) # rubocop:disable Metrics/ParameterLists, Layout/LineLength
+    #: (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)
       Instrumentation.instrument('activity_timeline', payload) do
         @traversal_preparer.call(record.class, historical: true)
@@ -77,21 +77,21 @@ module PaperTrailDiff
         reject_live_habtm_activity!(record.class) if Endpoint.record?(to) || live
         steps = activity_builder(
           record, from: from, to: to, within: within, version_scope: version_scope,
-                  live_endpoint: live, snapshots: snapshots
+                  live_endpoint: live, snapshots: snapshots, group: 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) -> Analysis
-    def analyze(record, from:, to:, within:, activity: false, version_scope: nil, close_on: nil, snapshots: false) # rubocop:disable Metrics/ParameterLists, Layout/LineLength
+    #: (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
       @traversal_preparer.call(record.class, historical: true)
       live = live_endpoint_for(record, close_on, within)
       if activity
         return analyze_activity(
           record, from: from, to: to, within: within, version_scope: version_scope,
-                  live_endpoint: live, snapshots: snapshots
+                  live_endpoint: live, snapshots: snapshots, group: group
         )
       end
 
@@ -119,6 +119,24 @@ module PaperTrailDiff
       end
     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?) -> ScopedAnalysis
+    def analyze_scope(scope, limit:, within:, activity: false, version_scope: nil, close_on: nil) # rubocop:disable Metrics/ParameterLists
+      raise ConfigurationError, 'limit: is required when selecting roots by scope' if limit.nil?
+
+      selection = ScopedRootSelection.new(
+        scope, time_range: within.nil? ? nil : TimeRange.new(within), limit: limit
+      ).call
+      ScopedAnalysis.new(
+        analyses: analyze_many(selection.records, within: within, activity: activity,
+                                                  version_scope: version_scope, close_on: close_on),
+        unreachable: selection.unreachable
+      )
+    end
+
     private
 
     # @rbs @association_tree: AssociationTree
@@ -133,12 +151,12 @@ 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) -> Analysis
-    def analyze_activity(record, from:, to:, within:, version_scope:, live_endpoint:, snapshots: false) # rubocop:disable Metrics/ParameterLists, Layout/LineLength
+    #: (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
       reject_live_habtm_activity!(record.class) if live_endpoint
       activity_builder(
         record, from: from, to: to, within: within, version_scope: version_scope,
-                live_endpoint: live_endpoint, snapshots: snapshots
+                live_endpoint: live_endpoint, snapshots: snapshots, group: group
       ).analyze
     end
 
@@ -234,8 +252,8 @@ module PaperTrailDiff
       )
     end
 
-    #: (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped, ?live_endpoint: untyped, ?snapshots: bool) -> ActivityTimelineBuilder
-    def activity_builder(record, from:, to:, within:, version_scope: nil, live_endpoint: nil, snapshots: false) # rubocop:disable Metrics/ParameterLists, Layout/LineLength
+    #: (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
       ActivityTimelineBuilder.new(
         record,
         range: TimelineRange.new(
@@ -244,7 +262,8 @@ module PaperTrailDiff
         ),
         tree: @association_tree,
         snapshotter: @activity_snapshotter,
-        snapshots: snapshots
+        snapshots: snapshots,
+        group: group
       )
     end
 

data/lib/paper_trail_diff/prepared_history_loader.rb

@@ -129,7 +129,7 @@ module PaperTrailDiff
 
     #: (untyped) -> bool
     def versioned?(model_class)
-      model_class.respond_to?(:paper_trail)
+      Support.versioned?(model_class)
     end
 
     #: (untyped, untyped) -> Array[String]

data/lib/paper_trail_diff/scoped_analysis.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # What the relation form of `analyze_many` returns: the analyses, plus the
+  # roots the relation could not reach.
+  #
+  # `to_ary` is defined so the pair destructures, which keeps the common case
+  # reading like the plain Hash the record form returns:
+  #
+  #   analyses, unreachable = PaperTrailDiff.analyze_many(scope: ..., limit: 500)
+  #
+  # It deliberately does not pretend to be a Hash beyond that. Somebody
+  # iterating this object should have to decide which half they meant.
+  class ScopedAnalysis
+    attr_reader :analyses #: Hash[Array[String], Analysis]
+    attr_reader :unreachable #: Array[Array[String]]
+
+    #: (analyses: Hash[Array[String], Analysis], unreachable: Array[Array[String]]) -> void
+    def initialize(analyses:, unreachable:)
+      @analyses = analyses
+      @unreachable = Support.immutable_copy(unreachable)
+      freeze
+    end
+
+    #: () -> [Hash[Array[String], Analysis], Array[Array[String]]]
+    def to_ary
+      [analyses, unreachable]
+    end
+  end
+end

data/lib/paper_trail_diff/scoped_root_selection.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # Chooses the roots a batch will analyze from a relation instead of from an
+  # array the caller assembled, so a reporting page does not reimplement the
+  # root selection this gem already performs.
+  #
+  # Two populations are deliberately kept apart, because conflating them would
+  # make the report wrong in a way nothing announces:
+  #
+  # - A root whose live row does not satisfy the relation is filtered out. That
+  #   is what the caller asked for, and it needs no reporting.
+  # - A root whose live row is gone cannot be filtered at all. The relation's
+  #   conditions read the live table, and a destroyed root has nothing there to
+  #   read -- even though its history is intact, and the state it held when it
+  #   was destroyed may well have satisfied those conditions. Reifying every
+  #   candidate to find out would cost the batched query plan this class exists
+  #   to provide.
+  #
+  # So the second population is returned by name rather than dropped. A caller
+  # that does not care can ignore it; one auditing deletions is told where to
+  # look instead of silently coming up short.
+  #
+  # Note that a relation filters on current state, not on state during the
+  # window. `where(status: 'published')` selects what is published now, which is
+  # not the same set as what was published while the window was open.
+  class ScopedRootSelection
+    # A plain class rather than Data.define, which arrived in Ruby 3.2 while this
+    # gem supports 3.1.
+    class Result
+      attr_reader :records #: Array[untyped]
+      attr_reader :unreachable #: Array[Array[String]]
+
+      #: (records: Array[untyped], unreachable: Array[Array[String]]) -> void
+      def initialize(records:, unreachable:)
+        @records = records
+        @unreachable = unreachable
+        freeze
+      end
+    end
+
+    #: (untyped, time_range: TimeRange?, limit: Integer) -> void
+    def initialize(scope, time_range:, limit:)
+      @scope = normalize_scope(scope)
+      @time_range = time_range
+      @limit = validate_limit(limit)
+    end
+
+    #: () -> Result
+    def call
+      candidates = versioned_ids
+      return Result.new(records: [], unreachable: []) if candidates.empty?
+
+      live = live_ids(candidates)
+      Result.new(
+        records: selected_records(live),
+        unreachable: (candidates - live).map { |id| identity(id) }.freeze
+      )
+    end
+
+    private
+
+    # @rbs @scope: untyped
+    # @rbs @time_range: TimeRange?
+    # @rbs @limit: Integer
+
+    # Accepts a model class as readily as a relation: `Article` and
+    # `Article.where(...)` both name a population, and `all` is what makes them
+    # the same kind of thing.
+    #: (untyped) -> untyped
+    def normalize_scope(scope)
+      unless scope.respond_to?(:all) && scope.respond_to?(:where)
+        raise ConfigurationError, 'scope: must be an ActiveRecord relation or model class'
+      end
+
+      relation = scope.all
+      return relation if Support.versioned?(relation.model)
+
+      raise UnversionedAssociationError,
+            "scope: #{relation.model.name} is not versioned, so it has no history to select from"
+    end
+
+    #: (Integer) -> Integer
+    def validate_limit(limit)
+      return limit if limit.is_a?(Integer) && limit.positive?
+
+      raise ConfigurationError, 'limit: must be a positive Integer'
+    end
+
+    # Every root whose history moved inside the window, destroyed ones included.
+    # This is the gem's own notion of "which roots changed", answered from the
+    # version table alone so that it does not depend on rows still existing.
+    #: () -> Array[String]
+    def versioned_ids
+      relation = version_class.where(item_type: item_type)
+      range = @time_range
+      relation = range.scope(relation) if range
+      relation.distinct.pluck(:item_id).map(&:to_s).uniq
+    end
+
+    # Which of those candidates still have a row, asked without the relation's
+    # conditions so that "filtered out" and "no longer exists" stay separable.
+    #: (Array[String]) -> Array[String]
+    def live_ids(candidates)
+      base_class.unscoped.where(primary_key => candidates).pluck(primary_key).map(&:to_s)
+    end
+
+    # Loading one past the limit is what turns an oversized page into an error
+    # rather than a silently truncated report.
+    #: (Array[String]) -> Array[untyped]
+    def selected_records(live)
+      return [] if live.empty?
+
+      records = @scope.where(primary_key => live).limit(@limit + 1).to_a
+      return records.freeze unless records.length > @limit
+
+      raise BatchLimitExceededError,
+            "scope: selected more than #{@limit} roots; narrow the window or the " \
+            'relation, or raise limit: to the page size you intend to analyze'
+    end
+
+    #: (String) -> Array[String]
+    def identity(id)
+      [item_type, id].freeze
+    end
+
+    #: () -> String
+    def item_type
+      base_class.name.to_s
+    end
+
+    #: () -> untyped
+    def base_class
+      @scope.model.base_class
+    end
+
+    #: () -> untyped
+    def primary_key
+      @scope.model.primary_key
+    end
+
+    #: () -> untyped
+    def version_class
+      @scope.model.paper_trail.version_class
+    end
+  end
+end

data/lib/paper_trail_diff/support.rb

@@ -81,6 +81,19 @@ module PaperTrailDiff
       versions.each_cons(2).find { |left, right| left.created_at == right.created_at }
     end
 
+    # Whether a model records history at all.
+    #
+    # PaperTrail defines `paper_trail` on every ActiveRecord model, so asking
+    # whether a class responds to it says nothing -- it is true for models that
+    # never called `has_paper_trail`, and reading history from one of those fails
+    # at the version class rather than at the question. Only configured options
+    # distinguish the two, which is why this lives in one place: the predicate is
+    # easy to write in a form that looks right and always answers true.
+    #: (untyped) -> bool
+    def versioned?(model_class)
+      model_class.respond_to?(:paper_trail_options) && !model_class.paper_trail_options.nil?
+    end
+
     #: (untyped) -> bool
     def sequential_id?(id)
       id.is_a?(Integer) || id.to_s.match?(/\A\d+\z/)

data/lib/paper_trail_diff/time_activity_timeline_builder.rb

@@ -4,9 +4,15 @@
 module PaperTrailDiff
   # Builds activity views for mutations selected by a wall-clock range.
   class TimeActivityTimelineBuilder
-    #: (untyped, range: TimelineRange, tree: AssociationTree, snapshotter: untyped, ?snapshots: bool) -> void
-    def initialize(record, range:, tree:, snapshotter:, snapshots: false)
+    include ActivityGrouping
+
+    #: (untyped, range: TimelineRange, tree: AssociationTree, snapshotter: untyped, ?snapshots: bool, ?group: Symbol?) -> void
+    def initialize(record, range:, tree:, snapshotter:, snapshots: false, group: nil) # rubocop:disable Metrics/ParameterLists
       @snapshots = snapshots
+      @group = group
+      # Merging a group compares its outer states, so the snapshots must survive
+      # the build even when the caller did not ask to keep them.
+      @retain = snapshots || grouping?
       @record = record
       @range = range
       @tree = tree
@@ -92,15 +98,14 @@ module PaperTrailDiff
         events,
         @snapshotter,
         include_step: ->(event) { @range.include?(event.version) },
-        snapshots: @snapshots
+        snapshots: @retain
       ).call
     end
 
     #: (ActivityHistory, ActivityStep?) -> Array[ActivityStep]
     def activity_steps(history, closing)
-      return history.steps unless closing
-
-      (history.steps + [closing]).freeze
+      steps = closing ? history.steps + [closing] : history.steps
+      group_steps(steps).freeze
     end
 
     # Root versions inside the window that the plan does not report are context
@@ -136,7 +141,7 @@ module PaperTrailDiff
         from_boundary: ActivityBoundary.from_version(version),
         to_boundary: ActivityBoundary.destroyed(version),
         from_snapshot: history.root_snapshots[ActivityRootSteps.version_key(version)],
-        to_snapshot: nil, retain: @snapshots
+        to_snapshot: nil, retain: @retain
       )
     end
 
@@ -151,7 +156,7 @@ module PaperTrailDiff
       ActivityStep.between(
         from_boundary: previous,
         to_boundary: ActivityBoundary.current(record, captured_at: captured_at),
-        from_snapshot: history.last_snapshot, to_snapshot: snapshot, retain: @snapshots
+        from_snapshot: history.last_snapshot, to_snapshot: snapshot, retain: @retain
       )
     end
 

data/lib/paper_trail_diff/traversal_preparer.rb

@@ -46,7 +46,7 @@ module PaperTrailDiff
 
     #: (untyped) -> bool
     def versioned?(model_class)
-      model_class.respond_to?(:paper_trail_options) && !model_class.paper_trail_options.nil?
+      Support.versioned?(model_class)
     end
 
     #: () -> void

data/lib/paper_trail_diff/value_objects.rb

@@ -20,6 +20,72 @@ module PaperTrailDiff
     end
   end
 
+  # A change to an array inside a value the database stores whole, reported by
+  # membership rather than by position.
+  #
+  # Position would be the obvious thing to report and the wrong one: elements
+  # here carry no identity, so inserting at the front makes every later index
+  # look changed, and one insertion is described as several edits. Membership is
+  # answerable without claiming any pairing -- "gained \"saturn v\"" is true
+  # whether the array is a set, a queue, or a ranked list.
+  #
+  # That leaves one case membership cannot see, so it is named rather than
+  # hidden: the same elements in a different order. `reordered?` says so.
+  #
+  # An element that is itself a Hash or Array is reported whole. Saying which
+  # field of which object changed would require pairing before-elements with
+  # after-elements, and nothing in the value licenses that pairing.
+  class ArrayChange
+    attr_reader :from #: Array[untyped]
+    attr_reader :to #: Array[untyped]
+    attr_reader :added #: Array[untyped]
+    attr_reader :removed #: Array[untyped]
+
+    #: (from: Array[untyped], to: Array[untyped]) -> void
+    def initialize(from:, to:)
+      @from = Support.immutable_copy(from)
+      @to = Support.immutable_copy(to)
+      @added = Support.immutable_copy(ArrayChange.surplus(to, from))
+      @removed = Support.immutable_copy(ArrayChange.surplus(from, to))
+      freeze
+    end
+
+    # Elements of `left` with no counterpart left in `right`, matching by value
+    # and respecting duplicates, so ["a", "a"] -> ["a"] reports one removal
+    # rather than none.
+    #: (Array[untyped], Array[untyped]) -> Array[untyped]
+    def self.surplus(left, right)
+      pool = right.dup
+      left.reject do |item|
+        index = pool.index(item)
+        index ? pool.delete_at(index) || true : false
+      end
+    end
+
+    # Same elements, different sequence. Only meaningful for a change that was
+    # recorded at all, which this only is when the two sides differ.
+    #: () -> bool
+    def reordered?
+      added.empty? && removed.empty?
+    end
+
+    #: () -> bool
+    def empty?
+      from == to
+    end
+
+    #: () -> Hash[Symbol, untyped]
+    def to_h
+      {
+        from: Support.serialize(from),
+        to: Support.serialize(to),
+        added: Support.serialize(added),
+        removed: Support.serialize(removed),
+        reordered: reordered?
+      }
+    end
+  end
+
   # Attribute and nested-association changes for a record whose identity did not change.
   class RecordChange
     attr_reader :record #: RecordReference

data/lib/paper_trail_diff/version.rb

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

data/lib/paper_trail_diff.rb

@@ -24,6 +24,7 @@ require_relative 'paper_trail_diff/snapshot_traversal'
 require_relative 'paper_trail_diff/association_diff_traversal'
 require_relative 'paper_trail_diff/traversal'
 require_relative 'paper_trail_diff/collection_comparator'
+require_relative 'paper_trail_diff/nested_comparator'
 require_relative 'paper_trail_diff/engine'
 require_relative 'paper_trail_diff/historical_association_reifier'
 require_relative 'paper_trail_diff/prepared_record_index'
@@ -59,10 +60,14 @@ require_relative 'paper_trail_diff/activity_event_snapshot_refresher'
 require_relative 'paper_trail_diff/activity_root_snapshot_refresher'
 require_relative 'paper_trail_diff/branch_snapshot_refresher'
 require_relative 'paper_trail_diff/activity_boundary'
+require_relative 'paper_trail_diff/activity_grouping'
+require_relative 'paper_trail_diff/activity_transaction_grouper'
 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/scoped_analysis'
+require_relative 'paper_trail_diff/scoped_root_selection'
 require_relative 'paper_trail_diff/batched_root_analyzer'
 require_relative 'paper_trail_diff/version_range'
 require_relative 'paper_trail_diff/version_sequence_diagnostics'
@@ -87,6 +92,8 @@ require_relative 'paper_trail_diff/paper_trail_adapter'
 #     type attribute_changes = Hash[String, ValueChange]
 #     type association_diff = ToOneAssociationDiff | CollectionAssociationDiff
 #     type association_diffs = Hash[String, association_diff]
+#     type nested_change = ValueChange | ArrayChange
+#     type nested_changes = Hash[Array[String], nested_change]
 #     type association_snapshots = Hash[String, AssociationSnapshot]
 #     type identity = Array[untyped]
 #     type comparison_input = Hash[String | Symbol, untyped]
@@ -181,7 +188,8 @@ module PaperTrailDiff # rubocop:disable Metrics/ModuleLength
       reload_live_endpoints: true,
       version_scope: nil,
       close_on: nil,
-      snapshots: false
+      snapshots: false,
+      group: nil
     )
       PaperTrailAdapter.new(
         associations: associations,
@@ -194,12 +202,13 @@ module PaperTrailDiff # rubocop:disable Metrics/ModuleLength
         within: within,
         version_scope: version_scope,
         close_on: close_on,
+        group: group,
         snapshots: snapshots
       )
     end
 
     # Builds an endpoint diff and root-checkpoint timeline while normalizing each version once.
-    #: (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool) -> Analysis
+    #: (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool, ?group: Symbol?) -> Analysis
     def analyze( # rubocop:disable Metrics/ParameterLists
       record,
       from: nil,
@@ -210,7 +219,8 @@ module PaperTrailDiff # rubocop:disable Metrics/ModuleLength
       activity: false,
       version_scope: nil,
       close_on: nil,
-      snapshots: false
+      snapshots: false,
+      group: nil
     )
       PaperTrailAdapter.new(associations: associations, ignore: ignore).analyze(
         record,
@@ -220,16 +230,25 @@ module PaperTrailDiff # rubocop:disable Metrics/ModuleLength
         activity: activity,
         version_scope: version_scope,
         close_on: close_on,
-        snapshots: snapshots
+        snapshots: snapshots,
+        group: group
       )
     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, ?version_scope: untyped, ?close_on: Symbol?) -> Hash[identity, Analysis]
+    #
+    # Pass `records` to analyze a list you assembled, which returns a Hash keyed
+    # by identity. Pass `scope:` with a `limit:` to have the roots selected for
+    # you from a relation, which returns a `ScopedAnalysis` -- the same Hash,
+    # plus the roots the relation could not reach. See `analyze_scope` for why
+    # that second collection exists.
+    #: (?Array[untyped]?, ?scope: untyped, ?limit: Integer?, ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?) -> (Hash[identity, Analysis] | ScopedAnalysis)
     def analyze_many( # rubocop:disable Metrics/ParameterLists
-      records,
+      records = nil,
+      scope: nil,
+      limit: nil,
       within: nil,
       associations: [],
       ignore: DEFAULT_IGNORED_ATTRIBUTES,
@@ -237,12 +256,57 @@ module PaperTrailDiff # rubocop:disable Metrics/ModuleLength
       version_scope: nil,
       close_on: nil
     )
-      PaperTrailAdapter.new(associations: associations, ignore: ignore).analyze_many(
-        records,
-        within: within,
-        activity: activity,
-        version_scope: version_scope,
-        close_on: close_on
+      adapter = PaperTrailAdapter.new(associations: associations, ignore: ignore)
+      if scope
+        raise ConfigurationError, 'pass either records or scope:, not both' unless records.nil?
+
+        return adapter.analyze_scope(scope, limit: limit, within: within, activity: activity,
+                                            version_scope: version_scope, close_on: close_on)
+      end
+      raise ConfigurationError, 'pass records or scope:' if records.nil?
+
+      adapter.analyze_many(records, within: within, activity: activity,
+                                    version_scope: version_scope, close_on: close_on)
+    end
+
+    # Analyzes every root the relation reaches whose history moved inside the
+    # window, selecting them in a fixed number of queries rather than making the
+    # caller rediscover them.
+    #
+    # `limit:` is required and exceeding it raises. Selection moves into the gem
+    # here, so the bound on how much work a page can ask for has to move with
+    # it, and a truncated audit report is worse than a refused one.
+    #
+    # Returns a `ScopedAnalysis`, which destructures:
+    #
+    #   analyses, unreachable = PaperTrailDiff.analyze_scope(
+    #     Article.where(status: 'published'), within: july, limit: 500
+    #   )
+    #
+    # `unreachable` names roots that changed in the window but have no live row
+    # left. A relation's conditions are evaluated against the live table, so a
+    # destroyed root cannot be tested against them at all -- its history is
+    # intact and the state it held at destruction may well have matched. Those
+    # roots are reported rather than dropped so that a page auditing deletions
+    # is told where to look instead of quietly coming up short.
+    #
+    # Note also that a relation selects on current state, not on state during
+    # the window: `where(status: 'published')` means published *now*, which is a
+    # different set from what was published while the window was open.
+    #: (untyped, limit: Integer?, ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?) -> ScopedAnalysis
+    def analyze_scope( # rubocop:disable Metrics/ParameterLists
+      scope,
+      limit:,
+      within: nil,
+      associations: [],
+      ignore: DEFAULT_IGNORED_ATTRIBUTES,
+      activity: false,
+      version_scope: nil,
+      close_on: nil
+    )
+      PaperTrailAdapter.new(associations: associations, ignore: ignore).analyze_scope(
+        scope, limit: limit, within: within, activity: activity,
+               version_scope: version_scope, close_on: close_on
       )
     end
 
@@ -263,5 +327,32 @@ module PaperTrailDiff # rubocop:disable Metrics/ModuleLength
     def diagnose(from_version, to_version, associations: [])
       HistoryDiagnostics.new(from_version, to_version, associations: associations).call
     end
+
+    # Looks inside an attribute the database stores whole, such as a JSON or
+    # jsonb column, and reports which keys changed.
+    #
+    #   change = diff.attributes.fetch('config')
+    #   PaperTrailDiff.nested_changes(change)
+    #   # => { ['theme'] => <from "dark" to "light">,
+    #   #      ['limits', 'max'] => <from 10 to 20> }
+    #
+    # Accepts the `ValueChange` an attribute diff already produced, or a bare
+    # pair. Returns an empty hash when the pair is not two readable structures,
+    # which is the honest answer: a column that held text on one side and JSON
+    # on the other changed wholesale, and the caller still has that change.
+    #
+    # Paths are arrays because a JSON key may contain a dot. Arrays are reported
+    # whole rather than by index, since their elements carry no identity and a
+    # list that merely shifted would otherwise look changed throughout. A key
+    # that was absent reads as `NestedComparator::ABSENT` rather than nil, which
+    # JSON uses for a present null.
+    #: (untyped, ?untyped) -> nested_changes
+    def nested_changes(change, to_value = nil)
+      # Tested by type rather than by responding to `from`: ActiveSupport gives
+      # String#from, so duck-typing here quietly reads a plain string as a pair.
+      return NestedComparator.call(change.from, change.to) if change.is_a?(ValueChange)
+
+      NestedComparator.call(change, to_value)
+    end
   end
 end

data/sig/generated/paper_trail_diff/activity_boundary.rbs

@@ -19,6 +19,11 @@ module PaperTrailDiff
 
     attr_reader record: RecordReference
 
+    # The transaction the version was written in, when PaperTrail recorded one.
+    # Several versions saved together share it, which is what lets a timeline
+    # report one save as one step rather than as its parts.
+    attr_reader transaction_id: untyped
+
     # : (untyped) -> ActivityBoundary
     def self.from_version: (untyped) -> ActivityBoundary
 
@@ -31,8 +36,14 @@ module PaperTrailDiff
     # : (untyped) -> ActivityBoundary
     def self.destroyed: (untyped) -> ActivityBoundary
 
-    # : (kind: Symbol, version_id: untyped, item_type: untyped, item_id: untyped, recorded_at: untyped, ?event: untyped, ?whodunnit: untyped) -> void
-    def initialize: (kind: Symbol, version_id: untyped, item_type: untyped, item_id: untyped, recorded_at: untyped, ?event: untyped, ?whodunnit: untyped) -> void
+    # A custom version class need not carry the column, and PaperTrail leaves
+    # it nil outside a transaction. Both read as "no transaction here", which
+    # groups with nothing.
+    # : (untyped) -> untyped
+    def self.transaction_id: (untyped) -> untyped
+
+    # : (kind: Symbol, version_id: untyped, item_type: untyped, item_id: untyped, recorded_at: untyped, ?event: untyped, ?whodunnit: untyped, ?transaction_id: untyped) -> void
+    def initialize: (kind: Symbol, version_id: untyped, item_type: untyped, item_id: untyped, recorded_at: untyped, ?event: untyped, ?whodunnit: untyped, ?transaction_id: untyped) -> void
 
     # : () -> bool
     def version?: () -> bool