paper_trail_diff 0.4.0 → 0.6.0

data/sig/generated/paper_trail_diff/analysis_batch.rbs

@@ -0,0 +1,49 @@
+# Generated from lib/paper_trail_diff/analysis_batch.rb with RBS::Inline
+
+module PaperTrailDiff
+  # Builds one Analysis per root over a shared range, selecting every root's
+  # versions and preparing their association history once for the whole batch
+  # rather than once per root.
+  class AnalysisBatch
+    # : (Array[untyped], time_range: TimeRange?, live_loader: untyped, history_preparer: untyped, analyzer: untyped, ?version_scope: untyped) -> void
+    def initialize: (Array[untyped], time_range: TimeRange?, live_loader: untyped, history_preparer: untyped, analyzer: untyped, ?version_scope: untyped) -> void
+
+    # : () -> Hash[identity, Analysis]
+    def call: () -> Hash[identity, Analysis]
+
+    private
+
+    @analyzer: untyped
+
+    @history_preparer: untyped
+
+    @live_loader: untyped
+
+    @records: Array[untyped]
+
+    @time_range: TimeRange?
+
+    @version_scope: untyped
+
+    # A filter is a callable that narrows the version relation, so it is checked
+    # up front rather than failing partway through a batch.
+    # : (untyped) -> untyped
+    def validated_scope: (untyped) -> untyped
+
+    # : () -> Array[untyped]
+    def validated_records: () -> Array[untyped]
+
+    # Association history is prepared per model class across every selected root
+    # version, which is the work that would otherwise repeat for each record.
+    # The roots are preloaded first, because preparation reads their current
+    # association state as a fallback and would otherwise walk it one root at a
+    # time.
+    # : (Array[untyped], Hash[Array[String], RootVersionPlan]) -> void
+    def prepare: (Array[untyped], Hash[Array[String], RootVersionPlan]) -> void
+
+    # A root with no versions in range has nothing to report, which is an empty
+    # result rather than a failed request.
+    # : (untyped, RootVersionPlan) -> Analysis
+    def analysis_for: (untyped, RootVersionPlan) -> Analysis
+  end
+end

data/sig/generated/paper_trail_diff/batch_boundary_resolver.rbs

@@ -0,0 +1,62 @@
+# Generated from lib/paper_trail_diff/batch_boundary_resolver.rb with RBS::Inline
+
+module PaperTrailDiff
+  # Resolves `:first` and `:last` endpoints for a whole batch in two queries per
+  # model class. Left to the caller this is a per-root lookup, which reintroduces
+  # exactly the queries a batched comparison exists to remove.
+  class BatchBoundaryResolver
+    BOUNDARIES: untyped
+
+    # : (untyped) -> bool
+    def self.symbolic?: (untyped) -> bool
+
+    # : (Array[[untyped, untyped]]) -> void
+    def initialize: (Array[[ untyped, untyped ]]) -> void
+
+    # Returns the pairs with every resolvable symbol replaced. A symbol that
+    # names history the record does not have is left in place, so the caller can
+    # decide what an absent history means rather than being handed nil.
+    # : () -> Array[[untyped, untyped]]
+    def call: () -> Array[[ untyped, untyped ]]
+
+    private
+
+    @pairs: Array[[ untyped, untyped ]]
+
+    # : (untyped) -> bool
+    def symbolic?: (untyped) -> bool
+
+    # : (untyped, untyped, Hash[Array[String], Hash[Symbol, untyped]]) -> untyped
+    def resolve: (untyped, untyped, Hash[Array[String], Hash[Symbol, untyped]]) -> untyped
+
+    # A symbol carries no identity of its own, so the pair's other endpoint has
+    # to say which record is meant.
+    # : (untyped) -> Array[String]?
+    def anchor_identity: (untyped) -> Array[String]?
+
+    # : () -> Hash[Array[String], Hash[Symbol, untyped]]
+    def boundary_index: () -> Hash[Array[String], Hash[Symbol, untyped]]
+
+    # : () -> Array[[untyped, untyped]]
+    def anchors: () -> Array[[ untyped, untyped ]]
+
+    # : (untyped) -> [untyped, untyped]?
+    def anchor: (untyped) -> [ untyped, untyped ]?
+
+    # : (Hash[Array[String], Hash[Symbol, untyped]], untyped, Array[untyped]) -> void
+    def add_model_boundaries: (Hash[Array[String], Hash[Symbol, untyped]], untyped, Array[untyped]) -> void
+
+    # Two grouped queries name each root's outermost versions, and one more
+    # loads them, whatever the size of the batch.
+    # : (untyped, Array[untyped]) -> [Hash[untyped, untyped], Hash[untyped, untyped], Hash[untyped, untyped]]
+    def boundary_versions: (untyped, Array[untyped]) -> [ Hash[untyped, untyped], Hash[untyped, untyped], Hash[untyped, untyped] ]
+
+    # Grouped keys come back with whatever type the column uses, so match on the
+    # string form rather than assuming integers.
+    # : (Hash[untyped, untyped], untyped) -> untyped
+    def boundary_key: (Hash[untyped, untyped], untyped) -> untyped
+
+    # : (untyped, untyped) -> Array[String]
+    def identity_key: (untyped, untyped) -> Array[String]
+  end
+end

