paper_trail_diff 0.14.0 → 0.15.0

data/lib/paper_trail_diff/version_sequence_diagnostics.rb

@@ -4,13 +4,13 @@
 module PaperTrailDiff
   # Checks the recorded sequence itself, before any question of association
   # setup: whether the versions can be ordered at all, and whether timestamps
-  # they share hide changes that ordering alone cannot recover.
+  # they share hide changes from a path PT-AT reads.
   class VersionSequenceDiagnostics
-    #: (untyped, untyped, ?associations_selected: bool) -> void
-    def initialize(from_version, to_version, associations_selected: false)
+    #: (untyped, untyped, ?fallback_selected: bool) -> void
+    def initialize(from_version, to_version, fallback_selected: false)
       @from_version = from_version
       @to_version = to_version
-      @associations_selected = associations_selected
+      @fallback_selected = fallback_selected
     end
 
     #: () -> Array[DiagnosticIssue]
@@ -18,7 +18,7 @@ module PaperTrailDiff
       versions = ordered_range_versions
       issues = [] #: Array[DiagnosticIssue?]
       issues << unorderable(versions)
-      issues << tied_timestamps(versions) if @associations_selected
+      issues << tied_timestamps(versions) if @fallback_selected
       issues.compact
     rescue StandardError
       []
@@ -28,7 +28,7 @@ module PaperTrailDiff
 
     # @rbs @from_version: untyped
     # @rbs @to_version: untyped
-    # @rbs @associations_selected: bool
+    # @rbs @fallback_selected: bool
 
     # Ordering falls back to the id when timestamps tie, which only recovers the
     # real sequence for ids that increase with insertion. Reported before a run
@@ -46,11 +46,12 @@ module PaperTrailDiff
       )
     end
 
-    # Association membership is recorded per version but resolved by timestamp,
-    # so a tie hides any association change across that pair. Unlike an
-    # unorderable sequence this is not always wrong: if nothing associated
-    # changed between them the result is correct, and the gem cannot tell which
-    # it is, because not seeing the change is the symptom. So it warns.
+    # Loaded history orders versions that share a timestamp by id, but PT-AT
+    # places association changes by timestamp alone, so a path it reads loses
+    # any change between such a pair. Unlike an unorderable sequence this is
+    # not always wrong: if nothing that path reaches changed between them the
+    # result is correct, and the gem cannot tell which it is, because not
+    # seeing the change is the symptom. So it warns.
     #: (Array[untyped]) -> DiagnosticIssue?
     def tied_timestamps(versions)
       pair = Support.tied_timestamp_pair(versions)
@@ -61,22 +62,36 @@ module PaperTrailDiff
         severity: :warning,
         code: :tied_version_timestamps,
         message: "versions #{left.id.inspect} and #{right.id.inspect} share the timestamp " \
-                 "#{left.created_at.inspect}, so association changes between them cannot " \
-                 'be detected; record versions at sub-second precision to separate them',
+                 "#{left.created_at.inspect}, and an association requested here is read with " \
+                 'PT-AT, which places association changes by timestamp alone, so a change ' \
+                 'between them can be missed; record versions at sub-second precision to ' \
+                 'separate them',
         version_id: left.id
       )
     end
 
     #: () -> Array[untyped]
     def ordered_range_versions
-      bounds = [@from_version.created_at, @to_version.created_at].compact.sort
-      return [] unless bounds.length == 2
+      range = time_range
+      return [] unless range
 
       @from_version.class
                    .where(item_type: @from_version.item_type, item_id: @from_version.item_id)
-                   .where(created_at: bounds.first..bounds.last)
+                   .where(created_at: range)
                    .to_a
                    .sort_by { |version| Support.chronological_version_key(version) }
     end
+
+    # Between the two versions, in either order, or from the one version on
+    # when the other endpoint is the current record. A version that recorded
+    # no time bounds nothing.
+    #: () -> Range[untyped]?
+    def time_range
+      from = @from_version.created_at
+      return from && (from..) unless @to_version
+
+      bounds = [from, @to_version.created_at].compact.sort
+      bounds.first..bounds.last if bounds.length == 2
+    end
   end
 end

