paper_trail_diff 0.9.0 → 0.11.0

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'
@@ -181,7 +186,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 +200,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 +217,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 +228,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 +254,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 +325,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) -> Hash[Array[String], ValueChange]
+    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

data/sig/generated/paper_trail_diff/activity_grouping.rbs

@@ -0,0 +1,19 @@
+# Generated from lib/paper_trail_diff/activity_grouping.rb with RBS::Inline
+
+module PaperTrailDiff
+  # Shared by the two activity builders. They differ in how they choose
+  # boundaries -- one from an explicit version range, one from a wall-clock
+  # window -- but a transaction has to collapse the same way in both, or the
+  # same history would read differently depending on how it was asked for.
+  module ActivityGrouping
+    private
+
+    # : () -> bool
+    def grouping?: () -> bool
+
+    # Applied last, to finished steps, so grouping sees the same timeline the
+    # caller would otherwise have received.
+    # : (Array[ActivityStep]) -> Array[ActivityStep]
+    def group_steps: (Array[ActivityStep]) -> Array[ActivityStep]
+  end
+end

data/sig/generated/paper_trail_diff/activity_timeline_builder.rbs

@@ -3,8 +3,10 @@
 module PaperTrailDiff
   # Compares adjacent root and selected-descendant activity boundaries.
   class ActivityTimelineBuilder
-    # : (untyped, range: TimelineRange, tree: AssociationTree, snapshotter: untyped, ?snapshots: bool) -> void
-    def initialize: (untyped, range: TimelineRange, tree: AssociationTree, snapshotter: untyped, ?snapshots: bool) -> void
+    include ActivityGrouping
+
+    # : (untyped, range: TimelineRange, tree: AssociationTree, snapshotter: untyped, ?snapshots: bool, ?group: Symbol?) -> void
+    def initialize: (untyped, range: TimelineRange, tree: AssociationTree, snapshotter: untyped, ?snapshots: bool, ?group: Symbol?) -> void
 
     # : () -> Array[ActivityStep]
     def build: () -> Array[ActivityStep]

data/sig/generated/paper_trail_diff/activity_transaction_grouper.rbs

@@ -0,0 +1,54 @@
+# Generated from lib/paper_trail_diff/activity_transaction_grouper.rb with RBS::Inline
+
+module PaperTrailDiff
+  # Reports one saved transaction as one activity step.
+  #
+  # A parent and its children saved together produce a version each, and the
+  # timeline reports the gap between every pair of them. One deliberate action
+  # therefore arrives as several steps, none of which is the thing the person
+  # did.
+  #
+  # A version records the state before its own event. Two things follow.
+  #
+  # The change a step reports was made by the event that *opens* it, so a step
+  # belongs to the transaction of its `from_boundary`, and consecutive steps
+  # sharing one are the parts of a single save. Grouping on the closing boundary
+  # instead would credit each change to whoever made the next one.
+  #
+  # And a child's new value is revealed only by something later -- a further
+  # version of that child, its destroy version, or the live row. Inside a
+  # transaction there is usually none of those yet, so a step can read as empty
+  # while a change was in fact made at that boundary, and the change surfaces
+  # later, folded in with whatever that step carried. Grouping puts it back
+  # together with the save it belongs to.
+  #
+  # Merging compares the group's outer snapshots rather than combining the
+  # diffs between them. A field set and then restored inside one transaction
+  # has not changed, and only a comparison of the endpoints can say so.
+  #
+  # A boundary with no transaction groups with nothing. PaperTrail leaves the
+  # column nil outside a transaction, and a custom version class need not carry
+  # it at all; treating those as one shared transaction would merge unrelated
+  # history into a single step.
+  class ActivityTransactionGrouper
+    # : (Array[ActivityStep], retain: bool) -> void
+    def initialize: (Array[ActivityStep], retain: bool) -> void
+
+    # : () -> Array[ActivityStep]
+    def call: () -> Array[ActivityStep]
+
+    private
+
+    @retain: bool
+
+    @steps: Array[ActivityStep]
+
+    # : (Array[ActivityStep], ActivityStep) -> bool
+    def continues?: (Array[ActivityStep], ActivityStep) -> bool
+
+    # Rebuilt rather than reused even when a group holds one step, so that every
+    # returned step retains its snapshots on the same terms.
+    # : (Array[ActivityStep]) -> ActivityStep
+    def merge: (Array[ActivityStep]) -> ActivityStep
+  end
+end

data/sig/generated/paper_trail_diff/errors.rbs

@@ -41,10 +41,20 @@ module PaperTrailDiff
   class AmbiguousVersionOrderError < Error
   end
 
+  # Raised when a relation selects more roots than the batch was told to analyze.
+  # Truncating instead would hand back a report that is short without saying so.
+  class BatchLimitExceededError < Error
+  end
+
   # Raised when a requested ActiveRecord association does not exist.
   class UnknownAssociationError < Error
   end
 
