paper_trail_diff 0.4.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fac7dbbad6368383d2b73f4c5acbdcabb1599da6c096a5c8363327a8602a1298
-  data.tar.gz: 7657cc9ae4b3e8f7d9f1026ac06fb93b6571ba7258bca66183b84053bb8469c0
+  metadata.gz: 88e9b952c5cfe214974d5eab1a9d6e5a30dcfeb34ebc4193110f478d0cd9884a
+  data.tar.gz: 3a66b3ae3a77b65097ece227010c423beb05ec4ebd981edee396b824638c801c
 SHA512:
-  metadata.gz: adadf85c15151889247d0791ffc944731c781c6dc3f4d23b4a04fa046e489b74f2a6501a16fb53386e6c80c3fae4d6c583d4b91db198bfbe8919a3a19eaf1a4e
-  data.tar.gz: 2a3bf4422b73c513981b519d04f0c556574f75ebc08963fab606f872c2428acac2455869675318ae75d8f71bddeb208e952642eeafedae7131b4745b5f36f534
+  metadata.gz: 413fcd69a9ef2b49abb2238d77b279ac2dd4001cc8b5d98d1bbcb92843a6b428aeed967ba7ba8efb10dca1fcd5e912ca4221b0a8a854e0cd624a7b95fcc21ae1
+  data.tar.gz: f5968acfec8ce8189e1fcd3122b4fc3934b7cf989278c1b8feb87ed087da93132c35f7d20df8d64e49832fabe052b5cd80d6fdc5182af3e9be6c2d308ab3acf1

data/CHANGELOG.md

@@ -3,6 +3,50 @@
 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
+
+- Add `analyze_many`, which analyzes many roots over one shared `within:` window,
+  or over each root's whole history when the window is omitted, selecting their
+  versions and preparing their history once for the batch. Query cost is flat in
+  the number of roots for the endpoint diff and checkpoint timeline; descendant
+  event discovery under `activity: true` remains per-root. A root with no
+  versions in range returns an empty `Analysis`, and roots are supplied as live
+  records so a root deleted inside the window cannot be included.
+- Accept `:first` and `:last` as `compare_many` endpoints, resolved against the
+  record the pair's other endpoint names, in two queries per model class rather
+  than one lookup per root. A root with no recorded history compares as an empty
+  `Diff`, and an unanchored `{ from: :first, to: :last }` raises.
+- Accept `reload_live_endpoints:` on `activity_timeline`, which reads live state
+  whenever `to:` is a current record but previously had no way to reuse an
+  already-preloaded graph. `timeline` and `analyze` are bounded by versions and
+  never read live state, so the option is deliberately absent there.
+
 ## [0.4.0] - 2026-08-11
 
 ### Added

data/README.md

