paper_trail_diff 0.11.0 → 0.13.0

data/lib/paper_trail_diff.rb

@@ -5,11 +5,15 @@ require 'paper_trail'
 
 require_relative 'paper_trail_diff/version'
 require_relative 'paper_trail_diff/support'
+require_relative 'paper_trail_diff/version_query'
+require_relative 'paper_trail_diff/stored_time_precision'
+require_relative 'paper_trail_diff/version_boundary'
 require_relative 'paper_trail_diff/instrumentation'
 require_relative 'paper_trail_diff/errors'
 require_relative 'paper_trail_diff/configuration'
 require_relative 'paper_trail_diff/endpoint'
 require_relative 'paper_trail_diff/association_traversal'
+require_relative 'paper_trail_diff/batch_safety'
 require_relative 'paper_trail_diff/traversal_preparer'
 require_relative 'paper_trail_diff/association_discovery'
 require_relative 'paper_trail_diff/diagnostics'
@@ -28,6 +32,10 @@ require_relative 'paper_trail_diff/nested_comparator'
 require_relative 'paper_trail_diff/engine'
 require_relative 'paper_trail_diff/historical_association_reifier'
 require_relative 'paper_trail_diff/prepared_record_index'
+require_relative 'paper_trail_diff/direct_record_state_loader'
+require_relative 'paper_trail_diff/prepared_state_association_reader'
+require_relative 'paper_trail_diff/prepared_snapshot_builder'
+require_relative 'paper_trail_diff/prepared_activity_index'
 require_relative 'paper_trail_diff/prepared_history'
 require_relative 'paper_trail_diff/version_association_candidate_scope'
 require_relative 'paper_trail_diff/prepared_edge_loader'
@@ -66,8 +74,11 @@ require_relative 'paper_trail_diff/step'
 require_relative 'paper_trail_diff/analysis'
 require_relative 'paper_trail_diff/activity_root_steps'
 require_relative 'paper_trail_diff/analysis_batch'
+require_relative 'paper_trail_diff/deleted_analysis_batch'
 require_relative 'paper_trail_diff/scoped_analysis'
+require_relative 'paper_trail_diff/historical_filter'
 require_relative 'paper_trail_diff/scoped_root_selection'
+require_relative 'paper_trail_diff/scoped_analysis_builder'
 require_relative 'paper_trail_diff/batched_root_analyzer'
 require_relative 'paper_trail_diff/version_range'
 require_relative 'paper_trail_diff/version_sequence_diagnostics'
@@ -92,10 +103,16 @@ require_relative 'paper_trail_diff/paper_trail_adapter'
 #     type attribute_changes = Hash[String, ValueChange]
 #     type association_diff = ToOneAssociationDiff | CollectionAssociationDiff
 #     type association_diffs = Hash[String, association_diff]
+#     type nested_change = ValueChange | ArrayChange
+#     type nested_changes = Hash[Array[String], nested_change]
 #     type association_snapshots = Hash[String, AssociationSnapshot]
 #     type identity = Array[untyped]
 #     type comparison_input = Hash[String | Symbol, untyped]
 #     type comparison_results = Hash[identity, Diff]
+#     type report_options = {
+#       within: untyped, activity: bool, version_scope: untyped,
+#       close_on: Symbol?, snapshots: bool, group: Symbol?
+#     }
 #     type ignore_option = Array[String | Symbol] | Hash[String | Symbol, untyped]
 #     type reference_key = :type | :id | "type" | "id"
 #     type traversal_context = :change | :included_state
@@ -115,7 +132,7 @@ module PaperTrailDiff # rubocop:disable Metrics/ModuleLength
     has_and_belongs_to_many
   ].freeze
 
