paper_trail_diff 0.12.0 → 0.13.0

data/docs/testing.md

@@ -0,0 +1,146 @@
+# Testing
+
+The default suite uses an in-memory SQLite database:
+
+```console
+mise exec -- bundle install
+mise exec -- bundle exec rake
+```
+
+The default task runs the core specs without PT-AT loaded, the association specs
+in a separate process, RuboCop (with the rubocop-performance and rubocop-rspec
+plugins), generated-signature verification, and Steep.
+Ruby blocks in the README, quickstart, and API reference marked with
+`<!-- executable:... -->` run inside those specs, so documented examples stay
+correct.
+
+For reporting workloads, query counts, reconstruction cost, and memory readings,
+see [Reporting performance](performance.md). Those measurements run separately
+from the correctness suite and have no timing-based CI gate.
+
+CI keeps the Ruby 3.1–4.0 and PaperTrail 16/17 compatibility matrix on SQLite,
+including Windows runs. Separate Linux jobs run both core and association suites
+on PostgreSQL 17, MySQL 8.4, and SQL Server 2019 and 2022 with Ruby 4.0 and
+PaperTrail 17.
+The SQL jobs exercise the same regressions, including joined-column ordering,
+duplicate roots, pagination, and historical association reconstruction.
+
+## Consistency checks
+
+`spec/association/consistency_spec.rb` and `spec/integration/consistency_spec.rb`
+build seeded, generated histories: root edits, checkpoints, and child creates,
+edits, and deletes. For each one they check that every route to the same answer
+agrees: `analyze`, `analyze_many`, and `analyze_scope`; checkpoint and activity
+modes; `compare` and `timeline` against `analyze`; and that activity steps
+chain into the final state. They run over random windows as well as the whole
+history, with integer and string `versions.item_id`, YAML and JSON history, and
+a `has_paper_trail skip:` column. When one fails, its seed reproduces it. Add a
+variant here when a bug turns out to depend on a schema or configuration.
+
+## Mutation testing
+
+[Mutant](https://github.com/mbj/mutant) changes the comparison code one
+expression at a time and expects a spec to fail each time. A change that every
+spec still passes is behavior nothing checks. `mutant.yml` lists the classes it
+mutates: `Engine`, `CollectionComparator`, `CollectionIdentityIndex`, and
+`NestedComparator`, which decide what counts as a change. It runs the
+association suite, which reaches all of their paths.
+
+Mutant needs Ruby 3.3 or newer, so it has its own bundle:
+
+```console
+BUNDLE_GEMFILE=gemfiles/mutant.gemfile mise exec -- bundle install
+mise exec -- bundle exec rake mutant
+```
+
+Pass a subject to mutate one class, and `--since main` to mutate only what a
+branch changed:
+
+```console
+BUNDLE_GEMFILE=gemfiles/mutant.gemfile mise exec -- bundle exec mutant run 'PaperTrailDiff::Engine*'
+BUNDLE_GEMFILE=gemfiles/mutant.gemfile mise exec -- bundle exec mutant run --since main
+```
+
+When a mutation survives, either add the spec that would catch it, or, if the
+mutated code means the same thing, simplify the code to that form. Reserve a
+`mutant:disable` comment for a method whose mutations all mean the same thing,
+and say why next to it. Mutant forks a worker per CPU; `spec/support/mutant_hooks.rb`
+gives each worker its own copy of the SQLite fixture database.
+
+## Test clock
+
+The specs build time windows from `Time.now` around versions they have just
+written, so they need a clock that never runs backwards. Virtualized hosts,
+WSL2 in particular, step the wall clock back by hundreds of milliseconds when
+they resynchronize, which made window-based specs fail at random.
+`spec/support/monotonic_clock.rb` therefore makes `Time.now` strictly
+increasing, in whole microseconds, for the test process. ActiveRecord
+timestamps, PaperTrail's `created_at`, and windows built from `Time.now` all
+read it, so they stay consistent however the host clock moves. It affects only
+the test process; the gem itself reads the ordinary clock.
+
+## Other databases locally
+
+Install the adapter's client development libraries first. On Debian/Ubuntu,
+the packages are `libpq-dev` for PostgreSQL, `default-libmysqlclient-dev` for
+MySQL, and `freetds-dev` for SQL Server. The optional development group includes
+all three adapters:
+
+```console
+BUNDLE_WITH=database_adapters mise exec -- bundle install
+```
+
+Create a dedicated disposable database named `paper_trail_diff_test`. The suites
+recreate their fixture tables. Set `PAPER_TRAIL_DIFF_DATABASE_URL` to its
+connection URL and run both suites:
+
+```console
+BUNDLE_WITH=database_adapters PAPER_TRAIL_DIFF_DATABASE_URL=postgresql://paper_trail_diff:test@127.0.0.1:5432/paper_trail_diff_test mise exec -- bundle exec rake spec
+BUNDLE_WITH=database_adapters PAPER_TRAIL_DIFF_DATABASE_URL=mysql2://paper_trail_diff:test@127.0.0.1:3306/paper_trail_diff_test mise exec -- bundle exec rake spec
+BUNDLE_WITH=database_adapters PAPER_TRAIL_DIFF_DATABASE_URL=sqlserver://sa:PaperTrail_Test2026@127.0.0.1:1433/paper_trail_diff_test mise exec -- bundle exec rake spec
+```
+
+These credentials are examples for disposable local instances. SQL Server's
+adapter version follows ActiveRecord's version; Bundler selects a compatible
+adapter. No database driver is a runtime dependency of the gem.
+
+SQL Server's adapter wraps datetime2 values during serialization. With
+PaperTrail's default YAML serializer, the fixtures explicitly permit
+`ActiveRecord::ConnectionAdapters::SQLServer::Type::Data` and
+`ActiveRecord::ConnectionAdapters::SQLServer::Type::DateTime2`, in addition to
+`Symbol` and `Time`. Applications using that serializer need the corresponding
+`ActiveRecord.yaml_column_permitted_classes` configuration. The gem does not
+change an application's YAML configuration.
+
+The CI service configuration is in `.github/workflows/ci.yml`. PostgreSQL and
+MySQL create the named database during container initialization. The SQL Server
+jobs create it explicitly after the service passes its health check.
+
+## Generated signatures
+
+Inline RBS comments in `lib/` are the source of truth:
+
+```console
+mise exec -- bundle exec rake rbs
+mise exec -- bundle exec rake typecheck
+```
+
+The typecheck task regenerates signatures and compares them with Git's index
+before running Steep. Unstaged generated changes therefore fail the gate even
+when they are correct. Review and stage matching source/signature changes before
+running the complete gate. The Steep wrapper also fails on internal errors even
+if Steep returns exit status zero.
+
+## Releasing
+
+Tags matching `v*` publish through RubyGems trusted publishing. Never add a
+long-lived RubyGems API key. Before tagging:
+
+1. Update `PaperTrailDiff::VERSION` and replace `Unreleased` in the changelog
+   with that version and the release date.
+2. Run `mise exec -- bundle exec rake release:preflight`. It runs the full gate,
+   checks that the tree is clean and pushed, that the Appraisal gemfiles are
+   current, and that the changelog names the version, then builds the gem. It
+   does not tag, push, or publish.
+3. Configure the RubyGems trusted publisher for `release.yml` and the `release`
+   environment.

data/lib/paper_trail_diff/activity_belongs_to_event_applier.rb

@@ -45,7 +45,7 @@ module PaperTrailDiff
 
     #: (Array[untyped], untyped, SnapshotNormalizer, untyped, untyped) -> RecordSnapshot?
     def normalized_route_record(route, version, normalizer, root_endpoint, context_endpoint)
-      record = @record_resolver.record_after(version)
+      record = @record_resolver.record_after(version, direct: route.last.fetch(2).empty?)
       return unless record
 
       _name, reflection, subtree, path = route.last
@@ -70,7 +70,7 @@ module PaperTrailDiff
       return [snapshot, false] unless changed
 
       updated_association = AssociationSnapshot.new(kind: association.kind, records: records)
-      [replace_association(snapshot, name, updated_association), true]
+      [snapshot.with_association(name, updated_association), true]
     end
 
     #: (Array[RecordSnapshot], Array[untyped], untyped, RecordSnapshot?, Integer) -> [Array[RecordSnapshot], bool]
@@ -101,16 +101,6 @@ module PaperTrailDiff
       [updated.freeze, true]
     end
 
-    #: (RecordSnapshot, String, AssociationSnapshot) -> RecordSnapshot
-    def replace_association(snapshot, name, association)
-      RecordSnapshot.new(
-        type: snapshot.type,
-        id: snapshot.id,
-        attributes: snapshot.attributes,
-        associations: snapshot.associations.merge(name => association)
-      )
-    end
-
     #: (untyped, RecordSnapshot?) -> String
     def replacement_type(version, replacement)
       return replacement.type.to_s if replacement

data/lib/paper_trail_diff/activity_boundary.rb

@@ -107,15 +107,19 @@ module PaperTrailDiff
       kind == :destroyed
     end
 
-    #: () -> Hash[Symbol, untyped]
-    def to_h
-      {
+    #: (?metadata: bool) -> Hash[Symbol, untyped]
+    def to_h(metadata: false)
+      value = {
         kind: kind,
         version_id: version_id,
         item_type: item_type,
         item_id: item_id,
         recorded_at: recorded_at
       }
+      return value unless metadata
+
+      value.merge(event: event, whodunnit: whodunnit, transaction_id: transaction_id,
+                  record: record.to_h)
     end
   end
 
@@ -161,13 +165,21 @@ module PaperTrailDiff
       diff.empty?
     end
 
-    #: () -> Hash[Symbol, untyped]
-    def to_h
-      {
-        from: from_boundary.to_h,
-        to: to_boundary.to_h,
+    # The event whose change this step reports. For a transaction group, this
+    # is the first event in the group, not necessarily its only actor or record.
+    #: () -> ActivityBoundary
+    def source_boundary = from_boundary
+
+    #: (?metadata: bool, ?snapshots: bool) -> Hash[Symbol, untyped]
+    def to_h(metadata: false, snapshots: false)
+      value = {
+        from: from_boundary.to_h(metadata: metadata),
+        to: to_boundary.to_h(metadata: metadata),
         diff: diff.to_h
       }
+      return value unless snapshots
+
+      value.merge(from_snapshot: from_snapshot&.to_h, to_snapshot: to_snapshot&.to_h)
     end
   end
 end

data/lib/paper_trail_diff/activity_child_candidate_loader.rb

@@ -17,6 +17,27 @@ module PaperTrailDiff
       historical_ids | current_ids
     end
 
+    # One shared query retains the owner and timestamp needed to partition a
+    # batch's candidates back into each root's exact activity range.
+    #: () -> Array[Array[untyped]]
+    def historical_rows
+      version_class = @parent_class.paper_trail.version_class
+      versions = version_class.arel_table
+      associations = @parent_class.paper_trail.version_association_class.arel_table
+      typed_rows(
+        candidate_scope(version_class).call(historical_relation(version_class)).distinct.pluck(
+          associations[:foreign_key_id], versions[:item_id], versions[:created_at], versions[:event]
+        )
+      )
+    end
+
+    #: () -> Array[Array[untyped]]
+    def current_pairs
+      relation = @reflection.klass.base_class.unscoped.where(@reflection.foreign_key => @parent_ids)
+      relation = relation.where(@reflection.type => parent_types) if @reflection.options[:as]
+      relation.distinct.pluck(@reflection.foreign_key, @reflection.klass.primary_key)
+    end
+
     private
 
     # @rbs @parent_class: untyped
@@ -24,11 +45,19 @@ module PaperTrailDiff
     # @rbs @reflection: untyped
     # @rbs @range: ActivityRange
 
+    #: (Array[Array[untyped]]) -> Array[Array[untyped]]
+    def typed_rows(rows)
+      rows.map do |owner_id, item_id, created_at, event|
+        [owner_id, Support.record_id(@reflection.klass, item_id), created_at, event]
+      end
+    end
+
     #: () -> Array[untyped]
     def historical_ids
       version_class = @parent_class.paper_trail.version_class
       candidate_scope(version_class).call(historical_relation(version_class))
                                     .distinct.pluck(version_class.arel_table[:item_id])
+                                    .map { |id| Support.record_id(@reflection.klass, id) }
     end
 
     #: (untyped) -> untyped

data/lib/paper_trail_diff/activity_collection_event_applier.rb

@@ -30,9 +30,10 @@ module PaperTrailDiff
     )
       fallback_record = [] #: Array[untyped]
       endpoints = [root_endpoint, context_endpoint]
+      direct = routes.all? { |route| route.last.fetch(2).empty? }
       snapshot = routes.reduce(previous) do |current, route|
         apply_route(
-          current, route, version, delta, fallback_record, normalizer, endpoints
+          current, route, version, delta, fallback_record, normalizer, endpoints, direct: direct
         )
       end
       [true, snapshot]
@@ -45,12 +46,12 @@ module PaperTrailDiff
     # @rbs @route_updater: ActivityCollectionRouteUpdater
     # @rbs @relationship: ActivityRelationship
 
-    #: (RecordSnapshot, Array[untyped], untyped, ActivitySnapshotDelta?, Array[untyped], SnapshotNormalizer, Array[untyped]) -> RecordSnapshot
+    #: (RecordSnapshot, Array[untyped], untyped, ActivitySnapshotDelta?, Array[untyped], SnapshotNormalizer, Array[untyped], ?direct: bool) -> RecordSnapshot
     def apply_route( # rubocop:disable Metrics/ParameterLists
-      snapshot, route, version, delta, fallback_record, normalizer, endpoints
+      snapshot, route, version, delta, fallback_record, normalizer, endpoints, direct: false
     )
       record, replacement = route_event_state(
-        snapshot, route, version, delta, fallback_record, normalizer, endpoints
+        snapshot, route, version, delta, fallback_record, normalizer, endpoints, direct: direct
       )
       change = ActivityCollectionRouteChange.new(
         route: route,
@@ -81,14 +82,16 @@ module PaperTrailDiff
       end
     end
 
-    #: (RecordSnapshot, Array[untyped], untyped, ActivitySnapshotDelta?, Array[untyped], SnapshotNormalizer, Array[untyped]) -> [untyped, RecordSnapshot?]
+    #: (RecordSnapshot, Array[untyped], untyped, ActivitySnapshotDelta?, Array[untyped], SnapshotNormalizer, Array[untyped], ?direct: bool) -> [untyped, RecordSnapshot?]
     def route_event_state( # rubocop:disable Metrics/ParameterLists
-      snapshot, route, version, delta, fallback_record, normalizer, endpoints
+      snapshot, route, version, delta, fallback_record, normalizer, endpoints, direct: false
     )
       existing = existing_delta_record(snapshot, route, version, delta) if delta
       return [delta, delta.apply(existing)] if delta && existing
 
-      fallback_record << @record_resolver.record_after(version) if fallback_record.empty?
+      if fallback_record.empty?
+        fallback_record << @record_resolver.record_after(version, direct: direct)
+      end
       record = fallback_record.first
       return [record, nil] unless record
 

data/lib/paper_trail_diff/activity_collection_route_updater.rb

@@ -28,7 +28,7 @@ module PaperTrailDiff
           membership_preserved: membership_preserved
         )
       )
-      updated_snapshot = replace_association(snapshot, name, updated_association)
+      updated_snapshot = snapshot.with_association(name, updated_association)
       parent_path = depth.zero? ? '' : change.route.fetch(depth - 1).fetch(3)
       updated_snapshot = @pool.record(parent_path, updated_snapshot) unless parent_path.empty?
       [updated_snapshot, true]
@@ -114,15 +114,5 @@ module PaperTrailDiff
       owner_id = @relationship.owner_id(membership_record, reflection, state: :after)
       association.position_for_id(owner_id)
     end
-
-    #: (RecordSnapshot, String, AssociationSnapshot) -> RecordSnapshot
-    def replace_association(snapshot, name, association)
-      RecordSnapshot.new(
-        type: snapshot.type,
-        id: snapshot.id,
-        attributes: snapshot.attributes,
-        associations: snapshot.associations.merge(name => association)
-      )
-    end
   end
 end

data/lib/paper_trail_diff/activity_event_record_normalizer.rb

@@ -19,6 +19,10 @@ module PaperTrailDiff
       root_endpoint:,
       context_endpoint:
     )
