paper_trail_diff 0.14.0 → 0.15.0

data/sig/generated/paper_trail_diff/snapshot.rbs

@@ -70,6 +70,14 @@ module PaperTrailDiff
     # : (Array[RecordSnapshot], before: RecordSnapshot?, after: RecordSnapshot?, membership_preserved: bool) -> AssociationSnapshot
     def transition_to: (Array[RecordSnapshot], before: RecordSnapshot?, after: RecordSnapshot?, membership_preserved: bool) -> AssociationSnapshot
 
+    # Collections are documented in record type, then ID, order wherever they
+    # were read from. Most arrive sorted, so they are checked before sorting.
+    # : (Array[RecordSnapshot]) -> Array[RecordSnapshot]
+    def ordered: (Array[RecordSnapshot]) -> Array[RecordSnapshot]
+
+    # : (Array[Array[untyped]]) -> bool
+    def sorted?: (Array[Array[untyped]]) -> bool
+
     # : (AssociationSnapshot) -> CollectionTransition?
     def transition_from: (AssociationSnapshot) -> CollectionTransition?
 

data/sig/generated/paper_trail_diff/support.rbs

@@ -12,6 +12,13 @@ module PaperTrailDiff
     # : (untyped) -> untyped
     def self?.serialize: (untyped) -> untyped
 
+    # Records 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.
+    # : (untyped, untyped) -> Array[untyped]
+    def self?.sortable_identity: (untyped, untyped) -> Array[untyped]
+
     # : (untyped) -> Array[untyped]
     def self?.chronological_version_key: (untyped) -> Array[untyped]
 
@@ -28,6 +35,14 @@ module PaperTrailDiff
     # : (Array[untyped]) -> Array[untyped]?
     def self?.ambiguous_pair: (Array[untyped]) -> Array[untyped]?
 
+    # Ids order versions saved in one instant only when they count up in one
+    # table. Two version tables count separately, so ids there say nothing.
+    # : (untyped, untyped) -> bool
+    def self?.orderable_tie?: (untyped, untyped) -> bool
+
+    # : (untyped) -> untyped
+    def self?.version_table: (untyped) -> untyped
+
     # Versions sharing a timestamp, whether or not their ids order them. PT-AT
     # indexes association membership per version but resolves it by timestamp,
     # so association state cannot be told apart across such a pair even when the

data/sig/generated/paper_trail_diff/time_range.rbs

@@ -2,6 +2,10 @@
 
 module PaperTrailDiff
   # Validates and applies a finite wall-clock range without loading model state.
+  #
+  # A Date is a whole day and a String a local time, both in Time.zone, as
+  # Rails reads them, or in UTC without one: never the server's own zone. An
+  # inclusive Date end runs through that day.
   class TimeRange
     attr_reader begin_time: Time
 
@@ -41,12 +45,22 @@ module PaperTrailDiff
     # : (untyped, boundary: Symbol) -> Time
     def coerce_time: (untyped, boundary: Symbol) -> Time
 
-    # Active Support 8.0 and older warn, once per process, that `to_time` will
-    # change on a zoned time, so read zoned values without it. Every branch
-    # gives the same instant, so no spec (and no mutation) can tell them apart.
-    # mutant:disable
-    # : (untyped) -> Time
-    def time_value: (untyped) -> Time
+    # Anything else names its instant, and `getutc` reads it without
+    # `to_time`, which Active Support 8.0 and older warn will change on a
+    # zoned time, and without changing the caller's own value as `utc` does.
+    # : (untyped) -> untyped
+    def time_value: (untyped) -> untyped
+
+    # An inclusive date end runs through the day: to the next one's start.
+    # : (Range[untyped]) -> untyped
+    def end_value: (Range[untyped]) -> untyped
+
+    # A DateTime is a Date too, but names its instant.
+    # : (untyped) -> bool
+    def calendar_date?: (untyped) -> bool
+
+    # : () -> untyped
+    def zone: () -> untyped
 
     # : () -> void
     def validate_order!: () -> void