-  class << self
+  class << self # rubocop:disable Metrics/ClassLength
     # Compares net state between explicit PaperTrail-version or current-record endpoints.
     #: (untyped, untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?reload_live_endpoints: bool) -> Diff
     def compare(
@@ -136,21 +153,23 @@ module PaperTrailDiff # rubocop:disable Metrics/ModuleLength
     end
 
     # Compares many independent endpoint pairs while batching current-record loading.
-    #: (Array[comparison_input], ?associations: Array[String | Symbol], ?ignore: ignore_option, ?reload_live_endpoints: bool) -> comparison_results
+    #: (Array[comparison_input], ?associations: Array[String | Symbol], ?ignore: ignore_option, ?reload_live_endpoints: bool, ?allow_expensive: bool) -> comparison_results
     def compare_many(
       comparisons,
       associations: [],
       ignore: DEFAULT_IGNORED_ATTRIBUTES,
-      reload_live_endpoints: true
+      reload_live_endpoints: true,
+      allow_expensive: false
     )
       PaperTrailAdapter.new(
         associations: associations,
         ignore: ignore,
-        reload_live_endpoints: reload_live_endpoints
+        reload_live_endpoints: reload_live_endpoints, allow_expensive: allow_expensive
       ).compare_many(comparisons)
     end
 
-    # Compares every adjacent reconstructed state in an inclusive version range.
+    # Compares every adjacent reconstructed state in an inclusive version range,
+    # by default the record's whole history through its current state.
     #: (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?version_scope: untyped, ?close_on: Symbol?) -> Array[Step]
     def timeline( # rubocop:disable Metrics/ParameterLists
       record,
@@ -173,9 +192,10 @@ module PaperTrailDiff # rubocop:disable Metrics/ModuleLength
     end
 
     # Compares adjacent root and selected-descendant activity boundaries.
-    # `reload_live_endpoints:` applies only when `to:` is a current record; the
-    # other range forms never read live state.
-    #: (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?reload_live_endpoints: bool, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool) -> Array[ActivityStep]
+    # `reload_live_endpoints:` applies whenever the range ends at the current
+    # record: an explicit `to:` record, the default range, or a window with no
+    # later version.
+    #: (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?reload_live_endpoints: bool, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool, ?group: Symbol?) -> Array[ActivityStep]
     def activity_timeline( # rubocop:disable Metrics/ParameterLists
       record,
       from: nil,
@@ -233,47 +253,36 @@ module PaperTrailDiff # rubocop:disable Metrics/ModuleLength
       )
     end
 
-    # Analyzes many roots over one shared time window, preparing their selected
-    # history once for the batch instead of once per record. Roots with no
-    # versions in the window return an empty `Analysis`.
-    #
-    # Pass `records` to analyze a list you assembled, which returns a Hash keyed
-    # by identity. Pass `scope:` with a `limit:` to have the roots selected for
-    # you from a relation, which returns a `ScopedAnalysis` -- the same Hash,
-    # plus the roots the relation could not reach. See `analyze_scope` for why
-    # that second collection exists.
-    #: (?Array[untyped]?, ?scope: untyped, ?limit: Integer?, ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?) -> (Hash[identity, Analysis] | ScopedAnalysis)
+    # Analyzes an array of records over one shared range, preparing their
+    # selected history once for the batch instead of once per record, and
+    # returns a frozen Hash keyed by identity. Roots with nothing to report in
+    # the window return an empty `Analysis`. To let a relation choose the
+    # records, use `analyze_scope`.
+    #: (Array[untyped], ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool, ?group: Symbol?, ?allow_expensive: bool) -> Hash[identity, Analysis]
     def analyze_many( # rubocop:disable Metrics/ParameterLists
-      records = nil,
-      scope: nil,
-      limit: nil,
+      records,
       within: nil,
       associations: [],
       ignore: DEFAULT_IGNORED_ATTRIBUTES,
       activity: false,
       version_scope: nil,
-      close_on: nil
+      close_on: nil,
+      snapshots: false,
+      group: nil,
+      allow_expensive: false
     )
-      adapter = PaperTrailAdapter.new(associations: associations, ignore: ignore)
-      if scope
-        raise ConfigurationError, 'pass either records or scope:, not both' unless records.nil?
-
-        return adapter.analyze_scope(scope, limit: limit, within: within, activity: activity,
-                                            version_scope: version_scope, close_on: close_on)
-      end
-      raise ConfigurationError, 'pass records or scope:' if records.nil?
-
-      adapter.analyze_many(records, within: within, activity: activity,
-                                    version_scope: version_scope, close_on: close_on)
+      PaperTrailAdapter.new(
+        associations: associations, ignore: ignore, allow_expensive: allow_expensive
+      ).analyze_many(records, within: within, activity: activity, version_scope: version_scope,
+                              close_on: close_on, snapshots: snapshots, group: group)
     end
 
     # Analyzes every root the relation reaches whose history moved inside the
-    # window, selecting them in a fixed number of queries rather than making the
-    # caller rediscover them.
+    # window. Joined duplicates are read in bounded pages and analyzed once.
     #
     # `limit:` is required and exceeding it raises. Selection moves into the gem
-    # here, so the bound on how much work a page can ask for has to move with
-    # it, and a truncated audit report is worse than a refused one.
+    # here. The relation's own limit/offset select the live page; this separate
+    # ceiling rejects too many unique roots rather than truncating that page.
     #
     # Returns a `ScopedAnalysis`, which destructures:
     #
@@ -282,7 +291,8 @@ module PaperTrailDiff # rubocop:disable Metrics/ModuleLength
     #   )
     #
     # `unreachable` names roots that changed in the window but have no live row
-    # left. A relation's conditions are evaluated against the live table, so a
+    # left, independently of the live page's pagination and safety ceiling.
+    # A relation's conditions are evaluated against the live table, so a
     # destroyed root cannot be tested against them at all -- its history is
     # intact and the state it held at destruction may well have matched. Those
     # roots are reported rather than dropped so that a page auditing deletions
@@ -291,7 +301,7 @@ module PaperTrailDiff # rubocop:disable Metrics/ModuleLength
     # Note also that a relation selects on current state, not on state during
     # the window: `where(status: 'published')` means published *now*, which is a
     # different set from what was published while the window was open.
-    #: (untyped, limit: Integer?, ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?) -> ScopedAnalysis
+    #: (untyped, limit: Integer?, ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool, ?group: Symbol?, ?historical_filter: untyped, ?max_filter_versions: Integer, ?include_deleted: bool, ?allow_expensive: bool) -> ScopedAnalysis
     def analyze_scope( # rubocop:disable Metrics/ParameterLists
       scope,
       limit:,
@@ -300,11 +310,39 @@ module PaperTrailDiff # rubocop:disable Metrics/ModuleLength
       ignore: DEFAULT_IGNORED_ATTRIBUTES,
       activity: false,
       version_scope: nil,
-      close_on: nil
+      close_on: nil,
+      snapshots: false,
+      group: nil,
+      historical_filter: nil,
+      max_filter_versions: HistoricalFilter::DEFAULT_VERSION_LIMIT,
+      include_deleted: false,
+      allow_expensive: false
     )
-      PaperTrailAdapter.new(associations: associations, ignore: ignore).analyze_scope(
+      adapter = PaperTrailAdapter.new(associations: associations, ignore: ignore,
+                                      allow_expensive: allow_expensive)
+      adapter.analyze_scope(
         scope, limit: limit, within: within, activity: activity,
-               version_scope: version_scope, close_on: close_on
+               version_scope: version_scope, close_on: close_on, snapshots: snapshots, group: group,
+               historical_filter: historical_filter, max_filter_versions: max_filter_versions,
+               include_deleted: include_deleted
+      )
+    end
+
+    # Recent root and selected-child activity through the current saved state.
+    # Historical windows remain explicit on analyze_scope; this entry point is
+    # deliberately named for a report through now rather than an as-of query.
+    #: (untyped, since: untyped, limit: Integer, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?snapshots: bool, ?group: Symbol?, ?include_deleted: bool, ?historical_filter: untyped, ?max_filter_versions: Integer, ?allow_expensive: bool) -> ScopedAnalysis
+    def report( # rubocop:disable Metrics/ParameterLists
+      scope, since:, limit:, associations: [], ignore: DEFAULT_IGNORED_ATTRIBUTES,
+      snapshots: false, group: nil, include_deleted: false, historical_filter: nil,
+      max_filter_versions: HistoricalFilter::DEFAULT_VERSION_LIMIT, allow_expensive: false
+    )
+      analyze_scope(
+        scope,
+        within: since..Time.now.utc, limit: limit, associations: associations,
+        ignore: ignore, activity: true, close_on: :current, snapshots: snapshots, group: group,
+        include_deleted: include_deleted, historical_filter: historical_filter,
+        max_filter_versions: max_filter_versions, allow_expensive: allow_expensive
       )
     end
 
@@ -344,7 +382,7 @@ module PaperTrailDiff # rubocop:disable Metrics/ModuleLength
     # list that merely shifted would otherwise look changed throughout. A key
     # that was absent reads as `NestedComparator::ABSENT` rather than nil, which
     # JSON uses for a present null.
-    #: (untyped, ?untyped) -> Hash[Array[String], ValueChange]
+    #: (untyped, ?untyped) -> nested_changes
     def nested_changes(change, to_value = nil)
       # Tested by type rather than by responding to `from`: ActiveSupport gives
       # String#from, so duck-typing here quietly reads a plain string as a pair.

data/sig/generated/paper_trail_diff/activity_belongs_to_event_applier.rbs

@@ -29,9 +29,6 @@ module PaperTrailDiff
     # : (Array[RecordSnapshot], untyped, RecordSnapshot?) -> [Array[RecordSnapshot], bool]
     def replace_existing_target: (Array[RecordSnapshot], untyped, RecordSnapshot?) -> [ Array[RecordSnapshot], bool ]
 
-    # : (RecordSnapshot, String, AssociationSnapshot) -> RecordSnapshot
-    def replace_association: (RecordSnapshot, String, AssociationSnapshot) -> RecordSnapshot
-
     # : (untyped, RecordSnapshot?) -> String
     def replacement_type: (untyped, RecordSnapshot?) -> String
 

data/sig/generated/paper_trail_diff/activity_boundary.rbs

@@ -54,8 +54,8 @@ module PaperTrailDiff
     # : () -> bool
     def destroyed?: () -> bool
 
-    # : () -> Hash[Symbol, untyped]
-    def to_h: () -> Hash[Symbol, untyped]
+    # : (?metadata: bool) -> Hash[Symbol, untyped]
+    def to_h: (?metadata: bool) -> Hash[Symbol, untyped]
   end
 
   # One adjacent transition in a descendant-aware activity timeline.
@@ -87,7 +87,12 @@ module PaperTrailDiff
     # : () -> bool
     def empty?: () -> bool
 
-    # : () -> Hash[Symbol, untyped]
-    def to_h: () -> Hash[Symbol, untyped]
+    # 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: () -> ActivityBoundary
+
+    # : (?metadata: bool, ?snapshots: bool) -> Hash[Symbol, untyped]
+    def to_h: (?metadata: bool, ?snapshots: bool) -> Hash[Symbol, untyped]
   end
 end

data/sig/generated/paper_trail_diff/activity_child_candidate_loader.rbs

@@ -9,6 +9,14 @@ module PaperTrailDiff
     # : () -> Array[untyped]
     def call: () -> Array[untyped]
 
+    # 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: () -> Array[Array[untyped]]
+
+    # : () -> Array[Array[untyped]]
+    def current_pairs: () -> Array[Array[untyped]]
+
     private
 
     @parent_class: untyped
@@ -19,6 +27,9 @@ module PaperTrailDiff
 
     @reflection: untyped
 
+    # : (Array[Array[untyped]]) -> Array[Array[untyped]]
+    def typed_rows: (Array[Array[untyped]]) -> Array[Array[untyped]]
+
     # : () -> Array[untyped]
     def historical_ids: () -> Array[untyped]
 

data/sig/generated/paper_trail_diff/activity_collection_event_applier.rbs

@@ -22,8 +22,8 @@ module PaperTrailDiff
 
     @route_updater: ActivityCollectionRouteUpdater
 
-    # : (RecordSnapshot, Array[untyped], untyped, ActivitySnapshotDelta?, Array[untyped], SnapshotNormalizer, Array[untyped]) -> RecordSnapshot
-    def apply_route: (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: (RecordSnapshot, Array[untyped], untyped, ActivitySnapshotDelta?, Array[untyped], SnapshotNormalizer, Array[untyped], ?direct: bool) -> RecordSnapshot
 
     # : (Array[Array[untyped]], untyped) -> bool
     def unsafe_through_membership_event?: (Array[Array[untyped]], untyped) -> bool
@@ -31,8 +31,8 @@ module PaperTrailDiff
     # : (Array[Array[untyped]], ActivitySnapshotDelta?) -> bool
     def unsafe_nested_membership_delta?: (Array[Array[untyped]], ActivitySnapshotDelta?) -> bool
 
-    # : (RecordSnapshot, Array[untyped], untyped, ActivitySnapshotDelta?, Array[untyped], SnapshotNormalizer, Array[untyped]) -> [untyped, RecordSnapshot?]
-    def route_event_state: (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: (RecordSnapshot, Array[untyped], untyped, ActivitySnapshotDelta?, Array[untyped], SnapshotNormalizer, Array[untyped], ?direct: bool) -> [ untyped, RecordSnapshot? ]
 
     # : (untyped, Array[untyped], SnapshotNormalizer, Array[untyped]) -> RecordSnapshot?
     def normalized_event_record: (untyped, Array[untyped], SnapshotNormalizer, Array[untyped]) -> RecordSnapshot?

data/sig/generated/paper_trail_diff/activity_collection_route_updater.rbs

@@ -37,8 +37,5 @@ module PaperTrailDiff
 
     # : (AssociationSnapshot, untyped, ActivityCollectionRouteChange) -> Integer?
     def nested_owner_position: (AssociationSnapshot, untyped, ActivityCollectionRouteChange) -> Integer?
-
-    # : (RecordSnapshot, String, AssociationSnapshot) -> RecordSnapshot
-    def replace_association: (RecordSnapshot, String, AssociationSnapshot) -> RecordSnapshot
   end
 end

data/sig/generated/paper_trail_diff/activity_event_record_resolver.rbs

@@ -5,11 +5,17 @@ module PaperTrailDiff
   class ActivityEventRecordResolver
     RECORD_AFTER_HANDLERS: untyped
 
-    # : (?record_transition: untyped) -> void
-    def initialize: (?record_transition: untyped) -> void
+    # : (?record_transition: untyped, ?prepared_record_after: untyped) -> void
+    def initialize: (?record_transition: untyped, ?prepared_record_after: untyped) -> void
+
+    # : (untyped, ?direct: bool) -> untyped
+    def record_after: (untyped, ?direct: bool) -> untyped
+
+    # : (untyped) -> [bool, untyped]
+    def direct_after: (untyped) -> [ bool, untyped ]
 
     # : (untyped) -> untyped
-    def record_after: (untyped) -> untyped
+    def fallback_record_after: (untyped) -> untyped
 
     # : (untyped) -> ActivitySnapshotDelta?
     def snapshot_delta: (untyped) -> ActivitySnapshotDelta?
@@ -30,8 +36,18 @@ module PaperTrailDiff
 
     private
 
+    @direct_loader: DirectRecordStateLoader
+
+    @prepared_record_after: untyped
+
     @record_transition: untyped
 
+    # : (untyped) -> PreparedRecordState?
+    def direct_record_after: (untyped) -> PreparedRecordState?
+
+    # : (untyped) -> untyped
+    def prepared_changeset: (untyped) -> untyped
+
     # : (untyped, untyped) -> Hash[untyped, untyped]
     def after_attributes: (untyped, untyped) -> Hash[untyped, untyped]
 

data/sig/generated/paper_trail_diff/activity_event_snapshot_refresher.rbs

@@ -3,8 +3,8 @@
 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: AssociationTraversal, pool: SnapshotPool, components: untyped, ?association_reader: untyped, ?record_transition: untyped) -> void
+    # : (traversal: AssociationTraversal, pool: SnapshotPool, components: untyped, ?association_reader: untyped, ?record_transition: untyped, ?prepared_record_after: untyped) -> void
+    def initialize: (traversal: AssociationTraversal, pool: SnapshotPool, components: untyped, ?association_reader: untyped, ?record_transition: untyped, ?prepared_record_after: untyped) -> void
 
     # : (SnapshotPool, untyped) -> void
     def configure_appliers: (SnapshotPool, untyped) -> void

data/sig/generated/paper_trail_diff/activity_grouping.rbs

@@ -6,6 +6,9 @@ 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!: (Symbol?, ?activity: bool, ?snapshots: bool) -> void
+
     private
 
     # : () -> bool

data/sig/generated/paper_trail_diff/activity_history.rbs

@@ -11,8 +11,12 @@ module PaperTrailDiff
 
     attr_reader last_snapshot: RecordSnapshot?
 
-    # : (steps: Array[ActivityStep], root_snapshots: Hash[Array[untyped], RecordSnapshot?], first_snapshot: RecordSnapshot?, last_snapshot: RecordSnapshot?) -> void
-    def initialize: (steps: Array[ActivityStep], root_snapshots: Hash[Array[untyped], RecordSnapshot?], first_snapshot: RecordSnapshot?, last_snapshot: RecordSnapshot?) -> void
+    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?, ?last_boundary: ActivityBoundary?, ?last_event_snapshot: RecordSnapshot?) -> void
+    def initialize: (steps: Array[ActivityStep], root_snapshots: Hash[Array[untyped], RecordSnapshot?], first_snapshot: RecordSnapshot?, last_snapshot: RecordSnapshot?, ?last_boundary: ActivityBoundary?, ?last_event_snapshot: RecordSnapshot?) -> void
 
     # : () -> ActivityHistory
     def self.empty: () -> ActivityHistory

data/sig/generated/paper_trail_diff/activity_snapshot_sequence.rbs

@@ -3,8 +3,8 @@
 module PaperTrailDiff
   # Optional full/partial snapshot operations consumed by the activity sequence.
   class ActivitySnapshotProvider
-    # : (snapshotter: untyped, refresher: untyped, preparer: untyped) -> void
-    def initialize: (snapshotter: untyped, refresher: untyped, preparer: untyped) -> void
+    # : (snapshotter: untyped, refresher: untyped, preparer: untyped, ?activity_index: untyped) -> void
+    def initialize: (snapshotter: untyped, refresher: untyped, preparer: untyped, ?activity_index: untyped) -> void
 
     # : (untyped, Array[untyped], ?start_at: untyped, ?end_at: untyped) -> void
     def prepare: (untyped, Array[untyped], ?start_at: untyped, ?end_at: untyped) -> void
@@ -18,6 +18,11 @@ module PaperTrailDiff
     # : (untyped, untyped, RecordSnapshot?, event: ActivityEvent) -> RecordSnapshot?
     def advance_root: (untyped, untyped, RecordSnapshot?, event: ActivityEvent) -> RecordSnapshot?
 
+    # : () -> PreparedActivityIndex?
+    def activity_index: () -> PreparedActivityIndex?
+
+    @activity_index: untyped
+
     @preparer: untyped
 
     @refresher: untyped

data/sig/generated/paper_trail_diff/activity_timeline_builder.rbs

@@ -44,6 +44,14 @@ module PaperTrailDiff
     # : () -> Array[ActivityStep]
     def build_to_current: () -> Array[ActivityStep]
 
+    # : () -> Analysis
+    def analyze_current: () -> Analysis
+
+    # The explicit live endpoint and a batch's live closing endpoint use the
+    # same selected plan. A version filter can close earlier, on its successor.
+    # : () -> [RootVersionPlan, Array[ActivityEvent], ActivityHistory, RecordSnapshot?, ActivityBoundary?]
+    def current_history: () -> [ RootVersionPlan, Array[ActivityEvent], ActivityHistory, RecordSnapshot?, ActivityBoundary? ]
+
     # : () -> [RecordSnapshot?, untyped]
     def capture_current: () -> [ RecordSnapshot?, untyped ]
 
@@ -56,9 +64,6 @@ module PaperTrailDiff
     # : (Array[untyped], ?end_at: untyped) -> void
     def prepare_history: (Array[untyped], ?end_at: untyped) -> void
 
-    # : (Array[untyped], Array[ActivityEvent], ?current: untyped, ?final_boundary: ActivityBoundary?, ?final_snapshot: RecordSnapshot?) -> Array[ActivityStep]
-    def build_event_steps: (Array[untyped], Array[ActivityEvent], ?current: untyped, ?final_boundary: ActivityBoundary?, ?final_snapshot: RecordSnapshot?) -> Array[ActivityStep]
-
     # Appends the transition into an explicit closing boundary, which is either
     # a requested current record or the absence a final root destroy leaves.
     # : (ActivityHistory, Array[ActivityEvent], ActivityBoundary?, RecordSnapshot?) -> Array[ActivityStep]

data/sig/generated/paper_trail_diff/activity_version_collector.rbs

@@ -3,14 +3,16 @@
 module PaperTrailDiff
   # Collects root and selected-descendant versions relevant to one root history range.
   class ActivityVersionCollector
-    # : (untyped, root_versions: Array[untyped], tree: AssociationTree, traversal: AssociationTraversal, ?range_start: untyped, ?range_end: untyped) -> void
-    def initialize: (untyped, root_versions: Array[untyped], tree: AssociationTree, traversal: AssociationTraversal, ?range_start: untyped, ?range_end: untyped) -> void
+    # : (untyped, root_versions: Array[untyped], tree: AssociationTree, traversal: AssociationTraversal, ?range_start: untyped, ?range_end: untyped, ?prepared: PreparedActivityIndex?) -> void
+    def initialize: (untyped, root_versions: Array[untyped], tree: AssociationTree, traversal: AssociationTraversal, ?range_start: untyped, ?range_end: untyped, ?prepared: PreparedActivityIndex?) -> void
 
     # : () -> Array[ActivityEvent]
     def call: () -> Array[ActivityEvent]
 
     private
 
+    @prepared: PreparedActivityIndex?
+
     @range: ActivityRange
 
     @record: untyped
@@ -58,11 +60,5 @@ module PaperTrailDiff
 
     # : (untyped, untyped) -> untyped
     def target_class: (untyped, untyped) -> untyped
-
-    # : (untyped) -> bool
-    def in_range?: (untyped) -> bool
-
-    # : (String, String) -> String
-    def join_path: (String, String) -> String
   end
 end

data/sig/generated/paper_trail_diff/analysis.rbs

@@ -26,7 +26,7 @@ module PaperTrailDiff
     # 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: bool) -> Hash[Symbol, untyped]
+    # : (?snapshots: bool, ?metadata: bool) -> Hash[Symbol, untyped]
+    def to_h: (?snapshots: bool, ?metadata: bool) -> Hash[Symbol, untyped]
   end
 end

data/sig/generated/paper_trail_diff/analysis_batch.rbs

@@ -5,8 +5,8 @@ module PaperTrailDiff
   # versions and preparing their association history once for the whole batch
   # rather than once per root.
   class AnalysisBatch
-    # : (Array[untyped], time_range: TimeRange?, live_loader: untyped, history_preparer: untyped, analyzer: untyped, ?version_scope: untyped, ?close_on_current: bool) -> void
-    def initialize: (Array[untyped], time_range: TimeRange?, live_loader: untyped, history_preparer: untyped, analyzer: untyped, ?version_scope: untyped, ?close_on_current: bool) -> void
+    # : (Array[untyped], time_range: TimeRange?, live_loader: untyped, history_preparer: untyped, analyzer: untyped, ?version_scope: untyped, ?close_on_current: bool, ?context_required: bool) -> void
+    def initialize: (Array[untyped], time_range: TimeRange?, live_loader: untyped, history_preparer: untyped, analyzer: untyped, ?version_scope: untyped, ?close_on_current: bool, ?context_required: bool) -> void
 
     # : () -> Hash[identity, Analysis]
     def call: () -> Hash[identity, Analysis]
@@ -17,6 +17,8 @@ module PaperTrailDiff
 
     @close_on_current: bool
 
+    @context_required: bool
+
     @history_preparer: untyped
 
     @live_loader: untyped
@@ -43,8 +45,17 @@ module PaperTrailDiff
     # : (Array[untyped], Hash[Array[String], RootVersionPlan], Hash[Array[String], untyped]) -> void
     def prepare: (Array[untyped], Hash[Array[String], RootVersionPlan], Hash[Array[String], untyped]) -> void
 
+    # : (Array[untyped], Hash[Array[String], RootVersionPlan]) -> bool
+    def closes_live?: (Array[untyped], Hash[Array[String], RootVersionPlan]) -> bool
+
+    # A plan closing on the live record reads history up to now; the others
+    # stop at the window, so a past window does not load everything since.
+    # : (Array[untyped], ?live: bool) -> Hash[Symbol, untyped]
+    def preparation_range: (Array[untyped], ?live: bool) -> Hash[Symbol, untyped]
+
     # A root with no versions in range has nothing to report, which is an empty
-    # result rather than a failed request.
+    # result rather than a failed request -- unless an activity view closes it
+    # on current state, where its descendants may still have moved.
     # : (untyped, RootVersionPlan) -> Analysis
     def analysis_for: (untyped, RootVersionPlan) -> Analysis
   end

data/sig/generated/paper_trail_diff/association_traversal.rbs

@@ -3,6 +3,11 @@
 module PaperTrailDiff
   # Resolves and validates ActiveRecord reflections for a bounded association tree.
   class AssociationTraversal
+    # The class a `belongs_to` points at for this record, reading a polymorphic
+    # type column when there is one. Nil when that type names no class.
+    # : (untyped, untyped) -> untyped
+    def self.belongs_to_target: (untyped, untyped) -> untyped
+
     # : (AssociationTree) -> void
     def initialize: (AssociationTree) -> void
 
@@ -18,6 +23,12 @@ module PaperTrailDiff
     # : (untyped) -> Array[String]
     def habtm_paths: (untyped) -> Array[String]
 
+    # HABTM join rows have no versions of their own, so membership changes
+    # cannot be split into events once a range runs past the last root version
+    # into live state.
+    # : (untyped) -> void
+    def reject_live_habtm_activity!: (untyped) -> void
+
     # : (untyped, AssociationTree, path: String) -> Array[untyped]
     def reflections_for: (untyped, AssociationTree, path: String) -> Array[untyped]
 

data/sig/generated/paper_trail_diff/batch_boundary_resolver.rbs

@@ -1,7 +1,7 @@
 # Generated from lib/paper_trail_diff/batch_boundary_resolver.rb with RBS::Inline
 
 module PaperTrailDiff
-  # Resolves `:first` and `:last` endpoints for a whole batch in two queries per
+  # Resolves `:first` endpoints for a whole batch in a fixed number of 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
@@ -46,15 +46,12 @@ module PaperTrailDiff
     # : (Hash[Array[String], Hash[Symbol, untyped]], untyped, Array[untyped]) -> void
     def add_model_boundaries: (Hash[Array[String], Hash[Symbol, untyped]], untyped, Array[untyped]) -> void
 
-    # 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: (untyped, Array[untyped]) -> [ Hash[untyped, untyped], Hash[untyped, untyped], Hash[untyped, untyped] ]
-
-    # 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: (Hash[untyped, untyped], untyped) -> untyped
+    # Each root's earliest version by time, in one query whatever the size of
+    # the batch. The lowest id is not the earliest version when ids are not
+    # sequential, as with UUIDs, so time decides and the usual ordering breaks
+    # a tie -- refusing one that ids cannot order.
+    # : (untyped, Array[untyped]) -> Hash[String, untyped]
+    def first_versions: (untyped, Array[untyped]) -> Hash[String, untyped]
 
     # : (untyped, untyped) -> Array[String]
     def identity_key: (untyped, untyped) -> Array[String]

data/sig/generated/paper_trail_diff/batch_safety.rbs

@@ -0,0 +1,24 @@
+# Generated from lib/paper_trail_diff/batch_safety.rb with RBS::Inline
+
+module PaperTrailDiff
+  # Refuses known per-record association loading before a batch reconstructs it.
+  class BatchSafety
+    # : (AssociationTraversal, allow_expensive: bool) -> void
+    def initialize: (AssociationTraversal, allow_expensive: bool) -> void
+
+    # : (untyped, ?historical: bool) -> void
+    def call: (untyped, ?historical: bool) -> void
+
+    private
+
+    @allow_expensive: bool
+
+    @traversal: AssociationTraversal
+
+    # : (untyped, String, bool) -> void
+    def check: (untyped, String, bool) -> void
+
+    # : (untyped, bool) -> String?
+    def reason_for: (untyped, bool) -> String?
+  end
+end