paper_trail_diff 0.6.0 → 0.7.1

data/lib/paper_trail_diff/root_version_selection.rb

@@ -11,11 +11,17 @@ module PaperTrailDiff
   # 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) -> void
+    # An error is a specification, so it names the way out as well as the wall.
+    # A window ending at the present can never gain a later version, which makes
+    # "write a checkpoint afterwards" impossible advice on its own.
+    INCOMPLETE = 'time range requires a later root version to reconstruct its ' \
+                 'final change: pass close_on: :current to end at current state, ' \
+                 'or narrow the window to end before the last recorded version'
+
+    #: (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
+      in_range:, selected:, after_range:, windowed:, context_required: false, filtered: false,
+      live_endpoint: nil
     )
       @in_range = in_range
       @selected = selected
@@ -23,18 +29,18 @@ module PaperTrailDiff
       @windowed = windowed
       @context_required = context_required
       @filtered = filtered
+      @live_endpoint = live_endpoint
     end
 
     #: () -> RootVersionPlan
     def call
       return without_selection if @selected.empty?
 
-      revealing = revealing_version
-      raise IncompleteTimeRangeError, INCOMPLETE if !revealing && @windowed && !terminal_destroy?
-      return filtered_plan(revealing) if @filtered
+      closing = revealing_version || @live_endpoint
+      raise IncompleteTimeRangeError, INCOMPLETE if !closing && @windowed && !terminal_destroy?
+      return filtered_plan(closing) if @filtered
 
-      versions = revealing ? (@selected + [revealing]) : @selected
-      RootVersionPlan.contiguous(versions, context_version: revealing)
+      contiguous_plan(closing)
     end
 
     private
@@ -45,6 +51,22 @@ module PaperTrailDiff
     # @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.
@@ -68,13 +90,20 @@ module PaperTrailDiff
         successor = version.equal?(@selected.last) ? revealing : immediate_successor(version)
         [version, successor] if successor
       end #: Array[[untyped, untyped]]
-      versions = chronological(steps.flatten(1) + closing_versions)
+      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,
+        versions: versions, steps: steps,
+        context_version: (revealing unless live),
         reconstruction_versions: spanned(versions),
-        mutations: @selected
+        mutations: @selected, closing_record: live
       )
     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,19 +14,23 @@ module PaperTrailDiff
 
     #: () -> Array[ActivityStep]
     def build
-      history, _plan, closing = history_and_versions
+      history, _plan, closing, = history_and_versions
       activity_steps(history, closing)
     end
 
     #: () -> Analysis
     def analyze
-      history, plan, 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(plan, history.root_snapshots),
+        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: history.last_snapshot
+        to_snapshot: final
       )
     end
 
@@ -37,19 +41,46 @@ module PaperTrailDiff
     # @rbs @tree: AssociationTree
     # @rbs @snapshotter: untyped
 
-    #: () -> [ActivityHistory, RootVersionPlan, ActivityStep?]
+    #: () -> [ActivityHistory, RootVersionPlan, ActivityStep?, RecordSnapshot?, untyped]
     def history_and_versions
       plan = @range.select_plan(context_required: !@tree.empty?)
-      root_versions = plan.reconstruction_versions
-      return [ActivityHistory.empty, plan, nil] if root_versions.empty?
+      return [ActivityHistory.empty, plan, nil, nil, nil] if plan.reconstruction_versions.empty?
+
+      # 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
 
-      prepare_history(root_versions)
-      events = collect_events(root_versions)
+    #: (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)
-      return [ActivityHistory.empty, plan, nil] unless time_events?(selected, events)
+      unless time_events?(selected, events, plan)
+        return [ActivityHistory.empty, plan, nil, nil, nil]
+      end
 
       history = build_history(root_versions, events)
-      [history, plan, 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
@@ -83,12 +114,20 @@ module PaperTrailDiff
       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),
@@ -97,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
@@ -104,32 +158,38 @@ 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'
+      message = 'time range requires a later activity boundary to reconstruct its ' \
+                'final change: pass close_on: :current to end at current state, ' \
+                'or narrow the window to end before the last recorded boundary'
       raise IncompleteTimeRangeError, message
     end
 

data/lib/paper_trail_diff/time_version_range.rb

@@ -4,11 +4,12 @@
 module PaperTrailDiff
   # Selects in-range root versions plus one later reconstruction boundary.
   class TimeVersionRange