data/sig/generated/paper_trail_diff/timeline_builder.rbs

@@ -23,8 +23,8 @@ module PaperTrailDiff
     # : (RootVersionPlan) -> [Array[Step], RecordSnapshot?, RecordSnapshot?]
     def compare_history: (RootVersionPlan) -> [ Array[Step], RecordSnapshot?, RecordSnapshot? ]
 
-    # : (RootVersionPlan) -> Array[Step]
-    def build_steps: (RootVersionPlan) -> Array[Step]
+    # : (RootVersionPlan, untyped) -> Array[Step]
+    def build_steps: (RootVersionPlan, untyped) -> Array[Step]
 
     # : () -> [Array[Step], nil, nil]
     def empty_history: () -> [ Array[Step], nil, nil ]

data/sig/generated/paper_trail_diff/timeline_range.rbs

@@ -73,6 +73,8 @@ module PaperTrailDiff
     # : () -> untyped
     def ordered_versions: () -> untyped
 
+    # A batch passes each root the window it already moved to transaction
+    # edges; a single record's window is moved here.
     # : (untyped) -> TimeRange?
     def build_time_range: (untyped) -> TimeRange?
 

data/sig/generated/paper_trail_diff/timeline_snapshot_provider.rbs

@@ -1,23 +1,33 @@
 # Generated from lib/paper_trail_diff/timeline_snapshot_provider.rb with RBS::Inline
 
 module PaperTrailDiff
-  # Gives TimelineBuilder one-argument access to a range-prepared snapshot store.
+  # Prepares the snapshot store for TimelineBuilder, one root at a time.
   class TimelineSnapshotProvider
     # : (HistoricalSnapshotStore, live_snapshotter: untyped) -> void
     def initialize: (HistoricalSnapshotStore, live_snapshotter: untyped) -> void
 
-    # : (untyped, Array[untyped]) -> void
-    def prepare: (untyped, Array[untyped]) -> void
+    # : (untyped, Array[untyped]) -> PreparedTimelineSnapshots
+    def prepare: (untyped, Array[untyped]) -> PreparedTimelineSnapshots
+
+    @live_snapshotter: untyped
+
+    @store: HistoricalSnapshotStore
+  end
+
+  # One root's timeline snapshots, read with the history prepared for it.
+  # Adjacent steps share endpoints, so each immutable snapshot, including a
+  # nil create state, is kept for this root only and released with it, and
+  # batch memory does not retain every reconstructed graph.
+  class PreparedTimelineSnapshots
+    # : (PreparedHistory?, store: HistoricalSnapshotStore, live_snapshotter: untyped) -> void
+    def initialize: (PreparedHistory?, store: HistoricalSnapshotStore, live_snapshotter: untyped) -> void
 
     # A window closing on current state ends at the live record rather than at a
     # version, which is the one endpoint no version history can reconstruct.
     # : (untyped) -> RecordSnapshot?
     def call: (untyped) -> RecordSnapshot?
 
-    private
-
-    # : (untyped) -> RecordSnapshot?
-    def live_snapshot: (untyped) -> RecordSnapshot?
+    @history: PreparedHistory?
 
     @live_snapshotter: untyped
 

data/sig/generated/paper_trail_diff/transaction_cut.rbs

