paper_trail_diff 0.5.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a4d3c1e15ef20c4e3d05f5c0442d7e55cd0eb811a15766d2119a3cf35b2e729c
-  data.tar.gz: 4cc8dceb10e7aa71f1feb7d9fcc3917040bec4b2cc69641b4b3817d6761aad94
+  metadata.gz: 33b445f893d6d95faf0ad22b72d35e8b248f3c00240e537898cac2d067ece043
+  data.tar.gz: 57ee0b8fc242825852726933a9aa332cd309c38d2af21724a41c4bfcfbf2bd41
 SHA512:
-  metadata.gz: 3887a515ee90f1c14b890a21d4a91b4892f4097b74c9ec27f136fd8476f01cd285c0a310a03b0c528e709cdca299bca2e243522844d09a86d272c043e48879b1
-  data.tar.gz: a1390db78cc31cbf20420fd18b536ad8cd826de4927943cbdddc08b7a31f9dad5f81acee77db97059f044ad435bd3170e54f8ef2ccd5c68f3e256bfa5d848642
+  metadata.gz: bbbdea8be4b4300705da0f915dbe3b61ede862817fa27c44f0371c8454f9995f20b16120acc43cf0272f8fdecfdef4fa5fce160642812805a2c636f6f6acf9a0
+  data.tar.gz: e6f9a063c376a1214b1deacbd0ea15e325e82a1cccecd86d3d747268471bac0b20585249a4dcb1f039730f39bb019cc35a7e12a2e0bbfb963d4cc856acd6d2ef

data/CHANGELOG.md

@@ -3,6 +3,58 @@
 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
+
+- Accept `version_scope:` on `timeline`, `activity_timeline`, `analyze`, and
+  `analyze_many`, narrowing which root versions count as selected mutations.
+  Excluded versions are still loaded, because a version records the state before
+  its own event and the one following a selected change is what reveals it;
+  their own changes are never attributed to a selected mutation. Each selected
+  mutation is bounded by the version that immediately followed it rather than by
+  the next selected one, so its diff is exactly what that mutation did however
+  many excluded changes follow it. A selected mutation nothing follows yet is
+  not reported, since no version records the state it produced; a selected
+  destruction is the exception, because the absence it leaves is what it
+  produced and `activity_timeline` closes on it. A root left with
+  no selected mutation reports an empty `Analysis`. Under `activity: true` the
+  filter decides the span; `activity_timeline` still lists every boundary inside
+  it, because dropping one would fold its change into a neighbouring step.
+- Expose `from_snapshot` and `to_snapshot` on `Analysis`, the reconstructed
+  states its diff was taken between, so a report can render unchanged columns
+  without selecting versions or reifying them itself. `Analysis#to_h` keeps its
+  shape by default and takes `snapshots: true` to include them, because they
+  carry the whole selected graph whether or not anything changed.
+
 ## [0.5.0] - 2026-08-11
 
 ### Added

data/README.md

@@ -324,6 +324,58 @@ 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 root mutations
+
+`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) }
+
+PaperTrailDiff.analyze_many(articles, within: window, version_scope: user_edits)
+PaperTrailDiff.timeline(article, within: window, version_scope: user_edits)
+```
+
+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
+shown at all. Those extra versions are reconstruction context, so their own
+changes are never attributed to a selected mutation.
+
+Each selected mutation is bounded by the version that immediately followed it,
+not by the next selected one. So each step's diff is exactly what that mutation
+did, and it reads the same however many excluded changes happen to follow it:
+
+```
+versions   system → alice → system → bob → system
+reported   alice: what alice changed    bob: what bob changed
+```
+
+Given a user edit followed by a system edit, filtering to user changes yields
+one step running from the user version to the system version, whose diff is
+exactly the user's change. A selected mutation that nothing follows yet is not
+reported, since no version records the state it produced — the same blind spot
+an unfiltered timeline has at its `to:` boundary. A selected *destruction* is
+the exception: nothing can follow one, but the absence it leaves is what it
+produced, so `activity_timeline` still closes on it. A root with no selected
+mutation reports an empty `Analysis` rather than raising.
+
+The hook applies to root versions only. Under `activity: true` the filter
+decides where the span starts and ends, and `timeline` within that span reports
+only selected mutations, but `activity_timeline` still lists every boundary
+inside it — dropping one would fold the change it carried into a neighbouring
+step and credit it to whoever made that one.
+
 Omit `within:` to analyze each root's whole recorded history instead, which is
 the batched equivalent of `analyze(record, from: :first, to: :last)`. Explicit
 version endpoints are not accepted, because a single pair cannot mean the same
