paper_trail_diff 0.14.0 → 0.15.0

data/lib/paper_trail_diff/batched_root_analyzer.rb

@@ -5,22 +5,22 @@ module PaperTrailDiff
   # Builds one root's Analysis inside a batch, from versions the batch already
   # selected and history it already prepared.
   class BatchedRootAnalyzer
-    #: (tree: AssociationTree, timeline_snapshotter: untyped, activity_snapshotter: untyped, preparer: untyped, activity: bool, ?within: untyped, ?snapshots: bool, ?group: Symbol?) -> void
-    def initialize(tree:, timeline_snapshotter:, activity_snapshotter:, preparer:, activity:, within: nil, snapshots: false, group: nil) # rubocop:disable Metrics/ParameterLists, Layout/LineLength
+    #: (tree: AssociationTree, timeline_snapshotter: untyped, activity_snapshotter: untyped, preparer: untyped, activity: bool, view: ActivityView, ?within: untyped) -> void
+    def initialize(tree:, timeline_snapshotter:, activity_snapshotter:, preparer:, activity:, view:, within: nil) # rubocop:disable Metrics/ParameterLists, Layout/LineLength
       @tree = tree
       @timeline_snapshotter = timeline_snapshotter
       @activity_snapshotter = activity_snapshotter
       @preparer = preparer
       @activity = activity
+      @view = view
       @within = within
-      @snapshots = snapshots
-      @group = group
     end
 
-    #: (untyped, RootVersionPlan) -> Analysis
-    def call(record, plan)
+    # `window` is the root's window as the batch moved it to transaction edges.
+    #: (untyped, RootVersionPlan, ?TimeRange?) -> Analysis
+    def call(record, plan, window = nil)
       @preparer.call(record.class, historical: true)