@@ -0,0 +1,94 @@
+# Generated from lib/paper_trail_diff/transaction_cut.rb with RBS::Inline
+
+module PaperTrailDiff
+  # Moves each edge of a wall-clock window that falls inside one of a root's
+  # transactions back to where that transaction began, so the transaction is
+  # wholly in the later window.
+  #
+  # PT-AT reads a root's associations at the start of the transaction of the
+  # root version it reifies. A window starting just after a child saved its
+  # part of such a transaction therefore starts from the state before that
+  # child's change, and one ending there ends at it too, so the change belonged
+  # to no window and surfaced at the next transaction, under its author.
+  #
+  # Only the root's own versions on either side of an edge are consulted:
+  # rows locked by an update keep two transactions of one root from
+  # interleaving, so a transaction holding a root version and crossing the edge
+  # holds the root's nearest version on one side of it. Each edge is moved from
+  # where it was asked for, never from where another edge moved, so adjacent
+  # windows move their shared edge alike.
+  module TransactionCut
+    # One edge of a window. A strict edge keeps versions recorded at its
+    # instant on the left, as an inclusive end does. A plain class rather than
+    # Data.define, which arrived in Ruby 3.2 while this gem supports 3.1.
+    class Edge
+      # : (Time, bool) -> void
+      def initialize: (Time, bool) -> void
+
+      # : (untyped) -> untyped
+      def left: (untyped) -> untyped
+
+      # : (untyped) -> untyped
+      def right: (untyped) -> untyped
+
+      # : (untyped, later: bool) -> untyped
+      def side: (untyped, later: bool) -> untyped
+
+      @strict: bool
+
+      @time: Time
+    end
+
+    # Roots per statement: two lookups each stays under SQLite's limit of 500
+    # terms in a compound SELECT.
+    SLICE: ::Integer
+
+    # The same as `windows` for a batch of roots, keyed by identity.
+    # : (Array[untyped], TimeRange?) -> Hash[Array[String], TimeRange]
+    def self.batch_windows: (Array[untyped], TimeRange?) -> Hash[Array[String], TimeRange]
+
+    # Where history for a batch must be read from: the earliest moved start.
+    # : (TimeRange?, Hash[Array[String], TimeRange]) -> Time?
+    def self.earliest_start: (TimeRange?, Hash[Array[String], TimeRange]) -> Time?
+
+    # The windows that move, keyed by root id. A root missing from the result
+    # keeps the window as asked.
+    # : (untyped, Array[untyped], TimeRange) -> Hash[String, TimeRange]
+    def self.windows: (untyped, Array[untyped], TimeRange) -> Hash[String, TimeRange]
+
+    # : (untyped) -> untyped
+    def self.transaction_versions: (untyped) -> untyped
+
+    # Each root's earliest start among its transactions that cross the edge.
+    # : (untyped, Array[untyped], Edge) -> Hash[String, Time]
+    def self.moved_edges: (untyped, Array[untyped], Edge) -> Hash[String, Time]
+
+    # The roots whose versions next to the edge each transaction holds.
+    # : (untyped, Array[untyped], Edge) -> Hash[untyped, Array[String]]
+    def self.nearest_roots: (untyped, Array[untyped], Edge) -> Hash[untyped, Array[String]]
+
+    # Each root's nearest versions on either side of an edge, as [id,
+    # transaction] pairs; versions tied at the nearest instant are all kept.
+    # One indexed lookup per root and side, where a single query over the
+    # roots would read every version before the edge. The lookups are written
+    # once with the root's id left open, as building a relation for each root
+    # costs more than the query. Rows read as SQL text come back as the adapter
+    # returns them, so the transaction is cast as the grouped query's keys are.
+    # : (untyped, Array[untyped], Edge) -> Array[[String, untyped]]
+    def self.nearest: (untyped, Array[untyped], Edge) -> Array[[ String, untyped ]]
+
+    # Both sides' lookups for a root whose id is each `?`.
+    # : (untyped, Edge) -> String
+    def self.nearest_lookups: (untyped, Edge) -> String
+
+    # : (untyped, Edge, bool) -> String
+    def self.nearest_lookup: (untyped, Edge, bool) -> String
+
+    # Where each transaction that has versions on both sides of the edge began.
+    # : (untyped, Array[untyped], Edge) -> Hash[untyped, Time]
+    def self.crossing_starts: (untyped, Array[untyped], Edge) -> Hash[untyped, Time]
+
+    # : (TimeRange, Time?, Time?) -> TimeRange
+    def self.moved: (TimeRange, Time?, Time?) -> TimeRange
+  end
+end

data/sig/generated/paper_trail_diff/traversal_preparer.rbs

@@ -3,30 +3,88 @@
 module PaperTrailDiff
   # Checks that a model can be traversed before any reconstruction starts, and
   # that association tracking is actually available when history is involved.