+  # Raised when a selected association's target is not versioned, so its history
+  # cannot be reconstructed at all.
+  class UnversionedAssociationError < Error
+  end
+
   # Raised when a requested association macro is not supported.
   class UnsupportedAssociationError < Error
   end

data/sig/generated/paper_trail_diff/nested_comparator.rbs

@@ -0,0 +1,68 @@
+# Generated from lib/paper_trail_diff/nested_comparator.rb with RBS::Inline
+
+module PaperTrailDiff
+  # Compares the inside of a value a database column holds whole.
+  #
+  # A JSON or jsonb column reifies to one Hash, so an ordinary attribute diff
+  # can only say that the blob changed. This says which keys changed, leaving
+  # the surrounding diff untouched.
+  #
+  # Three decisions worth knowing about.
+  #
+  # Paths are arrays, not dotted strings. A JSON key may contain a dot -- host
+  # names and locales routinely do -- and joining would make `a.b` ambiguous
+  # between one key and two.
+  #
+  # Arrays are leaves. Their elements carry no identity, so an insertion at the
+  # front makes every later index look changed; reporting "element 2 changed"
+  # would be confidently wrong about a list that merely shifted. The whole array
+  # is reported as one change, which is the same rule the collection comparator
+  # follows for records it cannot identify.
+  #
+  # An absent key is not a null one. `{"a": null}` and `{}` mean different
+  # things in JSON and an audit trail that conflated them would be lying about
+  # one of them, so absence is its own value rather than nil.
+  class NestedComparator
+    # Stands in for a key that was not there at all.
+    ABSENT: untyped
+
+    def inspect: () -> untyped
+
+    def to_s: () -> untyped
+
+    # : (untyped, untyped) -> Hash[Array[String], ValueChange]
+    def self.call: (untyped, untyped) -> Hash[Array[String], ValueChange]
+
+    # : (untyped, untyped) -> void
+    def initialize: (untyped, untyped) -> void
+
+    # 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.
+    # : () -> Hash[Array[String], ValueChange]
+    def call: () -> Hash[Array[String], ValueChange]
+
+    private
+
+    @from_value: untyped
+
+    @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]?]
+    def structures: () -> [ Hash[untyped, untyped]?, Hash[untyped, untyped]? ]
+
+    # : (untyped) -> Hash[untyped, untyped]?
+    def structure: (untyped) -> Hash[untyped, untyped]?
+
+    # : (Hash[untyped, untyped], Hash[untyped, untyped], Array[String], Hash[Array[String], ValueChange]) -> void
+    def walk: (Hash[untyped, untyped], Hash[untyped, untyped], Array[String], Hash[Array[String], ValueChange]) -> void
+
+    # Sorted so a report reads the same twice, and stringified because a hash
+    # loaded from JSON and one built in Ruby can key the same field differently.
+    # : (Hash[untyped, untyped], Hash[untyped, untyped]) -> Array[untyped]
+    def keys: (Hash[untyped, untyped], Hash[untyped, untyped]) -> Array[untyped]
+  end
+end

data/sig/generated/paper_trail_diff/paper_trail_adapter.rbs

@@ -22,16 +22,23 @@ module PaperTrailDiff
     # : (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped, ?close_on: Symbol?) -> Array[Step]
     def timeline: (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped, ?close_on: Symbol?) -> Array[Step]
 
-    # : (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool) -> Array[ActivityStep]
-    def activity_timeline: (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool) -> Array[ActivityStep]
+    # : (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool, ?group: Symbol?) -> Array[ActivityStep]
+    def activity_timeline: (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool, ?group: Symbol?) -> Array[ActivityStep]
 
-    # : (untyped, from: untyped, to: untyped, within: untyped, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool) -> Analysis
-    def analyze: (untyped, from: untyped, to: untyped, within: untyped, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool) -> Analysis
+    # : (untyped, from: untyped, to: untyped, within: untyped, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool, ?group: Symbol?) -> Analysis
+    def analyze: (untyped, from: untyped, to: untyped, within: untyped, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool, ?group: Symbol?) -> Analysis
 
     # Analyzes many roots over one shared range, preparing their history once.
     # : (Array[untyped], within: untyped, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?) -> Hash[identity, Analysis]
     def analyze_many: (Array[untyped], within: untyped, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?) -> Hash[identity, Analysis]
 
+    # 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: (untyped, limit: Integer?, within: untyped, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?) -> ScopedAnalysis
+
     private
 
     @activity_snapshotter: ActivitySnapshotProvider
@@ -56,8 +63,8 @@ module PaperTrailDiff
 
     @traversal_preparer: TraversalPreparer
 