data/sig/generated/paper_trail_diff/batched_root_analyzer.rbs

@@ -0,0 +1,28 @@
+# Generated from lib/paper_trail_diff/batched_root_analyzer.rb with RBS::Inline
+
+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) -> void
+    def initialize: (tree: AssociationTree, timeline_snapshotter: untyped, activity_snapshotter: untyped, preparer: untyped, activity: bool) -> void
+
+    # : (untyped, RootVersionPlan) -> Analysis
+    def call: (untyped, RootVersionPlan) -> Analysis
+
+    private
+
+    @activity: bool
+
+    @activity_snapshotter: untyped
+
+    @preparer: untyped
+
+    @timeline_snapshotter: untyped
+
+    @tree: AssociationTree
+
+    # : (untyped, RootVersionPlan) -> Analysis
+    def activity_analysis: (untyped, RootVersionPlan) -> Analysis
+  end
+end

data/sig/generated/paper_trail_diff/batched_root_versions.rbs

@@ -0,0 +1,69 @@
+# Generated from lib/paper_trail_diff/batched_root_versions.rb with RBS::Inline
+
+module PaperTrailDiff
+  # Selects each root's versions for a batched range in a fixed number of
+  # 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) -> void
+    def initialize: (Array[untyped], time_range: TimeRange?, ?version_scope: untyped) -> void
+
+    # Returns a plan per record identity.
+    # : () -> Hash[Array[String], RootVersionPlan]
+    def call: () -> Hash[Array[String], RootVersionPlan]
+
+    private
+
+    @records: Array[untyped]
+
+    @time_range: TimeRange?
+
+    @version_scope: untyped
+
+    # : (untyped, Array[untyped], Hash[Array[String], RootVersionPlan]) -> void
+    def select_model: (untyped, Array[untyped], Hash[Array[String], RootVersionPlan]) -> void
+
+    # : (untyped, Array[untyped]) -> [Hash[String, Array[untyped]], Set[untyped]?, Hash[String, untyped]]
+    def model_versions: (untyped, Array[untyped]) -> [ Hash[String, Array[untyped]], Set[untyped]?, Hash[String, untyped] ]
+
+    # : (Array[untyped], Set[untyped]?, untyped) -> RootVersionPlan
+    def versions_for: (Array[untyped], Set[untyped]?, untyped) -> RootVersionPlan
+
+    # One extra query names the selected mutations without discarding the
+    # unfiltered versions the successor lookup still needs.
+    # : (untyped, Array[untyped], TimeRange?) -> Set[untyped]?
+    def chosen_version_ids: (untyped, Array[untyped], TimeRange?) -> Set[untyped]?
+
+    # : (untyped, Array[untyped], TimeRange?) -> Hash[String, Array[untyped]]
+    def grouped_versions: (untyped, Array[untyped], TimeRange?) -> Hash[String, Array[untyped]]
+
+    # : (untyped, Array[untyped], TimeRange?) -> untyped
+    def range_scope: (untyped, Array[untyped], TimeRange?) -> untyped
+
+    # One row per root: the earliest version after the window, found without a
+    # window function so the query stays portable.
+    # : (untyped, Array[untyped], TimeRange) -> Hash[String, untyped]
+    def trailing_versions: (untyped, Array[untyped], TimeRange) -> Hash[String, untyped]
+
+    # : (untyped, TimeRange) -> untyped
+    def no_earlier_trailing: (untyped, TimeRange) -> untyped
+
+    # Mirrors the window's own end handling, so a version sitting exactly on an
+    # inclusive boundary stays inside the window instead of masking the trailing
+    # version that follows it.
+    # : (untyped, untyped, TimeRange) -> untyped
+    def preceding: (untyped, untyped, TimeRange) -> untyped
+
+    # : (untyped, TimeRange) -> untyped
+    def after_window: (untyped, TimeRange) -> untyped
+
+    # : (untyped, Array[untyped]) -> untyped
+    def base_scope: (untyped, Array[untyped]) -> untyped
+
+    # : (untyped) -> Array[untyped]
+    def ordered: (untyped) -> Array[untyped]
+
+    # : (untyped, untyped) -> Array[String]
+    def identity: (untyped, untyped) -> Array[String]
+  end
+end

