paper_trail_diff 0.12.0 → 0.13.1

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

data/sig/generated/paper_trail_diff/batched_root_analyzer.rbs

@@ -4,8 +4,8 @@ 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: AssociationTree, timeline_snapshotter: untyped, activity_snapshotter: untyped, preparer: untyped, activity: bool) -> void
+    # : (tree: AssociationTree, timeline_snapshotter: untyped, activity_snapshotter: untyped, preparer: untyped, activity: bool, ?within: untyped, ?snapshots: bool, ?group: Symbol?) -> void
+    def initialize: (tree: AssociationTree, timeline_snapshotter: untyped, activity_snapshotter: untyped, preparer: untyped, activity: bool, ?within: untyped, ?snapshots: bool, ?group: Symbol?) -> void
 
     # : (untyped, RootVersionPlan) -> Analysis
     def call: (untyped, RootVersionPlan) -> Analysis
@@ -16,12 +16,18 @@ module PaperTrailDiff
 
     @activity_snapshotter: untyped
 
+    @group: Symbol?
+
     @preparer: untyped
 
+    @snapshots: bool
+
     @timeline_snapshotter: untyped
 
     @tree: AssociationTree
 
+    @within: untyped
+
     # : (untyped, RootVersionPlan) -> Analysis
     def activity_analysis: (untyped, RootVersionPlan) -> Analysis
   end

data/sig/generated/paper_trail_diff/batched_root_versions.rbs

@@ -5,8 +5,8 @@ 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?, ?version_scope: untyped, ?live_endpoints: Hash[Array[String], untyped]?) -> void
-    def initialize: (Array[untyped], time_range: TimeRange?, ?version_scope: untyped, ?live_endpoints: Hash[Array[String], untyped]?) -> void
+    # : (Array[untyped], time_range: TimeRange?, ?version_scope: untyped, ?live_endpoints: Hash[Array[String], untyped]?, ?context_required: bool) -> void
+    def initialize: (Array[untyped], time_range: TimeRange?, ?version_scope: untyped, ?live_endpoints: Hash[Array[String], untyped]?, ?context_required: bool) -> void
 
     # Returns a plan per record identity.
     # : () -> Hash[Array[String], RootVersionPlan]
@@ -14,6 +14,8 @@ module PaperTrailDiff
 
     private
 
+    @context_required: bool
+
     @live_endpoints: Hash[Array[String], untyped]?
 
     @records: Array[untyped]
@@ -47,23 +49,9 @@ module PaperTrailDiff
     # : (untyped, Array[untyped], TimeRange?) -> untyped
     def range_scope: (untyped, Array[untyped], TimeRange?) -> untyped
 
-    # One row per root: the earliest version after the window, found without a
-    # window function so the query stays portable.
     # : (untyped, Array[untyped], TimeRange) -> Hash[String, untyped]
     def trailing_versions: (untyped, Array[untyped], TimeRange) -> Hash[String, untyped]
 
-    # : (untyped, TimeRange) -> untyped
-    def no_earlier_trailing: (untyped, TimeRange) -> untyped
-
-    # Mirrors the window's own end handling, so a version sitting exactly on an
-    # inclusive boundary stays inside the window instead of masking the trailing
-    # version that follows it.
-    # : (untyped, untyped, TimeRange) -> untyped
-    def preceding: (untyped, untyped, TimeRange) -> untyped
-
-    # : (untyped, TimeRange) -> untyped
-    def after_window: (untyped, TimeRange) -> untyped
-
     # : (untyped, Array[untyped]) -> untyped
     def base_scope: (untyped, Array[untyped]) -> untyped
 

data/sig/generated/paper_trail_diff/branch_snapshot_refresher.rbs

@@ -3,8 +3,8 @@
 module PaperTrailDiff
   # Reconstructs selected root branches and merges them into a prior immutable snapshot.
   class BranchSnapshotRefresher