-    # : (untyped, from: untyped, to: untyped, within: untyped, version_scope: untyped, live_endpoint: untyped, ?snapshots: bool) -> Analysis
-    def analyze_activity: (untyped, from: untyped, to: untyped, within: untyped, version_scope: untyped, live_endpoint: untyped, ?snapshots: bool) -> Analysis
+    # : (untyped, from: untyped, to: untyped, within: untyped, version_scope: untyped, live_endpoint: untyped, ?snapshots: bool, ?group: Symbol?) -> Analysis
+    def analyze_activity: (untyped, from: untyped, to: untyped, within: untyped, version_scope: untyped, live_endpoint: untyped, ?snapshots: bool, ?group: Symbol?) -> Analysis
 
     # Association membership is resolved by timestamp, so endpoints sharing one
     # cannot be told apart and any association change between them is invisible.
@@ -89,8 +96,8 @@ module PaperTrailDiff
     # : () -> ActivitySnapshotProvider
     def build_activity_snapshotter: () -> ActivitySnapshotProvider
 
-    # : (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped, ?live_endpoint: untyped, ?snapshots: bool) -> ActivityTimelineBuilder
-    def activity_builder: (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped, ?live_endpoint: untyped, ?snapshots: bool) -> ActivityTimelineBuilder
+    # : (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped, ?live_endpoint: untyped, ?snapshots: bool, ?group: Symbol?) -> ActivityTimelineBuilder
+    def activity_builder: (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped, ?live_endpoint: untyped, ?snapshots: bool, ?group: Symbol?) -> ActivityTimelineBuilder
 
     # : (untyped) -> void
     def reject_live_habtm_activity!: (untyped) -> void

data/sig/generated/paper_trail_diff/scoped_analysis.rbs

@@ -0,0 +1,25 @@
+# Generated from lib/paper_trail_diff/scoped_analysis.rb with RBS::Inline
+
+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: Hash[Array[String], Analysis], unreachable: Array[Array[String]]) -> void
+
+    # : () -> [Hash[Array[String], Analysis], Array[Array[String]]]
+    def to_ary: () -> [ Hash[Array[String], Analysis], Array[Array[String]] ]
+  end
+end

data/sig/generated/paper_trail_diff/scoped_root_selection.rbs

@@ -0,0 +1,93 @@
+# Generated from lib/paper_trail_diff/scoped_root_selection.rb with RBS::Inline
+
+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: Array[untyped], unreachable: Array[Array[String]]) -> void
+    end
+
+    # : (untyped, time_range: TimeRange?, limit: Integer) -> void
+    def initialize: (untyped, time_range: TimeRange?, limit: Integer) -> void
+
+    # : () -> Result
+    def call: () -> Result
+
+    private
+
+    @limit: Integer
+
+    @scope: untyped
+
+    @time_range: TimeRange?
+
+    # 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: (untyped) -> untyped
+
+    # : (Integer) -> Integer
+    def validate_limit: (Integer) -> Integer
+
+    # 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: () -> Array[String]
+
+    # 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: (Array[String]) -> Array[String]
+
+    # 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: (Array[String]) -> Array[untyped]
+
+    # : (String) -> Array[String]
+    def identity: (String) -> Array[String]
+
+    # : () -> String
+    def item_type: () -> String
+
+    # : () -> untyped
+    def base_class: () -> untyped
+
+    # : () -> untyped
+    def primary_key: () -> untyped
+
+    # : () -> untyped
+    def version_class: () -> untyped
+  end
+end

data/sig/generated/paper_trail_diff/support.rbs

@@ -32,6 +32,17 @@ module PaperTrailDiff
     # : (Array[untyped]) -> Array[untyped]?
     def self?.tied_timestamp_pair: (Array[untyped]) -> Array[untyped]?
 
+    # 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 self?.versioned?: (untyped) -> bool
+
     # : (untyped) -> bool
     def self?.sequential_id?: (untyped) -> bool
 

data/sig/generated/paper_trail_diff/time_activity_timeline_builder.rbs

@@ -3,8 +3,10 @@
 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: (untyped, range: TimelineRange, tree: AssociationTree, snapshotter: untyped, ?snapshots: bool) -> void
+    include ActivityGrouping
+
+    # : (untyped, range: TimelineRange, tree: AssociationTree, snapshotter: untyped, ?snapshots: bool, ?group: Symbol?) -> void
+    def initialize: (untyped, range: TimelineRange, tree: AssociationTree, snapshotter: untyped, ?snapshots: bool, ?group: Symbol?) -> void
 
     # : () -> Array[ActivityStep]
     def build: () -> Array[ActivityStep]

data/sig/generated/paper_trail_diff/traversal_preparer.rbs

@@ -16,6 +16,16 @@ module PaperTrailDiff
 
     @tree: AssociationTree
 
+    # A model PaperTrail never versioned has no history to reconstruct, so a
+    # comparison over it can only ever answer "nothing changed" -- which is a
+    # wrong answer rather than an empty one. Live-to-live comparison reads
+    # current state and is unaffected, so this applies to historical work only.
+    # : (untyped) -> void
+    def ensure_versioned_targets!: (untyped) -> void
+
+    # : (untyped) -> bool
+    def versioned?: (untyped) -> bool
+
     # : () -> void
     def ensure_association_tracking!: () -> void
   end