data/sig/generated/paper_trail_diff/comparison_batch.rbs

@@ -23,6 +23,21 @@ module PaperTrailDiff
 
     @preparer: untyped
 
+    # : (Array[[untyped, untyped]]) -> Hash[identity, RecordSnapshot]
+    def prepared_live_snapshots: (Array[[ untyped, untyped ]]) -> Hash[identity, RecordSnapshot]
+
+    # : (untyped) -> bool
+    def symbolic?: (untyped) -> bool
+
+    # A boundary symbol that stayed unresolved means the root has no recorded
+    # history. An absent history is an empty result rather than a failed
+    # request, matching how the timeline APIs answer the same question.
+    # : (Array[[untyped, untyped]], Hash[identity, RecordSnapshot]) -> comparison_results
+    def results: (Array[[ untyped, untyped ]], Hash[identity, RecordSnapshot]) -> comparison_results
+
+    # : (untyped, untyped) -> identity
+    def entry_identity: (untyped, untyped) -> identity
+
     # : (untyped, untyped, Hash[identity, RecordSnapshot]) -> Diff
     def compare: (untyped, untyped, Hash[identity, RecordSnapshot]) -> Diff
 

data/sig/generated/paper_trail_diff/historical_snapshot_store.rbs

@@ -9,7 +9,6 @@ module PaperTrailDiff
     # : (untyped, Array[untyped], ?start_at: untyped, ?end_at: untyped) -> void
     def prepare: (untyped, Array[untyped], ?start_at: untyped, ?end_at: untyped) -> void
 
-    # Prepares selected history for several roots of the same model class.
     # : (Array[untyped], Array[untyped]) -> void
     def prepare_batch: (Array[untyped], Array[untyped]) -> void
 

data/sig/generated/paper_trail_diff/paper_trail_adapter.rbs

@@ -1,7 +1,10 @@
 # Generated from lib/paper_trail_diff/paper_trail_adapter.rb with RBS::Inline
 
 module PaperTrailDiff
-  # PaperTrail/ActiveRecord boundary that produces plain record snapshots.
+  # PaperTrail/ActiveRecord boundary that produces plain record snapshots. It is
+  # deliberately the widest class here: it fronts every public operation and is
+  # the only place allowed to know about both PaperTrail and the pure engine.
+  # Reconstruction logic lives in the collaborators it wires together.
   class PaperTrailAdapter
     # : (associations: Array[String | Symbol], ignore: ignore_option, ?reload_live_endpoints: bool) -> void
     def initialize: (associations: Array[String | Symbol], ignore: ignore_option, ?reload_live_endpoints: bool) -> void
@@ -13,14 +16,18 @@ module PaperTrailDiff
     # : (Array[comparison_input]) -> comparison_results
     def compare_many: (Array[comparison_input]) -> comparison_results
 
-    # : (untyped, from: untyped, to: untyped, within: untyped) -> Array[Step]
-    def timeline: (untyped, from: untyped, to: untyped, within: untyped) -> Array[Step]
+    # : (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped) -> Array[Step]
+    def timeline: (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped) -> Array[Step]
 
-    # : (untyped, from: untyped, to: untyped, within: untyped) -> Array[ActivityStep]
-    def activity_timeline: (untyped, from: untyped, to: untyped, within: untyped) -> Array[ActivityStep]
+    # : (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped) -> Array[ActivityStep]
+    def activity_timeline: (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped) -> Array[ActivityStep]
 
