paper_trail_diff 0.12.0 → 0.13.0

data/lib/paper_trail_diff/timeline_range.rb

@@ -4,18 +4,21 @@
 module PaperTrailDiff
   # Chooses explicit-version or wall-clock selection for one timeline request.
   class TimelineRange
-    BOUNDARY_SYMBOLS = %i[first last].freeze
+    BOUNDARY_SYMBOLS = %i[first].freeze
+    # `:last` once named the last version, whose recorded state is the one
+    # *before* the latest change, so a range ending there silently dropped it.
+    LAST_REMOVED = '`:last` was removed because it left out the latest change: omit `to:` ' \
+                   'to end at current state, or pass a version'
 
     attr_reader :from #: untyped
     attr_reader :to #: untyped
     attr_reader :time_range #: TimeRange?
 
-    #: (untyped, from: untyped, to: untyped, within: untyped, ?versions: Array[untyped]?, ?version_scope: untyped, ?plan: RootVersionPlan?, ?live_endpoint: untyped) -> void
-    def initialize(record, from:, to:, within:, versions: nil, version_scope: nil, plan: nil, live_endpoint: nil) # rubocop:disable Metrics/ParameterLists, Layout/LineLength
+    #: (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped, ?plan: RootVersionPlan?, ?live_endpoint: untyped) -> void
+    def initialize(record, from:, to:, within:, version_scope: nil, plan: nil, live_endpoint: nil) # rubocop:disable Metrics/ParameterLists
       @record = record
       @plan = plan
       @live_endpoint = live_endpoint
-      @versions = (plan ? plan.versions : versions)&.freeze
       @version_scope = version_scope
       @requested_from = from
       @requested_to = to
@@ -26,7 +29,7 @@ module PaperTrailDiff
       freeze
     end
 
-    # A record with no versions has no first or last boundary to resolve, which
+    # A record with no versions has no first boundary to resolve, which
     # is an empty history rather than a bad request.
     #: () -> bool
     def unresolved?
@@ -49,27 +52,7 @@ module PaperTrailDiff
                    live_endpoint: @live_endpoint
         ).select_plan(context_required: context_required)
       end
-      return RootVersionPlan.empty if unresolved?
-
-      VersionRange.new(
-        @record, from: @from, to: @to, version_scope: @version_scope
-      ).select_plan_for_range
-    end
-
-    #: (?context_required: bool) -> Array[untyped]
-    def select(context_required: false)
-      preselected = @versions
-      return preselected if preselected
-
-      range = time_range
-      if range
-        return TimeVersionRange.new(
-          @record, time_range: range, version_scope: @version_scope
-        ).select(context_required: context_required)
-      end
-      return empty_versions if unresolved?
-
-      VersionRange.new(@record, from: @from, to: @to, version_scope: @version_scope).select
+      explicit_plan
     end
 
     #: () -> bool
@@ -91,7 +74,6 @@ module PaperTrailDiff
     private
 
     # @rbs @record: untyped
-    # @rbs @versions: Array[untyped]?
     # @rbs @plan: RootVersionPlan?
     # @rbs @version_scope: untyped
     # @rbs @live_endpoint: untyped
@@ -100,10 +82,17 @@ module PaperTrailDiff
     # @rbs @from: untyped
     # @rbs @to: untyped
 
-    #: () -> Array[untyped]
-    def empty_versions
-      versions = [] #: Array[untyped]
-      versions.freeze
+    #: () -> RootVersionPlan
+    def explicit_plan
+      return RootVersionPlan.empty if unresolved?
+      if Endpoint.record?(@to)
+        return VersionRange.new(@record, from: @from, to: @from, version_scope: @version_scope)
+                           .select_plan_through_current(@to)
+      end
+
+      VersionRange.new(
+        @record, from: @from, to: @to, version_scope: @version_scope
+      ).select_plan_for_range
     end
 
     #: (untyped) -> bool
@@ -111,32 +100,25 @@ module PaperTrailDiff
       boundary.is_a?(Symbol)
     end
 
-    # Resolving `:first` and `:last` here keeps callers from depending on the
+    # Resolving `:first` here keeps callers from depending on the
     # order PaperTrail happens to give its versions association, which a caller
     # is also free to reorder.
     #: (untyped) -> untyped
     def resolve(boundary)
       return boundary unless symbolic?(boundary)
+      raise InvalidTimelineRangeError, LAST_REMOVED if boundary == :last
 
       unless BOUNDARY_SYMBOLS.include?(boundary)
         raise InvalidTimelineRangeError,
