paper_trail_diff 0.6.0 → 0.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 88e9b952c5cfe214974d5eab1a9d6e5a30dcfeb34ebc4193110f478d0cd9884a
-  data.tar.gz: 3a66b3ae3a77b65097ece227010c423beb05ec4ebd981edee396b824638c801c
+  metadata.gz: a84116670d1dd65a6cf569a266ccc8587a9eab4e65d38cf84df485c26d33d9dc
+  data.tar.gz: 2c8ddb0fd1b2203e644f3c50ed24da33ed25cb4c4240665eab85368cd4534f22
 SHA512:
-  metadata.gz: 413fcd69a9ef2b49abb2238d77b279ac2dd4001cc8b5d98d1bbcb92843a6b428aeed967ba7ba8efb10dca1fcd5e912ca4221b0a8a854e0cd624a7b95fcc21ae1
-  data.tar.gz: f5968acfec8ce8189e1fcd3122b4fc3934b7cf989278c1b8feb87ed087da93132c35f7d20df8d64e49832fabe052b5cd80d6fdc5182af3e9be6c2d308ab3acf1
+  metadata.gz: 3e32ecbedd636456388129cc664cf688b0aa909d5c05b45124eb1a6bd82dabbffa96557fe5efc946e93fe459234d3c4c5ce9af11f39228ddab55228f5a53e2f9
+  data.tar.gz: 1b29680ab942334fd98ce5cc0a4f2bc823fd180b258282e8be2c07ba784c9c3b5aa9edc76e0e118fec3baabcfbc94344c208aef116702874c0eb4dd226cddcac

data/CHANGELOG.md