-    # : (tree: AssociationTree, ignore_policy: IgnorePolicy, traversal: AssociationTraversal, pool: SnapshotPool, normalizer: SnapshotNormalizer, full_snapshotter: untyped, partial_snapshotter: untyped, association_reader: untyped, record_transition: untyped) -> void
-    def initialize: (tree: AssociationTree, ignore_policy: IgnorePolicy, traversal: AssociationTraversal, pool: SnapshotPool, normalizer: SnapshotNormalizer, full_snapshotter: untyped, partial_snapshotter: untyped, association_reader: untyped, record_transition: untyped) -> void
+    # : (tree: AssociationTree, ignore_policy: IgnorePolicy, traversal: AssociationTraversal, pool: SnapshotPool, normalizer: SnapshotNormalizer, full_snapshotter: untyped, partial_snapshotter: untyped, association_reader: untyped, record_transition: untyped, ?prepared_record_after: untyped) -> void
+    def initialize: (tree: AssociationTree, ignore_policy: IgnorePolicy, traversal: AssociationTraversal, pool: SnapshotPool, normalizer: SnapshotNormalizer, full_snapshotter: untyped, partial_snapshotter: untyped, association_reader: untyped, record_transition: untyped, ?prepared_record_after: untyped) -> void
 
     # : (untyped, untyped, RecordSnapshot?, event: ActivityEvent) -> RecordSnapshot?
     def advance_root: (untyped, untyped, RecordSnapshot?, event: ActivityEvent) -> RecordSnapshot?

data/sig/generated/paper_trail_diff/collection_comparator.rbs

@@ -17,12 +17,12 @@ module PaperTrailDiff
 
     @to: AssociationSnapshot
 
+    # A transition names the one record that changed between adjacent
+    # snapshots. With matching identities it is an update; otherwise the
+    # before record left and the after record joined.
     # : (CollectionTransition) -> CollectionAssociationDiff
     def transition_difference: (CollectionTransition) -> CollectionAssociationDiff
 
-    # : (RecordSnapshot?, RecordSnapshot?) -> RecordChange?
-    def compare_transition_records: (RecordSnapshot?, RecordSnapshot?) -> RecordChange?
-
     # : () -> Array[RecordChange]?
     def aligned_changes: () -> Array[RecordChange]?
 
@@ -57,6 +57,9 @@ module PaperTrailDiff
     # : (identity) -> Array[untyped]
     def sortable_identity: (identity) -> Array[untyped]
 
+    # Only the order of the group numbers matters, so moving the lowest one
+    # down or the highest one up changes nothing; the spec checks the order.
+    # mutant:disable
     # : (untyped) -> Array[untyped]
     def sortable_id: (untyped) -> Array[untyped]
 

data/sig/generated/paper_trail_diff/collection_identity_index.rbs

@@ -6,8 +6,8 @@ module PaperTrailDiff
     # : (Array[untyped]) -> void
     def initialize: (Array[untyped]) -> void
 
-    # : (untyped, untyped) -> Integer?
-    def position: (untyped, untyped) -> Integer?
+    # : (String, untyped) -> Integer?
+    def position: (String, untyped) -> Integer?
 
     # : (untyped) -> Integer?
     def position_for_id: (untyped) -> Integer?
@@ -16,7 +16,7 @@ module PaperTrailDiff
 
     @id_positions: Hash[String, Integer?]
 
-    @positions: Hash[Array[untyped], Integer]
+    @identities: Set[Array[untyped]]
 
     @serialized_positions: Hash[Array[String], Integer]
 

data/sig/generated/paper_trail_diff/deleted_analysis_batch.rbs