-              "unsupported boundary: #{boundary.inspect}; use :first, :last, a version, or a record"
+              "unsupported boundary: #{boundary.inspect}; use :first, a version, or a record"
       end
 
-      boundary == :first ? ordered_versions.first : ordered_versions.last
+      ordered_versions.first
     end
 
     #: () -> untyped
     def ordered_versions
-      versions_relation.reorder(created_at: :asc, id: :asc)
-    end
-
-    #: () -> untyped
-    def versions_relation
-      @record.public_send(@record.class.versions_association_name)
-    rescue NoMethodError => e
-      message = 'record does not expose a PaperTrail version history'
-      raise InvalidTimelineRangeError, message, cause: e
+      Endpoint.versions(@record).reorder(created_at: :asc, id: :asc)
     end
 
     #: (untyped) -> TimeRange?

data/lib/paper_trail_diff/timeline_snapshot_provider.rb

@@ -8,10 +8,15 @@ module PaperTrailDiff
     def initialize(store, live_snapshotter:)
       @store = store
       @live_snapshotter = live_snapshotter
+      @snapshots = {} #: Hash[Array[untyped], RecordSnapshot?]
     end
 
     #: (untyped, Array[untyped]) -> void
     def prepare(record, versions)
+      # Adjacent steps share endpoints. Keep their immutable snapshots for this
+      # root only, including nil create states, and release them before the next
+      # root so batch memory does not retain every reconstructed graph.
+      @snapshots.clear
       @store.prepare(record, versions)
     end
 
@@ -19,9 +24,14 @@ module PaperTrailDiff
     # version, which is the one endpoint no version history can reconstruct.
     #: (untyped) -> RecordSnapshot?
     def call(endpoint)
-      return live_snapshot(endpoint) if Endpoint.record?(endpoint)
+      key = [endpoint.class.name, endpoint.id]
+      return @snapshots[key] if @snapshots.key?(key)
 
-      @store.uncached(endpoint, endpoint)
+      @snapshots[key] = if Endpoint.record?(endpoint)
+                          live_snapshot(endpoint)
+                        else
+                          @store.uncached(endpoint, endpoint)
+                        end
     end
 
     private
@@ -33,5 +43,6 @@ module PaperTrailDiff
 
     # @rbs @store: HistoricalSnapshotStore
     # @rbs @live_snapshotter: untyped
+    # @rbs @snapshots: Hash[Array[untyped], RecordSnapshot?]
   end
 end

data/lib/paper_trail_diff/traversal.rb

@@ -73,7 +73,7 @@ module PaperTrailDiff
     def each_change(&receiver)
       return enum_for(:each_change) unless receiver
 
-      each_entry { |entry| receiver.call(entry) if entry.change? }
+      each_entry { |entry| yield(entry) if entry.change? }
       self
     end
   end

data/lib/paper_trail_diff/version.rb

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

data/lib/paper_trail_diff/version_association_candidate_scope.rb

@@ -32,7 +32,7 @@ module PaperTrailDiff
     def with_connection(&block)
       return @version_class.with_connection(&block) if @version_class.respond_to?(:with_connection)
 
-      block.call(@version_class.connection)
+      yield(@version_class.connection)
     end
 
     #: () -> String

data/lib/paper_trail_diff/version_boundary.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # Places one version relative to another on the recorded timeline.
+  module VersionBoundary
+    module_function
+
+    # Whether `candidate` was recorded at or after `boundary`. Versions sharing
+    # a timestamp are ordered by id, which reflects insertion order only for
+    # sequential ids in one version table; any other tie cannot be ordered, and
+    # guessing would place a change on an arbitrary side of the boundary. A
+    # bare instant has no position among same-time versions, so it keeps them.
+    #: (untyped, untyped) -> bool
+    def at_or_after?(candidate, boundary)
+      tied = candidate.created_at == boundary.created_at
+      return candidate.created_at > boundary.created_at unless tied
+      return true unless version_record?(boundary)
+      return true if same_version?(candidate, boundary)
+
+      unless orderable_tie?(candidate, boundary)
+        raise AmbiguousVersionOrderError, Support.ambiguous_message([boundary, candidate])
+      end
+
+      Support.compare_versions(candidate, boundary) >= 0
+    end
+
+    #: (untyped) -> bool
+    def version_record?(value)
+      value.respond_to?(:id) && value.respond_to?(:item_type) &&
+        value.class.respond_to?(:table_name)
+    end
+    private_class_method :version_record?
+
+    #: (untyped, untyped) -> bool
+    def same_version?(left, right)
+      left.class.table_name == right.class.table_name && left.id.to_s == right.id.to_s
+    end
+    private_class_method :same_version?
+
+    #: (untyped, untyped) -> bool
+    def orderable_tie?(left, right)
+      left.class.table_name == right.class.table_name &&
+        Support.sequential_id?(left.id) && Support.sequential_id?(right.id)
+    end
+    private_class_method :orderable_tie?
+  end
+end