-    # : (untyped, from: untyped, to: untyped, within: untyped, ?activity: bool) -> Analysis
-    def analyze: (untyped, from: untyped, to: untyped, within: untyped, ?activity: bool) -> Analysis
+    # : (untyped, from: untyped, to: untyped, within: untyped, ?activity: bool, ?version_scope: untyped) -> Analysis
+    def analyze: (untyped, from: untyped, to: untyped, within: untyped, ?activity: bool, ?version_scope: untyped) -> Analysis
+
+    # Analyzes many roots over one shared range, preparing their history once.
+    # : (Array[untyped], within: untyped, ?activity: bool, ?version_scope: untyped) -> Hash[identity, Analysis]
+    def analyze_many: (Array[untyped], within: untyped, ?activity: bool, ?version_scope: untyped) -> Hash[identity, Analysis]
 
     private
 
@@ -44,14 +51,22 @@ module PaperTrailDiff
 
     @traversal: AssociationTraversal
 
+    @traversal_preparer: TraversalPreparer
+
+    # : () -> void
+    def build_snapshotters: () -> void
+
+    # : (bool) -> BatchedRootAnalyzer
+    def batched_root_analyzer: (bool) -> BatchedRootAnalyzer
+
     # : () -> HistoricalSnapshotStore
     def build_historical_store: () -> HistoricalSnapshotStore
 
     # : () -> ActivitySnapshotProvider
     def build_activity_snapshotter: () -> ActivitySnapshotProvider
 
-    # : (untyped, from: untyped, to: untyped, within: untyped) -> ActivityTimelineBuilder
-    def activity_builder: (untyped, from: untyped, to: untyped, within: untyped) -> ActivityTimelineBuilder
+    # : (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped) -> ActivityTimelineBuilder
+    def activity_builder: (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped) -> ActivityTimelineBuilder
 
     # : (untyped) -> void
     def reject_live_habtm_activity!: (untyped) -> void
@@ -73,11 +88,5 @@ module PaperTrailDiff
 
     # : (untyped) -> RecordSnapshot
     def normalize_live_snapshot: (untyped) -> RecordSnapshot
-
-    # : (untyped, historical: bool) -> void
-    def prepare_traversal!: (untyped, historical: bool) -> void
-
-    # : () -> void
-    def ensure_association_tracking!: () -> void
   end
 end

data/sig/generated/paper_trail_diff/root_version_plan.rbs

@@ -0,0 +1,56 @@
+# Generated from lib/paper_trail_diff/root_version_plan.rb with RBS::Inline
+
+module PaperTrailDiff
+  # Which versions a range reconstructs, and which pairs of them become steps.
+  #
+  # Without a filter those are the same thing: every selected version is a
+  # boundary and adjacent ones bound each other. A filter separates them, because
+  # each selected mutation then has to be bounded by the version that actually
+  # reveals it rather than by the next mutation that happened to be selected.
+  #
+  # A filter also separates what is *reported* from what has to be *replayed*.
+  # The activity view rebuilds state by carrying one snapshot forward across
+  # every event in order, so skipping a filtered-out version would leave that
+  # snapshot holding a state the record had already moved past. `versions` are
+  # the boundaries the steps refer to; `reconstruction_versions` are every root
+  # version the span passes through, which is what any forward replay must walk.
+  class RootVersionPlan
+    attr_reader versions: Array[untyped]
+
+    attr_reader reconstruction_versions: Array[untyped]
+
+    attr_reader steps: Array[[ untyped, untyped ]]
+
+    attr_reader context_version: untyped
+
+    # The root versions this plan reports as mutations, which excludes any
+    # version present only to reveal what the last of them produced.
+    attr_reader mutations: Array[untyped]
+
+    # Adjacent boundaries, which is what an unfiltered range reports.
+    # : (Array[untyped], ?context_version: untyped) -> RootVersionPlan
+    def self.contiguous: (Array[untyped], ?context_version: untyped) -> RootVersionPlan
+
+    # : () -> RootVersionPlan
+    def self.empty: () -> RootVersionPlan
+
+    # : (versions: Array[untyped], steps: Array[[untyped, untyped]], ?context_version: untyped, ?reconstruction_versions: Array[untyped]?, ?mutations: Array[untyped]?) -> void
+    def initialize: (versions: Array[untyped], steps: Array[[ untyped, untyped ]], ?context_version: untyped, ?reconstruction_versions: Array[untyped]?, ?mutations: Array[untyped]?) -> void
+
+    # : () -> bool
+    def empty?: () -> bool
+
+    # : (untyped) -> bool
+    def mutation?: (untyped) -> bool
+
+    private
+
+    @mutation_keys: Set[Array[untyped]]
+
+    # : () -> Array[untyped]
+    def default_mutations: () -> Array[untyped]
+
+    # : (untyped) -> Array[untyped]
+    def key: (untyped) -> Array[untyped]
+  end
+end