@@ -339,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
@@ -533,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
@@ -922,10 +1044,27 @@ The public result types are:
 - `PaperTrailDiff::DiagnosticReport`
 - `PaperTrailDiff::DiagnosticIssue`
 
+`Analysis` also exposes the reconstructed states its diff was taken between, as
+`from_snapshot` and `to_snapshot`. A report that renders unchanged columns needs
+the whole final state, not only what moved, and these are the states the gem
+already reconstructed:
+
+```ruby
+analysis.to_snapshot.attributes    # every selected scalar, changed or not
+analysis.to_snapshot.associations  # the selected association tree
+```
+
+Either is `nil` when that endpoint has no reconstructable state — most often a
+`from_snapshot` at a `create` boundary, whose pre-change state is the absence of
+the record. Following the precedent set by `Step`, `Analysis#to_h` is unchanged;
+serialize `to_snapshot.to_h` when a serialized form is wanted.
+
 They expose readers, are frozen after construction, and provide deterministic
 `to_h` output. Collection results are ordered by record identity: by type, then
 naturally within one id type, so numeric ids sort `2` before `10`. Mixed or
-unusual id types still order totally rather than raising. Structural hash keys are symbols; attribute and association
+unusual id types still order totally rather than raising.
+
+Structural hash keys are symbols; attribute and association
 names are strings. Attribute values retain their Ruby types. `RecordChange#record`
 is a `RecordReference` with `type` and `id` readers. `TraversalEntry#record` and
 `#association` return the final components of their corresponding paths. `Step`

data/lib/paper_trail_diff/activity_root_steps.rb

@@ -7,18 +7,30 @@ module PaperTrailDiff
   module ActivityRootSteps
     module_function
 
-    #: (Array[untyped], Hash[Array[untyped], RecordSnapshot?]) -> Array[Step]
-    def call(root_versions, root_snapshots)
-      snapshots = root_versions.map { |version| root_snapshots.fetch(version_key(version)) }
-      root_versions.each_cons(2).with_index.map do |versions, index|
+    # 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: versions.fetch(0),
-          to_version: versions.fetch(1),
-          diff: Engine.compare(snapshots.fetch(index), snapshots.fetch(index + 1))
+          from_version: from_endpoint,
+          to_version: to_endpoint,
+          captured_at: captured_at,
+          diff: Engine.compare(
+            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/activity_timeline_builder.rb

@@ -34,10 +34,11 @@ module PaperTrailDiff
         raise InvalidTimelineRangeError, '`to` must be a root PaperTrail version'
       end
 
-      root_versions = @range.select
+      plan = @range.select_plan
+      root_versions = plan.reconstruction_versions
       prepare_history(root_versions)
       events = collect_events(root_versions)
-      build_analysis(root_versions, events, event_history(root_versions, events))
+      build_analysis(plan, events, event_history(root_versions, events))
     end
 
     private
@@ -55,9 +56,13 @@ module PaperTrailDiff
       steps.freeze
     end
 
+    # Every boundary in the span, filtered out or not. A filter narrows where the
+    # span starts and ends, but the sequence inside it stays complete: dropping
+    # boundaries would fold the changes they carried into a neighbouring step and
+    # credit them to whoever made that one.
     #: () -> Array[ActivityStep]
     def build_between_versions
-      root_versions = @range.select
+      root_versions = @range.select_plan.reconstruction_versions
       prepare_history(root_versions)
       events = collect_events(root_versions)
       build_event_steps(root_versions, events)
@@ -177,14 +182,16 @@ module PaperTrailDiff
     # Only the activity view gains the closing removal. The endpoint diff and
     # the root timeline keep their `compare` and `timeline` semantics, under
     # which the state at a destroy version is the state before the deletion.
-    #: (Array[untyped], Array[ActivityEvent], ActivityHistory) -> Analysis
-    def build_analysis(root_versions, events, history)
+    #: (RootVersionPlan, Array[ActivityEvent], ActivityHistory) -> Analysis
+    def build_analysis(plan, events, history)
       Analysis.new(
         diff: Engine.compare(history.first_snapshot, history.last_snapshot),
-        timeline: ActivityRootSteps.call(root_versions, history.root_snapshots),
+        timeline: ActivityRootSteps.call(plan, history.root_snapshots),
         activity_timeline: activity_steps(
-          history, events, destroyed_boundary(root_versions), nil
-        )
+          history, events, destroyed_boundary(plan.reconstruction_versions), nil
+        ),
+        from_snapshot: history.first_snapshot,
+        to_snapshot: history.last_snapshot
       )
     end
 