@@ -213,6 +213,21 @@ diffs = PaperTrailDiff.compare_many(
 diffs.fetch(["Order", orders.first.id.to_s]) # => PaperTrailDiff::Diff
 ```
 
+Endpoints may also be given as `:first` or `:last`, resolved against the record
+the pair's other endpoint names. That replaces the lookup above entirely, and
+resolves every root in two queries per model class rather than one per root:
+
+```ruby
+diffs = PaperTrailDiff.compare_many(
+  orders.map { |order| { from: :first, to: order } },
+  associations: [:line_items]
+)
+```
+
+A symbol carries no identity of its own, so `{ from: :first, to: :last }` raises
+rather than guessing. A root with no recorded history resolves to an empty
+`Diff`, matching how the timeline APIs answer the same question.
+
 Root identities must be unique within one call. Historical reconstruction for
 ordinary versioned, unscoped association paths is also prepared across the
 collection. Paths that require the existing point-in-time PT-AT fallback retain
@@ -225,8 +240,10 @@ must observe one atomic snapshot.
 
 ### Reuse already-preloaded current endpoints
 
-`compare` and `compare_many` reload current endpoints by default. A caller that
-already owns a consistent, fully preloaded graph may opt out:
+`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:
 
 ```ruby
 orders = Order.where(id: order_ids).preload(line_items: :product).to_a
@@ -285,6 +302,89 @@ ActiveSupport::Notifications.subscribed(callback, "sql.active_record") do
 end
 ```
 
+## Analyze many records over one window
+
+`analyze_many` answers "what changed for these records during this period" for a
+whole collection, selecting every root's versions and preparing their selected
+association history once for the batch:
+
+```ruby
+results = PaperTrailDiff.analyze_many(
+  Order.where(status: "open").to_a,
+  within: Time.zone.parse("2026-08-01")...Time.zone.parse("2026-09-01"),
+  associations: [:line_items]
+)
+
+results.fetch(["Order", order.id.to_s]).diff      # net change across the window
+results.fetch(["Order", order.id.to_s]).timeline  # its checkpoint steps
+```
+
+Results are a frozen hash keyed by `[item_type, item_id]` strings, and each
+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
+thing for every root.
+
+Query cost is flat in the number of roots for the diff and timeline views:
+selecting versions and preparing history are both shared across the batch. On a
+twenty-root batch that is 7 queries against 120 for the same work done one
+record at a time. Passing `activity: true` also works and returns the same
+results, but discovering descendant events is inherently per-root, so that view
+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.
+
 ## Build a root-checkpoint timeline
 
 `timeline` accepts two version objects from the supplied record's history, or
@@ -868,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

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # Builds one Analysis per root over a shared range, selecting every root's
+  # versions and preparing their association history once for the whole batch
+  # rather than once per root.
+  class AnalysisBatch
+    #: (Array[untyped], time_range: TimeRange?, live_loader: untyped, history_preparer: untyped, analyzer: untyped, ?version_scope: untyped) -> void
+    def initialize( # 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
+    end
+
+    #: () -> Hash[identity, Analysis]
+    def call
+      records = validated_records
+      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)
+        plan = selected.fetch(key, RootVersionPlan.empty)
+        [Support.immutable_copy(key), analysis_for(record, plan)]
+      end.freeze
+    end
+
+    private
+
+    # @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)
+
+      @records.each { |record| Endpoint.validate!(record) }
+      identities = @records.map { |record| Endpoint.identity(record) }
+      return @records if identities.uniq.length == identities.length
+
+      raise ConfigurationError, 'records: identities must be unique'
+    end
+
+    # Association history is prepared per model class across every selected root
+    # version, which is the work that would otherwise repeat for each record.
+    # 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)
+      records.group_by(&:class).each_value do |grouped|
+        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) }
+        @history_preparer.call(roots, versions)
+      end
+    end
+
+    # A root with no versions in range has nothing to report, which is an empty
+    # result rather than a failed request.
+    #: (untyped, RootVersionPlan) -> Analysis
+    def analysis_for(record, plan)
+      return Analysis.empty if plan.empty?
+
+      @analyzer.call(record, plan)
+    end
+  end
+end