-      return activity_analysis(record, plan) if @activity
+      return activity_analysis(record, plan, window) if @activity
 
       TimelineBuilder.new(
         record,
@@ -40,19 +40,17 @@ module PaperTrailDiff
     # @rbs @preparer: untyped
     # @rbs @activity: bool
     # @rbs @within: untyped
-    # @rbs @snapshots: bool
-    # @rbs @group: Symbol?
+    # @rbs @view: ActivityView
 
-    #: (untyped, RootVersionPlan) -> Analysis
-    def activity_analysis(record, plan)
+    #: (untyped, RootVersionPlan, TimeRange?) -> Analysis
+    def activity_analysis(record, plan, window)
       range = TimelineRange.new(
         record, from: (@within ? nil : plan.versions.first),
                 to: (@within ? nil : plan.closing_record || plan.versions.last),
-                within: @within, plan: plan
+                within: (window || @within if @within), plan: plan
       )
       ActivityTimelineBuilder.new(
-        record, range: range, tree: @tree, snapshotter: @activity_snapshotter,
-                snapshots: @snapshots, group: @group
+        record, range: range, tree: @tree, snapshotter: @activity_snapshotter, view: @view
       ).analyze
     end
   end

data/lib/paper_trail_diff/batched_root_versions.rb

@@ -6,9 +6,13 @@ module PaperTrailDiff
   # queries. Only the range forms that mean the same thing for every root are
   # supported: a shared wall-clock window, or each root's own whole history.
   class BatchedRootVersions
-    #: (Array[untyped], time_range: TimeRange?, version_scope: untyped, live_endpoints: Hash[Array[String], untyped]?, context_required: bool) -> void
-    def initialize(records, time_range:, version_scope:, live_endpoints:, context_required:)
+    #: (Array[untyped], time_range: TimeRange?, version_scope: untyped, live_endpoints: Hash[Array[String], untyped]?, context_required: bool, windows: Hash[Array[String], TimeRange]) -> void
+    def initialize( # rubocop:disable Metrics/ParameterLists
+      records, time_range:, version_scope:, live_endpoints:, context_required:, windows:
+    )
       @records = records
+      # Roots whose window moved to a transaction's start, by identity.
+      @windows = windows
       # An activity view needs a root to reconstruct from even in a window with
       # no root version, exactly as a single-record activity timeline does.
       @context_required = context_required
@@ -34,32 +38,55 @@ module PaperTrailDiff
     # @rbs @version_scope: untyped
     # @rbs @live_endpoints: Hash[Array[String], untyped]?
     # @rbs @context_required: bool
+    # @rbs @windows: Hash[Array[String], TimeRange]
 
     #: (untyped, Array[untyped], Hash[Array[String], RootVersionPlan]) -> void
     def select_model(model_class, records, selected)
       in_range, chosen, trailing = model_versions(model_class, records)
       records.each do |record|
         key = Endpoint.identity(record)
-        selected[key] = versions_for(
-          in_range.fetch(record.id.to_s, []), chosen, trailing[record.id.to_s],
-          live_endpoint(key, record)
-        )
+        own = own_window(key, record.id.to_s, in_range, trailing)
+        selected[key] = versions_for(*own, chosen, live_endpoint(key, record))
       end
     end
 
+    # Moved windows only start and end earlier, so the versions read for the
+    # widest of them hold each root's own, and the first left past a moved end.
+    #: (Array[String], String, Hash[String, Array[untyped]], Hash[String, untyped]) -> [Array[untyped], untyped]
+    def own_window(key, id, in_range, trailing)
+      loaded = in_range.fetch(id, [])
+      return [loaded, trailing[id]] if @windows.empty?
+
+      # A batch moves windows only when it has one, so this is never nil.
+      window = @windows.fetch(key) { @time_range } #: untyped
+      own, rest = loaded.partition { |version| window.include?(version.created_at) }
+      [own, rest.find { |version| version.created_at >= window.end_time } || trailing[id]]
+    end
+
     #: (untyped, Array[untyped]) -> [Hash[String, Array[untyped]], Set[untyped]?, Hash[String, untyped]]
     def model_versions(model_class, records)
       range = @time_range
       empty = {} #: Hash[String, untyped]
+      widest = widest_range(records)
       [
-        grouped_versions(model_class, records, range),
-        chosen_version_ids(model_class, records, range),
+        grouped_versions(model_class, records, widest),
+        chosen_version_ids(model_class, records, widest),
         range ? trailing_versions(model_class, records, range) : empty
       ]
     end
 
-    #: (Array[untyped], Set[untyped]?, untyped, untyped) -> RootVersionPlan
-    def versions_for(in_range, chosen, after_range, live_endpoint)
+    #: (Array[untyped]) -> TimeRange?
+    def widest_range(records)
+      range = @time_range
+      return unless range
+
+      moved = records.filter_map { |record| @windows[Endpoint.identity(record)]&.begin_time }
+      start = [range.begin_time, *moved].min
+      TimeRange.new(range.exclude_end? ? (start...range.end_time) : (start..range.end_time))
+    end
+
+    #: (Array[untyped], untyped, Set[untyped]?, untyped) -> RootVersionPlan
+    def versions_for(in_range, after_range, chosen, live_endpoint)
       RootVersionSelection.new(
         in_range: in_range,
         selected: chosen ? in_range.select { |version| chosen.include?(version.id) } : in_range,
@@ -109,10 +136,7 @@ module PaperTrailDiff
     #: (untyped, Array[untyped]) -> untyped
     def base_scope(model_class, records)
       # Active Record reads each record's id.
-      model_class.paper_trail.version_class.where(
-        item_type: model_class.base_class.name,
-        item_id: records
-      )
+      VersionQuery.for_items(model_class, records)
     end
   end
 end

data/lib/paper_trail_diff/change_row.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # One change from an activity step, flat enough for a history table or an
+  # export: a field that changed, or a record that appeared or disappeared,
+  # with the event the step attributes it to.
+  class ChangeRow
+    attr_reader :change #: Symbol
+    attr_reader :association_path #: Array[String]
+    attr_reader :association_kind #: Symbol?
+    # The record the row is about, or nil for the root itself.
+    attr_reader :record #: RecordReference?
+    # The field the row is about, or nil for a row about a whole record.
+    attr_reader :attribute #: String?
+    attr_reader :from #: untyped
+    attr_reader :to #: untyped
+    # The step's source boundary: for a transaction group, its first event.
+    attr_reader :source #: ActivityBoundary
+
+    #: (change: Symbol, association_path: Array[String], association_kind: Symbol?, record: RecordReference?, attribute: String?, from: untyped, to: untyped, source: ActivityBoundary) -> void
+    def initialize( # rubocop:disable Metrics/ParameterLists
+      change:, association_path:, association_kind:, record:, attribute:, from:, to:, source:
+    )
+      @change = change
+      @association_path = association_path
+      @association_kind = association_kind
+      @record = record
+      @attribute = attribute
+      @from = from
+      @to = to
+      @source = source
+      freeze
+    end
+
+    # The source's identifying fields sit beside the change rather than nested,
+    # so the hash is one row of a table as it stands.
+    #: () -> Hash[Symbol, untyped]
+    def to_h
+      {
+        change: change, association_path: association_path, association_kind: association_kind,
+        record: record&.to_h, attribute: attribute,
+        from: Support.serialize(from), to: Support.serialize(to)
+      }.merge(source_fields)
+    end
+
+    private
+
+    #: () -> Hash[Symbol, untyped]
+    def source_fields
+      { version_id: source.version_id, event: source.event, whodunnit: source.whodunnit,
+        recorded_at: source.recorded_at, transaction_id: source.transaction_id }
+    end
+  end
+
+  # Flattens one step's diff into change rows, in the diff's walking order.
+  #
+  # A row is about one record. An edited field is `:changed`. A record that
+  # appeared or disappeared is one `:added` or `:removed` row, followed by a
+  # row for each of its fields and for each record it holds, so a table can
+  # list a new comment's body without a second walker. That covers a record
+  # joining or leaving a collection, a to-one target set, cleared or replaced
+  # (the old target removed, then the new one added), and the root's own
+  # creation or deletion.
+  #
+  # Two kinds of entry add nothing a row would show. One that only groups
+  # others (an edited record, an association, a relationship) is left out,
+  # because the rows under it name the same record. A blank field of an added
+  # or removed record is left out too, because the record's own row already
+  # says it appeared or disappeared.
+  class ChangeRows
+    RECORD_ENTRIES = %i[record_added record_removed record_included].freeze
+    private_constant :RECORD_ENTRIES
+
+    #: (Diff, source: ActivityBoundary) -> Array[ChangeRow]
+    def self.call(diff, source:)
+      new(source).call(diff)
+    end
+
+    #: (ActivityBoundary) -> void
+    def initialize(source)
+      @source = source
+    end
+
+    #: (Diff) -> Array[ChangeRow]
+    def call(diff)
+      rows = [] #: Array[ChangeRow]
+      diff.each_entry do |entry|
+        row = row_for(entry)
+        rows << row if row
+      end
+      rows.freeze
+    end
+
+    private
+
+    # @rbs @source: ActivityBoundary
+
+    #: (TraversalEntry) -> ChangeRow?
+    def row_for(entry)
+      return changed_row(entry) if entry.kind == :attribute_changed
+      return presence_row(entry, nil) if RECORD_ENTRIES.include?(entry.kind)
+      return unless entry.kind == :attribute_included && !entry.value.nil?
+
+      presence_row(entry, entry.attribute)
+    end
+
+    #: (TraversalEntry) -> ChangeRow
+    def changed_row(entry)
+      value = entry.value #: ValueChange
+      row(entry, :changed, entry.attribute, value.from, value.to)
+    end
+
+    # An added record's state is the after side and a removed one's the before
+    # side, so a field's value goes on the side that has it.
+    #: (TraversalEntry, String?) -> ChangeRow
+    def presence_row(entry, attribute)
+      value = attribute ? entry.value : nil
+      return row(entry, :added, attribute, nil, value) if entry.state == :after
+
+      row(entry, :removed, attribute, value, nil)
+    end
+
+    #: (TraversalEntry, Symbol, String?, untyped, untyped) -> ChangeRow
+    def row(entry, change, attribute, from, to)
+      ChangeRow.new(
+        change: change, association_path: entry.association_path,
+        association_kind: entry.association_kind, record: entry.record,
+        attribute: attribute, from: from, to: to, source: @source
+      )
+    end
+  end
+end

data/lib/paper_trail_diff/collection_comparator.rb

@@ -3,6 +3,8 @@
 
 module PaperTrailDiff
   # Compares collection snapshots with a low-allocation path for stable membership.
+  # Snapshots hold their records in type and ID order, so results follow it
+  # without sorting here.
   class CollectionComparator
     #: (AssociationSnapshot, AssociationSnapshot, record_comparer: untyped) -> void
     def initialize(from_association, to_association, record_comparer:)
@@ -50,9 +52,7 @@ module PaperTrailDiff
       pairs = aligned_changed_pairs
       return unless pairs
 
-      pairs.sort_by { |_from, to| sortable_identity(to.identity) }.filter_map do |pair|
-        @record_comparer.call(pair.fetch(0), pair.fetch(1))
-      end
+      pairs.filter_map { |pair| @record_comparer.call(pair.fetch(0), pair.fetch(1)) }
     end
 
     #: () -> Array[[RecordSnapshot, RecordSnapshot]]?
@@ -105,13 +105,12 @@ module PaperTrailDiff
 
     #: (Hash[identity, RecordSnapshot], Hash[identity, RecordSnapshot]) -> Array[RecordSnapshot]
     def records_missing_from(records, other_records)
-      identities = sorted_identities(records.keys - other_records.keys)
-      identities.map { |identity| records.fetch(identity) }
+      (records.keys - other_records.keys).map { |identity| records.fetch(identity) }
     end
 
     #: (Hash[identity, RecordSnapshot], Hash[identity, RecordSnapshot]) -> Array[RecordChange]
     def changed_records(from_records, to_records)
-      sorted_identities(from_records.keys & to_records.keys).filter_map do |identity|
+      (from_records.keys & to_records.keys).filter_map do |identity|
         from_record = from_records.fetch(identity)
         to_record = to_records.fetch(identity)
         next if from_record.equal?(to_record)
@@ -132,32 +131,6 @@ module PaperTrailDiff
       index
     end
 
-    #: (Array[identity]) -> Array[identity]
-    def sorted_identities(identities)
-      identities.sort_by { |identity| sortable_identity(identity) }
-    end
-
-    # Identities sort by type first so that mixed id types stay comparable, then
-    # naturally within one type. Ordering by the printed form instead would put
-    # id 10 before id 2, which is deterministic but reads as unsorted wherever a
-    # result is rendered.
-    #: (identity) -> Array[untyped]
-    def sortable_identity(identity)
-      [identity.fetch(0), sortable_id(identity.fetch(1))]
-    end
-
-    # Only the order of the group numbers matters, so moving the lowest one
-    # down or the highest one up changes nothing; the spec checks the order.
-    # mutant:disable
-    #: (untyped) -> Array[untyped]
-    def sortable_id(id)
-      case id
-      when Numeric then [0, id]
-      when String, Symbol then [1, id.to_s]
-      else [2, id.inspect]
-      end
-    end
-
     #: (identity) -> void
     def raise_duplicate_identity!(identity)
       raise ArgumentError, "duplicate record identity: #{identity}"

data/lib/paper_trail_diff/configuration.rb

@@ -7,19 +7,40 @@ module PaperTrailDiff
     attr_reader :children #: Hash[String, AssociationTree]
 
     class << self
+      # Takes what `includes` takes: a name, a dotted path, a hash of names to
+      # what to include below them, or an array of any of these.
       #: (untyped) -> AssociationTree
       def build(values)
-        unless valid_values?(values)
-          raise ConfigurationError, 'associations: must be an array of strings or symbols'
-        end
-
         tree = {} #: Hash[String, untyped]
-        values.each { |value| add_path(tree, value.to_s) }
+        paths(values, nil).each { |path| add_path(tree, path) }
         from_hash(tree)
       end
 
       private
 
+      #: (untyped, String?) -> Array[String]
+      def paths(value, prefix)
+        case value
+        when String, Symbol then [joined(prefix, value)]
+        when Array then value.flat_map { |item| paths(item, prefix) }
+        when Hash then value.flat_map { |name, nested| nested_paths(name, nested, prefix) }
+        else
+          raise ConfigurationError,
+                'associations: must be names, dotted paths, hashes of them, or arrays of these'
+        end
+      end
+
+      # `{ comments: :replies }` names comments as well as their replies.
+      #: (untyped, untyped, String?) -> Array[String]
+      def nested_paths(name, nested, prefix)
+        paths(name, prefix).flat_map { |path| [path, *paths(nested, path)] }
+      end
+
+      #: (String?, String | Symbol) -> String
+      def joined(prefix, name)
+        prefix ? "#{prefix}.#{name}" : name.to_s
+      end
+
       #: (Hash[String, untyped], String) -> void
       def add_path(tree, path)
         segments = path.split('.', -1)
@@ -39,13 +60,6 @@ module PaperTrailDiff
         end
         new(children)
       end
-
-      #: (untyped) -> bool
-      def valid_values?(values)
-        values.is_a?(Array) && values.all? do |value|
-          value.is_a?(String) || value.is_a?(Symbol)
-        end
-      end
     end
 
     #: (Hash[String, AssociationTree]) -> void
@@ -166,5 +180,14 @@ module PaperTrailDiff
       external_path = path.empty? ? ROOT_PATH : path
       (all + paths.fetch(external_path, [])).uniq.freeze
     end
+
+    # The names to leave out of what a version recorded. A root version is
+    # known to be the root's, so its own path's names apply; any other version
+    # does not say which path reached it, so only the names ignored everywhere
+    # do.
+    #: (root: bool) -> Array[String]
+    def recorded_attributes(root:)
+      root ? attributes_for('') : all
+    end
   end
 end

data/lib/paper_trail_diff/deleted_analysis_batch.rb

@@ -24,12 +24,14 @@ module PaperTrailDiff
     def call
       destroys = destroy_versions
       records = historical_roots(destroys)
-      selected = plans(records, destroys)
-      prepare(records, selected)
+      windows = TransactionCut.batch_windows(records, @time_range)
+      selected = plans(records, destroys, windows)
+      prepare(records, selected, windows)
       analyses = records.to_h do |record|
         key = Endpoint.identity(record)
         plan = selected.fetch(key)
-        [key, plan.empty? ? Analysis.empty : @analyzer.call(record, plan)]
+        window = windows.fetch(key, @time_range)
+        [key, plan.empty? ? Analysis.empty : @analyzer.call(record, plan, window)]
       end
       with_unavailable(analyses)
     end
@@ -51,20 +53,20 @@ module PaperTrailDiff
 
     # A root destroyed before the window had no state inside it to read, so
     # only the others take the version after the window as context.
-    #: (Array[untyped], Array[untyped]) -> Hash[Array[String], RootVersionPlan]
-    def plans(records, destroys)
+    #: (Array[untyped], Array[untyped], Hash[Array[String], TimeRange]) -> Hash[Array[String], RootVersionPlan]
+    def plans(records, destroys, windows)
       start = @time_range&.begin_time
       early = destroys.select { |version| start && version.created_at < start }
                       .map { |version| version.item_id.to_s }
       before, during = records.partition { |record| early.include?(record.id.to_s) }
-      plans_for(during, @context_required).merge(plans_for(before, false))
+      plans_for(during, @context_required, windows).merge(plans_for(before, false, windows))
     end
 
-    #: (Array[untyped], bool) -> Hash[Array[String], RootVersionPlan]
-    def plans_for(records, context_required)
+    #: (Array[untyped], bool, Hash[Array[String], TimeRange]) -> Hash[Array[String], RootVersionPlan]
+    def plans_for(records, context_required, windows)
       BatchedRootVersions.new(
         records, time_range: @time_range, version_scope: @version_scope,
-                 live_endpoints: nil, context_required: context_required
+                 live_endpoints: nil, context_required: context_required, windows: windows
       ).call
     end
 
@@ -84,28 +86,26 @@ module PaperTrailDiff
 
     #: () -> Array[untyped]
     def destroy_versions
-      destroys = @model.paper_trail.version_class.where(
-        item_type: @model.base_class.name, item_id: @identities.map(&:last), event: 'destroy'
-      )
+      destroys = VersionQuery.for_items(@model, @identities.map(&:last)).where(event: 'destroy')
       # Oldest first, so each item keeps its latest destroy.
       VersionQuery.chronological(destroys).index_by(&:item_id).values
     end
 
-    #: (Array[untyped]) -> Hash[Symbol, untyped]
-    def preparation_range(versions)
-      { start_at: @time_range&.begin_time,
+    #: (Array[untyped], Hash[Array[String], TimeRange]) -> Hash[Symbol, untyped]
+    def preparation_range(versions, windows)
+      { start_at: TransactionCut.earliest_start(@time_range, windows),
         end_at: [@time_range&.end_time, versions.map(&:created_at).max].compact.max }
     end
 
-    #: (Array[untyped], Hash[Array[String], RootVersionPlan]) -> void
-    def prepare(records, selected)
+    #: (Array[untyped], Hash[Array[String], RootVersionPlan], Hash[Array[String], TimeRange]) -> void
+    def prepare(records, selected, windows)
       records.group_by(&:class).each_value do |group|
         versions = group.flat_map do |record|
           selected.fetch(Endpoint.identity(record)).reconstruction_versions
         end
         next if versions.empty?
 
-        @history_preparer.call(group, versions, **preparation_range(versions))
+        @history_preparer.call(group, versions, **preparation_range(versions, windows))
       end
     end
   end

data/lib/paper_trail_diff/deleted_root_filter.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # Keeps the deleted roots the relation would have selected, by the state
+  # each held when it was destroyed. A relation's conditions read the live
+  # table, where a destroyed root has no row, so without this a report on one
+  # account's records would include every account's deletions.
+  class DeletedRootFilter
+    #: (untyped) -> void
+    def initialize(relation)
+      @relation = relation
+      condition = ScopeCondition.for_relation(relation, model)
+      unless condition
+        raise ConfigurationError,
+              'include_deleted: cannot test deleted records against this relation: its ' \
+              "conditions must be plain conditions on #{model.name}'s own columns, as an " \
+              "association scope's must; select deleted records some other way"
+      end
+
+      @condition = condition
+      @loader = DirectRecordStateLoader.new
+    end
+
+    # A root whose destroy PaperTrail did not record has no state to test
+    # and stays, as it has no state to report either. One whose destroy
+    # recorded no state is left out.
+    #: (Array[Array[String]]) -> Array[Array[String]]
+    def call(identities)
+      states = destroyed_states(identities.map(&:last))
+      identities.select do |identity|
+        id = identity.last
+        !states.key?(id) || selected?(states.fetch(id))
+      end
+    end
+
+    private
+
+    # @rbs @relation: untyped
+    # @rbs @condition: ScopeCondition
+    # @rbs @loader: DirectRecordStateLoader
+
+    # A relation delegates class methods to its model, so every mutation here,
+    # which drops `.model`, answers the same.
+    # mutant:disable
+    #: () -> untyped
+    def model
+      @relation.model
+    end
+
+    #: (Hash[String, untyped]?) -> bool
+    def selected?(attributes)
+      return false unless attributes
+
+      AssociationTraversal.sti_member?(model, attributes) && @condition.matches?(attributes)
+    end
+
+    # The state each root held before its latest destroy.
+    #: (Array[String]) -> Hash[String, Hash[String, untyped]?]
+    def destroyed_states(ids)
+      destroys = VersionQuery.for_items(model, ids).where(event: 'destroy')
+      VersionQuery.chronological(destroys).to_h do |version|
+        [version.item_id.to_s, @loader.call(version)&.attributes || reified_attributes(version)]
+      end
+    end
+
+    # Read directly, with a column `skip:` left out of history as its default,
+    # so a report checks its ceiling before reifying anything. A version the
+    # direct reader declines, such as one naming a column since removed, is
+    # reified. Only the record's own attributes are read, so the association
+    # options, which only spare queries, cannot change an answer.
+    # mutant:disable
+    #: (untyped) -> Hash[String, untyped]?
+    def reified_attributes(version)
+      version.reify(dup: true, has_many: false, has_one: false, belongs_to: false,
+                    has_and_belongs_to_many: false)&.attributes
+    end
+  end
+end

data/lib/paper_trail_diff/deprecation.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # Warns about options that do nothing any more and will be removed. In a
+  # Rails app, register the deprecator to configure it with the app's own:
+  #
+  #   Rails.application.deprecators[:paper_trail_diff] = PaperTrailDiff.deprecator
+  module Deprecation
+    CLOSE_ON = 'close_on: is deprecated and has no effect: a window already closes on the ' \
+               'current record when nothing on its requested paths was recorded after it. ' \
+               'Remove the option.'
+    ALLOW_EXPENSIVE = 'allow_expensive: is deprecated and has no effect: allow_approximate: true ' \
+                      'alone accepts a path read with PT-AT, in batch methods too. Remove the ' \
+                      'option.'
+    RELOAD_LIVE_ENDPOINTS = 'reload_live_endpoints: is deprecated and will be removed: skipping ' \
+                            'the reload saves a query for the records and one per association ' \
+                            'level, and reads values that may be stale. Remove the option.'
+
+    # Required when first used, as the library loads nothing it does not need.
+    #: () -> untyped
+    def self.deprecator
+      @deprecator ||= begin
+        require 'active_support/deprecation'
+        active_support = Object.const_get(:ActiveSupport) #: untyped
+        active_support.const_get(:Deprecation).new('a future release', 'paper_trail_diff')
+      end
+    end
+
+    # The one value close_on: took. It named what ends a wall-clock window,
+    # so it was meaningless without one, and until it is removed it is still
+    # checked as it was.
+    CLOSE_ON_CURRENT = :current
+
+    #: (Symbol?, untyped) -> void
+    def self.close_on!(close_on, within)
+      return if close_on.nil?
+      unless close_on == CLOSE_ON_CURRENT
+        raise ConfigurationError, "close_on: must be #{CLOSE_ON_CURRENT.inspect} or nil"
+      end
+      raise ConfigurationError, 'close_on: requires `within`' if within.nil?
+
+      deprecator.warn(CLOSE_ON)
+    end
+
+    #: (untyped) -> void
+    def self.allow_expensive!(allow_expensive)
+      deprecator.warn(ALLOW_EXPENSIVE) unless allow_expensive.nil?
+    end
+
+    # The value to use: the option still works until it is removed, and nil
+    # stands for its old default.
+    #: (untyped) -> untyped
+    def self.reload_live_endpoints!(reload)
+      return true if reload.nil?
+
+      deprecator.warn(RELOAD_LIVE_ENDPOINTS)
+      reload
+    end
+  end
+end