@@ -0,0 +1,44 @@
+# Generated from lib/paper_trail_diff/deleted_analysis_batch.rb with RBS::Inline
+
+module PaperTrailDiff
+  # Analyzes missing roots together without pretending that they have live rows.
+  class DeletedAnalysisBatch
+    # : (untyped, identities: Array[Array[String]], time_range: TimeRange?, analyzer: untyped, history_preparer: untyped, ?version_scope: untyped) -> void
+    def initialize: (untyped, identities: Array[Array[String]], time_range: TimeRange?, analyzer: untyped, history_preparer: untyped, ?version_scope: untyped) -> void
+
+    # : () -> Hash[Array[String], Analysis?]
+    def call: () -> Hash[Array[String], Analysis?]
+
+    private
+
+    # : (Hash[Array[String], Analysis]) -> Hash[Array[String], Analysis?]
+    def with_unavailable: (Hash[Array[String], Analysis]) -> Hash[Array[String], Analysis?]
+
+    @analyzer: untyped
+
+    @history_preparer: untyped
+
+    @identities: Array[Array[String]]
+
+    @model: untyped
+
+    @time_range: TimeRange?
+
+    @version_scope: untyped
+
+    # These records supply identity and model metadata only. Every reported
+    # value comes from the batched historical plan; no per-root reify or live
+    # lookup is needed to get into the comparison engine.
+    # : () -> Array[untyped]
+    def historical_roots: () -> Array[untyped]
+
+    # : () -> Array[untyped]
+    def destroy_versions: () -> Array[untyped]
+
+    # : (Array[untyped]) -> Hash[Symbol, untyped]
+    def preparation_range: (Array[untyped]) -> Hash[Symbol, untyped]
+
+    # : (Array[untyped], Hash[Array[String], RootVersionPlan]) -> void
+    def prepare: (Array[untyped], Hash[Array[String], RootVersionPlan]) -> void
+  end
+end

data/sig/generated/paper_trail_diff/direct_record_state_loader.rbs

@@ -0,0 +1,42 @@
+# Generated from lib/paper_trail_diff/direct_record_state_loader.rb with RBS::Inline
+
+module PaperTrailDiff
+  # Completes plain recorded state without invoking model initialization or writers.
+  # Decline model behavior whose values require an actual ActiveRecord instance.
+  class DirectRecordStateLoader
+    # : () -> void
+    def initialize: () -> void
+
+    # : (untyped) -> PreparedRecordState?
+    def call: (untyped) -> PreparedRecordState?
+
+    # : (PreparedRecordState) -> PreparedRecordState?
+    def complete: (PreparedRecordState) -> PreparedRecordState?
+
+    private
+
+    @defaults: Hash[untyped, Hash[untyped, untyped]]
+
+    @loader: PreparedVersionStateLoader
+
+    @supported: Hash[untyped, bool]
+
+    # : (untyped) -> bool
+    def supported?: (untyped) -> bool
+
+    # : (untyped) -> bool
+    def plain_model?: (untyped) -> bool
+
+    # : (untyped) -> bool
+    def plain_attributes?: (untyped) -> bool
+
+    # : (untyped) -> bool
+    def application_defaults?: (untyped) -> bool
+
+    # : (untyped) -> bool
+    def encrypted?: (untyped) -> bool
+
+    # : (untyped) -> bool
+    def framework_class?: (untyped) -> bool
+  end
+end

data/sig/generated/paper_trail_diff/endpoint.rbs

@@ -33,6 +33,11 @@ module PaperTrailDiff
     # : (untyped) -> untyped
     def self?.model_class: (untyped) -> untyped
 
+    # The record's own PaperTrail versions, under whatever name the model gave
+    # the association.
+    # : (untyped) -> untyped
+    def self?.versions: (untyped) -> untyped
+
     # : (untyped) -> untyped
     def self?.reload_record: (untyped) -> untyped
 

data/sig/generated/paper_trail_diff/engine.rbs

@@ -18,6 +18,8 @@ module PaperTrailDiff
     # : (AssociationSnapshot?, AssociationSnapshot?) -> void
     private def self.validate_association_kinds!: (AssociationSnapshot?, AssociationSnapshot?) -> void
 
+    # Kinds are symbols, so `!=`, `equal?`, and `eql?` all agree here.
+    # mutant:disable
     # : (AssociationSnapshot?, AssociationSnapshot?) -> bool
     private def self.kinds_differ?: (AssociationSnapshot?, AssociationSnapshot?) -> bool
 
@@ -36,7 +38,7 @@ module PaperTrailDiff
     # : (AssociationSnapshot, AssociationSnapshot) -> CollectionAssociationDiff
     private def self.compare_collection: (AssociationSnapshot, AssociationSnapshot) -> CollectionAssociationDiff
 