data/sig/generated/paper_trail_diff/root_version_selection.rbs

@@ -0,0 +1,77 @@
+# Generated from lib/paper_trail_diff/root_version_selection.rb with RBS::Inline
+
+module PaperTrailDiff
+  # Decides which versions a range reports, and which one reveals the last of
+  # them. A version records the state before its own event, so whatever follows
+  # the final selected mutation is the only thing that can show what it produced.
+  # That successor is reconstruction context rather than a reported mutation, so
+  # a filter must never remove it.
+  #
+  # Both the single-record and the batched selectors resolve this here, because
+  # the rule is subtle enough that two copies of it would drift apart.
+  class RootVersionSelection
+    INCOMPLETE: ::String
+
+    # : (in_range: Array[untyped], selected: Array[untyped], after_range: untyped, windowed: bool, ?context_required: bool, ?filtered: bool) -> void
+    def initialize: (in_range: Array[untyped], selected: Array[untyped], after_range: untyped, windowed: bool, ?context_required: bool, ?filtered: bool) -> void
+
+    # : () -> RootVersionPlan
+    def call: () -> RootVersionPlan
+
+    private
+
+    @after_range: untyped
+
+    @context_required: bool
+
+    @filtered: bool
+
+    @in_range: Array[untyped]
+
+    @selected: Array[untyped]
+
+    @windowed: bool
+
+    # An activity view still needs a root to reconstruct from even when no root
+    # version falls inside the window, because descendants may have moved.
+    # : () -> RootVersionPlan
+    def without_selection: () -> RootVersionPlan
+
+    # Each selected mutation is bounded by the version that reveals it, not by
+    # the next mutation that happened to be selected. Bounding by the next
+    # selection would fold anything filtered out in between into it, so the same
+    # edit would read differently depending on what followed it.
+    # : (untyped) -> RootVersionPlan
+    def filtered_plan: (untyped) -> RootVersionPlan
+
+    # Nothing can follow a destroy, so it never pairs into a step. It is still a
+    # selected mutation, and the activity view closes on the absence it leaves,
+    # so it has to stay a boundary or a filtered report loses the deletion
+    # entirely — the one event it can least afford to drop.
+    # : () -> Array[untyped]
+    def closing_versions: () -> Array[untyped]
+
+    # Everything the span passes through, filtered out or not. A replay that
+    # skipped the excluded versions would carry a stale state into the next
+    # reported step, so the two selected mutations either side of a gap would
+    # disagree about what the record looked like between them.
+    # : (Array[untyped]) -> Array[untyped]
+    def spanned: (Array[untyped]) -> Array[untyped]
+
+    # : (Array[untyped]) -> Array[untyped]
+    def chronological: (Array[untyped]) -> Array[untyped]
+
+    # : (untyped) -> untyped
+    def immediate_successor: (untyped) -> untyped
+
+    # A version left out by a filter is still the state the last selected change
+    # produced, so it is preferred over anything after the range.
+    # : () -> untyped
+    def revealing_version: () -> untyped
+
+    # A range closing on the record's own destruction needs no later version:
+    # nothing can follow it, so demanding one would reject the range forever.
+    # : () -> bool
+    def terminal_destroy?: () -> bool
+  end
+end

data/sig/generated/paper_trail_diff/time_activity_timeline_builder.rbs

@@ -22,8 +22,8 @@ module PaperTrailDiff
 
     @tree: AssociationTree
 
-    # : () -> [ActivityHistory, Array[untyped], ActivityStep?]
-    def history_and_versions: () -> [ ActivityHistory, Array[untyped], ActivityStep? ]
+    # : () -> [ActivityHistory, RootVersionPlan, ActivityStep?]
+    def history_and_versions: () -> [ ActivityHistory, RootVersionPlan, ActivityStep? ]
 
     # : (Array[untyped], Array[ActivityEvent]) -> ActivityHistory
     def build_history: (Array[untyped], Array[ActivityEvent]) -> ActivityHistory