+      if record.is_a?(PreparedRecordState)
+        return normalizer.from_state(record, tree: subtree, path: path, incoming: reflection)
+      end
+
       boundary = Endpoint.version?(root_endpoint) ? root_endpoint : context_endpoint
       reifier = @association_reader.call(context_endpoint, habtm_version: boundary)
       normalizer.call_child(

data/lib/paper_trail_diff/activity_event_record_resolver.rb

@@ -10,15 +10,39 @@ module PaperTrailDiff
     }.freeze
     private_constant :RECORD_AFTER_HANDLERS
 
-    #: (?record_transition: untyped) -> void
-    def initialize(record_transition: nil)
+    #: (?record_transition: untyped, ?prepared_record_after: untyped) -> void
+    def initialize(record_transition: nil, prepared_record_after: nil)
       @record_transition = record_transition
+      @prepared_record_after = prepared_record_after
+      @direct_loader = DirectRecordStateLoader.new
     end
 
-    #: (untyped) -> untyped
-    def record_after(version)
+    #: (untyped, ?direct: bool) -> untyped
+    def record_after(version, direct: false)
       return if version.event.to_s == 'destroy'
 
+      if direct
+        handled, state = direct_after(version)
+        return state if handled
+      end
+
+      handled, prepared = @prepared_record_after&.call(version)
+      return prepared if handled
+
+      fallback_record_after(version)
+    end
+
+    #: (untyped) -> [bool, untyped]
+    def direct_after(version)
+      handled, state = @prepared_record_after&.call(version, direct: true)
+      return [true, state] if handled
+
+      state = direct_record_after(version)
+      [!state.nil?, state]
+    end
+
+    #: (untyped) -> untyped
+    def fallback_record_after(version)
       changed_record = changed_record_after(version)
       return changed_record if changed_record
 