@@ -3,6 +3,55 @@
 All notable changes to this project will be documented in this file. The
 project follows [Semantic Versioning](https://semver.org/).
 
+## [0.7.1] - 2026-08-11
+
+### Fixed
+
+- Load each current endpoint once per call instead of once per request for it,
+  so `close_on: :current` no longer costs a live read per root and
+  `analyze_many` keeps the flat query cost it exists for. A twenty-root batch
+  closing on current state issued 43 queries against the 3 a closed window
+  needs. Every root in one result now also reflects the same instant rather
+  than whenever its turn came.
+
+### Changed
+
+- Name the way out in `IncompleteTimeRangeError`: the message now points at
+  `close_on: :current` and at narrowing the window. Its previous advice — add a
+  checkpoint after the window — cannot be followed by a report about the
+  present, which is the case that raises it most.
+- Correct the `reload_live_endpoints:` documentation, which claimed `timeline`
+  and `analyze` never read live state. They do under `close_on: :current`, and
+  they do not accept the option.
+
+## [0.7.0] - 2026-08-11
+
+### Added
+
+- Accept `close_on: :current` on `timeline`, `activity_timeline`, `analyze`, and
+  `analyze_many`, closing a wall-clock window on the live record when no later
+  root version can reveal its final mutation. A window ending at the present
+  otherwise raises `IncompleteTimeRangeError`, since a version records the state
+  before its own event and nothing follows the last one. The closing step's
+  `to_boundary.kind` is `:current` and its `to_version` is `nil`; `Step#to_h`
+  now carries `to_boundary` so a serialized step still names its endpoint. Only
+  valid alongside `within:`, because an explicit `from:`/`to:` range already
+  says where it ends. Under `activity: true` the window runs to the instant
+  state is captured rather than to the last root version, so a descendant that
+  moved after that version is reported rather than dropped. A destroyed root has
+  no current state to close on and keeps closing on its own destruction.
+
+### Changed
+
+- Document that `version_scope:` selects root versions only, and that "what did
+  this person change?" is answered by an activity timeline filtered on
+  `step.from_boundary.whodunnit` instead. A step's diff is exactly what the
+  event at that boundary did, so the predicate covers descendant edits, which a
+  root-version filter cannot see at all. Filtering in Ruby rather than selecting
+  fewer versions is also what keeps the attribution correct: every boundary has
+  to be reconstructed, or the snapshot carried into the next step is a state the
+  record had already moved past.
+
 ## [0.6.0] - 2026-08-11
 
 ### Added

data/README.md

@@ -242,8 +242,13 @@ must observe one atomic snapshot.
 
 `compare`, `compare_many`, and `activity_timeline(..., to: record)` reload
 current endpoints by default. A caller that already owns a consistent, fully
-preloaded graph may opt out. The option has no effect on `timeline` or
-`analyze`, which are bounded by versions and never read live state:
+preloaded graph may opt out. Each endpoint is loaded once per call, so a batch
+that resolves every root up front and then reads one of them again pays
+nothing the second time, and every root in one result reflects the same instant.
+
+The option is not accepted by `timeline`, `analyze`, or `analyze_many`. Those
+are bounded by versions and read live state only under
+[`close_on: :current`](#reporting-up-to-now), which always reloads:
 
 ```ruby
 orders = Order.where(id: order_ids).preload(line_items: :product).to_a
@@ -324,10 +329,10 @@ value is the same `Analysis` that `analyze` returns for one record. A root with
 no versions inside the window gets an empty `Analysis` rather than raising, so a
 listing page needs no special case. Root identities must be unique.
 
-### Reporting on a subset of mutations
+### Reporting on a subset of root mutations
 
-`version_scope:` narrows which root versions count as *selected mutations*,
-which is what a "changes made by a user" report needs:
+`version_scope:` narrows which root versions count as *selected mutations*, so a
+checkpoint timeline reports only some of them:
 
 ```ruby
 user_edits = ->(scope) { scope.where.not(whodunnit: nil) }
@@ -340,6 +345,12 @@ The hook receives the version relation for the range and returns a narrowed one.
 It is accepted by `timeline`, `activity_timeline`, `analyze`, and
 `analyze_many`, with any range form.
 
+**It sees root versions only.** Someone who edited only comments or tags has no
+root versions to select, so filtering to them yields an empty result even though
+they changed plenty. For "what did this person change?", reach for
+[one person's changes](#reporting-on-one-persons-changes) instead — this hook
+answers the different question of which *root checkpoints* a timeline reports.
+
 It filters *selected mutations only*. Versions the filter excludes are still
 loaded, because a version records the state before its own event: without the
 one that follows a selected change, whatever that change produced cannot be
@@ -385,6 +396,49 @@ batches far less.
 Roots are supplied as live records, so a root deleted inside the window cannot
 be included; use `activity_timeline` for a history that ends in a deletion.
 
+### Reporting on one person's changes
+
+An activity timeline already carries this. Every boundary in the span becomes a
+step, and a step's diff is exactly what the event at its `from_boundary` did, so
+that boundary's `whodunnit` is who made the change:
+
+<!-- executable:readme-person-changes -->
+```ruby
+steps = PaperTrailDiff.activity_timeline(
+  article, within: window, associations: %i[comments tags]
+)
+
+attributed = steps.reject(&:empty?)
+by_priya = attributed.select { |step| step.from_boundary.whodunnit == "Priya Shah" }
+
+by_priya.first.from_boundary.whodunnit  # "Priya Shah"
+by_priya.first.diff                     # exactly what that one event changed
+
+authors = attributed.group_by { |step| step.from_boundary.whodunnit }
+                    .transform_values(&:length)
+```
+
+This covers descendants, which is what `version_scope:` cannot do. On one demo
+history a contributor who only ever touched comments and authorships has four
+attributed activity steps and *zero* root steps.
+
+Filter in Ruby rather than asking the gem to select fewer versions. Attribution
+is only correct because every boundary is reconstructed: skip one and the
+snapshot carried into the next step is a state the record had already moved
+past, so the change lands on the wrong person. There is nothing to save by
+filtering earlier — the work is the reconstruction, not the comparison — and a
+predicate can say things a version relation cannot, such as several people at
+once or "anyone but the importer".
+
+`reject(&:empty?)` first, because a boundary that changed nothing you selected
+still produces a step. The final event in the range has no boundary after it, so
+what it produced is not shown — the same blind spot `to:` has everywhere else.
+
+For "which of these records did someone touch?" across a listing, note that
+`analyze_many` batches the diff and timeline views but not descendant discovery.
+Querying versions by `whodunnit` and mapping them back to roots yourself will be
+much cheaper than an activity pass per record.
+
 ## Build a root-checkpoint timeline
 
 `timeline` accepts two version objects from the supplied record's history, or
@@ -579,12 +633,39 @@ version to reveal the final selected mutation. That version is reconstruction
 context, not an additional selected mutation.
 
 If the window contains a relevant mutation but no later root version exists,
-the call raises `PaperTrailDiff::IncompleteTimeRangeError`. Create a root
-checkpoint after the reporting window before running historical analysis. The
-gem does not silently substitute current database state. A root-only window
-with no selected mutation returns a frozen empty timeline. The one exception is
-a window that closes on the root's own destruction, which no later version can
-ever follow; see [closing a destroyed root](#closing-a-destroyed-root).
+the call raises `PaperTrailDiff::IncompleteTimeRangeError`. The gem does not
+silently substitute current database state; pass
+[`close_on: :current`](#reporting-up-to-now) to ask for it, or create a root
+checkpoint after the reporting window. A root-only window with no selected
+mutation returns a frozen empty timeline. The one exception is a window that
+closes on the root's own destruction, which no later version can ever follow;
+see [closing a destroyed root](#closing-a-destroyed-root).
+
+### Reporting up to now
+
+A window whose end is the present has nothing recorded after its final
+mutation, so by default it raises. `close_on: :current` closes it on the live
+record instead:
+
+```ruby
+PaperTrailDiff.analyze_many(
+  articles, within: month_start..Time.current, close_on: :current
+)
+```
+
+It is accepted by `timeline`, `activity_timeline`, `analyze`, and
+`analyze_many`, and only alongside `within:` — a range whose endpoints you gave
+explicitly already says where it ends. The closing step's `to_boundary.kind` is
+`:current` and its `to_version` is `nil`, so read the boundary rather than the
+version on the last step. Under `activity: true` the window runs to the instant
+state is captured rather than to the last root version, so a descendant that
+moved after that version is still reported.
+
+Two things follow from closing on live state. Current state includes changes
+PaperTrail never recorded — an `update_columns` write shows up in that final
+step, attributed to the version that precedes it, because nothing else records
+who made it. And a destroyed root has no current state to close on, so it keeps
+closing on its own destruction as it already did.
 
 Time ranges and explicit `from:`/`to:` endpoints are mutually exclusive.
 Malformed, open-ended, or reversed ranges raise

data/lib/paper_trail_diff/activity_root_steps.rb

@@ -7,20 +7,30 @@ module PaperTrailDiff
   module ActivityRootSteps
     module_function
 
-    #: (RootVersionPlan, Hash[Array[untyped], RecordSnapshot?]) -> Array[Step]
-    def call(plan, root_snapshots)
-      plan.steps.map do |from_version, to_version|
+    # 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 call(plan, root_snapshots, closing_snapshot: nil, captured_at: nil)
+      plan.steps.map do |from_endpoint, to_endpoint|
         Step.new(
-          from_version: from_version,
-          to_version: to_version,
+          from_version: from_endpoint,
+          to_version: to_endpoint,
+          captured_at: captured_at,
           diff: Engine.compare(
-            root_snapshots[version_key(from_version)],
-            root_snapshots[version_key(to_version)]
+            root_snapshots[version_key(from_endpoint)],
+            snapshot_for(to_endpoint, root_snapshots, closing_snapshot)
           )
         )
       end.freeze
     end
 
+    #: (untyped, Hash[Array[untyped], RecordSnapshot?], RecordSnapshot?) -> RecordSnapshot?
+    def snapshot_for(endpoint, root_snapshots, closing_snapshot)
+      return closing_snapshot if Endpoint.record?(endpoint)
+
+      root_snapshots[version_key(endpoint)]
+    end
+
     #: (untyped) -> Array[untyped]
     def version_key(version)
       [version.class.name, version.id]

data/lib/paper_trail_diff/analysis_batch.rb

@@ -6,13 +6,15 @@ 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
+    #: (Array[untyped], time_range: TimeRange?, live_loader: untyped, history_preparer: untyped, analyzer: untyped, ?version_scope: untyped, ?close_on_current: bool) -> void
     def initialize( # rubocop:disable Metrics/ParameterLists
-      records, time_range:, live_loader:, history_preparer:, analyzer:, version_scope: nil
+      records, time_range:, live_loader:, history_preparer:, analyzer:, version_scope: nil,
+      close_on_current: false
     )
       @records = records
       @time_range = time_range
       @version_scope = validated_scope(version_scope)
+      @close_on_current = close_on_current
       @live_loader = live_loader
       @history_preparer = history_preparer
       @analyzer = analyzer
@@ -21,10 +23,12 @@ module PaperTrailDiff
     #: () -> Hash[identity, Analysis]
     def call
       records = validated_records
+      loaded = @live_loader.call(records)
       selected = BatchedRootVersions.new(
-        records, time_range: @time_range, version_scope: @version_scope
+        records, time_range: @time_range, version_scope: @version_scope,
+                 live_endpoints: (loaded if @close_on_current)
       ).call
-      prepare(records, selected)
+      prepare(records, selected, loaded)
       records.to_h do |record|
         key = Endpoint.identity(record)
         plan = selected.fetch(key, RootVersionPlan.empty)
@@ -37,6 +41,7 @@ module PaperTrailDiff
     # @rbs @records: Array[untyped]
     # @rbs @time_range: TimeRange?
     # @rbs @version_scope: untyped
+    # @rbs @close_on_current: bool
     # @rbs @live_loader: untyped
     # @rbs @history_preparer: untyped
     # @rbs @analyzer: untyped
@@ -66,9 +71,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(records, selected)
-      loaded = @live_loader.call(records)
+    #: (Array[untyped], Hash[Array[String], RootVersionPlan], Hash[Array[String], untyped]) -> void
+    def prepare(records, selected, loaded)
       records.group_by(&:class).each_value do |grouped|
         versions = grouped.flat_map do |record|
           selected.fetch(Endpoint.identity(record), RootVersionPlan.empty).versions

data/lib/paper_trail_diff/batched_root_versions.rb

@@ -6,11 +6,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?, ?version_scope: untyped) -> void
-    def initialize(records, time_range:, version_scope: nil)
+    #: (Array[untyped], time_range: TimeRange?, ?version_scope: untyped, ?live_endpoints: Hash[Array[String], untyped]?) -> void
+    def initialize(records, time_range:, version_scope: nil, live_endpoints: nil)
       @records = records
       @time_range = time_range
       @version_scope = version_scope
+      @live_endpoints = live_endpoints
     end
 
     # Returns a plan per record identity.
@@ -30,6 +31,7 @@ module PaperTrailDiff
     # @rbs @records: Array[untyped]
     # @rbs @time_range: TimeRange?
     # @rbs @version_scope: untyped
+    # @rbs @live_endpoints: Hash[Array[String], untyped]?
 
     #: (untyped, Array[untyped], Hash[Array[String], RootVersionPlan]) -> void
     def select_model(model_class, records, selected)
@@ -38,7 +40,8 @@ module PaperTrailDiff
       records.each do |record|
         key = identity(model_class, record.id)
         selected[key] = versions_for(
-          in_range.fetch(record.id.to_s, []), chosen, trailing[record.id.to_s]
+          in_range.fetch(record.id.to_s, []), chosen, trailing[record.id.to_s],
+          live_endpoint(key, record)
         )
       end
     end
@@ -54,17 +57,29 @@ module PaperTrailDiff
       ]
     end
 
-    #: (Array[untyped], Set[untyped]?, untyped) -> RootVersionPlan
-    def versions_for(in_range, chosen, after_range)
+    #: (Array[untyped], Set[untyped]?, untyped, untyped) -> RootVersionPlan
+    def versions_for(in_range, chosen, after_range, live_endpoint)
       RootVersionSelection.new(
         in_range: in_range,
         selected: chosen ? in_range.select { |version| chosen.include?(version.id) } : in_range,
         after_range: after_range,
         windowed: !@time_range.nil?,
-        filtered: !@version_scope.nil?
+        filtered: !@version_scope.nil?,
+        live_endpoint: live_endpoint
       ).call
     end
 
+    # 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(key, record)
+      loaded = @live_endpoints
+      return unless loaded
+
+      current = loaded.fetch(key, record)
+      current unless current.destroyed?
+    end
+
     # One extra query names the selected mutations without discarding the
     # unfiltered versions the successor lookup still needs.
     #: (untyped, Array[untyped], TimeRange?) -> Set[untyped]?

data/lib/paper_trail_diff/live_endpoint_provider.rb

@@ -23,18 +23,37 @@ module PaperTrailDiff
                 else
                   PreloadedEndpointBatchLoader.new(tree: tree, traversal: traversal)
                 end
+      @loaded = {} #: Hash[identity, untyped]
     end
 
+    # Loads each endpoint at most once for the life of this provider, which is
+    # one public call. A batch that resolves every root up front and then asks
+    # again for one of them costs nothing the second time, and every root in the
+    # result reflects the same instant rather than whenever its turn came.
     #: (Array[untyped]) -> Hash[identity, untyped]
     def call(records)
-      Instrumentation.instrument('load_live_endpoints', payload(records)) do
-        @loader.call(records)
+      missing = records.reject { |record| @loaded.key?(Endpoint.identity(record)) }
+      return known(records) if missing.empty?
+
+      loaded = Instrumentation.instrument('load_live_endpoints', payload(missing)) do
+        @loader.call(missing)
       end
+      @loaded.merge!(loaded)
+      known(records)
     end
 
     private
 
     # @rbs @loader: untyped
+    # @rbs @loaded: Hash[identity, untyped]
+
+    #: (Array[untyped]) -> Hash[identity, untyped]
+    def known(records)
+      records.to_h do |record|
+        identity = Endpoint.identity(record)
+        [identity, @loaded.fetch(identity)]
+      end
+    end
 
     #: (Array[untyped]) -> Hash[Symbol, untyped]
     def payload(records)

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,8 +53,8 @@ module PaperTrailDiff
       end
     end
 
-    #: (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped) -> Array[Step]
-    def timeline(record, from:, to:, within:, version_scope: nil)
+    #: (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)
       TimelineBuilder.new(
         record,
@@ -59,46 +62,47 @@ module PaperTrailDiff
         to: to,
         within: within,
         version_scope: version_scope,
+        live_endpoint: live_endpoint_for(record, close_on, within),
         snapshotter: @timeline_snapshotter
       ).build
     end
 
-    #: (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped) -> Array[ActivityStep]
-    def activity_timeline(record, from:, to:, within:, version_scope: nil)
+    #: (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)
+        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
+          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, ?version_scope: untyped) -> Analysis
-    def analyze(record, from:, to:, within:, activity: false, version_scope: nil) # rubocop:disable Metrics/ParameterLists
+    #: (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
-        return activity_builder(
-          record, from: from, to: to, within: within, version_scope: version_scope
-        ).analyze
+        return analyze_activity(
+          record, from: from, to: to, within: within,
+                  version_scope: version_scope, live_endpoint: live
+        )
       end
 
       TimelineBuilder.new(
-        record,
-        from: from,
-        to: to,
-        within: within,
-        version_scope: version_scope,
-        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, ?version_scope: untyped) -> Hash[identity, Analysis]
-    def analyze_many(records, within:, activity: false, version_scope: nil)
+    #: (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
@@ -106,6 +110,7 @@ module PaperTrailDiff
           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)
@@ -127,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
 
@@ -173,12 +212,13 @@ module PaperTrailDiff
       )
     end
 
-    #: (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped) -> ActivityTimelineBuilder
-    def activity_builder(record, from:, to:, within:, version_scope: nil)
+    #: (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, version_scope: version_scope
+          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

@@ -20,6 +20,10 @@ module PaperTrailDiff
     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]
@@ -43,10 +47,12 @@ module PaperTrailDiff
       end
     end
 
-    #: (versions: Array[untyped], steps: Array[[untyped, untyped]], ?context_version: untyped, ?reconstruction_versions: Array[untyped]?, ?mutations: Array[untyped]?) -> void
-    def initialize(
-      versions:, steps:, context_version: nil, reconstruction_versions: nil, mutations: nil
+    #: (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
@@ -61,6 +67,13 @@ module PaperTrailDiff
       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))