data/lib/paper_trail_diff/analysis.rb

@@ -7,6 +7,8 @@ module PaperTrailDiff
     attr_reader :diff #: Diff
     attr_reader :timeline #: Array[Step]
     attr_reader :activity_timeline #: Array[ActivityStep]?
+    attr_reader :from_snapshot #: RecordSnapshot?
+    attr_reader :to_snapshot #: RecordSnapshot?
 
     # The result for a record whose requested history contains no versions,
     # which is an empty history rather than a failed request.
@@ -17,19 +19,31 @@ module PaperTrailDiff
       new(diff: Diff.new, timeline: timeline, activity_timeline: activity_timeline)
     end
 
-    #: (diff: Diff, timeline: Array[Step], ?activity_timeline: Array[ActivityStep]?) -> void
-    def initialize(diff:, timeline:, activity_timeline: nil)
+    # The reconstructed states the diff was taken between. A report that has to
+    # render unchanged columns needs the whole final state, not only what moved.
+    #: (diff: Diff, timeline: Array[Step], ?activity_timeline: Array[ActivityStep]?, ?from_snapshot: RecordSnapshot?, ?to_snapshot: RecordSnapshot?) -> void
+    def initialize(diff:, timeline:, activity_timeline: nil, from_snapshot: nil, to_snapshot: nil)
       @diff = diff
       @timeline = timeline.dup.freeze
       @activity_timeline = activity_timeline&.dup&.freeze
+      @from_snapshot = from_snapshot
+      @to_snapshot = to_snapshot
       freeze
     end
 
-    #: () -> Hash[Symbol, untyped]
-    def to_h
+    # Reconstructed endpoint states are opt-in, because they carry the whole
+    # selected graph whether or not anything changed, which dwarfs the rest of
+    # the payload for a wide graph.
+    #: (?snapshots: bool) -> Hash[Symbol, untyped]
+    def to_h(snapshots: false)
       value = { diff: diff.to_h, timeline: Support.serialize(timeline) }
       value[:activity_timeline] = Support.serialize(activity_timeline) if activity_timeline
-      value
+      return value unless snapshots
+
+      value.merge(
+        from_snapshot: Support.serialize(from_snapshot),
+        to_snapshot: Support.serialize(to_snapshot)
+      )
     end
   end
 end

data/lib/paper_trail_diff/analysis_batch.rb

@@ -6,10 +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) -> void
-    def initialize(records, time_range:, live_loader:, history_preparer:, analyzer:)
+    #: (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,
+      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
@@ -18,11 +23,16 @@ module PaperTrailDiff
     #: () -> Hash[identity, Analysis]
     def call
       records = validated_records