data/lib/paper_trail_diff/version_query.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # Arel conditions shared by the version queries that need one row per item.
+  module VersionQuery
+    module_function
+
+    # Keeps each item's earliest version among those the block also accepts:
+    # no other version of the same item that the block accepts is earlier. A
+    # correlated NOT EXISTS stays portable where window functions are not.
+    #: (untyped) ?{ (untyped) -> untyped } -> untyped
+    def no_earlier_version(table, &block)
+      arel = Object.const_get(:Arel) #: untyped
+      earlier = table.alias('paper_trail_diff_earlier_versions')
+      arel.const_get(:SelectManager).new
+          .from(earlier)
+          .project(arel.sql('1'))
+          .where(earlier_version(table, earlier, &block))
+          .exists
+          .not
+    end
+
+    #: (untyped, untyped) ?{ (untyped) -> untyped } -> untyped
+    def earlier_version(table, earlier)
+      same_item = earlier[:item_type].eq(table[:item_type])
+                                     .and(earlier[:item_id].eq(table[:item_id]))
+                                     .and(earlier[:created_at].lt(table[:created_at]))
+      block_given? ? same_item.and(yield(earlier)) : same_item
+    end
+    private_class_method :earlier_version
+  end
+end

data/lib/paper_trail_diff/version_range.rb

@@ -12,7 +12,7 @@ module PaperTrailDiff
       @version_scope = version_scope
     end
 
-    # Same selection as `select`, but keeping the step pairs a filter implies.
+    # Keep both reconstruction boundaries and the step pairs a filter implies.
     #: () -> RootVersionPlan
     def select_plan_for_range
       relation = validated_relation
@@ -24,7 +24,7 @@ module PaperTrailDiff
 
     #: () -> untyped
     def validated_relation
-      relation = versions_relation
+      relation = Endpoint.versions(@record)
       validate_boundary!(@from, relation, boundary: :from)
       validate_boundary!(@to, relation, boundary: :to)
       if Support.compare_versions(@from, @to).positive?
@@ -34,26 +34,12 @@ module PaperTrailDiff
       relation
     end
 
-    #: () -> Array[untyped]
-    def select
-      relation = versions_relation
+    #: (untyped) -> RootVersionPlan
+    def select_plan_through_current(current)
+      Endpoint.validate_pair!(@record, current)
+      relation = Endpoint.versions(@record)
       validate_boundary!(@from, relation, boundary: :from)
-      validate_boundary!(@to, relation, boundary: :to)
-      if Support.compare_versions(@from, @to).positive?
-        raise InvalidTimelineRangeError, '`from` version must not follow `to` version'
-      end
-
-      select_relation(
-        relation.where(created_at: @from.created_at..@to.created_at),
-        through: @to
-      )
-    end
-
-    #: () -> Array[untyped]
-    def select_through_latest
-      relation = versions_relation
-      validate_boundary!(@from, relation, boundary: :from)
-      select_relation(relation.where(created_at: @from.created_at..))
+      select_plan(relation.where(created_at: @from.created_at..), live_endpoint: current)
     end
 
     private
@@ -63,22 +49,8 @@ module PaperTrailDiff
     # @rbs @to: untyped
     # @rbs @version_scope: untyped
 
