paper_trail_diff 0.5.0 → 0.6.0

data/lib/paper_trail_diff.rb

@@ -39,6 +39,9 @@ require_relative 'paper_trail_diff/live_endpoint_provider'
 require_relative 'paper_trail_diff/live_graph_collector'
 require_relative 'paper_trail_diff/batch_boundary_resolver'
 require_relative 'paper_trail_diff/comparison_batch'
+require_relative 'paper_trail_diff/root_version_plan'
+require_relative 'paper_trail_diff/version_scope_filter'
+require_relative 'paper_trail_diff/root_version_selection'
 require_relative 'paper_trail_diff/batched_root_versions'
 require_relative 'paper_trail_diff/snapshot_normalizer'
 require_relative 'paper_trail_diff/historical_snapshot_store'
@@ -142,27 +145,29 @@ module PaperTrailDiff # rubocop:disable Metrics/ModuleLength
     end
 
     # 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]
+    #: (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?version_scope: untyped) -> Array[Step]
     def timeline( # rubocop:disable Metrics/ParameterLists
       record,
       from: nil,
       to: nil,
       within: nil,
       associations: [],
-      ignore: DEFAULT_IGNORED_ATTRIBUTES
+      ignore: DEFAULT_IGNORED_ATTRIBUTES,
+      version_scope: nil
     )
       PaperTrailAdapter.new(associations: associations, ignore: ignore).timeline(
         record,
         from: from,
         to: to,
-        within: within
+        within: within,
+        version_scope: version_scope
       )
     end
 
     # 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]
+    #: (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?reload_live_endpoints: bool, ?version_scope: untyped) -> Array[ActivityStep]
     def activity_timeline( # rubocop:disable Metrics/ParameterLists
       record,
       from: nil,
@@ -170,7 +175,8 @@ module PaperTrailDiff # rubocop:disable Metrics/ModuleLength
       within: nil,
       associations: [],
       ignore: DEFAULT_IGNORED_ATTRIBUTES,
-      reload_live_endpoints: true
+      reload_live_endpoints: true,
+      version_scope: nil
     )
       PaperTrailAdapter.new(
         associations: associations,
@@ -180,12 +186,13 @@ module PaperTrailDiff # rubocop:disable Metrics/ModuleLength
         record,
         from: from,
         to: to,
-        within: within
+        within: within,
+        version_scope: version_scope
       )
     end
 
     # Builds an endpoint diff and root-checkpoint timeline while normalizing each version once.
-    #: (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?activity: bool) -> Analysis
+    #: (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?activity: bool, ?version_scope: untyped) -> Analysis
     def analyze( # rubocop:disable Metrics/ParameterLists
       record,
       from: nil,
@@ -193,32 +200,36 @@ module PaperTrailDiff # rubocop:disable Metrics/ModuleLength
       within: nil,
       associations: [],
       ignore: DEFAULT_IGNORED_ATTRIBUTES,
-      activity: false
+      activity: false,
+      version_scope: nil
     )
       PaperTrailAdapter.new(associations: associations, ignore: ignore).analyze(
         record,
         from: from,
         to: to,
         within: within,
-        activity: activity
+        activity: activity,
+        version_scope: version_scope
       )
     end
 
     # 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 analyze_many(
+    #: (Array[untyped], ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?activity: bool, ?version_scope: untyped) -> Hash[identity, Analysis]
+    def analyze_many( # rubocop:disable Metrics/ParameterLists
       records,
       within: nil,
       associations: [],
       ignore: DEFAULT_IGNORED_ATTRIBUTES,
-      activity: false
+      activity: false,
+      version_scope: nil
     )
       PaperTrailAdapter.new(associations: associations, ignore: ignore).analyze_many(
         records,
         within: within,
-        activity: activity
+        activity: activity,
+        version_scope: version_scope
       )
     end
 

data/sig/generated/paper_trail_diff/activity_root_steps.rbs

@@ -4,8 +4,8 @@ module PaperTrailDiff
   # Root checkpoint steps recovered from the snapshots an activity pass retained,
   # so a combined result does not reconstruct the same boundaries twice.
   module ActivityRootSteps
-    # : (Array[untyped], Hash[Array[untyped], RecordSnapshot?]) -> Array[Step]
-    def self?.call: (Array[untyped], Hash[Array[untyped], RecordSnapshot?]) -> Array[Step]
+    # : (RootVersionPlan, Hash[Array[untyped], RecordSnapshot?]) -> Array[Step]
+    def self?.call: (RootVersionPlan, Hash[Array[untyped], RecordSnapshot?]) -> Array[Step]
 
     # : (untyped) -> Array[untyped]
     def self?.version_key: (untyped) -> Array[untyped]

data/sig/generated/paper_trail_diff/activity_timeline_builder.rbs

@@ -30,6 +30,10 @@ module PaperTrailDiff
     # : () -> Array[ActivityStep]
     def no_steps: () -> Array[ActivityStep]
 
+    # Every boundary in the span, filtered out or not. A filter narrows where the
+    # span starts and ends, but the sequence inside it stays complete: dropping
+    # boundaries would fold the changes they carried into a neighbouring step and
+    # credit them to whoever made that one.
     # : () -> Array[ActivityStep]
     def build_between_versions: () -> Array[ActivityStep]
 
@@ -67,8 +71,8 @@ module PaperTrailDiff
     # Only the activity view gains the closing removal. The endpoint diff and
     # the root timeline keep their `compare` and `timeline` semantics, under
     # which the state at a destroy version is the state before the deletion.
