paper_trail_diff 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 88e9b952c5cfe214974d5eab1a9d6e5a30dcfeb34ebc4193110f478d0cd9884a
-  data.tar.gz: 3a66b3ae3a77b65097ece227010c423beb05ec4ebd981edee396b824638c801c
+  metadata.gz: 33b445f893d6d95faf0ad22b72d35e8b248f3c00240e537898cac2d067ece043
+  data.tar.gz: 57ee0b8fc242825852726933a9aa332cd309c38d2af21724a41c4bfcfbf2bd41
 SHA512:
-  metadata.gz: 413fcd69a9ef2b49abb2238d77b279ac2dd4001cc8b5d98d1bbcb92843a6b428aeed967ba7ba8efb10dca1fcd5e912ca4221b0a8a854e0cd624a7b95fcc21ae1
-  data.tar.gz: f5968acfec8ce8189e1fcd3122b4fc3934b7cf989278c1b8feb87ed087da93132c35f7d20df8d64e49832fabe052b5cd80d6fdc5182af3e9be6c2d308ab3acf1
+  metadata.gz: bbbdea8be4b4300705da0f915dbe3b61ede862817fa27c44f0371c8454f9995f20b16120acc43cf0272f8fdecfdef4fa5fce160642812805a2c636f6f6acf9a0
+  data.tar.gz: e6f9a063c376a1214b1deacbd0ea15e325e82a1cccecd86d3d747268471bac0b20585249a4dcb1f039730f39bb019cc35a7e12a2e0bbfb963d4cc856acd6d2ef

data/CHANGELOG.md

@@ -3,6 +3,34 @@
 All notable changes to this project will be documented in this file. The
 project follows [Semantic Versioning](https://semver.org/).
 
+## [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

@@ -324,10 +324,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 +340,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 +391,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 +628,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/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))

data/lib/paper_trail_diff/root_version_selection.rb

@@ -13,9 +13,10 @@ module PaperTrailDiff
   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
+    #: (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 +24,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 +46,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 +85,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