@@ -31,8 +31,13 @@ module PaperTrailDiff
     # : (ActivityHistory, ActivityStep?) -> Array[ActivityStep]
     def activity_steps: (ActivityHistory, ActivityStep?) -> Array[ActivityStep]
 
-    # : (Array[ActivityEvent]) -> Array[ActivityEvent]
-    def selected_events: (Array[ActivityEvent]) -> Array[ActivityEvent]
+    # Root versions inside the window that the plan does not report are context
+    # rather than mutations: the version appended to reveal the last selected
+    # change, and anything a filter excluded but the replay still walks. Neither
+    # may be counted as a selected mutation. Descendant events are not filtered,
+    # so window membership is the whole test for them.
+    # : (Array[ActivityEvent], RootVersionPlan) -> Array[ActivityEvent]
+    def selected_events: (Array[ActivityEvent], RootVersionPlan) -> Array[ActivityEvent]
 
     # The window's last selected mutation is the root's own destruction, so the
     # timeline closes on the absence it leaves rather than on a later boundary.

data/sig/generated/paper_trail_diff/time_version_range.rbs

@@ -3,28 +3,26 @@
 module PaperTrailDiff
   # Selects in-range root versions plus one later reconstruction boundary.
   class TimeVersionRange
-    # : (untyped, time_range: TimeRange) -> void
-    def initialize: (untyped, time_range: TimeRange) -> void
+    # : (untyped, time_range: TimeRange, ?version_scope: untyped) -> void
+    def initialize: (untyped, time_range: TimeRange, ?version_scope: untyped) -> void
 
     # : (?context_required: bool) -> Array[untyped]
     def select: (?context_required: bool) -> Array[untyped]
 
+    # : (?context_required: bool) -> RootVersionPlan
+    def select_plan: (?context_required: bool) -> RootVersionPlan
+
     private
 
     @record: untyped
 
     @time_range: TimeRange
 
+    @version_scope: untyped
+
     # : () -> untyped
     def versions_relation: () -> untyped
 
-    # A window closing on the record's own destruction needs no later version:
-    # the destroy reveals the preceding mutation and nothing can follow it, so
-    # demanding a checkpoint that can never be written would reject the range
-    # permanently.
-    # : (Array[untyped]) -> bool
-    def terminal_destroy?: (Array[untyped]) -> bool
-
     # : (untyped) -> untyped
     def trailing_version: (untyped) -> untyped
 

data/sig/generated/paper_trail_diff/timeline_builder.rbs

@@ -3,8 +3,8 @@
 module PaperTrailDiff
   # Selects and compares a chronological slice of a record's version history.
   class TimelineBuilder
-    # : (untyped, from: untyped, to: untyped, snapshotter: untyped, ?within: untyped) -> void
-    def initialize: (untyped, from: untyped, to: untyped, snapshotter: untyped, ?within: untyped) -> void
+    # : (untyped, from: untyped, to: untyped, snapshotter: untyped, ?within: untyped, ?versions: Array[untyped]?, ?version_scope: untyped, ?plan: RootVersionPlan?) -> void
+    def initialize: (untyped, from: untyped, to: untyped, snapshotter: untyped, ?within: untyped, ?versions: Array[untyped]?, ?version_scope: untyped, ?plan: RootVersionPlan?) -> void
 
     # : () -> Array[Step]
     def build: () -> Array[Step]
@@ -20,13 +20,13 @@ module PaperTrailDiff
 
     @snapshotter: untyped
 
-    # : (Array[untyped]) -> [Array[Step], RecordSnapshot?, RecordSnapshot?]
-    def compare_history: (Array[untyped]) -> [ Array[Step], RecordSnapshot?, RecordSnapshot? ]
+    # : (RootVersionPlan) -> [Array[Step], RecordSnapshot?, RecordSnapshot?]
+    def compare_history: (RootVersionPlan) -> [ Array[Step], RecordSnapshot?, RecordSnapshot? ]
 
     # : () -> [Array[Step], nil, nil]
     def empty_history: () -> [ Array[Step], nil, nil ]
 
-    # : () -> Array[untyped]
-    def selected_versions: () -> Array[untyped]
+    # : () -> RootVersionPlan
+    def selected_versions: () -> RootVersionPlan
   end
 end

