paper_trail_diff 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a4d3c1e15ef20c4e3d05f5c0442d7e55cd0eb811a15766d2119a3cf35b2e729c
-  data.tar.gz: 4cc8dceb10e7aa71f1feb7d9fcc3917040bec4b2cc69641b4b3817d6761aad94
+  metadata.gz: 88e9b952c5cfe214974d5eab1a9d6e5a30dcfeb34ebc4193110f478d0cd9884a
+  data.tar.gz: 3a66b3ae3a77b65097ece227010c423beb05ec4ebd981edee396b824638c801c
 SHA512:
-  metadata.gz: 3887a515ee90f1c14b890a21d4a91b4892f4097b74c9ec27f136fd8476f01cd285c0a310a03b0c528e709cdca299bca2e243522844d09a86d272c043e48879b1
-  data.tar.gz: a1390db78cc31cbf20420fd18b536ad8cd826de4927943cbdddc08b7a31f9dad5f81acee77db97059f044ad435bd3170e54f8ef2ccd5c68f3e256bfa5d848642
+  metadata.gz: 413fcd69a9ef2b49abb2238d77b279ac2dd4001cc8b5d98d1bbcb92843a6b428aeed967ba7ba8efb10dca1fcd5e912ca4221b0a8a854e0cd624a7b95fcc21ae1
+  data.tar.gz: f5968acfec8ce8189e1fcd3122b4fc3934b7cf989278c1b8feb87ed087da93132c35f7d20df8d64e49832fabe052b5cd80d6fdc5182af3e9be6c2d308ab3acf1

data/CHANGELOG.md

