paper_trail_diff 0.5.0 → 0.7.0

data/lib/paper_trail_diff/paper_trail_adapter.rb

@@ -7,6 +7,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 # rubocop:disable Metrics/ClassLength
+    # The only thing a wall-clock window can close on besides a later version.
+    CLOSE_ON_CURRENT = :current
+
     #: (associations: Array[String | Symbol], ignore: ignore_option, ?reload_live_endpoints: bool) -> void
     def initialize(associations:, ignore:, reload_live_endpoints: true)
       @association_tree = AssociationTree.build(associations)
@@ -50,57 +53,64 @@ module PaperTrailDiff
       end
     end
 
-    #: (untyped, from: untyped, to: untyped, within: untyped) -> Array[Step]
-    def timeline(record, from:, to:, within:)
+    #: (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped, ?close_on: Symbol?) -> Array[Step]
+    def timeline(record, from:, to:, within:, version_scope: nil, close_on: nil) # rubocop:disable Metrics/ParameterLists
       @traversal_preparer.call(record.class, historical: true)
-      builder = TimelineBuilder.new(
+      TimelineBuilder.new(
         record,
         from: from,
         to: to,
         within: within,
+        version_scope: version_scope,
+        live_endpoint: live_endpoint_for(record, close_on, within),
         snapshotter: @timeline_snapshotter
-      )
-      builder.build
+      ).build
     end
 
-    #: (untyped, from: untyped, to: untyped, within: untyped) -> Array[ActivityStep]
-    def activity_timeline(record, from:, to:, within:)
+    #: (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped, ?close_on: Symbol?) -> Array[ActivityStep]
+    def activity_timeline(record, from:, to:, within:, version_scope: nil, close_on: nil) # rubocop:disable Metrics/ParameterLists
       payload = @instrumentation_payload.merge(model_type: record.class.base_class.name.to_s)
       Instrumentation.instrument('activity_timeline', payload) do
         @traversal_preparer.call(record.class, historical: true)
-        reject_live_habtm_activity!(record.class) if Endpoint.record?(to)
-        steps = activity_builder(record, from: from, to: to, within: within).build
+        live = live_endpoint_for(record, close_on, within)
+        reject_live_habtm_activity!(record.class) if Endpoint.record?(to) || live
+        steps = activity_builder(
+          record, from: from, to: to, within: within, version_scope: version_scope,
+                  live_endpoint: live
+        ).build
         payload[:step_count] = steps.length
         steps
       end
     end
 
-    #: (untyped, from: untyped, to: untyped, within: untyped, ?activity: bool) -> Analysis
-    def analyze(record, from:, to:, within:, activity: false)
+    #: (untyped, from: untyped, to: untyped, within: untyped, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?) -> Analysis
+    def analyze(record, from:, to:, within:, activity: false, version_scope: nil, close_on: nil) # rubocop:disable Metrics/ParameterLists
+      @traversal_preparer.call(record.class, historical: true)
+      live = live_endpoint_for(record, close_on, within)
       if activity
-        @traversal_preparer.call(record.class, historical: true)
-        return activity_builder(record, from: from, to: to, within: within).analyze
+        return analyze_activity(
+          record, from: from, to: to, within: within,
+                  version_scope: version_scope, live_endpoint: live
+        )
       end
 
-      @traversal_preparer.call(record.class, historical: true)
       TimelineBuilder.new(
-        record,
-        from: from,
-        to: to,
-        within: within,
-        snapshotter: @timeline_snapshotter
+        record, from: from, to: to, within: within, version_scope: version_scope,
+                live_endpoint: live, snapshotter: @timeline_snapshotter
       ).analyze
     end
 
     # Analyzes many roots over one shared range, preparing their history once.