data/lib/paper_trail_diff/version_table.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # PT-AT reads an association's history from its owner's version tables: it
+  # looks for a child's versions in the owner's version table, and numbers a
+  # transaction by the first version saved in it, in whichever table. A model
+  # whose versions, or version associations, live in another table than its
+  # owner's would read other records' versions or none, so it is refused.
+  module VersionTable
+    # Why the association, or a part of a through, cannot be read across
+    # version tables.
+    #: (untyped) -> String?
+    def self.unsupported_reason(reflection)
+      part = separate_part(reflection)
+      return unless part
+
+      "#{part.active_record.name}##{part.name} keeps versions in #{tables(part.active_record)} " \
+        "but #{part.klass.name} in #{tables(part.klass)}, and association history is read " \
+        'from one set of version tables'
+    end
+
+    # The reflection, or the first part of a through, whose ends keep versions
+    # in different tables. A polymorphic belongs_to names no single target,
+    # and an unversioned target has no history to compare.
+    #: (untyped) -> untyped
+    def self.separate_part(reflection)
+      if reflection.through_reflection?
+        return [reflection.through_reflection, reflection.source_reflection].filter_map do |part|
+          separate_part(part)
+        end.first
+      end
+      return if reflection.polymorphic?
+
+      owner = reflection.active_record
+      target = reflection.klass
+      return unless Support.versioned?(owner) && Support.versioned?(target)
+
+      reflection unless tables(owner) == tables(target)
+    end
+    private_class_method :separate_part
+
+    # PT-AT's version association rows joined to the versions they were saved
+    # with. Its `belongs_to :version` names PaperTrail's default class whatever
+    # table a model's versions are in, so the join names the table instead.
+    #: (untyped, untyped) -> untyped
+    def self.joined(associations, versions)
+      rows = associations.arel_table
+      table = versions.arel_table
+      associations.joins(rows.join(table).on(table[:id].eq(rows[:version_id])).join_sources)
+    end
+
+    #: (untyped) -> String
+    def self.tables(model)
+      history = model.paper_trail
+      "#{history.version_class.table_name} and #{history.version_association_class.table_name}"
+    end
+    private_class_method :tables
+  end
+end

data/lib/paper_trail_diff.rb

@@ -9,14 +9,18 @@ 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/deprecation'
 require_relative 'paper_trail_diff/errors'
 require_relative 'paper_trail_diff/configuration'
 require_relative 'paper_trail_diff/endpoint'
 require_relative 'paper_trail_diff/recorded_class'
+require_relative 'paper_trail_diff/association_key'
+require_relative 'paper_trail_diff/version_table'
 require_relative 'paper_trail_diff/association_traversal'
 require_relative 'paper_trail_diff/scope_ranking'
 require_relative 'paper_trail_diff/scope_condition'
-require_relative 'paper_trail_diff/batch_safety'
+require_relative 'paper_trail_diff/approximate_paths'
+require_relative 'paper_trail_diff/fallback_paths'
 require_relative 'paper_trail_diff/traversal_preparer'
 require_relative 'paper_trail_diff/association_discovery'
 require_relative 'paper_trail_diff/diagnostics'
@@ -30,6 +34,7 @@ require_relative 'paper_trail_diff/traversal_emitter'
 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/change_row'
 require_relative 'paper_trail_diff/collection_comparator'
 require_relative 'paper_trail_diff/nested_comparator'
 require_relative 'paper_trail_diff/engine'
@@ -46,6 +51,7 @@ require_relative 'paper_trail_diff/prepared_edge_loader'
 require_relative 'paper_trail_diff/prepared_history_loader'
 require_relative 'paper_trail_diff/prepared_association_reifier'
 require_relative 'paper_trail_diff/live_association_reader'
+require_relative 'paper_trail_diff/batch_preload'
 require_relative 'paper_trail_diff/live_endpoint_batch_loader'
 require_relative 'paper_trail_diff/preloaded_endpoint_batch_loader'
 require_relative 'paper_trail_diff/live_endpoint_provider'