-    #: (untyped, time_range: TimeRange, ?version_scope: untyped) -> void
-    def initialize(record, time_range:, version_scope: nil)
+    #: (untyped, time_range: TimeRange, ?version_scope: untyped, ?live_endpoint: untyped) -> void
+    def initialize(record, time_range:, version_scope: nil, live_endpoint: nil)
       @record = record
       @time_range = time_range
       @version_scope = version_scope
+      @live_endpoint = live_endpoint
     end
 
     #: (?context_required: bool) -> Array[untyped]
@@ -27,7 +28,8 @@ module PaperTrailDiff
         after_range: trailing_version(relation),
         windowed: true,
         context_required: context_required,
-        filtered: !@version_scope.nil?
+        filtered: !@version_scope.nil?,
+        live_endpoint: @live_endpoint
       ).call
     end
 
@@ -36,6 +38,7 @@ module PaperTrailDiff
     # @rbs @record: untyped
     # @rbs @time_range: TimeRange
     # @rbs @version_scope: untyped
+    # @rbs @live_endpoint: untyped
 
     #: () -> untyped
     def versions_relation

data/lib/paper_trail_diff/timeline_builder.rb

@@ -4,14 +4,16 @@
 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]?, ?version_scope: untyped, ?plan: RootVersionPlan?) -> void
+    #: (untyped, from: untyped, to: untyped, snapshotter: untyped, ?within: untyped, ?versions: Array[untyped]?, ?version_scope: untyped, ?plan: RootVersionPlan?, ?live_endpoint: untyped) -> void
     def initialize( # rubocop:disable Metrics/ParameterLists
-      record, from:, to:, snapshotter:, within: nil, versions: nil, version_scope: nil, plan: nil
+      record, from:, to:, snapshotter:, within: nil, versions: nil, version_scope: nil, plan: nil,
+      live_endpoint: nil
     )
       @record = record
       @range = TimelineRange.new(
         record, from: from, to: to, within: within,
-                versions: versions, version_scope: version_scope, plan: plan
+                versions: versions, version_scope: version_scope, plan: plan,
+                live_endpoint: live_endpoint
       )
       @snapshotter = snapshotter
     end
@@ -45,14 +47,21 @@ module PaperTrailDiff
 
       versions = plan.versions
       @snapshotter.prepare(@record, versions) if @snapshotter.respond_to?(:prepare)
-      steps = plan.steps.map do |from_version, to_version|
+      steps = build_steps(plan)
+      [steps, @snapshotter.call(versions.first), @snapshotter.call(plan.final_endpoint)]
+    end
+
+    #: (RootVersionPlan) -> Array[Step]
+    def build_steps(plan)
+      captured_at = Time.now.utc if plan.closing_record
+      plan.steps.map do |from_endpoint, to_endpoint|
         Step.new(
-          from_version: from_version,
-          to_version: to_version,
-          diff: Engine.compare(@snapshotter.call(from_version), @snapshotter.call(to_version))
+          from_version: from_endpoint,
+          to_version: to_endpoint,
+          captured_at: captured_at,
+          diff: Engine.compare(@snapshotter.call(from_endpoint), @snapshotter.call(to_endpoint))
         )
       end.freeze
-      [steps, @snapshotter.call(versions.first), @snapshotter.call(versions.last)]
     end
 
     #: () -> [Array[Step], nil, nil]

data/lib/paper_trail_diff/timeline_range.rb

@@ -10,10 +10,11 @@ module PaperTrailDiff
     attr_reader :to #: untyped
     attr_reader :time_range #: TimeRange?
 
-    #: (untyped, from: untyped, to: untyped, within: untyped, ?versions: Array[untyped]?, ?version_scope: untyped, ?plan: RootVersionPlan?) -> void
-    def initialize(record, from:, to:, within:, versions: nil, version_scope: nil, plan: nil) # rubocop:disable Metrics/ParameterLists
+    #: (untyped, from: untyped, to: untyped, within: untyped, ?versions: Array[untyped]?, ?version_scope: untyped, ?plan: RootVersionPlan?, ?live_endpoint: untyped) -> void
+    def initialize(record, from:, to:, within:, versions: nil, version_scope: nil, plan: nil, live_endpoint: nil) # rubocop:disable Metrics/ParameterLists, Layout/LineLength
       @record = record
       @plan = plan
+      @live_endpoint = live_endpoint
       @versions = (plan ? plan.versions : versions)&.freeze
       @version_scope = version_scope
       @requested_from = from