+  # `diagnose` reports the same refusals instead of raising the first.
   class TraversalPreparer
-    # : (tree: AssociationTree, traversal: AssociationTraversal) -> void
-    def initialize: (tree: AssociationTree, traversal: AssociationTraversal) -> void
+    # One reason to refuse a request: the error `call` raises, and the code
+    # and path `diagnose` reports.
+    class Refusal
+      attr_reader error: untyped
+
+      attr_reader code: Symbol
+
+      attr_reader message: String
+
+      attr_reader path: String?
+
+      # : (untyped, Symbol, String, ?String?) -> void
+      def initialize: (untyped, Symbol, String, ?String?) -> void
+    end
+
+    PROBLEMS: untyped
+
+    # Each model a path's history needs versions of and has none, with the
+    # refusal's code: the target, then each model a has_many :through goes
+    # through. A polymorphic target is not known until a row names it;
+    # `diagnose` reports that separately rather than guessing here.
+    # : (untyped) -> Array[[Symbol, untyped]]
+    def self.unversioned_models: (untyped) -> Array[[ Symbol, untyped ]]
+
+    # A has_many :through reads past membership from the versions of the
+    # models it goes through, so each of them needs history too.
+    # : (untyped) -> Array[untyped]
+    def self.through_models: (untyped) -> Array[untyped]
+
+    # : (tree: AssociationTree, traversal: AssociationTraversal, ?allow_approximate: bool) -> void
+    def initialize: (tree: AssociationTree, traversal: AssociationTraversal, ?allow_approximate: bool) -> void
 
     # : (untyped, historical: bool) -> void
     def call: (untyped, historical: bool) -> void
 
+    # Every reason to refuse a request over the model, in the order `call`
+    # raises them. Live-to-live comparison reads current state, so only the
+    # traversal itself is checked for it.
+    # : (untyped, historical: bool) -> Array[Refusal]
+    def refusals: (untyped, historical: bool) -> Array[Refusal]
+
     private
 
+    @allow_approximate: bool
+
+    @refusals: Hash[Array[untyped], Array[Refusal]]
+
     @traversal: AssociationTraversal
 
     @tree: AssociationTree
 
+    # : (untyped, bool) -> Array[Refusal]
+    def collect: (untyped, bool) -> Array[Refusal]
+
+    # : (untyped) -> Refusal?
+    def traversal_refusal: (untyped) -> Refusal?
+
+    # A path prepared history cannot read is read with PT-AT, which rebuilds
+    # an association from its current members, swapping in older versions of
+    # them. A record that entered the association since, such as one moved
+    # into a scope or restored from a soft delete, then reads as a member it
+    # was not, and one that left reads as missing. Only a caller who accepts
+    # that may read such a path.
+    # : (untyped) -> Array[Refusal]
+    def approximate_refusals: (untyped) -> Array[Refusal]
+
     # 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) -> Array[Refusal]
+    def unversioned_refusals: (untyped) -> Array[Refusal]
+
+    # : (String, untyped, Symbol) -> Refusal
+    def unversioned: (String, untyped, Symbol) -> Refusal
 
-    # : (untyped) -> bool
-    def versioned?: (untyped) -> bool
+    # : () -> bool
+    def association_tracking?: () -> bool
 
-    # : () -> void
-    def ensure_association_tracking!: () -> void
+    # : () -> Refusal
+    def tracking_refusal: () -> Refusal
   end
 end

data/sig/generated/paper_trail_diff/version_boundary.rbs

@@ -11,13 +11,30 @@ module PaperTrailDiff
     # : (untyped, untyped) -> bool
     def self?.at_or_after?: (untyped, untyped) -> bool
 