@@ -73,7 +79,7 @@ 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_view'
 require_relative 'paper_trail_diff/activity_transaction_grouper'
 require_relative 'paper_trail_diff/step'
 require_relative 'paper_trail_diff/analysis'
@@ -85,11 +91,13 @@ require_relative 'paper_trail_diff/historical_filter'
 require_relative 'paper_trail_diff/association_activity_edge'
 require_relative 'paper_trail_diff/association_activity_selection'
 require_relative 'paper_trail_diff/scoped_root_selection'
+require_relative 'paper_trail_diff/deleted_root_filter'
 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'
 require_relative 'paper_trail_diff/time_range'
+require_relative 'paper_trail_diff/transaction_cut'
 require_relative 'paper_trail_diff/time_version_range'
 require_relative 'paper_trail_diff/timeline_range'
 require_relative 'paper_trail_diff/timeline_builder'
@@ -99,8 +107,8 @@ require_relative 'paper_trail_diff/activity_child_candidate_loader'
 require_relative 'paper_trail_diff/activity_target_candidate_loader'
 require_relative 'paper_trail_diff/activity_version_collector'
 require_relative 'paper_trail_diff/activity_snapshot_sequence'
+require_relative 'paper_trail_diff/activity_tree_filter'
 require_relative 'paper_trail_diff/activity_history'
-require_relative 'paper_trail_diff/time_activity_timeline_builder'
 require_relative 'paper_trail_diff/activity_timeline_builder'
 require_relative 'paper_trail_diff/paper_trail_adapter'
 
@@ -118,10 +126,10 @@ require_relative 'paper_trail_diff/paper_trail_adapter'
 #     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?
+#       within: untyped, activity: bool, version_scope: untyped, view: ActivityView
 #     }
 #     type ignore_option = Array[String | Symbol] | Hash[String | Symbol, untyped]
+#     type association_option = String | Symbol | Array[untyped] | Hash[untyped, untyped]
 #     type reference_key = :type | :id | "type" | "id"
 #     type traversal_context = :change | :included_state
 #     type traversal_state = :before | :after
@@ -142,43 +150,45 @@ module PaperTrailDiff # rubocop:disable Metrics/ModuleLength
 
   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(
+    #: (untyped, untyped, ?associations: association_option, ?ignore: ignore_option, ?reload_live_endpoints: bool?, ?allow_approximate: bool) -> Diff
+    def compare( # rubocop:disable Metrics/ParameterLists
       from_version,
       to_version,
       associations: [],
       ignore: DEFAULT_IGNORED_ATTRIBUTES,
-      reload_live_endpoints: true
+      reload_live_endpoints: nil,
+      allow_approximate: false
     )
       PaperTrailAdapter.new(
         associations: associations,
         ignore: ignore,
-        reload_live_endpoints: reload_live_endpoints
-      ).compare(
-        from_version,
-        to_version
-      )
+        reload_live_endpoints: Deprecation.reload_live_endpoints!(reload_live_endpoints),
+        allow_approximate: allow_approximate
+      ).compare(from_version, to_version)
     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, ?allow_expensive: bool) -> comparison_results