@@ -44,7 +45,8 @@ module PaperTrailDiff
       range = time_range
       if range
         return TimeVersionRange.new(
-          @record, time_range: range, version_scope: @version_scope
+          @record, time_range: range, version_scope: @version_scope,
+                   live_endpoint: @live_endpoint
         ).select_plan(context_required: context_required)
       end
       return RootVersionPlan.empty if unresolved?
@@ -92,6 +94,7 @@ module PaperTrailDiff
     # @rbs @versions: Array[untyped]?
     # @rbs @plan: RootVersionPlan?
     # @rbs @version_scope: untyped
+    # @rbs @live_endpoint: untyped
     # @rbs @requested_from: untyped
     # @rbs @requested_to: untyped
     # @rbs @from: untyped

data/lib/paper_trail_diff/timeline_snapshot_provider.rb

@@ -4,9 +4,10 @@
 module PaperTrailDiff
   # Gives TimelineBuilder one-argument access to a range-prepared snapshot store.
   class TimelineSnapshotProvider
-    #: (HistoricalSnapshotStore) -> void
-    def initialize(store)
+    #: (HistoricalSnapshotStore, ?live_snapshotter: untyped) -> void
+    def initialize(store, live_snapshotter: nil)
       @store = store
+      @live_snapshotter = live_snapshotter
     end
 
     #: (untyped, Array[untyped]) -> void
@@ -14,11 +15,26 @@ module PaperTrailDiff
       @store.prepare(record, versions)
     end
 
+    # 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(version)
-      @store.uncached(version, version)
+    def call(endpoint)
+      return live_snapshot(endpoint) if Endpoint.record?(endpoint)
+
+      @store.uncached(endpoint, endpoint)
+    end
+
+    private
+
+    #: (untyped) -> RecordSnapshot?
+    def live_snapshot(record)
+      snapshotter = @live_snapshotter
+      raise InvalidTimelineRangeError, 'live endpoints are unavailable here' unless snapshotter
+
+      snapshotter.call(record)
     end
 
     # @rbs @store: HistoricalSnapshotStore
+    # @rbs @live_snapshotter: untyped
   end
 end

data/lib/paper_trail_diff/version.rb

@@ -2,5 +2,5 @@
 # rbs_inline: enabled
 
 module PaperTrailDiff
-  VERSION = '0.6.0'
+  VERSION = '0.7.1'
 end

data/lib/paper_trail_diff.rb

@@ -145,7 +145,7 @@ 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, ?version_scope: untyped) -> 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 timeline( # rubocop:disable Metrics/ParameterLists
       record,
       from: nil,
@@ -153,21 +153,23 @@ module PaperTrailDiff # rubocop:disable Metrics/ModuleLength
       within: nil,
       associations: [],
       ignore: DEFAULT_IGNORED_ATTRIBUTES,
-      version_scope: nil
+      version_scope: nil,
+      close_on: nil
     )
       PaperTrailAdapter.new(associations: associations, ignore: ignore).timeline(
         record,
         from: from,
         to: to,
         within: within,
-        version_scope: version_scope
+        version_scope: version_scope,
+        close_on: close_on
       )
     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, ?version_scope: untyped) -> 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 activity_timeline( # rubocop:disable Metrics/ParameterLists
       record,
       from: nil,
@@ -176,7 +178,8 @@ module PaperTrailDiff # rubocop:disable Metrics/ModuleLength
       associations: [],
       ignore: DEFAULT_IGNORED_ATTRIBUTES,
       reload_live_endpoints: true,
-      version_scope: nil
+      version_scope: nil,
+      close_on: nil
     )
       PaperTrailAdapter.new(
         associations: associations,
@@ -187,12 +190,13 @@ module PaperTrailDiff # rubocop:disable Metrics/ModuleLength
         from: from,
         to: to,
         within: within,
-        version_scope: version_scope
+        version_scope: version_scope,
+        close_on: close_on
       )
     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, ?version_scope: untyped) -> 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 analyze( # rubocop:disable Metrics/ParameterLists
       record,
       from: nil,
@@ -201,7 +205,8 @@ module PaperTrailDiff # rubocop:disable Metrics/ModuleLength
       associations: [],
       ignore: DEFAULT_IGNORED_ATTRIBUTES,
       activity: false,
-      version_scope: nil
+      version_scope: nil,
+      close_on: nil
     )
       PaperTrailAdapter.new(associations: associations, ignore: ignore).analyze(
         record,
@@ -209,27 +214,30 @@ module PaperTrailDiff # rubocop:disable Metrics/ModuleLength
         to: to,
         within: within,
         activity: activity,
-        version_scope: version_scope
+        version_scope: version_scope,
+        close_on: close_on
       )
     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, ?version_scope: untyped) -> 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 analyze_many( # rubocop:disable Metrics/ParameterLists
       records,
       within: nil,
       associations: [],
       ignore: DEFAULT_IGNORED_ATTRIBUTES,
       activity: false,
-      version_scope: nil
+      version_scope: nil,
+      close_on: nil
     )
       PaperTrailAdapter.new(associations: associations, ignore: ignore).analyze_many(
         records,
         within: within,
         activity: activity,
-        version_scope: version_scope
+        version_scope: version_scope,
+        close_on: close_on
       )
     end
 

