paper_trail_diff 0.5.0 → 0.7.0

data/sig/generated/paper_trail_diff/batched_root_versions.rbs

@@ -5,34 +5,48 @@ 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?) -> void
-    def initialize: (Array[untyped], time_range: TimeRange?) -> void
+    # : (Array[untyped], time_range: TimeRange?, ?version_scope: untyped, ?live_endpoints: Hash[Array[String], untyped]?) -> void
+    def initialize: (Array[untyped], time_range: TimeRange?, ?version_scope: untyped, ?live_endpoints: Hash[Array[String], untyped]?) -> void
 
-    # Returns root versions per record identity, in chronological order.
-    # : () -> Hash[Array[String], Array[untyped]]
-    def call: () -> Hash[Array[String], Array[untyped]]
+    # Returns a plan per record identity.
+    # : () -> Hash[Array[String], RootVersionPlan]
+    def call: () -> Hash[Array[String], RootVersionPlan]
 
     private
 
+    @live_endpoints: Hash[Array[String], untyped]?
+
     @records: Array[untyped]
 
     @time_range: TimeRange?
 
-    # : (untyped, Array[untyped], Hash[Array[String], Array[untyped]]) -> void
-    def select_model: (untyped, Array[untyped], Hash[Array[String], Array[untyped]]) -> void
+    @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] ]
 
-    # The window's own versions plus, when it has one, the later version needed
-    # to reveal the last mutation inside it. A window closing on the root's own
-    # destruction needs no later version, because none can exist.
-    # : (Array[untyped], untyped) -> Array[untyped]
-    def versions_for: (Array[untyped], untyped) -> Array[untyped]
+    # : (Array[untyped], Set[untyped]?, untyped, untyped) -> RootVersionPlan
+    def versions_for: (Array[untyped], Set[untyped]?, untyped, untyped) -> RootVersionPlan
 
-    # : (Array[untyped]) -> bool
-    def terminal_destroy?: (Array[untyped]) -> bool
+    # The batch already loaded every root, so closing on current state reuses
+    # that rather than reading each record again.
+    # : (Array[String], untyped) -> untyped
+    def live_endpoint: (Array[String], untyped) -> untyped
+
+    # 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]

data/sig/generated/paper_trail_diff/paper_trail_adapter.rbs

@@ -6,6 +6,9 @@ module PaperTrailDiff
   # the only place allowed to know about both PaperTrail and the pure engine.
   # Reconstruction logic lives in the collaborators it wires together.
   class PaperTrailAdapter
+    # The only thing a wall-clock window can close on besides a later version.
+    CLOSE_ON_CURRENT: ::Symbol
+
     # : (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
 
@@ -16,18 +19,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, ?close_on: Symbol?) -> Array[Step]
+    def timeline: (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped, ?close_on: Symbol?) -> 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, ?close_on: Symbol?) -> Array[ActivityStep]
+    def activity_timeline: (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped, ?close_on: Symbol?) -> 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, ?close_on: Symbol?) -> Analysis
+    def analyze: (untyped, from: untyped, to: untyped, within: untyped, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?) -> Analysis
 
     # Analyzes many roots over one shared range, preparing their history once.
-    # : (Array[untyped], within: untyped, ?activity: bool) -> Hash[identity, Analysis]
-    def analyze_many: (Array[untyped], within: untyped, ?activity: bool) -> Hash[identity, Analysis]
+    # : (Array[untyped], within: untyped, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?) -> Hash[identity, Analysis]
+    def analyze_many: (Array[untyped], within: untyped, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?) -> Hash[identity, Analysis]
 
     private
 
@@ -53,6 +56,19 @@ module PaperTrailDiff
 
     @traversal_preparer: TraversalPreparer
 
+    # : (untyped, from: untyped, to: untyped, within: untyped, version_scope: untyped, live_endpoint: untyped) -> Analysis
+    def analyze_activity: (untyped, from: untyped, to: untyped, within: untyped, version_scope: untyped, live_endpoint: untyped) -> Analysis
+
+    # `close_on:` names what ends a wall-clock window, so it is meaningless for a
+    # range whose endpoints the caller already gave explicitly.
+    # : (Symbol?, untyped) -> bool
+    def close_on_current?: (Symbol?, untyped) -> bool
+
+    # A destroyed root has no current state to close on, and its own destroy
+    # version already terminates the history.
+    # : (untyped, Symbol?, untyped) -> untyped
+    def live_endpoint_for: (untyped, Symbol?, untyped) -> untyped
+
     # : () -> void
     def build_snapshotters: () -> void
 