-    def compare_many(
+    #: (Array[comparison_input], ?associations: association_option, ?ignore: ignore_option, ?reload_live_endpoints: bool?, ?allow_expensive: bool?, ?allow_approximate: bool) -> comparison_results
+    def compare_many( # rubocop:disable Metrics/ParameterLists
       comparisons,
       associations: [],
       ignore: DEFAULT_IGNORED_ATTRIBUTES,
-      reload_live_endpoints: true,
-      allow_expensive: false
+      reload_live_endpoints: nil,
+      allow_expensive: nil,
+      allow_approximate: false
     )
+      Deprecation.allow_expensive!(allow_expensive)
       PaperTrailAdapter.new(
         associations: associations,
         ignore: ignore,
-        reload_live_endpoints: reload_live_endpoints, allow_expensive: allow_expensive
+        reload_live_endpoints: Deprecation.reload_live_endpoints!(reload_live_endpoints),
+        allow_approximate: allow_approximate
       ).compare_many(comparisons)
     end
 
     # 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]
+    #: (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: association_option, ?ignore: ignore_option, ?version_scope: untyped, ?close_on: Symbol?, ?allow_approximate: bool) -> Array[Step]
     def timeline( # rubocop:disable Metrics/ParameterLists
       record,
       from: nil,
@@ -187,23 +197,23 @@ module PaperTrailDiff # rubocop:disable Metrics/ModuleLength
       associations: [],
       ignore: DEFAULT_IGNORED_ATTRIBUTES,
       version_scope: nil,
-      close_on: nil
+      close_on: nil,
+      allow_approximate: false
     )
-      PaperTrailAdapter.new(associations: associations, ignore: ignore).timeline(
+      Deprecation.close_on!(close_on, within)
+      PaperTrailAdapter.new(
+        associations: associations, ignore: ignore, allow_approximate: allow_approximate
+      ).timeline(
         record,
         from: from,
         to: to,
         within: within,
-        version_scope: version_scope,
-        close_on: close_on
+        version_scope: version_scope
       )
     end
 
     # Compares adjacent root and selected-descendant activity boundaries.
-    # `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]
+    #: (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: association_option, ?ignore: ignore_option, ?reload_live_endpoints: bool?, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool, ?group: Symbol?, ?recorded_changes: bool, ?allow_approximate: bool) -> Array[ActivityStep]
     def activity_timeline( # rubocop:disable Metrics/ParameterLists
       record,
       from: nil,
@@ -211,30 +221,32 @@ module PaperTrailDiff # rubocop:disable Metrics/ModuleLength
       within: nil,
       associations: [],
       ignore: DEFAULT_IGNORED_ATTRIBUTES,
-      reload_live_endpoints: true,
+      reload_live_endpoints: nil,
       version_scope: nil,
       close_on: nil,
       snapshots: false,
-      group: nil
+      group: nil,
+      recorded_changes: false,
+      allow_approximate: false
     )
+      Deprecation.close_on!(close_on, within)
       PaperTrailAdapter.new(
-        associations: associations,
-        ignore: ignore,
-        reload_live_endpoints: reload_live_endpoints
+        associations: associations, ignore: ignore,
+        reload_live_endpoints: Deprecation.reload_live_endpoints!(reload_live_endpoints),
+        recorded_changes: recorded_changes, allow_approximate: allow_approximate
       ).activity_timeline(
         record,
         from: from,
         to: to,
         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, ?group: Symbol?) -> Analysis
+    #: (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: association_option, ?ignore: ignore_option, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool, ?group: Symbol?, ?recorded_changes: bool, ?allow_approximate: bool) -> Analysis
     def analyze( # rubocop:disable Metrics/ParameterLists
       record,
       from: nil,
@@ -246,16 +258,21 @@ module PaperTrailDiff # rubocop:disable Metrics/ModuleLength
       version_scope: nil,
       close_on: nil,
       snapshots: false,
-      group: nil
+      group: nil,
+      recorded_changes: false,
+      allow_approximate: false
     )
-      PaperTrailAdapter.new(associations: associations, ignore: ignore).analyze(
+      Deprecation.close_on!(close_on, within)
+      PaperTrailAdapter.new(
+        associations: associations, ignore: ignore, recorded_changes: recorded_changes,
+        allow_approximate: allow_approximate
+      ).analyze(
         record,
         from: from,
         to: to,
         within: within,
         activity: activity,
         version_scope: version_scope,
-        close_on: close_on,
         snapshots: snapshots,
         group: group
       )
@@ -266,7 +283,7 @@ module PaperTrailDiff # rubocop:disable Metrics/ModuleLength
     # 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]
+    #: (Array[untyped], ?within: untyped, ?associations: association_option, ?ignore: ignore_option, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool, ?group: Symbol?, ?allow_expensive: bool?, ?recorded_changes: bool, ?allow_approximate: bool) -> Hash[identity, Analysis]
     def analyze_many( # rubocop:disable Metrics/ParameterLists
       records,
       within: nil,
@@ -277,12 +294,17 @@ module PaperTrailDiff # rubocop:disable Metrics/ModuleLength
       close_on: nil,
       snapshots: false,
       group: nil,
-      allow_expensive: false
+      allow_expensive: nil,
+      recorded_changes: false,
+      allow_approximate: false
     )
+      Deprecation.close_on!(close_on, within)
+      Deprecation.allow_expensive!(allow_expensive)
       PaperTrailAdapter.new(
-        associations: associations, ignore: ignore, allow_expensive: allow_expensive
+        associations: associations, ignore: ignore,
+        recorded_changes: recorded_changes, allow_approximate: allow_approximate
       ).analyze_many(records, within: within, activity: activity, version_scope: version_scope,
-                              close_on: close_on, snapshots: snapshots, group: group)
+                              snapshots: snapshots, group: group)
     end
 
     # Analyzes every root the relation reaches whose history moved inside the
@@ -311,7 +333,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?, ?snapshots: bool, ?group: Symbol?, ?historical_filter: untyped, ?max_filter_versions: Integer, ?include_deleted: bool, ?allow_expensive: bool) -> ScopedAnalysis
+    #: (untyped, limit: Integer?, ?within: untyped, ?associations: association_option, ?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?, ?recorded_changes: bool, ?allow_approximate: bool) -> ScopedAnalysis
     def analyze_scope( # rubocop:disable Metrics/ParameterLists
       scope,
       limit:,
@@ -326,13 +348,18 @@ module PaperTrailDiff # rubocop:disable Metrics/ModuleLength
       historical_filter: nil,
       max_filter_versions: HistoricalFilter::DEFAULT_VERSION_LIMIT,
       include_deleted: false,
-      allow_expensive: false
+      allow_expensive: nil,
+      recorded_changes: false,
+      allow_approximate: false
     )
+      Deprecation.close_on!(close_on, within)
+      Deprecation.allow_expensive!(allow_expensive)
       adapter = PaperTrailAdapter.new(associations: associations, ignore: ignore,
-                                      allow_expensive: allow_expensive)
+                                      recorded_changes: recorded_changes,
+                                      allow_approximate: allow_approximate)
       adapter.analyze_scope(
         scope, limit: limit, within: within, activity: activity,
-               version_scope: version_scope, close_on: close_on, snapshots: snapshots, group: group,
+               version_scope: version_scope, snapshots: snapshots, group: group,
                historical_filter: historical_filter, max_filter_versions: max_filter_versions,
                include_deleted: include_deleted
       )