data/lib/paper_trail_diff/batch_boundary_resolver.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # Resolves `:first` and `:last` endpoints for a whole batch in two queries per
+  # model class. Left to the caller this is a per-root lookup, which reintroduces
+  # exactly the queries a batched comparison exists to remove.
+  class BatchBoundaryResolver
+    BOUNDARIES = %i[first last].freeze
+
+    class << self
+      #: (untyped) -> bool
+      def symbolic?(endpoint)
+        endpoint.is_a?(Symbol)
+      end
+    end
+
+    #: (Array[[untyped, untyped]]) -> void
+    def initialize(pairs)
+      @pairs = pairs
+    end
+
+    # Returns the pairs with every resolvable symbol replaced. A symbol that
+    # names history the record does not have is left in place, so the caller can
+    # decide what an absent history means rather than being handed nil.
+    #: () -> Array[[untyped, untyped]]
+    def call
+      return @pairs unless @pairs.flatten(1).any? { |endpoint| symbolic?(endpoint) }
+
+      index = boundary_index
+      @pairs.map do |from, to|
+        [resolve(from, to, index), resolve(to, from, index)]
+      end
+    end
+
+    private
+
+    # @rbs @pairs: Array[[untyped, untyped]]
+
+    #: (untyped) -> bool
+    def symbolic?(endpoint)
+      self.class.symbolic?(endpoint)
+    end
+
+    #: (untyped, untyped, Hash[Array[String], Hash[Symbol, untyped]]) -> untyped
+    def resolve(endpoint, other, index)
+      return endpoint unless symbolic?(endpoint)
+
+      unless BOUNDARIES.include?(endpoint)
+        raise ConfigurationError,
+              "unsupported boundary: #{endpoint.inspect}; use :first, :last, a version, or a record"
+      end
+
+      identity = anchor_identity(other)
+      unless identity
+        raise ConfigurationError,
+              'a :first or :last endpoint needs the other endpoint to name a record'
+      end
+
+      index.dig(identity, endpoint) || endpoint
+    end
+
+    # A symbol carries no identity of its own, so the pair's other endpoint has
+    # to say which record is meant.
+    #: (untyped) -> Array[String]?
+    def anchor_identity(endpoint)
+      return if endpoint.nil? || symbolic?(endpoint)
+
+      Endpoint.identity(endpoint)
+    rescue InvalidEndpointError
+      nil
+    end
+
+    #: () -> Hash[Array[String], Hash[Symbol, untyped]]
+    def boundary_index
+      index = {} #: Hash[Array[String], Hash[Symbol, untyped]]
+      anchors.group_by { |model_class, _id| model_class }.each do |model_class, entries|
+        add_model_boundaries(index, model_class, entries.map { |_klass, id| id }.uniq)
+      end
+      index
+    end
+
+    #: () -> Array[[untyped, untyped]]
+    def anchors
+      @pairs.flatten(1).filter_map { |endpoint| anchor(endpoint) }.uniq
+    end
+
+    #: (untyped) -> [untyped, untyped]?
+    def anchor(endpoint)
+      return if endpoint.nil? || symbolic?(endpoint)
+
+      if Endpoint.version?(endpoint)
+        [Endpoint.model_class(endpoint), endpoint.item_id]
+      elsif Endpoint.record?(endpoint)
+        [endpoint.class, endpoint.id]
+      end
+    rescue InvalidEndpointError
+      nil
+    end
+
+    #: (Hash[Array[String], Hash[Symbol, untyped]], untyped, Array[untyped]) -> void
+    def add_model_boundaries(index, model_class, ids)
+      first_ids, last_ids, versions = boundary_versions(model_class, ids)
+      ids.each do |id|
+        index[identity_key(model_class, id)] = {
+          first: versions[boundary_key(first_ids, id)],
+          last: versions[boundary_key(last_ids, id)]
+        }
+      end
+    end
+
+    # Two grouped queries name each root's outermost versions, and one more
+    # loads them, whatever the size of the batch.
+    #: (untyped, Array[untyped]) -> [Hash[untyped, untyped], Hash[untyped, untyped], Hash[untyped, untyped]]
+    def boundary_versions(model_class, ids)
+      version_class = model_class.paper_trail.version_class
+      scope = version_class.where(item_type: model_class.base_class.name.to_s, item_id: ids)
+      first_ids = scope.group(:item_id).minimum(:id)
+      last_ids = scope.group(:item_id).maximum(:id)
+      loaded = version_class.where(id: (first_ids.values + last_ids.values).uniq).index_by(&:id)
+      [first_ids, last_ids, loaded]
+    end
+
+    # Grouped keys come back with whatever type the column uses, so match on the
+    # string form rather than assuming integers.
+    #: (Hash[untyped, untyped], untyped) -> untyped
+    def boundary_key(grouped, id)
+      key = grouped.keys.find { |candidate| candidate.to_s == id.to_s }
+      grouped[key]
+    end
+
+    #: (untyped, untyped) -> Array[String]
+    def identity_key(model_class, id)
+      [model_class.base_class.name.to_s, id.to_s]
+    end
+  end
+end

data/lib/paper_trail_diff/batched_root_analyzer.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # Builds one root's Analysis inside a batch, from versions the batch already
+  # selected and history it already prepared.
+  class BatchedRootAnalyzer
+    #: (tree: AssociationTree, timeline_snapshotter: untyped, activity_snapshotter: untyped, preparer: untyped, activity: bool) -> void
+    def initialize(tree:, timeline_snapshotter:, activity_snapshotter:, preparer:, activity:)
+      @tree = tree
+      @timeline_snapshotter = timeline_snapshotter
+      @activity_snapshotter = activity_snapshotter
+      @preparer = preparer
+      @activity = activity
+    end
+
+    #: (untyped, RootVersionPlan) -> Analysis
+    def call(record, plan)
+      @preparer.call(record.class, historical: true)
+      return activity_analysis(record, plan) if @activity
+
+      TimelineBuilder.new(
+        record,
+        from: plan.versions.first,
+        to: plan.versions.last,
+        within: nil,
+        plan: plan,
+        snapshotter: @timeline_snapshotter
+      ).analyze
+    end
+
+    private
+
+    # @rbs @tree: AssociationTree
+    # @rbs @timeline_snapshotter: untyped
+    # @rbs @activity_snapshotter: untyped
+    # @rbs @preparer: untyped
+    # @rbs @activity: bool
+
+    #: (untyped, RootVersionPlan) -> Analysis
+    def activity_analysis(record, plan)
+      range = TimelineRange.new(
+        record, from: plan.versions.first, to: plan.versions.last, within: nil, plan: plan
+      )
+      ActivityTimelineBuilder.new(
+        record, range: range, tree: @tree, snapshotter: @activity_snapshotter
+      ).analyze
+    end
+  end
+end