+    # A range starting at a version starts before that version's transaction,
+    # as PT-AT reads associations there. A version saved earlier in the same
+    # transaction, such as the child update behind a `touch: true` parent
+    # version, can be recorded before the start, so the start moves back to
+    # the earliest version of each root's first transaction in the range.
+    # History loaded from the start alone would read that child after its
+    # change.
+    # : (Array[untyped], untyped) -> untyped
+    def self?.transaction_start: (Array[untyped], untyped) -> untyped
+
+    # The transaction of each root's first version at or after the start.
+    # : (Array[untyped], untyped) -> Array[untyped]
+    def self?.opening_transactions: (Array[untyped], untyped) -> Array[untyped]
+
+    # 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
+
     # : (untyped) -> bool
     def self?.version_record?: (untyped) -> bool
 
     # : (untyped, untyped) -> bool
     def self?.same_version?: (untyped, untyped) -> bool
-
-    # : (untyped, untyped) -> bool
-    def self?.orderable_tie?: (untyped, untyped) -> bool
   end
 end

data/sig/generated/paper_trail_diff/version_query.rbs

@@ -9,13 +9,29 @@ module PaperTrailDiff
     # : (untyped) -> untyped
     def self?.chronological: (untyped) -> untyped
 
+    # Every version of a model's items. They are read from the version class
+    # rather than through the model's versions association, whose scope may
+    # leave some out: a history replayed without them credits their changes to
+    # the next version kept.
+    # : (untyped) -> untyped
+    def self?.for_model: (untyped) -> untyped
+
+    # The versions of the given items, read the same way.
+    # : (untyped, untyped) -> untyped
+    def self?.for_items: (untyped, untyped) -> untyped
+
     # 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 self?.no_earlier_version: (untyped) ?{ (untyped) -> untyped } -> untyped
 
-    # : (untyped, untyped) ?{ (untyped) -> untyped } -> untyped
-    def self?.earlier_version: (untyped, untyped) ?{ (untyped) -> untyped } -> untyped
+    # The same for either side of an instant: each item's earliest version
+    # when the versions lie after it, and its latest when they lie before.
+    # : (untyped, later: bool) ?{ (untyped) -> untyped } -> untyped
+    def self?.no_nearer_version: (untyped, later: bool) ?{ (untyped) -> untyped } -> untyped
+
+    # : (untyped, untyped, later: bool) ?{ (untyped) -> untyped } -> untyped
+    def self?.nearer_version: (untyped, untyped, later: bool) ?{ (untyped) -> untyped } -> untyped
   end
 end

data/sig/generated/paper_trail_diff/version_scope_filter.rbs

@@ -6,6 +6,10 @@ module PaperTrailDiff
   # caller, because the one that reveals the last selected mutation is drawn
   # from them.
   class VersionScopeFilter
+    # A filter is a callable that narrows the version relation.
+    # : (untyped) -> untyped
+    def self.validated: (untyped) -> untyped
+
     # : (untyped) -> void
     def initialize: (untyped) -> void
 
@@ -16,11 +20,6 @@ module PaperTrailDiff
     # : (untyped) -> Set[untyped]?
     def chosen_ids: (untyped) -> Set[untyped]?
 
-    private
-
     @scope: untyped
-
-    # : (untyped) -> untyped
-    def validated: (untyped) -> untyped
   end
 end

data/sig/generated/paper_trail_diff/version_sequence_diagnostics.rbs

@@ -3,17 +3,17 @@
 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: (untyped, untyped, ?associations_selected: bool) -> void
+    # : (untyped, untyped, ?fallback_selected: bool) -> void
+    def initialize: (untyped, untyped, ?fallback_selected: bool) -> void
 
     # : () -> Array[DiagnosticIssue]
     def call: () -> Array[DiagnosticIssue]
 
     private
 
-    @associations_selected: bool
+    @fallback_selected: bool
 
     @from_version: untyped
 
@@ -25,15 +25,22 @@ module PaperTrailDiff
     # : (Array[untyped]) -> DiagnosticIssue?
     def unorderable: (Array[untyped]) -> DiagnosticIssue?
 
-    # 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: (Array[untyped]) -> DiagnosticIssue?
 
     # : () -> Array[untyped]
     def ordered_range_versions: () -> Array[untyped]