@@ -342,21 +369,35 @@ module PaperTrailDiff # rubocop:disable Metrics/ModuleLength
     # for every root that changed or whose requested associations did.
     # 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
+    #: (untyped, since: untyped, limit: Integer, ?associations: association_option, ?ignore: ignore_option, ?snapshots: bool, ?group: Symbol?, ?include_deleted: bool, ?historical_filter: untyped, ?max_filter_versions: Integer, ?allow_expensive: bool?, ?recorded_changes: bool, ?allow_approximate: 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
+      max_filter_versions: HistoricalFilter::DEFAULT_VERSION_LIMIT, allow_expensive: nil,
+      recorded_changes: false, allow_approximate: false
     )
+      # A range here would become the start of another range.
+      if since.nil? || since.is_a?(Range)
+        raise InvalidTimeRangeError, '`since` must be a time, date, or string; for a range, ' \
+                                     'pass it as `within:` to analyze_scope'
+      end
+
       analyze_scope(
         scope,
         within: since..Time.now.utc, limit: limit, associations: associations,
-        ignore: ignore, activity: true, close_on: :current, snapshots: snapshots, group: group,
+        ignore: ignore, activity: true, snapshots: snapshots, group: group,
         include_deleted: include_deleted, historical_filter: historical_filter,
-        max_filter_versions: max_filter_versions, allow_expensive: allow_expensive
+        max_filter_versions: max_filter_versions, allow_expensive: allow_expensive,
+        recorded_changes: recorded_changes, allow_approximate: allow_approximate
       )
     end
 