-    # : (RecordSnapshot?, RecordSnapshot?) -> bool
-    private def self.same_identity?: (RecordSnapshot?, RecordSnapshot?) -> bool
+    # : (RecordSnapshot?, RecordSnapshot?) -> boolish
+    private def self.same_identity?: (RecordSnapshot?, RecordSnapshot?) -> boolish
   end
 end

data/sig/generated/paper_trail_diff/errors.rbs

@@ -9,6 +9,10 @@ module PaperTrailDiff
   class ConfigurationError < Error
   end
 
+  # Raised when nested data keys cannot be represented by unique string paths.
+  class AmbiguousNestedKeyError < Error
+  end
+
   # Raised when compare endpoints do not belong to the same PaperTrail item.
   class VersionMismatchError < Error
   end
@@ -46,6 +50,14 @@ module PaperTrailDiff
   class BatchLimitExceededError < Error
   end
 
+  # Historical candidate loading exceeded its explicitly bounded work budget.
+  class FilterLimitExceededError < Error
+  end
+
+  # A batch selected a known expensive association without explicitly opting in.
+  class UnsupportedBatchPathError < ConfigurationError
+  end
+
   # Raised when a requested ActiveRecord association does not exist.
   class UnknownAssociationError < Error
   end

data/sig/generated/paper_trail_diff/historical_association_reifier.rbs

@@ -25,6 +25,14 @@ module PaperTrailDiff
     # : (untyped, untyped) -> void
     def reify_has_many: (untyped, untyped) -> void
 
+    # PT-AT's collection-source helper reifies every has_many on each join
+    # record. Walk only the requested source instead, including nested throughs.
+    # : (untyped, untyped) -> void
+    def reify_through: (untyped, untyped) -> void
+
+    # : (untyped, untyped, untyped) -> Array[untyped]
+    def through_members: (untyped, untyped, untyped) -> Array[untyped]
+
     # : (untyped, untyped) -> void
     def reify_habtm: (untyped, untyped) -> void
 

data/sig/generated/paper_trail_diff/historical_filter.rbs

@@ -0,0 +1,75 @@
+# Generated from lib/paper_trail_diff/historical_filter.rb with RBS::Inline
+
+module PaperTrailDiff
+  # Selects roots by the values they held at any point in the window, with an
+  # explicit ceiling on version loading.
+  #
+  # A version records the state *before* its own change, so the versions in
+  # the window supply the state at its start and after every change but the
+  # last. The state after the last change lives in the first version after
+  # the window, or in the live row when nothing follows; a destroy leaves none.
+  class HistoricalFilter
+    DEFAULT_VERSION_LIMIT: ::Integer
+
+    CANDIDATE_BATCH: ::Integer
+
+    # : (untyped, predicate: untyped, time_range: TimeRange?, limit: Integer, max_versions: Integer) -> void
+    def initialize: (untyped, predicate: untyped, time_range: TimeRange?, limit: Integer, max_versions: Integer) -> void
+
+    # : (Array[String]) -> Array[String]
+    def call: (Array[String]) -> Array[String]
+
+    private
+
+    @limit: Integer
+
+    @loaded: Integer
+
+    @max_versions: Integer
+
+    @model: untyped
+
+    @predicate: untyped
+
+    @state_loader: PreparedVersionStateLoader
+
+    @time_range: TimeRange?
+
+    # : (untyped) -> untyped
+    def validate_predicate: (untyped) -> untyped
+
+    # : (untyped) -> Integer
+    def validate_budget: (untyped) -> Integer
+
+    # : (Array[String]) -> Hash[String, Array[untyped]]
+    def candidate_versions: (Array[String]) -> Hash[String, Array[untyped]]
+
+    # : (Array[untyped], untyped) -> boolish
+    def held?: (Array[untyped], untyped) -> boolish
+
+    # What each candidate held after its last change in the window.
+    # : (Array[String], Hash[String, Array[untyped]]) -> Hash[String, untyped]
+    def closing_states: (Array[String], Hash[String, Array[untyped]]) -> Hash[String, untyped]
+
+    # : (Array[String]) -> Hash[String, untyped]
+    def trailing_versions: (Array[String]) -> Hash[String, untyped]
+
+    # : (Array[String]) -> Hash[String, untyped]
+    def live_records: (Array[String]) -> Hash[String, untyped]
+
+    # : (untyped) -> boolish
+    def record_matches?: (untyped) -> boolish
+
+    # : (Integer) -> void
+    def account_versions!: (Integer) -> void
+
+    # : (untyped) -> boolish
+    def matches?: (untyped) -> boolish
+
+    # : (untyped) -> bool
+    def attributes_match?: (untyped) -> bool
+
+    # : () -> void
+    def reject_root_limit!: () -> void
+  end
+end