-      selected = BatchedRootVersions.new(records, time_range: @time_range).call
-      prepare(records, selected)
+      loaded = @live_loader.call(records)
+      selected = BatchedRootVersions.new(
+        records, time_range: @time_range, version_scope: @version_scope,
+                 live_endpoints: (loaded if @close_on_current)
+      ).call
+      prepare(records, selected, loaded)
       records.to_h do |record|
         key = Endpoint.identity(record)
-        [Support.immutable_copy(key), analysis_for(record, selected.fetch(key, []))]
+        plan = selected.fetch(key, RootVersionPlan.empty)
+        [Support.immutable_copy(key), analysis_for(record, plan)]
       end.freeze
     end
 
@@ -30,10 +40,21 @@ 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
 
+    # A filter is a callable that narrows the version relation, so it is checked
+    # up front rather than failing partway through a batch.
+    #: (untyped) -> untyped
+    def validated_scope(scope)
+      return scope if scope.nil? || scope.respond_to?(:call)
+
+      raise ConfigurationError, 'version_scope: must respond to call'
+    end
+
     #: () -> Array[untyped]
     def validated_records
       raise ConfigurationError, 'records: must be an array' unless @records.is_a?(Array)
@@ -50,11 +71,12 @@ 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], Array[untyped]]) -> 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 { |record| selected.fetch(Endpoint.identity(record), []) }
+        versions = grouped.flat_map do |record|
+          selected.fetch(Endpoint.identity(record), RootVersionPlan.empty).versions
+        end
         next if versions.empty?
 
         roots = grouped.map { |record| loaded.fetch(Endpoint.identity(record), record) }
@@ -64,11 +86,11 @@ module PaperTrailDiff
 
     # A root with no versions in range has nothing to report, which is an empty
     # result rather than a failed request.
-    #: (untyped, Array[untyped]) -> Analysis
-    def analysis_for(record, versions)
-      return Analysis.empty if versions.empty?
+    #: (untyped, RootVersionPlan) -> Analysis
+    def analysis_for(record, plan)
+      return Analysis.empty if plan.empty?
 
-      @analyzer.call(record, versions)
+      @analyzer.call(record, plan)
     end
   end
 end

data/lib/paper_trail_diff/batched_root_analyzer.rb

@@ -14,17 +14,17 @@ module PaperTrailDiff
       @activity = activity
     end
 
-    #: (untyped, Array[untyped]) -> Analysis
-    def call(record, versions)
+    #: (untyped, RootVersionPlan) -> Analysis
+    def call(record, plan)
       @preparer.call(record.class, historical: true)
-      return activity_analysis(record, versions) if @activity
+      return activity_analysis(record, plan) if @activity
 
       TimelineBuilder.new(
         record,
-        from: versions.first,
-        to: versions.last,
+        from: plan.versions.first,
+        to: plan.versions.last,
         within: nil,
-        versions: versions,
+        plan: plan,
         snapshotter: @timeline_snapshotter
       ).analyze
     end
@@ -37,10 +37,10 @@ module PaperTrailDiff
     # @rbs @preparer: untyped
     # @rbs @activity: bool
 
-    #: (untyped, Array[untyped]) -> Analysis
-    def activity_analysis(record, versions)
+    #: (untyped, RootVersionPlan) -> Analysis
+    def activity_analysis(record, plan)
       range = TimelineRange.new(
-        record, from: versions.first, to: versions.last, within: nil, versions: versions
+        record, from: plan.versions.first, to: plan.versions.last, within: nil, plan: plan
       )
       ActivityTimelineBuilder.new(
         record, range: range, tree: @tree, snapshotter: @activity_snapshotter

data/lib/paper_trail_diff/batched_root_versions.rb

@@ -6,18 +6,20 @@ 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?) -> void
-    def initialize(records, time_range:)
+    #: (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 root versions per record identity, in chronological order.
-    #: () -> Hash[Array[String], Array[untyped]]
+    # Returns a plan per record identity.
+    #: () -> Hash[Array[String], RootVersionPlan]
     def call
       return {} if @records.empty?
 