+
+    # 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: () -> Range[untyped]?
   end
 end

data/sig/generated/paper_trail_diff/version_table.rbs

@@ -0,0 +1,30 @@
+# Generated from lib/paper_trail_diff/version_table.rb with RBS::Inline
+
+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: (untyped) -> String?
+
+    # 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: (untyped) -> untyped
+
+    # 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: (untyped, untyped) -> untyped
+
+    # : (untyped) -> String
+    def self.tables: (untyped) -> String
+  end
+end

data/sig/generated/paper_trail_diff.rbs

@@ -9,36 +9,33 @@ module PaperTrailDiff
   SUPPORTED_ASSOCIATION_MACROS: untyped
 
   # 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 self.compare: (untyped, untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?reload_live_endpoints: bool) -> Diff
+  # : (untyped, untyped, ?associations: association_option, ?ignore: ignore_option, ?reload_live_endpoints: bool?, ?allow_approximate: bool) -> Diff
+  def self.compare: (untyped, untyped, ?associations: association_option, ?ignore: ignore_option, ?reload_live_endpoints: bool?, ?allow_approximate: bool) -> Diff
 
   # 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 self.compare_many: (Array[comparison_input], ?associations: Array[String | Symbol], ?ignore: ignore_option, ?reload_live_endpoints: bool, ?allow_expensive: bool) -> comparison_results
+  # : (Array[comparison_input], ?associations: association_option, ?ignore: ignore_option, ?reload_live_endpoints: bool?, ?allow_expensive: bool?, ?allow_approximate: bool) -> comparison_results
+  def self.compare_many: (Array[comparison_input], ?associations: association_option, ?ignore: ignore_option, ?reload_live_endpoints: bool?, ?allow_expensive: bool?, ?allow_approximate: bool) -> comparison_results
 
   # 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 self.timeline: (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 self.timeline: (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: association_option, ?ignore: ignore_option, ?version_scope: untyped, ?close_on: Symbol?, ?allow_approximate: bool) -> Array[Step]
 
   # 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]
-  def self.activity_timeline: (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 self.activity_timeline: (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]
 
   # 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
-  def self.analyze: (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 self.analyze: (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
 
   # 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 self.analyze_many: (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 self.analyze_many: (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]
 
   # Analyzes every root the relation reaches whose history moved inside the
   # window. With `activity: true`, a change to a record on one of the
@@ -66,15 +63,19 @@ module PaperTrailDiff
   # 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
-  def self.analyze_scope: (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 self.analyze_scope: (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
 
   # Recent root and selected-child activity through the current saved state,
   # 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
-  def self.report: (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 self.report: (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
+
+  # Warns about deprecated options; see Deprecation.
+  # : () -> untyped
+  def self.deprecator: () -> untyped
 
   # Returns the association macros this release can normalize.
   # : () -> Array[Symbol]
@@ -84,9 +85,11 @@ module PaperTrailDiff
   # : (untyped, ?max_depth: Integer) -> Array[AssociationDescriptor]
   def self.association_paths: (untyped, ?max_depth: Integer) -> Array[AssociationDescriptor]
 
-  # Reports known reconstruction hazards without mutating application state.
-  # : (untyped, untyped, ?associations: Array[String | Symbol]) -> DiagnosticReport
-  def self.diagnose: (untyped, untyped, ?associations: Array[String | Symbol]) -> DiagnosticReport
+  # 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 self.diagnose: (untyped, untyped, ?associations: association_option, ?allow_approximate: bool) -> DiagnosticReport
 
   # Looks inside an attribute the database stores whole, such as a JSON or
   # jsonb column, and reports which keys changed.
@@ -111,9 +114,7 @@ module PaperTrailDiff
 
   # 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.
@@ -149,10 +150,12 @@ module PaperTrailDiff
 
   type comparison_results = Hash[identity, Diff]
 
-  type report_options = { within: untyped, activity: bool, version_scope: untyped, close_on: Symbol?, snapshots: bool, group: Symbol? }
+  type report_options = { 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