-    #: () -> untyped
-    def versions_relation
-      association_name = @record.class.versions_association_name
-      @record.public_send(association_name)
-    rescue NoMethodError => e
-      message = 'record does not expose a PaperTrail version history'
-      raise InvalidTimelineRangeError, message, cause: e
-    end
-
-    #: (untyped, ?through: untyped) -> Array[untyped]
-    def select_relation(relation, through: nil)
-      select_plan(relation, through: through).versions
-    end
-
-    #: (untyped, ?through: untyped) -> RootVersionPlan
-    def select_plan(relation, through: nil)
+    #: (untyped, ?through: untyped, ?live_endpoint: untyped) -> RootVersionPlan
+    def select_plan(relation, through: nil, live_endpoint: nil)
       in_range = ordered(relation.to_a.select do |version|
         next false if Support.compare_versions(@from, version).positive?
         next true unless through
@@ -90,7 +62,7 @@ module PaperTrailDiff
         selected: VersionScopeFilter.new(@version_scope).call(relation, in_range),
         after_range: nil,
         windowed: false,
-        filtered: !@version_scope.nil?
+        filtered: !@version_scope.nil?, live_endpoint: live_endpoint
       ).call
     end
 

data/lib/paper_trail_diff.rb

@@ -5,11 +5,15 @@ require 'paper_trail'
 
 require_relative 'paper_trail_diff/version'
 require_relative 'paper_trail_diff/support'
+require_relative 'paper_trail_diff/version_query'
+require_relative 'paper_trail_diff/stored_time_precision'
+require_relative 'paper_trail_diff/version_boundary'
 require_relative 'paper_trail_diff/instrumentation'
 require_relative 'paper_trail_diff/errors'
 require_relative 'paper_trail_diff/configuration'
 require_relative 'paper_trail_diff/endpoint'
 require_relative 'paper_trail_diff/association_traversal'
+require_relative 'paper_trail_diff/batch_safety'
 require_relative 'paper_trail_diff/traversal_preparer'
 require_relative 'paper_trail_diff/association_discovery'
 require_relative 'paper_trail_diff/diagnostics'
@@ -28,6 +32,10 @@ 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'
+require_relative 'paper_trail_diff/direct_record_state_loader'
+require_relative 'paper_trail_diff/prepared_state_association_reader'
+require_relative 'paper_trail_diff/prepared_snapshot_builder'
+require_relative 'paper_trail_diff/prepared_activity_index'
 require_relative 'paper_trail_diff/prepared_history'
 require_relative 'paper_trail_diff/version_association_candidate_scope'
 require_relative 'paper_trail_diff/prepared_edge_loader'
@@ -66,8 +74,11 @@ 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/deleted_analysis_batch'
 require_relative 'paper_trail_diff/scoped_analysis'
+require_relative 'paper_trail_diff/historical_filter'
 require_relative 'paper_trail_diff/scoped_root_selection'
+require_relative 'paper_trail_diff/scoped_analysis_builder'
 require_relative 'paper_trail_diff/batched_root_analyzer'
 require_relative 'paper_trail_diff/version_range'
 require_relative 'paper_trail_diff/version_sequence_diagnostics'
@@ -98,6 +109,10 @@ require_relative 'paper_trail_diff/paper_trail_adapter'
 #     type identity = Array[untyped]
 #     type comparison_input = Hash[String | Symbol, untyped]
 #     type comparison_results = Hash[identity, Diff]
+#     type report_options = {
+#       within: untyped, activity: bool, version_scope: untyped,
+#       close_on: Symbol?, snapshots: bool, group: Symbol?
+#     }
 #     type ignore_option = Array[String | Symbol] | Hash[String | Symbol, untyped]
 #     type reference_key = :type | :id | "type" | "id"
 #     type traversal_context = :change | :included_state
@@ -117,7 +132,7 @@ module PaperTrailDiff # rubocop:disable Metrics/ModuleLength
     has_and_belongs_to_many
   ].freeze
 