-    # : (Array[untyped], Array[ActivityEvent], ActivityHistory) -> Analysis
-    def build_analysis: (Array[untyped], Array[ActivityEvent], ActivityHistory) -> Analysis
+    # : (RootVersionPlan, Array[ActivityEvent], ActivityHistory) -> Analysis
+    def build_analysis: (RootVersionPlan, Array[ActivityEvent], ActivityHistory) -> Analysis
 
     # : () -> TimeActivityTimelineBuilder
     def time_builder: () -> TimeActivityTimelineBuilder

data/sig/generated/paper_trail_diff/analysis.rbs

@@ -9,15 +9,24 @@ module PaperTrailDiff
 
     attr_reader activity_timeline: Array[ActivityStep]?
 
+    attr_reader from_snapshot: RecordSnapshot?
+
+    attr_reader to_snapshot: RecordSnapshot?
+
     # The result for a record whose requested history contains no versions,
     # which is an empty history rather than a failed request.
     # : () -> Analysis
     def self.empty: () -> Analysis
 
-    # : (diff: Diff, timeline: Array[Step], ?activity_timeline: Array[ActivityStep]?) -> void
-    def initialize: (diff: Diff, timeline: Array[Step], ?activity_timeline: Array[ActivityStep]?) -> void
+    # The reconstructed states the diff was taken between. A report that has to
+    # render unchanged columns needs the whole final state, not only what moved.
+    # : (diff: Diff, timeline: Array[Step], ?activity_timeline: Array[ActivityStep]?, ?from_snapshot: RecordSnapshot?, ?to_snapshot: RecordSnapshot?) -> void
+    def initialize: (diff: Diff, timeline: Array[Step], ?activity_timeline: Array[ActivityStep]?, ?from_snapshot: RecordSnapshot?, ?to_snapshot: RecordSnapshot?) -> void
 
-    # : () -> Hash[Symbol, untyped]
-    def to_h: () -> Hash[Symbol, untyped]
+    # Reconstructed endpoint states are opt-in, because they carry the whole
+    # selected graph whether or not anything changed, which dwarfs the rest of
+    # the payload for a wide graph.
+    # : (?snapshots: bool) -> Hash[Symbol, untyped]
+    def to_h: (?snapshots: bool) -> Hash[Symbol, untyped]
   end
 end

data/sig/generated/paper_trail_diff/analysis_batch.rbs

@@ -5,8 +5,8 @@ module PaperTrailDiff
   # 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) -> void
-    def initialize: (Array[untyped], time_range: TimeRange?, live_loader: untyped, history_preparer: untyped, analyzer: untyped) -> void
+    # : (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]
@@ -23,6 +23,13 @@ module PaperTrailDiff
 
     @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]
 
@@ -31,12 +38,12 @@ module PaperTrailDiff
     # 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], Array[untyped]]) -> void
-    def prepare: (Array[untyped], Hash[Array[String], Array[untyped]]) -> void
+    # : (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, Array[untyped]) -> Analysis
-    def analysis_for: (untyped, Array[untyped]) -> Analysis
+    # : (untyped, RootVersionPlan) -> Analysis
+    def analysis_for: (untyped, RootVersionPlan) -> Analysis
   end
 end

data/sig/generated/paper_trail_diff/batched_root_analyzer.rbs

@@ -7,8 +7,8 @@ module PaperTrailDiff
     # : (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, Array[untyped]) -> Analysis
-    def call: (untyped, Array[untyped]) -> Analysis
+    # : (untyped, RootVersionPlan) -> Analysis
+    def call: (untyped, RootVersionPlan) -> Analysis
 
     private
 
@@ -22,7 +22,7 @@ module PaperTrailDiff
 
     @tree: AssociationTree
 
-    # : (untyped, Array[untyped]) -> Analysis
-    def activity_analysis: (untyped, Array[untyped]) -> Analysis
+    # : (untyped, RootVersionPlan) -> Analysis
+    def activity_analysis: (untyped, RootVersionPlan) -> Analysis
   end
 end

data/sig/generated/paper_trail_diff/batched_root_versions.rbs

@@ -5,12 +5,12 @@ 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) -> void
+    def initialize: (Array[untyped], time_range: TimeRange?, ?version_scope: 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
 
@@ -18,21 +18,28 @@ module PaperTrailDiff
 
     @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
 
-    # 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]
+    # : (untyped, Array[untyped], Hash[Array[String], RootVersionPlan]) -> void
+    def select_model: (untyped, Array[untyped], Hash[Array[String], RootVersionPlan]) -> void
 
-    # : (Array[untyped]) -> bool
-    def terminal_destroy?: (Array[untyped]) -> bool
+    # : (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]

data/sig/generated/paper_trail_diff/paper_trail_adapter.rbs

@@ -16,18 +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) -> Hash[identity, Analysis]
-    def analyze_many: (Array[untyped], within: untyped, ?activity: bool) -> Hash[identity, Analysis]
+    # : (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
 
@@ -65,8 +65,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) -> ActivityTimelineBuilder
+    def activity_builder: (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped) -> ActivityTimelineBuilder
 
     # : (untyped) -> void
     def reject_live_habtm_activity!: (untyped) -> void

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, ?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?) -> 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,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?) -> 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.
@@ -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,8 @@ module PaperTrailDiff
 
     @from: untyped
 
+    @plan: RootVersionPlan?
+
     @record: untyped
 
     @requested_from: untyped
@@ -45,6 +52,8 @@ module PaperTrailDiff
 
     @to: untyped
 
+    @version_scope: untyped
+
     @versions: Array[untyped]?
 
     # : () -> Array[untyped]

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