@@ -65,8 +81,8 @@ module PaperTrailDiff
     # : () -> 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, ?live_endpoint: untyped) -> ActivityTimelineBuilder
+    def activity_builder: (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped, ?live_endpoint: untyped) -> ActivityTimelineBuilder
 
     # : (untyped) -> void
     def reject_live_habtm_activity!: (untyped) -> void

data/sig/generated/paper_trail_diff/root_version_plan.rbs

@@ -0,0 +1,66 @@
+# 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 live record a window closes on when no later version can reveal its
+    # final mutation. It is a boundary, never a version, so it stays out of
+    # `versions` and out of anything that reconstructs from version history.
+    attr_reader closing_record: 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]?, ?closing_record: untyped) -> void
+    def initialize: (versions: Array[untyped], steps: Array[[ untyped, untyped ]], ?context_version: untyped, ?reconstruction_versions: Array[untyped]?, ?mutations: Array[untyped]?, ?closing_record: untyped) -> void
+
+    # : () -> bool
+    def empty?: () -> bool
+
+    # What the range's final state is read from, which is the live record when
+    # the window closes on current state and the last version otherwise.
+    # : () -> untyped
+    def final_endpoint: () -> untyped
+
+    # : (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,88 @@
+# 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, ?live_endpoint: untyped) -> void
+    def initialize: (in_range: Array[untyped], selected: Array[untyped], after_range: untyped, windowed: bool, ?context_required: bool, ?filtered: bool, ?live_endpoint: untyped) -> void
+
+    # : () -> RootVersionPlan
+    def call: () -> RootVersionPlan
+
+    private
+
+    @after_range: untyped
+
+    @context_required: bool
+
+    @filtered: bool
+
+    @in_range: Array[untyped]
+
+    @live_endpoint: untyped
+
+    @selected: Array[untyped]
+
+    @windowed: bool
+
+    # A window reaching past the last recorded version has only the live record
+    # left to show what its final mutation produced. That record is a closing
+    # boundary rather than a selected mutation, so it never joins `versions`.
+    # : (untyped) -> RootVersionPlan
+    def contiguous_plan: (untyped) -> RootVersionPlan
+
+    # 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
+
+    # : (Array[[untyped, untyped]], untyped) -> RootVersionPlan
+    def filtered_plan_for: (Array[[ untyped, untyped ]], 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/step.rbs

@@ -13,8 +13,11 @@ module PaperTrailDiff
 
     attr_reader diff: Diff
 
-    # : (from_version: untyped, to_version: untyped, diff: Diff) -> void
-    def initialize: (from_version: untyped, to_version: untyped, diff: Diff) -> void
+    # `to_version` is nil for the one step that closes on current state, which a
+    # window reaching past the last recorded version has to do. Read
+    # `to_boundary` instead when a caller may have opted into that.
+    # : (from_version: untyped, to_version: untyped, diff: Diff, ?captured_at: untyped) -> void
+    def initialize: (from_version: untyped, to_version: untyped, diff: Diff, ?captured_at: untyped) -> void
 
     # : () -> bool
     def empty?: () -> bool

data/sig/generated/paper_trail_diff/time_activity_timeline_builder.rbs

@@ -22,8 +22,19 @@ module PaperTrailDiff
 
     @tree: AssociationTree
 
-    # : () -> [ActivityHistory, Array[untyped], ActivityStep?]
-    def history_and_versions: () -> [ ActivityHistory, Array[untyped], ActivityStep? ]
+    # : () -> [ActivityHistory, RootVersionPlan, ActivityStep?, RecordSnapshot?, untyped]
+    def history_and_versions: () -> [ ActivityHistory, RootVersionPlan, ActivityStep?, RecordSnapshot?, untyped ]
+
+    # : (RootVersionPlan, untyped) -> [ActivityHistory, RootVersionPlan, ActivityStep?, RecordSnapshot?, untyped]
+    def history_for: (RootVersionPlan, untyped) -> [ ActivityHistory, RootVersionPlan, ActivityStep?, RecordSnapshot?, untyped ]
+
+    # One live read serves both the closing activity step and the endpoint the
+    # analysis reports, which would otherwise reconstruct the graph twice.
+    # : (RootVersionPlan) -> RecordSnapshot?
+    def current_snapshot: (RootVersionPlan) -> RecordSnapshot?
+
+    # : (Array[untyped], untyped) -> Array[ActivityEvent]
+    def events_through: (Array[untyped], untyped) -> Array[ActivityEvent]
 
     # : (Array[untyped], Array[ActivityEvent]) -> ActivityHistory
     def build_history: (Array[untyped], Array[ActivityEvent]) -> ActivityHistory
@@ -31,25 +42,40 @@ module PaperTrailDiff
     # : (ActivityHistory, ActivityStep?) -> Array[ActivityStep]
     def activity_steps: (ActivityHistory, ActivityStep?) -> Array[ActivityStep]
 
-    # : (Array[ActivityEvent]) -> Array[ActivityEvent]
-    def selected_events: (Array[ActivityEvent]) -> 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.
-    # : (ActivityHistory, ActivityEvent?) -> ActivityStep?
-    def closing_step: (ActivityHistory, ActivityEvent?) -> ActivityStep?
+    # 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]
+
+    # A window either closes on the absence its final destruction leaves, or on
+    # current state when it reaches past everything recorded. Both are boundaries
+    # no version can supply.
+    # : (ActivityHistory, ActivityEvent?, RootVersionPlan, untyped, RecordSnapshot?) -> ActivityStep?
+    def closing_step: (ActivityHistory, ActivityEvent?, RootVersionPlan, untyped, RecordSnapshot?) -> ActivityStep?
+
+    # : (ActivityHistory, ActivityEvent) -> ActivityStep
+    def destroyed_step: (ActivityHistory, ActivityEvent) -> ActivityStep
+
+    # The last boundary reached is where current state is compared from, which
+    # is the final event rather than the final root version once descendants
+    # have moved since it.
+    # : (ActivityHistory, untyped, untyped, RecordSnapshot?) -> ActivityStep?
+    def current_step: (ActivityHistory, untyped, untyped, RecordSnapshot?) -> ActivityStep?
 
     # : (ActivityEvent?) -> bool
     def terminal_destroy?: (ActivityEvent?) -> bool
 
-    # : (Array[untyped]) -> void
-    def prepare_history: (Array[untyped]) -> void
+    # : (Array[untyped], ?end_at: untyped) -> void
+    def prepare_history: (Array[untyped], ?end_at: untyped) -> void
 
-    # : (Array[untyped]) -> Array[ActivityEvent]
-    def collect_events: (Array[untyped]) -> Array[ActivityEvent]
+    # : (Array[untyped], ?range_end: untyped) -> Array[ActivityEvent]
+    def collect_events: (Array[untyped], ?range_end: untyped) -> Array[ActivityEvent]
 
-    # : (Array[ActivityEvent], Array[ActivityEvent]) -> bool
-    def time_events?: (Array[ActivityEvent], Array[ActivityEvent]) -> bool
+    # : (Array[ActivityEvent], Array[ActivityEvent], RootVersionPlan) -> bool
+    def time_events?: (Array[ActivityEvent], Array[ActivityEvent], RootVersionPlan) -> bool
 
     # : (ActivityEvent, Array[ActivityEvent]) -> bool
     def later_event?: (ActivityEvent, Array[ActivityEvent]) -> bool

data/sig/generated/paper_trail_diff/time_version_range.rbs

@@ -3,28 +3,28 @@
 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, ?live_endpoint: untyped) -> void