-    #: (Array[untyped], within: untyped, ?activity: bool) -> Hash[identity, Analysis]
-    def analyze_many(records, within:, activity: false)
+    #: (Array[untyped], within: untyped, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?) -> Hash[identity, Analysis]
+    def analyze_many(records, within:, activity: false, version_scope: nil, close_on: nil)
       count = records.is_a?(Array) ? records.length : 0
       payload = @instrumentation_payload.merge(comparison_count: count)
       Instrumentation.instrument('analyze_many', payload) do
         AnalysisBatch.new(
           records,
           time_range: within.nil? ? nil : TimeRange.new(within),
+          version_scope: version_scope,
+          close_on_current: close_on_current?(close_on, within),
           live_loader: @live_endpoints.method(:call),
           history_preparer: @historical_store.method(:prepare_batch),
           analyzer: batched_root_analyzer(activity)
@@ -122,10 +132,44 @@ module PaperTrailDiff
     # @rbs @timeline_snapshotter: TimelineSnapshotProvider
     # @rbs @activity_snapshotter: ActivitySnapshotProvider
 
+    #: (untyped, from: untyped, to: untyped, within: untyped, version_scope: untyped, live_endpoint: untyped) -> Analysis
+    def analyze_activity(record, from:, to:, within:, version_scope:, live_endpoint:) # rubocop:disable Metrics/ParameterLists
+      reject_live_habtm_activity!(record.class) if live_endpoint
+      activity_builder(
+        record, from: from, to: to, within: within,
+                version_scope: version_scope, live_endpoint: live_endpoint
+      ).analyze
+    end
+
+    # `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?(close_on, within)
+      return false if close_on.nil?
+      unless close_on == CLOSE_ON_CURRENT
+        raise ConfigurationError, "close_on: must be #{CLOSE_ON_CURRENT.inspect} or nil"
+      end
+      raise ConfigurationError, 'close_on: requires `within`' if within.nil?
+
+      true
+    end
+
+    # 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(record, close_on, within)
+      return unless close_on_current?(close_on, within)
+      return unless Endpoint.record?(record) && !record.destroyed?
+
+      record
+    end
+
     #: () -> void
     def build_snapshotters
       @historical_store = build_historical_store
-      @timeline_snapshotter = TimelineSnapshotProvider.new(@historical_store)
+      @timeline_snapshotter = TimelineSnapshotProvider.new(
+        @historical_store, live_snapshotter: method(:live_snapshot)
+      )
       @activity_snapshotter = build_activity_snapshotter
     end
 
@@ -168,11 +212,14 @@ module PaperTrailDiff
       )
     end
 
-    #: (untyped, from: untyped, to: untyped, within: untyped) -> ActivityTimelineBuilder
-    def activity_builder(record, from:, to:, within:)
+    #: (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped, ?live_endpoint: untyped) -> ActivityTimelineBuilder
+    def activity_builder(record, from:, to:, within:, version_scope: nil, live_endpoint: nil) # rubocop:disable Metrics/ParameterLists
       ActivityTimelineBuilder.new(
         record,
-        range: TimelineRange.new(record, from: from, to: to, within: within),
+        range: TimelineRange.new(
+          record, from: from, to: to, within: within, version_scope: version_scope,
+                  live_endpoint: live_endpoint
+        ),
         tree: @association_tree,
         snapshotter: @activity_snapshotter
       )

data/lib/paper_trail_diff/root_version_plan.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+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]
+
+    class << self
+      # Adjacent boundaries, which is what an unfiltered range reports.
+      #: (Array[untyped], ?context_version: untyped) -> RootVersionPlan
+      def contiguous(versions, context_version: nil)
+        new(
+          versions: versions,
+          steps: versions.each_cons(2).map { |from, to| [from, to] },
+          context_version: context_version
+        )
+      end
+
+      #: () -> RootVersionPlan
+      def empty
+        versions = [] #: Array[untyped]
+        steps = [] #: Array[[untyped, untyped]]
+        new(versions: versions, steps: steps)
+      end
+    end
+
+    #: (versions: Array[untyped], steps: Array[[untyped, untyped]], ?context_version: untyped, ?reconstruction_versions: Array[untyped]?, ?mutations: Array[untyped]?, ?closing_record: untyped) -> void
+    def initialize( # rubocop:disable Metrics/ParameterLists
+      versions:, steps:, context_version: nil, reconstruction_versions: nil, mutations: nil,
+      closing_record: nil
+    )
+      @closing_record = closing_record
+      @versions = versions.freeze
+      @reconstruction_versions = (reconstruction_versions || versions).freeze
+      @steps = steps.freeze
+      @context_version = context_version
+      @mutations = (mutations || default_mutations).freeze
+      @mutation_keys = Set.new(@mutations.map { |version| key(version) }).freeze
+      freeze
+    end
+
+    #: () -> bool
+    def empty?
+      versions.empty?
+    end
+
+    # 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
+      @closing_record || @versions.last
+    end
+
+    #: (untyped) -> bool
+    def mutation?(version)
+      @mutation_keys.include?(key(version))
+    end
+
+    private
+
+    # @rbs @mutation_keys: Set[Array[untyped]]
+
+    #: () -> Array[untyped]
+    def default_mutations
+      return @versions unless @context_version
+
+      context = key(@context_version)
+      @versions.reject { |version| key(version) == context }
+    end
+
+    #: (untyped) -> Array[untyped]
+    def key(version)
+      [version.class.name, version.id]
+    end
+  end
+end