@@ -3,6 +3,30 @@
 All notable changes to this project will be documented in this file. The
 project follows [Semantic Versioning](https://semver.org/).
 
+## [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,52 @@ 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
+
+`version_scope:` narrows which root versions count as *selected mutations*,
+which is what a "changes made by a user" report needs:
+
+```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 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
@@ -922,10 +968,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,14 +7,16 @@ 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|
+    #: (RootVersionPlan, Hash[Array[untyped], RecordSnapshot?]) -> Array[Step]
+    def call(plan, root_snapshots)
+      plan.steps.map do |from_version, to_version|
         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_version,
+          to_version: to_version,
+          diff: Engine.compare(
+            root_snapshots[version_key(from_version)],
+            root_snapshots[version_key(to_version)]
+          )
         )
       end.freeze
     end

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,13 @@ 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) -> void
+    def initialize( # rubocop:disable Metrics/ParameterLists
+      records, time_range:, live_loader:, history_preparer:, analyzer:, version_scope: nil
+    )
       @records = records
       @time_range = time_range
+      @version_scope = validated_scope(version_scope)
       @live_loader = live_loader
       @history_preparer = history_preparer
       @analyzer = analyzer
@@ -18,11 +21,14 @@ module PaperTrailDiff
     #: () -> Hash[identity, Analysis]
     def call
       records = validated_records
-      selected = BatchedRootVersions.new(records, time_range: @time_range).call
+      selected = BatchedRootVersions.new(
+        records, time_range: @time_range, version_scope: @version_scope
+      ).call
       prepare(records, selected)
       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 +36,20 @@ module PaperTrailDiff
 
     # @rbs @records: Array[untyped]
     # @rbs @time_range: TimeRange?
+    # @rbs @version_scope: untyped
     # @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 +66,13 @@ 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
+    #: (Array[untyped], Hash[Array[String], RootVersionPlan]) -> void
     def prepare(records, selected)
       loaded = @live_loader.call(records)
       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 +82,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,19 @@ 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) -> void
+    def initialize(records, time_range:, version_scope: nil)
       @records = records
       @time_range = time_range
+      @version_scope = version_scope
     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 +29,64 @@ module PaperTrailDiff
 
     # @rbs @records: Array[untyped]
     # @rbs @time_range: TimeRange?
+    # @rbs @version_scope: 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]
+        )
       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)
-
-      unless trailing
-        raise IncompleteTimeRangeError,
-              'time range requires a later root version to reconstruct its final change'
-      end
+    #: (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
 
-      (in_range + [trailing]).freeze
+    #: (Array[untyped], Set[untyped]?, untyped) -> RootVersionPlan
+    def versions_for(in_range, chosen, after_range)
+      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?
+      ).call
     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

data/lib/paper_trail_diff/paper_trail_adapter.rb

@@ -50,57 +50,62 @@ module PaperTrailDiff
       end
     end
 
-    #: (untyped, from: untyped, to: untyped, within: untyped) -> Array[Step]
-    def timeline(record, from:, to:, within:)
+    #: (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped) -> Array[Step]
+    def timeline(record, from:, to:, within:, version_scope: nil)
       @traversal_preparer.call(record.class, historical: true)
-      builder = TimelineBuilder.new(
+      TimelineBuilder.new(
         record,
         from: from,
         to: to,
         within: within,
+        version_scope: version_scope,
         snapshotter: @timeline_snapshotter
-      )
-      builder.build
+      ).build
     end
 
-    #: (untyped, from: untyped, to: untyped, within: untyped) -> Array[ActivityStep]
-    def activity_timeline(record, from:, to:, within:)
+    #: (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped) -> Array[ActivityStep]
+    def activity_timeline(record, from:, to:, within:, version_scope: nil)
       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)
-        steps = activity_builder(record, from: from, to: to, within: within).build
+        steps = activity_builder(
+          record, from: from, to: to, within: within, version_scope: version_scope
+        ).build
         payload[:step_count] = steps.length
         steps
       end
     end
 
-    #: (untyped, from: untyped, to: untyped, within: untyped, ?activity: bool) -> Analysis
-    def analyze(record, from:, to:, within:, activity: false)
+    #: (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
+      @traversal_preparer.call(record.class, historical: true)
       if activity
-        @traversal_preparer.call(record.class, historical: true)
-        return activity_builder(record, from: from, to: to, within: within).analyze
+        return activity_builder(
+          record, from: from, to: to, within: within, version_scope: version_scope
+        ).analyze
       end
 
-      @traversal_preparer.call(record.class, historical: true)
       TimelineBuilder.new(
         record,
         from: from,
         to: to,
         within: within,
+        version_scope: version_scope,
         snapshotter: @timeline_snapshotter
       ).analyze
     end
 
     # Analyzes many roots over one shared range, preparing their history once.
-    #: (Array[untyped], within: untyped, ?activity: bool) -> Hash[identity, Analysis]
-    def analyze_many(records, within:, activity: false)
+    #: (Array[untyped], within: untyped, ?activity: bool, ?version_scope: untyped) -> Hash[identity, Analysis]
+    def analyze_many(records, within:, activity: false, version_scope: nil)
       count = records.is_a?(Array) ? records.length : 0
       payload = @instrumentation_payload.merge(comparison_count: count)
       Instrumentation.instrument('analyze_many', payload) do
         AnalysisBatch.new(
           records,
           time_range: within.nil? ? nil : TimeRange.new(within),
+          version_scope: version_scope,
           live_loader: @live_endpoints.method(:call),
           history_preparer: @historical_store.method(:prepare_batch),
           analyzer: batched_root_analyzer(activity)
@@ -168,11 +173,13 @@ module PaperTrailDiff
       )
     end
 
-    #: (untyped, from: untyped, to: untyped, within: untyped) -> ActivityTimelineBuilder
-    def activity_builder(record, from:, to:, within:)
+    #: (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped) -> ActivityTimelineBuilder
+    def activity_builder(record, from:, to:, within:, version_scope: nil)
       ActivityTimelineBuilder.new(
         record,
-        range: TimelineRange.new(record, from: from, to: to, within: within),
+        range: TimelineRange.new(
+          record, from: from, to: to, within: within, version_scope: version_scope
+        ),
         tree: @association_tree,
         snapshotter: @activity_snapshotter
       )