-  class << self
+  class << self # rubocop:disable Metrics/ClassLength
     # Compares net state between explicit PaperTrail-version or current-record endpoints.
     #: (untyped, untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?reload_live_endpoints: bool) -> Diff
     def compare(
@@ -138,21 +153,23 @@ module PaperTrailDiff # rubocop:disable Metrics/ModuleLength
     end
 
     # Compares many independent endpoint pairs while batching current-record loading.
-    #: (Array[comparison_input], ?associations: Array[String | Symbol], ?ignore: ignore_option, ?reload_live_endpoints: bool) -> comparison_results
+    #: (Array[comparison_input], ?associations: Array[String | Symbol], ?ignore: ignore_option, ?reload_live_endpoints: bool, ?allow_expensive: bool) -> comparison_results
     def compare_many(
       comparisons,
       associations: [],
       ignore: DEFAULT_IGNORED_ATTRIBUTES,
-      reload_live_endpoints: true
+      reload_live_endpoints: true,
+      allow_expensive: false
     )
       PaperTrailAdapter.new(
         associations: associations,
         ignore: ignore,
-        reload_live_endpoints: reload_live_endpoints
+        reload_live_endpoints: reload_live_endpoints, allow_expensive: allow_expensive
       ).compare_many(comparisons)
     end
 
-    # Compares every adjacent reconstructed state in an inclusive version range.
+    # Compares every adjacent reconstructed state in an inclusive version range,
+    # by default the record's whole history through its current state.
     #: (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?version_scope: untyped, ?close_on: Symbol?) -> Array[Step]
     def timeline( # rubocop:disable Metrics/ParameterLists
       record,
@@ -175,9 +192,10 @@ module PaperTrailDiff # rubocop:disable Metrics/ModuleLength
     end
 
     # Compares adjacent root and selected-descendant activity boundaries.
-    # `reload_live_endpoints:` applies only when `to:` is a current record; the
-    # other range forms never read live state.
-    #: (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?reload_live_endpoints: bool, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool) -> Array[ActivityStep]
+    # `reload_live_endpoints:` applies whenever the range ends at the current
+    # record: an explicit `to:` record, the default range, or a window with no
+    # later version.
+    #: (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?reload_live_endpoints: bool, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool, ?group: Symbol?) -> Array[ActivityStep]
     def activity_timeline( # rubocop:disable Metrics/ParameterLists
       record,
       from: nil,
@@ -235,47 +253,36 @@ module PaperTrailDiff # rubocop:disable Metrics/ModuleLength
       )
     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`.
-    #
-    # 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)
+    # Analyzes an array of records over one shared range, preparing their
+    # selected history once for the batch instead of once per record, and
+    # returns a frozen Hash keyed by identity. Roots with nothing to report in
+    # the window return an empty `Analysis`. To let a relation choose the
+    # records, use `analyze_scope`.
+    #: (Array[untyped], ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool, ?group: Symbol?, ?allow_expensive: bool) -> Hash[identity, Analysis]
     def analyze_many( # rubocop:disable Metrics/ParameterLists
-      records = nil,
-      scope: nil,
-      limit: nil,
+      records,
       within: nil,
       associations: [],
       ignore: DEFAULT_IGNORED_ATTRIBUTES,
       activity: false,
       version_scope: nil,
-      close_on: nil
+      close_on: nil,
+      snapshots: false,
+      group: nil,
+      allow_expensive: false
     )
-      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)
+      PaperTrailAdapter.new(
+        associations: associations, ignore: ignore, allow_expensive: allow_expensive
+      ).analyze_many(records, within: within, activity: activity, version_scope: version_scope,
+                              close_on: close_on, snapshots: snapshots, group: group)
     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.
+    # window. Joined duplicates are read in bounded pages and analyzed once.
     #
     # `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.
+    # here. The relation's own limit/offset select the live page; this separate
+    # ceiling rejects too many unique roots rather than truncating that page.
     #
     # Returns a `ScopedAnalysis`, which destructures:
     #
@@ -284,7 +291,8 @@ module PaperTrailDiff # rubocop:disable Metrics/ModuleLength
     #   )
     #
     # `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
+    # left, independently of the live page's pagination and safety ceiling.
+    # 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
@@ -293,7 +301,7 @@ module PaperTrailDiff # rubocop:disable Metrics/ModuleLength
     # 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
+    #: (untyped, limit: Integer?, ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool, ?group: Symbol?, ?historical_filter: untyped, ?max_filter_versions: Integer, ?include_deleted: bool, ?allow_expensive: bool) -> ScopedAnalysis
     def analyze_scope( # rubocop:disable Metrics/ParameterLists
       scope,
       limit:,
@@ -302,11 +310,39 @@ module PaperTrailDiff # rubocop:disable Metrics/ModuleLength
       ignore: DEFAULT_IGNORED_ATTRIBUTES,
       activity: false,
       version_scope: nil,
-      close_on: nil
+      close_on: nil,
+      snapshots: false,
+      group: nil,
+      historical_filter: nil,
+      max_filter_versions: HistoricalFilter::DEFAULT_VERSION_LIMIT,
+      include_deleted: false,
+      allow_expensive: false
     )
-      PaperTrailAdapter.new(associations: associations, ignore: ignore).analyze_scope(
+      adapter = PaperTrailAdapter.new(associations: associations, ignore: ignore,
+                                      allow_expensive: allow_expensive)
+      adapter.analyze_scope(
         scope, limit: limit, within: within, activity: activity,
-               version_scope: version_scope, close_on: close_on
+               version_scope: version_scope, close_on: close_on, snapshots: snapshots, group: group,
+               historical_filter: historical_filter, max_filter_versions: max_filter_versions,
+               include_deleted: include_deleted
+      )
+    end
+
+    # Recent root and selected-child activity through the current saved state.
+    # Historical windows remain explicit on analyze_scope; this entry point is
+    # deliberately named for a report through now rather than an as-of query.
+    #: (untyped, since: untyped, limit: Integer, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?snapshots: bool, ?group: Symbol?, ?include_deleted: bool, ?historical_filter: untyped, ?max_filter_versions: Integer, ?allow_expensive: bool) -> ScopedAnalysis
+    def report( # rubocop:disable Metrics/ParameterLists
+      scope, since:, limit:, associations: [], ignore: DEFAULT_IGNORED_ATTRIBUTES,
+      snapshots: false, group: nil, include_deleted: false, historical_filter: nil,
+      max_filter_versions: HistoricalFilter::DEFAULT_VERSION_LIMIT, allow_expensive: false
+    )
+      analyze_scope(
+        scope,
+        within: since..Time.now.utc, limit: limit, associations: associations,
+        ignore: ignore, activity: true, close_on: :current, snapshots: snapshots, group: group,
+        include_deleted: include_deleted, historical_filter: historical_filter,
+        max_filter_versions: max_filter_versions, allow_expensive: allow_expensive
       )
     end
 

data/sig/generated/paper_trail_diff/activity_belongs_to_event_applier.rbs

@@ -29,9 +29,6 @@ module PaperTrailDiff
     # : (Array[RecordSnapshot], untyped, RecordSnapshot?) -> [Array[RecordSnapshot], bool]
     def replace_existing_target: (Array[RecordSnapshot], untyped, RecordSnapshot?) -> [ Array[RecordSnapshot], bool ]
 
-    # : (RecordSnapshot, String, AssociationSnapshot) -> RecordSnapshot
-    def replace_association: (RecordSnapshot, String, AssociationSnapshot) -> RecordSnapshot
-
     # : (untyped, RecordSnapshot?) -> String
     def replacement_type: (untyped, RecordSnapshot?) -> String
 

data/sig/generated/paper_trail_diff/activity_boundary.rbs

@@ -54,8 +54,8 @@ module PaperTrailDiff
     # : () -> bool
     def destroyed?: () -> bool
 
-    # : () -> Hash[Symbol, untyped]
-    def to_h: () -> Hash[Symbol, untyped]
+    # : (?metadata: bool) -> Hash[Symbol, untyped]
+    def to_h: (?metadata: bool) -> Hash[Symbol, untyped]
   end
 
   # One adjacent transition in a descendant-aware activity timeline.
@@ -87,7 +87,12 @@ module PaperTrailDiff
     # : () -> bool
     def empty?: () -> bool
 
-    # : () -> Hash[Symbol, untyped]
-    def to_h: () -> Hash[Symbol, untyped]
+    # The event whose change this step reports. For a transaction group, this
+    # is the first event in the group, not necessarily its only actor or record.
+    # : () -> ActivityBoundary
+    def source_boundary: () -> ActivityBoundary
+
+    # : (?metadata: bool, ?snapshots: bool) -> Hash[Symbol, untyped]
+    def to_h: (?metadata: bool, ?snapshots: bool) -> Hash[Symbol, untyped]
   end
 end

data/sig/generated/paper_trail_diff/activity_child_candidate_loader.rbs

@@ -9,6 +9,14 @@ module PaperTrailDiff
     # : () -> Array[untyped]
     def call: () -> Array[untyped]
 
+    # One shared query retains the owner and timestamp needed to partition a
+    # batch's candidates back into each root's exact activity range.
+    # : () -> Array[Array[untyped]]
+    def historical_rows: () -> Array[Array[untyped]]
+
+    # : () -> Array[Array[untyped]]
+    def current_pairs: () -> Array[Array[untyped]]
+
     private
 
     @parent_class: untyped
@@ -19,6 +27,9 @@ module PaperTrailDiff
 
     @reflection: untyped
 
+    # : (Array[Array[untyped]]) -> Array[Array[untyped]]
+    def typed_rows: (Array[Array[untyped]]) -> Array[Array[untyped]]
+
     # : () -> Array[untyped]
     def historical_ids: () -> Array[untyped]