+    def initialize: (untyped, time_range: TimeRange, ?version_scope: untyped, ?live_endpoint: 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
 
+    @live_endpoint: untyped
+
     @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, ?versions: Array[untyped]?) -> void
-    def initialize: (untyped, from: untyped, to: untyped, snapshotter: untyped, ?within: untyped, ?versions: Array[untyped]?) -> void
+    # : (untyped, from: untyped, to: untyped, snapshotter: untyped, ?within: untyped, ?versions: Array[untyped]?, ?version_scope: untyped, ?plan: RootVersionPlan?, ?live_endpoint: untyped) -> void
+    def initialize: (untyped, from: untyped, to: untyped, snapshotter: untyped, ?within: untyped, ?versions: Array[untyped]?, ?version_scope: untyped, ?plan: RootVersionPlan?, ?live_endpoint: untyped) -> void
 
     # : () -> Array[Step]
     def build: () -> Array[Step]
@@ -20,13 +20,16 @@ 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? ]
+
+    # : (RootVersionPlan) -> Array[Step]
+    def build_steps: (RootVersionPlan) -> Array[Step]
 
     # : () -> [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,8 +11,8 @@ module PaperTrailDiff
 
     attr_reader time_range: TimeRange?
 
-    # : (untyped, from: untyped, to: untyped, within: untyped, ?versions: Array[untyped]?) -> void
-    def initialize: (untyped, from: untyped, to: untyped, within: untyped, ?versions: Array[untyped]?) -> void
+    # : (untyped, from: untyped, to: untyped, within: untyped, ?versions: Array[untyped]?, ?version_scope: untyped, ?plan: RootVersionPlan?, ?live_endpoint: untyped) -> void
+    def initialize: (untyped, from: untyped, to: untyped, within: untyped, ?versions: Array[untyped]?, ?version_scope: untyped, ?plan: RootVersionPlan?, ?live_endpoint: untyped) -> void
 
     # A record with no versions has no first or last boundary to resolve, which
     # is an empty history rather than a bad request.