@@ -70,18 +94,54 @@ module PaperTrailDiff
     # +version.item+, which would issue one live-record query per event.
     #: (untyped, untyped) -> untyped
     def deserialized_changeset(version, model_class)
-      return unless model_class && version.class.column_names.include?('object_changes')
+      return unless model_class
+      unless version.class.column_names.include?('object_changes')
+        return prepared_changeset(version)
+      end
 
       paper_trail = Object.const_get(:PaperTrail) #: untyped
       adapter = paper_trail.config.object_changes_adapter
       return adapter.load_changeset(version) if adapter.respond_to?(:load_changeset)
 
-      standard_changeset(paper_trail, version, model_class)
+      changes = standard_changeset(paper_trail, version, model_class)
+      changes.empty? ? prepared_changeset(version) : changes
     end
 
     private
 
     # @rbs @record_transition: untyped
+    # @rbs @prepared_record_after: untyped
+    # @rbs @direct_loader: DirectRecordStateLoader
+
+    #: (untyped) -> PreparedRecordState?
+    def direct_record_after(version)
+      model = Endpoint.model_class(version)
+      changes = deserialized_changeset(version, model)
+      return unless changes.respond_to?(:each) && !changes.empty?
+
+      before = if version.object
+                 @direct_loader.call(version)
+               else
+                 PreparedRecordState.from_attributes(
+                   model, {}
+                 )
+               end
+      return unless before
+
+      attributes = before.attributes.merge(after_attributes(changes, model))
+      @direct_loader.complete(PreparedRecordState.from_attributes(model, attributes))
+    end
+
+    #: (untyped) -> untyped
+    def prepared_changeset(version)
+      transition = @record_transition&.call(version)
+      return {} unless transition
+
+      before, after = transition
+      (before.keys | after.keys).filter_map do |name|
+        [name, [before[name], after[name]]] unless before[name] == after[name]
+      end.to_h
+    end
 
     #: (untyped, untyped) -> Hash[untyped, untyped]
     def after_attributes(changes, model_class)

