paper_trail_diff 0.6.0 → 0.7.0

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,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

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.0'
 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.

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, ?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, ?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, ?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, ?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, ?version_scope: untyped) -> Analysis
-    def analyze: (untyped, from: untyped, to: untyped, within: untyped, ?activity: bool, ?version_scope: untyped) -> 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, ?version_scope: untyped) -> Hash[identity, Analysis]
-    def analyze_many: (Array[untyped], within: untyped, ?activity: bool, ?version_scope: untyped) -> 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, ?version_scope: untyped) -> ActivityTimelineBuilder
-    def activity_builder: (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: 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

@@ -23,6 +23,11 @@ module PaperTrailDiff
 
     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]
@@ -34,12 +39,17 @@ module PaperTrailDiff
     # : () -> 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
+    # : (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