-      selected = {} #: Hash[Array[String], Array[untyped]]
+      selected = {} #: Hash[Array[String], RootVersionPlan]
       @records.group_by(&:class).each do |model_class, records|
         select_model(model_class, records, selected)
       end
@@ -28,47 +30,78 @@ 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], Array[untyped]]) -> void
+    #: (untyped, Array[untyped], Hash[Array[String], RootVersionPlan]) -> void
     def select_model(model_class, records, selected)
       ids = records.map(&:id)
-      range = @time_range
-      grouped = grouped_versions(model_class, ids, range)
-      empty = {} #: Hash[String, untyped]
-      trailing = range ? trailing_versions(model_class, ids, range) : empty
+      in_range, chosen, trailing = model_versions(model_class, ids)
       records.each do |record|
         key = identity(model_class, record.id)
-        selected[key] = versions_for(grouped.fetch(record.id.to_s, []), trailing[record.id.to_s])
+        selected[key] = versions_for(
+          in_range.fetch(record.id.to_s, []), chosen, trailing[record.id.to_s],
+          live_endpoint(key, record)
+        )
       end
     end
 
-    # The window's own versions plus, when it has one, the later version needed
-    # to reveal the last mutation inside it. A window closing on the root's own
-    # destruction needs no later version, because none can exist.
-    #: (Array[untyped], untyped) -> Array[untyped]
-    def versions_for(in_range, trailing)
-      return in_range if @time_range.nil?
-      return in_range.freeze if in_range.empty?
-      return in_range.freeze if trailing.nil? && terminal_destroy?(in_range)
+    #: (untyped, Array[untyped]) -> [Hash[String, Array[untyped]], Set[untyped]?, Hash[String, untyped]]
+    def model_versions(model_class, ids)
+      range = @time_range
+      empty = {} #: Hash[String, untyped]
+      [
+        grouped_versions(model_class, ids, range),
+        chosen_version_ids(model_class, ids, range),
+        range ? trailing_versions(model_class, ids, range) : empty
+      ]
+    end
+
+    #: (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?,
+        live_endpoint: live_endpoint
+      ).call
+    end
 
-      unless trailing
-        raise IncompleteTimeRangeError,
-              'time range requires a later root version to reconstruct its final change'
-      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
 
-      (in_range + [trailing]).freeze
+      current = loaded.fetch(key, record)
+      current unless current.destroyed?
     end
 
-    #: (Array[untyped]) -> bool
-    def terminal_destroy?(versions)
-      versions.last&.event.to_s == 'destroy'
+    # One extra query names the selected mutations without discarding the
+    # unfiltered versions the successor lookup still needs.
+    #: (untyped, Array[untyped], TimeRange?) -> Set[untyped]?
+    def chosen_version_ids(model_class, ids, range)
+      scope = @version_scope
+      return unless scope
+
+      # A narrowed relation is the expected return. Active Support also gives
+      # `pluck` to plain enumerables, so an array of versions works too.
+      filtered = scope.call(range_scope(model_class, ids, range))
+      Set.new(filtered.pluck(:id))
     end
 
     #: (untyped, Array[untyped], TimeRange?) -> Hash[String, Array[untyped]]
     def grouped_versions(model_class, ids, range)
+      ordered(range_scope(model_class, ids, range)).group_by { |version| version.item_id.to_s }
+    end
+
+    #: (untyped, Array[untyped], TimeRange?) -> untyped
+    def range_scope(model_class, ids, range)
       scope = base_scope(model_class, ids)
-      scope = range.scope(scope) if range
-      ordered(scope).group_by { |version| version.item_id.to_s }
+      range ? range.scope(scope) : scope
     end
 
     # One row per root: the earliest version after the window, found without a