data/lib/paper_trail_diff/activity_event_snapshot_refresher.rb

@@ -4,10 +4,12 @@
 module PaperTrailDiff
   # Dispatches safe descendant events to focused immutable snapshot appliers.
   class ActivityEventSnapshotRefresher
-    #: (traversal: AssociationTraversal, pool: SnapshotPool, components: untyped, ?association_reader: untyped, ?record_transition: untyped) -> void
-    def initialize(traversal:, pool:, components:, association_reader: nil, record_transition: nil)
+    #: (traversal: AssociationTraversal, pool: SnapshotPool, components: untyped, ?association_reader: untyped, ?record_transition: untyped, ?prepared_record_after: untyped) -> void
+    def initialize(traversal:, pool:, components:, association_reader: nil, record_transition: nil, prepared_record_after: nil) # rubocop:disable Layout/LineLength, Metrics/ParameterLists
       @components = components
-      @record_resolver = ActivityEventRecordResolver.new(record_transition: record_transition)
+      @record_resolver = ActivityEventRecordResolver.new(
+        record_transition: record_transition, prepared_record_after: prepared_record_after
+      )
       @route_finder = ActivityEventRouteFinder.new(traversal)
       @relationship = ActivityRelationship.new
       configure_appliers(pool, association_reader)
@@ -99,7 +101,7 @@ module PaperTrailDiff
 
     #: (untyped) -> untyped
     def record_after(version)