@@ -21,6 +21,11 @@ module PaperTrailDiff
 
     # 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]
 
@@ -37,6 +42,10 @@ module PaperTrailDiff
 
     @from: untyped
 
+    @live_endpoint: untyped
+
+    @plan: RootVersionPlan?
+
     @record: untyped
 
     @requested_from: untyped
@@ -45,6 +54,8 @@ module PaperTrailDiff
 
     @to: untyped
 
+    @version_scope: untyped
+
     @versions: Array[untyped]?
 
     # : () -> Array[untyped]

data/sig/generated/paper_trail_diff/timeline_snapshot_provider.rbs

@@ -3,15 +3,24 @@
 module PaperTrailDiff
   # Gives TimelineBuilder one-argument access to a range-prepared snapshot store.
   class TimelineSnapshotProvider
-    # : (HistoricalSnapshotStore) -> void
-    def initialize: (HistoricalSnapshotStore) -> void
+    # : (HistoricalSnapshotStore, ?live_snapshotter: untyped) -> void
+    def initialize: (HistoricalSnapshotStore, ?live_snapshotter: untyped) -> void
 
     # : (untyped, Array[untyped]) -> void
     def prepare: (untyped, Array[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?
+
+    @live_snapshotter: untyped
+
     @store: HistoricalSnapshotStore
   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
 

data/sig/generated/paper_trail_diff/version_scope_filter.rbs

@@ -0,0 +1,22 @@
+# Generated from lib/paper_trail_diff/version_scope_filter.rb with RBS::Inline
+
+module PaperTrailDiff
+  # Applies a caller's version filter to a range, naming which of its versions
+  # count as selected mutations. The unfiltered versions stay available to the
+  # caller, because the one that reveals the last selected mutation is drawn
+  # from them.
+  class VersionScopeFilter
+    # : (untyped) -> void
+    def initialize: (untyped) -> void
+
+    # : (untyped, Array[untyped]) -> Array[untyped]
+    def call: (untyped, Array[untyped]) -> Array[untyped]
+
+    private
+
+    @scope: untyped
+
+    # : (untyped) -> untyped
+    def validated: (untyped) -> untyped
+  end
+end

data/sig/generated/paper_trail_diff.rbs

@@ -17,24 +17,24 @@ module PaperTrailDiff
   def self.compare_many: (Array[comparison_input], ?associations: Array[String | Symbol], ?ignore: ignore_option, ?reload_live_endpoints: bool) -> comparison_results
 
   # Compares every adjacent reconstructed state in an inclusive version range.
-  # : (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option) -> Array[Step]
-  def self.timeline: (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option) -> Array[Step]
+  # : (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]
 
   # Compares adjacent root and selected-descendant activity boundaries.
   # `reload_live_endpoints:` applies only when `to:` is a current record; the
   # other range forms never read live state.
-  # : (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?reload_live_endpoints: bool) -> Array[ActivityStep]
-  def self.activity_timeline: (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?reload_live_endpoints: bool) -> Array[ActivityStep]
+  # : (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?reload_live_endpoints: bool, ?version_scope: untyped, ?close_on: 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?) -> 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) -> Analysis
-  def self.analyze: (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?activity: bool) -> Analysis
+  # : (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?activity: bool, ?version_scope: untyped, ?close_on: 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?) -> Analysis
 
   # Analyzes many roots over one shared time window, preparing their selected
   # history once for the batch instead of once per record. Roots with no
   # versions in the window return an empty `Analysis`.
-  # : (Array[untyped], ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?activity: bool) -> Hash[identity, Analysis]
-  def self.analyze_many: (Array[untyped], ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?activity: bool) -> Hash[identity, Analysis]
+  # : (Array[untyped], ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?) -> 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?) -> Hash[identity, Analysis]
 
   # Returns the association macros this release can normalize.
   # : () -> Array[Symbol]