data/sig/generated/paper_trail_diff/activity_root_steps.rbs

@@ -4,8 +4,13 @@ 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
-    # : (RootVersionPlan, Hash[Array[untyped], RecordSnapshot?]) -> Array[Step]
-    def self?.call: (RootVersionPlan, Hash[Array[untyped], RecordSnapshot?]) -> Array[Step]
+    # A window closing on current state ends at the live record, which no
+    # version-keyed snapshot can supply, so that endpoint is passed in.
+    # : (RootVersionPlan, Hash[Array[untyped], RecordSnapshot?], ?closing_snapshot: RecordSnapshot?, ?captured_at: untyped) -> Array[Step]
+    def self?.call: (RootVersionPlan, Hash[Array[untyped], RecordSnapshot?], ?closing_snapshot: RecordSnapshot?, ?captured_at: untyped) -> Array[Step]
+
+    # : (untyped, Hash[Array[untyped], RecordSnapshot?], RecordSnapshot?) -> RecordSnapshot?
+    def self?.snapshot_for: (untyped, Hash[Array[untyped], RecordSnapshot?], RecordSnapshot?) -> RecordSnapshot?
 
     # : (untyped) -> Array[untyped]
     def self?.version_key: (untyped) -> Array[untyped]

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, ?version_scope: untyped) -> void
-    def initialize: (Array[untyped], time_range: TimeRange?, live_loader: untyped, history_preparer: untyped, analyzer: untyped, ?version_scope: untyped) -> void
+    # : (Array[untyped], time_range: TimeRange?, live_loader: untyped, history_preparer: untyped, analyzer: untyped, ?version_scope: untyped, ?close_on_current: bool) -> void
+    def initialize: (Array[untyped], time_range: TimeRange?, live_loader: untyped, history_preparer: untyped, analyzer: untyped, ?version_scope: untyped, ?close_on_current: bool) -> void
 
     # : () -> Hash[identity, Analysis]
     def call: () -> Hash[identity, Analysis]
@@ -15,6 +15,8 @@ module PaperTrailDiff
 
     @analyzer: untyped
 
+    @close_on_current: bool
+
     @history_preparer: untyped
 
     @live_loader: untyped
@@ -38,8 +40,8 @@ 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], RootVersionPlan]) -> void
-    def prepare: (Array[untyped], Hash[Array[String], RootVersionPlan]) -> void
+    # : (Array[untyped], Hash[Array[String], RootVersionPlan], Hash[Array[String], untyped]) -> void
+    def prepare: (Array[untyped], Hash[Array[String], RootVersionPlan], Hash[Array[String], untyped]) -> void
 
     # A root with no versions in range has nothing to report, which is an empty
     # result rather than a failed request.

data/sig/generated/paper_trail_diff/batched_root_versions.rbs

@@ -5,8 +5,8 @@ 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?, ?version_scope: untyped) -> void
-    def initialize: (Array[untyped], time_range: TimeRange?, ?version_scope: untyped) -> 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 a plan per record identity.
     # : () -> Hash[Array[String], RootVersionPlan]
@@ -14,6 +14,8 @@ module PaperTrailDiff
 
     private
 
+    @live_endpoints: Hash[Array[String], untyped]?
+
     @records: Array[untyped]
 
     @time_range: TimeRange?
@@ -26,8 +28,13 @@ module PaperTrailDiff
     # : (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
+    # : (Array[untyped], Set[untyped]?, untyped, untyped) -> RootVersionPlan
+    def versions_for: (Array[untyped], Set[untyped]?, untyped, untyped) -> RootVersionPlan
+
+    # 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.