+    # Warns about deprecated options; see Deprecation.
+    #: () -> untyped
+    def deprecator
+      Deprecation.deprecator
+    end
+
     # Returns the association macros this release can normalize.
     #: () -> Array[Symbol]
     def supported_association_macros
@@ -369,10 +410,13 @@ module PaperTrailDiff # rubocop:disable Metrics/ModuleLength
       AssociationDiscovery.new(model_or_record, max_depth: max_depth).call
     end
 
-    # Reports known reconstruction hazards without mutating application state.
-    #: (untyped, untyped, ?associations: Array[String | Symbol]) -> DiagnosticReport
-    def diagnose(from_version, to_version, associations: [])
-      HistoryDiagnostics.new(from_version, to_version, associations: associations).call
+    # Reports known reconstruction hazards without mutating application state,
+    # for the endpoints `compare` takes: two versions, or a version and the
+    # current record. Every reason `compare` would refuse them is an error.
+    #: (untyped, untyped, ?associations: association_option, ?allow_approximate: bool) -> DiagnosticReport
+    def diagnose(from, to, associations: [], allow_approximate: false)
+      HistoryDiagnostics.new(from, to, associations: associations,
+                                       allow_approximate: allow_approximate).call
     end
 
     # Looks inside an attribute the database stores whole, such as a JSON or
@@ -404,9 +448,7 @@ module PaperTrailDiff # rubocop:disable Metrics/ModuleLength
 
     # Reads what PaperTrail recorded with one version: its `object_changes`,
     # typed by the version's model, as `{ "title" => <from "Draft" to "Published"> }`.
-    #
-    #   versions = PaperTrail::Version.where(id: steps.map { _1.source_boundary.version_id })
-    #   versions.to_h { [_1.id, PaperTrailDiff.recorded_changes(_1)] }
+    # Activity methods read it for every step source with `recorded_changes: true`.
     #
     # A step's diff compares the states before and after an event, so it also
     # includes anything saved without a version in between; this does not.

data/sig/generated/paper_trail_diff/activity_boundary.rbs

@@ -24,26 +24,49 @@ module PaperTrailDiff
     # report one save as one step rather than as its parts.
     attr_reader transaction_id: untyped
 
-    # : (untyped) -> ActivityBoundary
-    def self.from_version: (untyped) -> ActivityBoundary
+    @recorded_changes: untyped
 
-    # : (untyped, captured_at: untyped) -> ActivityBoundary
-    def self.current: (untyped, captured_at: untyped) -> ActivityBoundary
+    # Stands for recorded changes nobody asked to read, which differs from a
+    # version that recorded nothing (nil).
+    NOT_READ: untyped
+
+    NOT_READ_MESSAGE: ::String
+
+    # `recorded:` names the attributes to leave out of the version's recorded
+    # changes, or is nil when they were not asked for. Reading them decodes
+    # `object_changes`, which a caller who does not want them should not pay.
+    # : (untyped, ?recorded: Array[String]?) -> ActivityBoundary
+    def self.from_version: (untyped, ?recorded: Array[String]?) -> ActivityBoundary
+
+    # The current record has no version, so it recorded nothing.
+    # : (untyped, captured_at: untyped, ?recorded: Array[String]?) -> ActivityBoundary
+    def self.current: (untyped, captured_at: untyped, ?recorded: Array[String]?) -> ActivityBoundary
 
     # The state a `destroy` version leaves behind. A version records the state
     # before its own event, so the boundary built from a destroy version still
     # holds the record; this one is the absence that follows it.