data/sig/generated/paper_trail_diff/timeline_range.rbs

@@ -11,14 +11,21 @@ module PaperTrailDiff
 
     attr_reader time_range: TimeRange?
 
-    # : (untyped, from: untyped, to: untyped, within: untyped) -> void
-    def initialize: (untyped, from: untyped, to: untyped, within: untyped) -> void
+    # : (untyped, from: untyped, to: untyped, within: untyped, ?versions: Array[untyped]?, ?version_scope: untyped, ?plan: RootVersionPlan?) -> void
+    def initialize: (untyped, from: untyped, to: untyped, within: untyped, ?versions: Array[untyped]?, ?version_scope: untyped, ?plan: RootVersionPlan?) -> void
 
     # A record with no versions has no first or last boundary to resolve, which
     # is an empty history rather than a bad request.
     # : () -> bool
     def unresolved?: () -> bool
 
+    # A batch may have selected these versions already, in which case reselecting
+    # them per record would undo the batching.
+    # The plan says which pairs of versions become steps, which a filter can
+    # make different from adjacent pairs of the selected versions.
+    # : (?context_required: bool) -> RootVersionPlan
+    def select_plan: (?context_required: bool) -> RootVersionPlan
+
     # : (?context_required: bool) -> Array[untyped]
     def select: (?context_required: bool) -> Array[untyped]
 
@@ -35,6 +42,8 @@ module PaperTrailDiff
 
     @from: untyped
 
+    @plan: RootVersionPlan?
+
     @record: untyped
 
     @requested_from: untyped
@@ -43,6 +52,10 @@ module PaperTrailDiff
 
     @to: untyped
 
+    @version_scope: untyped
+
+    @versions: Array[untyped]?
+
     # : () -> Array[untyped]
     def empty_versions: () -> Array[untyped]
 

data/sig/generated/paper_trail_diff/traversal_preparer.rbs

@@ -0,0 +1,22 @@
+# Generated from lib/paper_trail_diff/traversal_preparer.rb with RBS::Inline
+
+module PaperTrailDiff
+  # Checks that a model can be traversed before any reconstruction starts, and
+  # that association tracking is actually available when history is involved.
+  class TraversalPreparer
+    # : (tree: AssociationTree, traversal: AssociationTraversal) -> void
+    def initialize: (tree: AssociationTree, traversal: AssociationTraversal) -> void
+
+    # : (untyped, historical: bool) -> void
+    def call: (untyped, historical: bool) -> void
+
+    private
+
+    @traversal: AssociationTraversal
+
+    @tree: AssociationTree
+
+    # : () -> void
+    def ensure_association_tracking!: () -> void
+  end
+end

data/sig/generated/paper_trail_diff/version_range.rbs

@@ -3,8 +3,15 @@
 module PaperTrailDiff
   # Selects an inclusive, chronological range from a record's root versions.
   class VersionRange
-    # : (untyped, from: untyped, to: untyped) -> void
-    def initialize: (untyped, from: untyped, to: untyped) -> void
+    # : (untyped, from: untyped, to: untyped, ?version_scope: untyped) -> void
+    def initialize: (untyped, from: untyped, to: untyped, ?version_scope: untyped) -> void
+
+    # Same selection as `select`, but keeping the step pairs a filter implies.
+    # : () -> RootVersionPlan
+    def select_plan_for_range: () -> RootVersionPlan
+
+    # : () -> untyped
+    def validated_relation: () -> untyped
 
     # : () -> Array[untyped]
     def select: () -> Array[untyped]
@@ -20,12 +27,20 @@ module PaperTrailDiff
 
     @to: untyped
 
+    @version_scope: untyped
+
     # : () -> untyped
     def versions_relation: () -> untyped
 
     # : (untyped, ?through: untyped) -> Array[untyped]
     def select_relation: (untyped, ?through: untyped) -> Array[untyped]
 
+    # : (untyped, ?through: untyped) -> RootVersionPlan
+    def select_plan: (untyped, ?through: untyped) -> RootVersionPlan
+
+    # : (Array[untyped]) -> Array[untyped]
+    def ordered: (Array[untyped]) -> Array[untyped]
+
     # : (untyped, untyped, boundary: Symbol) -> void
     def validate_boundary!: (untyped, untyped, boundary: Symbol) -> void