data/lib/paper_trail_diff/root_version_selection.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+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 = 'time range requires a later root version to reconstruct its final change'
+
+    #: (in_range: Array[untyped], selected: Array[untyped], after_range: untyped, windowed: bool, ?context_required: bool, ?filtered: bool, ?live_endpoint: untyped) -> void
+    def initialize( # rubocop:disable Metrics/ParameterLists
+      in_range:, selected:, after_range:, windowed:, context_required: false, filtered: false,
+      live_endpoint: nil
+    )
+      @in_range = in_range
+      @selected = selected
+      @after_range = after_range
+      @windowed = windowed
+      @context_required = context_required
+      @filtered = filtered
+      @live_endpoint = live_endpoint
+    end
+
+    #: () -> RootVersionPlan
+    def call
+      return without_selection if @selected.empty?
+
+      closing = revealing_version || @live_endpoint
+      raise IncompleteTimeRangeError, INCOMPLETE if !closing && @windowed && !terminal_destroy?
+      return filtered_plan(closing) if @filtered
+
+      contiguous_plan(closing)
+    end
+
+    private
+
+    # @rbs @in_range: Array[untyped]
+    # @rbs @selected: Array[untyped]
+    # @rbs @after_range: untyped
+    # @rbs @windowed: bool
+    # @rbs @context_required: bool
+    # @rbs @filtered: bool
+    # @rbs @live_endpoint: untyped
+
+    # 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(closing)
+      return RootVersionPlan.contiguous(@selected) unless closing
+      unless Endpoint.record?(closing)
+        return RootVersionPlan.contiguous(@selected + [closing], context_version: closing)
+      end
+
+      steps = @selected.each_cons(2).map { |from, to| [from, to] } #: Array[[untyped, untyped]]
+      steps << [@selected.last, closing]
+      RootVersionPlan.new(versions: @selected, steps: steps, closing_record: closing)
+    end
+
+    # 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
+      return RootVersionPlan.empty unless @context_required
+      if @after_range
+        return RootVersionPlan.contiguous([@after_range], context_version: @after_range)
+      end
+
+      raise IncompleteTimeRangeError, INCOMPLETE
+    end
+
+    # 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(revealing)
+      steps = @selected.filter_map do |version|
+        successor = version.equal?(@selected.last) ? revealing : immediate_successor(version)
+        [version, successor] if successor
+      end #: Array[[untyped, untyped]]
+      filtered_plan_for(steps, revealing)
+    end
+
+    #: (Array[[untyped, untyped]], untyped) -> RootVersionPlan
+    def filtered_plan_for(steps, revealing)
+      live = revealing if Endpoint.record?(revealing)
+      versions = chronological(
+        (steps.flatten(1) + closing_versions).reject { |entry| Endpoint.record?(entry) }
+      )
+      RootVersionPlan.new(
+        versions: versions, steps: steps,
+        context_version: (revealing unless live),
+        reconstruction_versions: spanned(versions),
+        mutations: @selected, closing_record: live
+      )
+    end
+
+    # 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
+      terminal_destroy? ? [@selected.last] : []
+    end
+
+    # 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(versions)
+      first = versions.first
+      last = versions.last
+      return versions unless first && last
+
+      @in_range.select do |candidate|
+        !Support.compare_versions(first, candidate).positive? &&
+          !Support.compare_versions(candidate, last).positive?
+      end
+    end
+
+    #: (Array[untyped]) -> Array[untyped]
+    def chronological(versions)
+      versions.uniq { |version| [version.class.name, version.id] }
+              .sort_by { |version| Support.chronological_version_key(version) }
+    end
+
+    #: (untyped) -> untyped
+    def immediate_successor(version)
+      @in_range.find { |candidate| Support.compare_versions(version, candidate).negative? }
+    end
+
+    # 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
+      immediate_successor(@selected.last) || @after_range
+    end
+
+    # 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?
+      @selected.last&.event.to_s == 'destroy'
+    end
+  end
+end