data/sig/generated/paper_trail_diff/historical_snapshot_store.rbs

@@ -9,8 +9,13 @@ module PaperTrailDiff
     # : (untyped, Array[untyped], ?start_at: untyped, ?end_at: untyped) -> void
     def prepare: (untyped, Array[untyped], ?start_at: untyped, ?end_at: untyped) -> void
 
-    # : (Array[untyped], Array[untyped]) -> void
-    def prepare_batch: (Array[untyped], Array[untyped]) -> void
+    # : (Array[untyped], Array[untyped], ?start_at: untyped, ?end_at: untyped) -> void
+    def prepare_batch: (Array[untyped], Array[untyped], ?start_at: untyped, ?end_at: untyped) -> void
+
+    # Missing roots have no live graph to collect. Reading their associations
+    # here would issue a query per root and seed nonexistent rows as live state.
+    # : (Array[untyped], Array[untyped], ?start_at: untyped, ?end_at: untyped) -> void
+    def prepare_deleted_batch: (Array[untyped], Array[untyped], ?start_at: untyped, ?end_at: untyped) -> void
 
     # : (untyped, untyped) -> RecordSnapshot?
     def call: (untyped, untyped) -> RecordSnapshot?
@@ -24,9 +29,15 @@ module PaperTrailDiff
     # : (untyped, habtm_version: untyped) -> untyped
     def association_reader: (untyped, habtm_version: untyped) -> untyped
 
+    # : () -> PreparedActivityIndex?
+    def activity_index: () -> PreparedActivityIndex?
+
     # : (untyped) -> [Hash[untyped, untyped], Hash[untyped, untyped]]?
     def record_transition: (untyped) -> [ Hash[untyped, untyped], Hash[untyped, untyped] ]?
 
+    # : (untyped, ?direct: bool) -> [bool, untyped]
+    def record_after: (untyped, ?direct: bool) -> [ bool, untyped ]
+
     private
 
     @live_graph_collector: LiveGraphCollector
@@ -37,6 +48,8 @@ module PaperTrailDiff
 
     @prepared_history: PreparedHistory?
 
+    @prepared_snapshotter: PreparedSnapshotBuilder
+
     @preparer: untyped
 
     @snapshots: Hash[Array[untyped], RecordSnapshot?]
@@ -51,8 +64,8 @@ module PaperTrailDiff
     # : (Array[untyped], Array[untyped]) -> Hash[Symbol, untyped]
     def batch_payload: (Array[untyped], Array[untyped]) -> Hash[Symbol, untyped]
 
-    # : (Array[untyped], Array[untyped]) -> void
-    def register_batch: (Array[untyped], Array[untyped]) -> void
+    # : (Array[untyped], Array[untyped], ?live_records: Array[untyped], ?start_at: untyped, ?end_at: untyped) -> void
+    def register_batch: (Array[untyped], Array[untyped], ?live_records: Array[untyped], ?start_at: untyped, ?end_at: untyped) -> void
 
     # : (untyped, untyped, tree: AssociationTree, normalizer: SnapshotNormalizer) -> RecordSnapshot?
     def snapshot_from_version: (untyped, untyped, tree: AssociationTree, normalizer: SnapshotNormalizer) -> RecordSnapshot?