-      @record_resolver.record_after(version)
+      @record_resolver.record_after(version, direct: true)
     end
 
     #: (untyped, untyped) -> untyped

data/lib/paper_trail_diff/activity_grouping.rb

@@ -7,6 +7,18 @@ module PaperTrailDiff
   # window -- but a transaction has to collapse the same way in both, or the
   # same history would read differently depending on how it was asked for.
   module ActivityGrouping
+    #: (Symbol?, ?activity: bool, ?snapshots: bool) -> void
+    def self.validate!(group, activity: true, snapshots: false)
+      unless group.nil? || group == :transaction
+        raise ConfigurationError, 'group: must be :transaction or nil'
+      end
+      raise ConfigurationError, 'snapshots: requires activity: true' if snapshots && !activity
+
+      return if group.nil? || activity
+
+      raise ConfigurationError, 'group: requires activity: true'
+    end
+
     private
 
     #: () -> bool

data/lib/paper_trail_diff/activity_history.rb

@@ -8,13 +8,17 @@ module PaperTrailDiff
     attr_reader :root_snapshots #: Hash[Array[untyped], RecordSnapshot?]
     attr_reader :first_snapshot #: RecordSnapshot?
     attr_reader :last_snapshot #: RecordSnapshot?
+    attr_reader :last_boundary #: ActivityBoundary?
+    attr_reader :last_event_snapshot #: RecordSnapshot?
 