data/lib/paper_trail_diff/step.rb

@@ -10,12 +10,20 @@ module PaperTrailDiff
     attr_reader :to_boundary #: ActivityBoundary
     attr_reader :diff #: Diff
 
-    #: (from_version: untyped, to_version: untyped, diff: Diff) -> void
-    def initialize(from_version:, to_version:, diff:)
+    # `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:, to_version:, diff:, captured_at: nil)
+      live = Endpoint.record?(to_version)
       @from_version = from_version
-      @to_version = to_version
+      @to_version = (to_version unless live)
       @from_boundary = ActivityBoundary.from_version(from_version)
-      @to_boundary = ActivityBoundary.from_version(to_version)
+      @to_boundary = if live
+                       ActivityBoundary.current(to_version, captured_at: captured_at)
+                     else
+                       ActivityBoundary.from_version(to_version)
+                     end
       @diff = diff
       freeze
     end
@@ -29,7 +37,8 @@ module PaperTrailDiff
     def to_h
       {
         from_version_id: from_version.id,
-        to_version_id: to_version.id,
+        to_version_id: to_version&.id,
+        to_boundary: to_boundary.to_h,
         diff: diff.to_h
       }
     end

data/lib/paper_trail_diff/time_activity_timeline_builder.rb

@@ -14,17 +14,23 @@ module PaperTrailDiff
 
     #: () -> Array[ActivityStep]
     def build
-      history, _root_versions, closing = history_and_versions
+      history, _plan, closing, = history_and_versions
       activity_steps(history, closing)
     end
 
     #: () -> Analysis
     def analyze
-      history, root_versions, closing = history_and_versions
+      history, plan, closing, closing_snapshot, captured_at = history_and_versions
+      final = closing_snapshot || history.last_snapshot
       Analysis.new(
-        diff: Engine.compare(history.first_snapshot, history.last_snapshot),
-        timeline: ActivityRootSteps.call(root_versions, history.root_snapshots),
-        activity_timeline: activity_steps(history, closing)
+        diff: Engine.compare(history.first_snapshot, final),
+        timeline: ActivityRootSteps.call(
+          plan, history.root_snapshots,
+          closing_snapshot: closing_snapshot, captured_at: captured_at
+        ),
+        activity_timeline: activity_steps(history, closing),
+        from_snapshot: history.first_snapshot,
+        to_snapshot: final
       )
     end
 
@@ -35,18 +41,46 @@ module PaperTrailDiff
     # @rbs @tree: AssociationTree
     # @rbs @snapshotter: untyped
 
-    #: () -> [ActivityHistory, Array[untyped], ActivityStep?]
+    #: () -> [ActivityHistory, RootVersionPlan, ActivityStep?, RecordSnapshot?, untyped]
     def history_and_versions
-      root_versions = @range.select(context_required: !@tree.empty?)
-      return [ActivityHistory.empty, root_versions, nil] if root_versions.empty?
+      plan = @range.select_plan(context_required: !@tree.empty?)
+      return [ActivityHistory.empty, plan, nil, nil, nil] if plan.reconstruction_versions.empty?
 
-      prepare_history(root_versions)
-      events = collect_events(root_versions)
-      selected = selected_events(events)
-      return [ActivityHistory.empty, root_versions, nil] unless time_events?(selected, events)
+      # A window closing on current state runs to the instant it is captured,
+      # not to the last root version, or descendants that moved after that
+      # version would be missing from a report that claims to reach now.
+      history_for(plan, plan.closing_record ? Time.now.utc : nil)
+    end
+
+    #: (RootVersionPlan, untyped) -> [ActivityHistory, RootVersionPlan, ActivityStep?, RecordSnapshot?, untyped]
+    def history_for(plan, captured_at)
+      root_versions = plan.reconstruction_versions
+      events = events_through(root_versions, captured_at)
+      selected = selected_events(events, plan)
+      unless time_events?(selected, events, plan)
+        return [ActivityHistory.empty, plan, nil, nil, nil]
+      end
 
       history = build_history(root_versions, events)