-    # : (untyped) -> ActivityBoundary
-    def self.destroyed: (untyped) -> ActivityBoundary
-
-    # 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
+    # : (untyped, ?recorded: Array[String]?) -> ActivityBoundary
+    def self.destroyed: (untyped, ?recorded: Array[String]?) -> ActivityBoundary
+
+    # : (untyped, Array[String]?) -> untyped
+    private def self.recorded_changes: (untyped, Array[String]?) -> untyped
+
+    # `recorded_changes:` takes what `PaperTrailDiff.recorded_changes` returns
+    # for the version; leave it out when they were not read.
+    # : (kind: Symbol, version_id: untyped, item_type: untyped, item_id: untyped, recorded_at: untyped, ?event: untyped, ?whodunnit: untyped, ?transaction_id: untyped, ?recorded_changes: 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, ?recorded_changes: untyped) -> void
+
+    # What PaperTrail recorded with this boundary's version, as
+    # `PaperTrailDiff.recorded_changes` returns it: nil when nothing was
+    # recorded, and always nil for the current record, which has no version.
+    # Raises unless the timeline was built with `recorded_changes: true`, so a
+    # forgotten option cannot pass for a version that recorded nothing.
+    # : () -> Hash[String, ValueChange]?
+    def recorded_changes: () -> Hash[String, ValueChange]?
+
+    # Whether this boundary's recorded changes were read.
+    # : () -> bool
+    def recorded_changes?: () -> bool
 
     # : () -> bool
     def version?: () -> bool
@@ -75,14 +98,20 @@ module PaperTrailDiff
 
     attr_reader to_snapshot: RecordSnapshot?
 
+    # The events whose changes this step reports, in the order they happened.
+    # That is `source_boundary` alone, unless the step is a transaction group,
+    # which holds every event in it: an attribution that names only the first
+    # would credit the rest of the save to whoever opened it.
+    attr_reader sources: Array[ActivityBoundary]
+
     # Compares two reconstructed states and keeps them only when asked, which is
     # every caller's shape: the diff always comes from the pair, the pair itself
     # is retained on request.
-    # : (from_boundary: ActivityBoundary, to_boundary: ActivityBoundary, from_snapshot: RecordSnapshot?, to_snapshot: RecordSnapshot?, retain: bool) -> ActivityStep
-    def self.between: (from_boundary: ActivityBoundary, to_boundary: ActivityBoundary, from_snapshot: RecordSnapshot?, to_snapshot: RecordSnapshot?, retain: bool) -> ActivityStep
+    # : (from_boundary: ActivityBoundary, to_boundary: ActivityBoundary, from_snapshot: RecordSnapshot?, to_snapshot: RecordSnapshot?, retain: bool, ?sources: Array[ActivityBoundary]?) -> ActivityStep
+    def self.between: (from_boundary: ActivityBoundary, to_boundary: ActivityBoundary, from_snapshot: RecordSnapshot?, to_snapshot: RecordSnapshot?, retain: bool, ?sources: Array[ActivityBoundary]?) -> ActivityStep
 
-    # : (from_boundary: ActivityBoundary, to_boundary: ActivityBoundary, diff: Diff, ?from_snapshot: RecordSnapshot?, ?to_snapshot: RecordSnapshot?) -> void
-    def initialize: (from_boundary: ActivityBoundary, to_boundary: ActivityBoundary, diff: Diff, ?from_snapshot: RecordSnapshot?, ?to_snapshot: RecordSnapshot?) -> void
+    # : (from_boundary: ActivityBoundary, to_boundary: ActivityBoundary, diff: Diff, ?from_snapshot: RecordSnapshot?, ?to_snapshot: RecordSnapshot?, ?sources: Array[ActivityBoundary]?) -> void
+    def initialize: (from_boundary: ActivityBoundary, to_boundary: ActivityBoundary, diff: Diff, ?from_snapshot: RecordSnapshot?, ?to_snapshot: RecordSnapshot?, ?sources: Array[ActivityBoundary]?) -> void
 
     # : () -> bool
     def empty?: () -> bool
@@ -92,6 +121,12 @@ module PaperTrailDiff
     # : () -> ActivityBoundary
     def source_boundary: () -> ActivityBoundary
 
+    # The diff as flat rows, each attributed to `source_boundary`.
+    # : () -> Array[ChangeRow]
+    def change_rows: () -> Array[ChangeRow]
+
+    # `metadata: true` also lists `sources`, since who made a change is
+    # metadata as much as the source boundary's own author is.
     # : (?metadata: bool, ?snapshots: bool) -> Hash[Symbol, untyped]
     def to_h: (?metadata: bool, ?snapshots: bool) -> Hash[Symbol, untyped]
   end