-    #: (steps: Array[ActivityStep], root_snapshots: Hash[Array[untyped], RecordSnapshot?], first_snapshot: RecordSnapshot?, last_snapshot: RecordSnapshot?) -> void
-    def initialize(steps:, root_snapshots:, first_snapshot:, last_snapshot:)
+    #: (steps: Array[ActivityStep], root_snapshots: Hash[Array[untyped], RecordSnapshot?], first_snapshot: RecordSnapshot?, last_snapshot: RecordSnapshot?, ?last_boundary: ActivityBoundary?, ?last_event_snapshot: RecordSnapshot?) -> void
+    def initialize(steps:, root_snapshots:, first_snapshot:, last_snapshot:, last_boundary: nil, last_event_snapshot: nil) # rubocop:disable Metrics/ParameterLists, Layout/LineLength
       @steps = steps.freeze
       @root_snapshots = root_snapshots.freeze
       @first_snapshot = first_snapshot
       @last_snapshot = last_snapshot
+      @last_boundary = last_boundary
+      @last_event_snapshot = last_event_snapshot
       freeze
     end
 
@@ -46,7 +50,9 @@ module PaperTrailDiff
         steps: @steps,
         root_snapshots: @root_snapshots,
         first_snapshot: @first_snapshot,
-        last_snapshot: final_snapshot
+        last_snapshot: final_snapshot,
+        last_boundary: @previous_boundary,
+        last_event_snapshot: @previous_snapshot
       )
     end
 

data/lib/paper_trail_diff/activity_relationship.rb

@@ -36,6 +36,8 @@ module PaperTrailDiff
 
     #: (untyped, untyped, state: Symbol) -> untyped
     def event_attribute(record, name, state:)
+      return record.attributes[name.to_s] if record.is_a?(PreparedRecordState)
+
       if record.is_a?(ActivitySnapshotDelta)
         return state == :before ? record.before_value(name) : record.after_value(name)
       end

data/lib/paper_trail_diff/activity_root_snapshot_refresher.rb

@@ -38,6 +38,7 @@ module PaperTrailDiff
 
       changes = @changeset.call(version, model_class)
       return [false, nil] unless changes.respond_to?(:each)
+      return [false, nil] if changes.empty?
 
       branches = branches_to_refresh(model_class, changes)
       partial = nil #: RecordSnapshot?

data/lib/paper_trail_diff/activity_snapshot_sequence.rb

@@ -4,8 +4,9 @@
 module PaperTrailDiff
   # Optional full/partial snapshot operations consumed by the activity sequence.
   class ActivitySnapshotProvider
-    #: (snapshotter: untyped, refresher: untyped, preparer: untyped) -> void
-    def initialize(snapshotter:, refresher:, preparer:)
+    #: (snapshotter: untyped, refresher: untyped, preparer: untyped, ?activity_index: untyped) -> void
+    def initialize(snapshotter:, refresher:, preparer:, activity_index: nil)
+      @activity_index = activity_index
       @snapshotter = snapshotter
       @refresher = refresher
       @preparer = preparer
@@ -55,6 +56,12 @@ module PaperTrailDiff
       )
     end
 
+    #: () -> PreparedActivityIndex?
+    def activity_index
+      @activity_index&.call
+    end
+
+    # @rbs @activity_index: untyped
     # @rbs @snapshotter: untyped
     # @rbs @refresher: untyped
     # @rbs @preparer: untyped