-      [history, root_versions, closing_step(history, selected.last)]
+      snapshot = current_snapshot(plan)
+      closing = closing_step(history, selected.last, plan, captured_at, snapshot)
+      [history, plan, closing, snapshot, captured_at]
+    end
+
+    # 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(plan)
+      record = plan.closing_record
+      return unless record
+
+      @snapshotter.call(record, record)
+    end
+
+    #: (Array[untyped], untyped) -> Array[ActivityEvent]
+    def events_through(root_versions, captured_at)
+      prepare_history(root_versions, end_at: captured_at)
+      collect_events(root_versions, range_end: captured_at)
     end
 
     #: (Array[untyped], Array[ActivityEvent]) -> ActivityHistory
@@ -66,17 +100,34 @@ module PaperTrailDiff
       (history.steps + [closing]).freeze
     end
 
-    #: (Array[ActivityEvent]) -> Array[ActivityEvent]
-    def selected_events(events)
-      events.select { |event| @range.include?(event.version) }
+    # 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(events, plan)
+      events.select do |event|
+        next false unless @range.include?(event.version)
+
+        !event.root? || plan.mutation?(event.version)
+      end
     end
 
-    # 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(history, event)
-      return unless event && terminal_destroy?(event)
+    # 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(history, event, plan, captured_at, snapshot)
+      return unless event
+      return destroyed_step(history, event) if terminal_destroy?(event)
+      return unless plan.closing_record
 
+      current_step(history, plan.closing_record, captured_at, snapshot)
+    end
+
+    #: (ActivityHistory, ActivityEvent) -> ActivityStep
+    def destroyed_step(history, event)
       version = event.version
       ActivityStep.new(
         from_boundary: ActivityBoundary.from_version(version),
@@ -85,6 +136,21 @@ module PaperTrailDiff
       )
     end
 
+    # 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(history, record, captured_at, snapshot)
+      previous = history.steps.last&.to_boundary
+      return unless previous
+
+      ActivityStep.new(
+        from_boundary: previous,
+        to_boundary: ActivityBoundary.current(record, captured_at: captured_at),
+        diff: Engine.compare(history.last_snapshot, snapshot)
+      )
+    end
+
     #: (ActivityEvent?) -> bool
     def terminal_destroy?(event)
       return false unless event
@@ -92,30 +158,34 @@ module PaperTrailDiff
       event.root? && event.version.event.to_s == 'destroy'
     end
 
-    #: (Array[untyped]) -> void
-    def prepare_history(root_versions)
+    #: (Array[untyped], ?end_at: untyped) -> void
+    def prepare_history(root_versions, end_at: nil)
       return unless @snapshotter.respond_to?(:prepare)
 
-      @snapshotter.prepare(@record, root_versions, start_at: @range.begin_time)
+      start_at = @range.begin_time
+      return @snapshotter.prepare(@record, root_versions, start_at: start_at) unless end_at
+
+      @snapshotter.prepare(@record, root_versions, start_at: start_at, end_at: end_at)
     end
 
-    #: (Array[untyped]) -> Array[ActivityEvent]
-    def collect_events(root_versions)
+    #: (Array[untyped], ?range_end: untyped) -> Array[ActivityEvent]
+    def collect_events(root_versions, range_end: nil)
       ActivityVersionCollector.new(
         @record,
         root_versions: root_versions,
         tree: @tree,
         traversal: AssociationTraversal.new(@tree),
         range_start: @range.begin_time,
-        range_end: root_versions.last
+        range_end: range_end || root_versions.last
       ).call
     end
 
-    #: (Array[ActivityEvent], Array[ActivityEvent]) -> bool
-    def time_events?(selected, events)
+    #: (Array[ActivityEvent], Array[ActivityEvent], RootVersionPlan) -> bool
+    def time_events?(selected, events, plan)
       return false if selected.empty?
       return true if later_event?(selected.last, events)
       return true if terminal_destroy?(selected.last)
+      return true if plan.closing_record
 
       message = 'time range requires a later activity boundary to reconstruct its final change'
       raise IncompleteTimeRangeError, message