paper_trail_diff 0.3.1 → 0.5.0

data/sig/generated/paper_trail_diff/activity_root_steps.rbs

@@ -0,0 +1,13 @@
+# Generated from lib/paper_trail_diff/activity_root_steps.rb with RBS::Inline
+
+module PaperTrailDiff
+  # Root checkpoint steps recovered from the snapshots an activity pass retained,
+  # so a combined result does not reconstruct the same boundaries twice.
+  module ActivityRootSteps
+    # : (Array[untyped], Hash[Array[untyped], RecordSnapshot?]) -> Array[Step]
+    def self?.call: (Array[untyped], Hash[Array[untyped], RecordSnapshot?]) -> Array[Step]
+
+    # : (untyped) -> Array[untyped]
+    def self?.version_key: (untyped) -> Array[untyped]
+  end
+end

data/sig/generated/paper_trail_diff/activity_snapshot_sequence.rbs

@@ -6,8 +6,8 @@ module PaperTrailDiff
     # : (snapshotter: untyped, refresher: untyped, preparer: untyped) -> void
     def initialize: (snapshotter: untyped, refresher: untyped, preparer: untyped) -> void
 
-    # : (untyped, Array[untyped], ?start_at: untyped) -> void
-    def prepare: (untyped, Array[untyped], ?start_at: untyped) -> void
+    # : (untyped, Array[untyped], ?start_at: untyped, ?end_at: untyped) -> void
+    def prepare: (untyped, Array[untyped], ?start_at: untyped, ?end_at: untyped) -> void
 
     # : (untyped, untyped) -> RecordSnapshot?
     def call: (untyped, untyped) -> RecordSnapshot?

data/sig/generated/paper_trail_diff/activity_timeline_builder.rbs

@@ -27,6 +27,9 @@ module PaperTrailDiff
 
     @tree: AssociationTree
 
+    # : () -> Array[ActivityStep]
+    def no_steps: () -> Array[ActivityStep]
+
     # : () -> Array[ActivityStep]
     def build_between_versions: () -> Array[ActivityStep]
 
@@ -42,23 +45,30 @@ module PaperTrailDiff
     # : (Array[untyped], ?range_start: untyped, ?range_end: untyped) -> Array[ActivityEvent]
     def collect_events: (Array[untyped], ?range_start: untyped, ?range_end: untyped) -> Array[ActivityEvent]
 
-    # : (Array[untyped], ?start_at: untyped) -> void
-    def prepare_history: (Array[untyped], ?start_at: untyped) -> void
+    # : (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]
 
-    # : (Array[untyped], Array[ActivityEvent], ?current: untyped) -> ActivityHistory
-    def event_history: (Array[untyped], Array[ActivityEvent], ?current: untyped) -> ActivityHistory
+    # 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]
+    def activity_steps: (ActivityHistory, Array[ActivityEvent], ActivityBoundary?, RecordSnapshot?) -> Array[ActivityStep]
 
-    # : (Array[untyped], ActivityHistory) -> Analysis
-    def build_analysis: (Array[untyped], ActivityHistory) -> Analysis
+    # A destroyed root has no later version, but its own event states that
+    # nothing follows it, so the removal can still close the timeline.
+    # : (Array[untyped]) -> ActivityBoundary?
+    def destroyed_boundary: (Array[untyped]) -> ActivityBoundary?
 
-    # : (Array[untyped], Array[RecordSnapshot?]) -> Array[Step]
-    def build_root_steps: (Array[untyped], Array[RecordSnapshot?]) -> Array[Step]
+    # : (Array[untyped], Array[ActivityEvent], ?current: untyped) -> ActivityHistory
+    def event_history: (Array[untyped], Array[ActivityEvent], ?current: untyped) -> ActivityHistory
 
-    # : (untyped) -> Array[untyped]
-    def version_key: (untyped) -> Array[untyped]
+    # 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: (Array[untyped], Array[ActivityEvent], ActivityHistory) -> Analysis
 
     # : () -> TimeActivityTimelineBuilder
     def time_builder: () -> TimeActivityTimelineBuilder

data/sig/generated/paper_trail_diff/analysis.rbs

@@ -9,6 +9,11 @@ module PaperTrailDiff
 
     attr_reader activity_timeline: Array[ActivityStep]?
 
+    # The result for a record whose requested history contains no versions,
+    # which is an empty history rather than a failed request.
+    # : () -> Analysis
+    def self.empty: () -> Analysis
+
     # : (diff: Diff, timeline: Array[Step], ?activity_timeline: Array[ActivityStep]?) -> void
     def initialize: (diff: Diff, timeline: Array[Step], ?activity_timeline: Array[ActivityStep]?) -> void
 

data/sig/generated/paper_trail_diff/analysis_batch.rbs

@@ -0,0 +1,42 @@
+# Generated from lib/paper_trail_diff/analysis_batch.rb with RBS::Inline
+
+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) -> void
+    def initialize: (Array[untyped], time_range: TimeRange?, live_loader: untyped, history_preparer: untyped, analyzer: untyped) -> void
+
+    # : () -> Hash[identity, Analysis]
+    def call: () -> Hash[identity, Analysis]
+
+    private
+
+    @analyzer: untyped
+
+    @history_preparer: untyped
+
+    @live_loader: untyped
+
+    @records: Array[untyped]
+
+    @time_range: TimeRange?
+
+    # : () -> Array[untyped]
+    def validated_records: () -> Array[untyped]
+
+    # 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], Array[untyped]]) -> void
+    def prepare: (Array[untyped], Hash[Array[String], Array[untyped]]) -> void
+
+    # A root with no versions in range has nothing to report, which is an empty
+    # result rather than a failed request.
+    # : (untyped, Array[untyped]) -> Analysis
+    def analysis_for: (untyped, Array[untyped]) -> Analysis
+  end
+end

data/sig/generated/paper_trail_diff/batch_boundary_resolver.rbs

@@ -0,0 +1,62 @@
+# 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
+  # 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: untyped
+
+    # : (untyped) -> bool
+    def self.symbolic?: (untyped) -> bool
+
+    # : (Array[[untyped, untyped]]) -> void
+    def initialize: (Array[[ untyped, untyped ]]) -> void
+
+    # 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: () -> Array[[ untyped, untyped ]]
+
+    private
+
+    @pairs: Array[[ untyped, untyped ]]
+
+    # : (untyped) -> bool
+    def symbolic?: (untyped) -> bool
+
+    # : (untyped, untyped, Hash[Array[String], Hash[Symbol, untyped]]) -> untyped
+    def resolve: (untyped, untyped, Hash[Array[String], Hash[Symbol, untyped]]) -> untyped
+
+    # 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: (untyped) -> Array[String]?
+
+    # : () -> Hash[Array[String], Hash[Symbol, untyped]]
+    def boundary_index: () -> Hash[Array[String], Hash[Symbol, untyped]]
+
+    # : () -> Array[[untyped, untyped]]
+    def anchors: () -> Array[[ untyped, untyped ]]
+
+    # : (untyped) -> [untyped, untyped]?
+    def anchor: (untyped) -> [ untyped, untyped ]?
+
+    # : (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
+
+    # : (untyped, untyped) -> Array[String]
+    def identity_key: (untyped, untyped) -> Array[String]
+  end
+end

data/sig/generated/paper_trail_diff/batched_root_analyzer.rbs

@@ -0,0 +1,28 @@
+# Generated from lib/paper_trail_diff/batched_root_analyzer.rb with RBS::Inline
+
+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
+
+    # : (untyped, Array[untyped]) -> Analysis
+    def call: (untyped, Array[untyped]) -> Analysis
+
+    private
+
+    @activity: bool
+
+    @activity_snapshotter: untyped
+
+    @preparer: untyped
+
+    @timeline_snapshotter: untyped
+
+    @tree: AssociationTree
+
+    # : (untyped, Array[untyped]) -> Analysis
+    def activity_analysis: (untyped, Array[untyped]) -> Analysis
+  end
+end

data/sig/generated/paper_trail_diff/batched_root_versions.rbs

@@ -0,0 +1,62 @@
+# Generated from lib/paper_trail_diff/batched_root_versions.rb with RBS::Inline
+
+module PaperTrailDiff
+  # Selects each root's versions for a batched range in a fixed number of
+  # queries. Only the range forms that mean the same thing for every root are
+  # supported: a shared wall-clock window, or each root's own whole history.
+  class BatchedRootVersions
+    # : (Array[untyped], time_range: TimeRange?) -> void
+    def initialize: (Array[untyped], time_range: TimeRange?) -> void
+
+    # Returns root versions per record identity, in chronological order.
+    # : () -> Hash[Array[String], Array[untyped]]
+    def call: () -> Hash[Array[String], Array[untyped]]
+
+    private
+
+    @records: Array[untyped]
+
+    @time_range: TimeRange?
+
+    # : (untyped, Array[untyped], Hash[Array[String], Array[untyped]]) -> void
+    def select_model: (untyped, Array[untyped], Hash[Array[String], Array[untyped]]) -> void
+
+    # The window's own versions plus, when it has one, the later version needed
+    # to reveal the last mutation inside it. A window closing on the root's own
+    # destruction needs no later version, because none can exist.
+    # : (Array[untyped], untyped) -> Array[untyped]
+    def versions_for: (Array[untyped], untyped) -> Array[untyped]
+
+    # : (Array[untyped]) -> bool
+    def terminal_destroy?: (Array[untyped]) -> bool
+
+    # : (untyped, Array[untyped], TimeRange?) -> Hash[String, Array[untyped]]
+    def grouped_versions: (untyped, Array[untyped], TimeRange?) -> Hash[String, Array[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
+
+    # : (untyped) -> Array[untyped]
+    def ordered: (untyped) -> Array[untyped]
+
+    # : (untyped, untyped) -> Array[String]
+    def identity: (untyped, untyped) -> Array[String]
+  end
+end

data/sig/generated/paper_trail_diff/collection_comparator.rbs

@@ -50,9 +50,16 @@ module PaperTrailDiff
     # : (Array[identity]) -> Array[identity]
     def sorted_identities: (Array[identity]) -> Array[identity]
 
+    # Identities sort by type first so that mixed id types stay comparable, then
+    # naturally within one type. Ordering by the printed form instead would put
+    # id 10 before id 2, which is deterministic but reads as unsorted wherever a
+    # result is rendered.
     # : (identity) -> Array[untyped]
     def sortable_identity: (identity) -> Array[untyped]
 
+    # : (untyped) -> Array[untyped]
+    def sortable_id: (untyped) -> Array[untyped]
+
     # : (identity) -> void
     def raise_duplicate_identity!: (identity) -> void
   end

data/sig/generated/paper_trail_diff/collection_transition.rbs

@@ -7,12 +7,15 @@ module PaperTrailDiff
 
     attr_reader after: RecordSnapshot?
 
+    # The origin is recorded by serial rather than by reference, because
+    # holding it would retain every earlier snapshot at the same path for the
+    # whole timeline.
     # : (from: AssociationSnapshot, before: RecordSnapshot?, after: RecordSnapshot?) -> void
     def initialize: (from: AssociationSnapshot, before: RecordSnapshot?, after: RecordSnapshot?) -> void
 
     # : (AssociationSnapshot) -> bool
     def from?: (AssociationSnapshot) -> bool
 
-    @from_object_id: Integer
+    @from_serial: Integer
   end
 end

data/sig/generated/paper_trail_diff/comparison_batch.rbs

@@ -23,6 +23,21 @@ module PaperTrailDiff
 
     @preparer: untyped
 
+    # : (Array[[untyped, untyped]]) -> Hash[identity, RecordSnapshot]
+    def prepared_live_snapshots: (Array[[ untyped, untyped ]]) -> Hash[identity, RecordSnapshot]
+
+    # : (untyped) -> bool
+    def symbolic?: (untyped) -> bool
+
+    # A boundary symbol that stayed unresolved means the root has no recorded
+    # history. An absent history is an empty result rather than a failed
+    # request, matching how the timeline APIs answer the same question.
+    # : (Array[[untyped, untyped]], Hash[identity, RecordSnapshot]) -> comparison_results
+    def results: (Array[[ untyped, untyped ]], Hash[identity, RecordSnapshot]) -> comparison_results
+
+    # : (untyped, untyped) -> identity
+    def entry_identity: (untyped, untyped) -> identity
+
     # : (untyped, untyped, Hash[identity, RecordSnapshot]) -> Diff
     def compare: (untyped, untyped, Hash[identity, RecordSnapshot]) -> Diff
 

data/sig/generated/paper_trail_diff/endpoint.rbs

@@ -6,6 +6,18 @@ module PaperTrailDiff
     # : (untyped, untyped) -> void
     def self?.validate_pair!: (untyped, untyped) -> void
 
+    # Two versions carry no visible cue about which is earlier, so transposing
+    # them is easy to do by accident and impossible to detect afterwards: the
+    # result is a valid inverse diff and carries no direction of its own. It is
+    # also redundant, because the two orders differ only in which side of each
+    # change is `from`. A current-record endpoint is exempt: it is self-evidently
+    # the live state, so putting it first is a deliberate reverse comparison.
+    # : (untyped, untyped) -> void
+    def self?.validate_order!: (untyped, untyped) -> void
+
+    # : (untyped, untyped) -> bool
+    def self?.reversed_versions?: (untyped, untyped) -> bool
+
     # : (untyped) -> void
     def self?.validate!: (untyped) -> void
 

data/sig/generated/paper_trail_diff/errors.rbs

@@ -13,6 +13,10 @@ module PaperTrailDiff
   class VersionMismatchError < Error
   end
 
+  # Raised when comparison endpoints are given in reverse chronological order.
+  class ReversedEndpointsError < Error
+  end
+
   # Raised when a live endpoint is not a clean, persisted ActiveRecord record.
   class InvalidEndpointError < Error
   end

data/sig/generated/paper_trail_diff/historical_association_reifier.rbs

@@ -13,7 +13,7 @@ module PaperTrailDiff
 
     @habtm_transaction_id: untyped
 
-    @reified_associations: Hash[Array[untyped], bool]
+    @reified_associations: Hash[untyped, Hash[untyped, bool]]
 
     @transaction_id: untyped
 

data/sig/generated/paper_trail_diff/historical_snapshot_store.rbs

@@ -6,10 +6,9 @@ module PaperTrailDiff
     # : (tree: AssociationTree, traversal: AssociationTraversal, normalizer: SnapshotNormalizer, preparer: untyped) -> void
     def initialize: (tree: AssociationTree, traversal: AssociationTraversal, normalizer: SnapshotNormalizer, preparer: untyped) -> void
 
-    # : (untyped, Array[untyped], ?start_at: untyped) -> void
-    def prepare: (untyped, Array[untyped], ?start_at: untyped) -> void
+    # : (untyped, Array[untyped], ?start_at: untyped, ?end_at: untyped) -> void
+    def prepare: (untyped, Array[untyped], ?start_at: untyped, ?end_at: untyped) -> void
 
-    # Prepares selected history for several roots of the same model class.
     # : (Array[untyped], Array[untyped]) -> void
     def prepare_batch: (Array[untyped], Array[untyped]) -> void
 

data/sig/generated/paper_trail_diff/paper_trail_adapter.rbs

@@ -1,7 +1,10 @@
 # Generated from lib/paper_trail_diff/paper_trail_adapter.rb with RBS::Inline
 
 module PaperTrailDiff
-  # PaperTrail/ActiveRecord boundary that produces plain record snapshots.
+  # PaperTrail/ActiveRecord boundary that produces plain record snapshots. It is
+  # deliberately the widest class here: it fronts every public operation and is
+  # the only place allowed to know about both PaperTrail and the pure engine.
+  # Reconstruction logic lives in the collaborators it wires together.
   class PaperTrailAdapter
     # : (associations: Array[String | Symbol], ignore: ignore_option, ?reload_live_endpoints: bool) -> void
     def initialize: (associations: Array[String | Symbol], ignore: ignore_option, ?reload_live_endpoints: bool) -> void
@@ -22,6 +25,10 @@ module PaperTrailDiff
     # : (untyped, from: untyped, to: untyped, within: untyped, ?activity: bool) -> Analysis
     def analyze: (untyped, from: untyped, to: untyped, within: untyped, ?activity: bool) -> Analysis
 
+    # Analyzes many roots over one shared range, preparing their history once.
+    # : (Array[untyped], within: untyped, ?activity: bool) -> Hash[identity, Analysis]
+    def analyze_many: (Array[untyped], within: untyped, ?activity: bool) -> Hash[identity, Analysis]
+
     private
 
     @activity_snapshotter: ActivitySnapshotProvider
@@ -44,6 +51,14 @@ module PaperTrailDiff
 
     @traversal: AssociationTraversal
 
+    @traversal_preparer: TraversalPreparer
+
+    # : () -> void
+    def build_snapshotters: () -> void
+
+    # : (bool) -> BatchedRootAnalyzer
+    def batched_root_analyzer: (bool) -> BatchedRootAnalyzer
+
     # : () -> HistoricalSnapshotStore
     def build_historical_store: () -> HistoricalSnapshotStore
 
@@ -73,11 +88,5 @@ module PaperTrailDiff
 
     # : (untyped) -> RecordSnapshot
     def normalize_live_snapshot: (untyped) -> RecordSnapshot
-
-    # : (untyped, historical: bool) -> void
-    def prepare_traversal!: (untyped, historical: bool) -> void
-
-    # : () -> void
-    def ensure_association_tracking!: () -> void
   end
 end

data/sig/generated/paper_trail_diff/prepared_association_reifier.rbs

@@ -19,7 +19,7 @@ module PaperTrailDiff
 
     @history: PreparedHistory
 
-    @reified: Hash[Array[untyped], bool]
+    @reified: Hash[untyped, Hash[untyped, bool]]
 
     # : (untyped, untyped) -> void
     def reify_association: (untyped, untyped) -> void

data/sig/generated/paper_trail_diff/prepared_edge_loader.rbs

@@ -64,6 +64,7 @@ module PaperTrailDiff
     # : (untyped, Array[untyped], ?owners: Hash[String, Array[untyped]]?) -> Hash[String, Hash[Symbol, untyped]]
     def group_for: (untyped, Array[untyped], ?owners: Hash[String, Array[untyped]]?) -> Hash[String, Hash[Symbol, untyped]]
 
+    # Keyed rather than scanned so that a wide edge stays linear in its width.
     # : (Array[Array[untyped]]) -> Hash[String, Array[untyped]]
     def group_ids_by_owner: (Array[Array[untyped]]) -> Hash[String, Array[untyped]]
 

data/sig/generated/paper_trail_diff/prepared_history_loader.rbs

@@ -3,8 +3,8 @@
 module PaperTrailDiff
   # Expands the explicit association tree into a request-scoped PreparedHistory.
   class PreparedHistoryLoader
-    # : (untyped, root_versions: Array[untyped], tree: AssociationTree, traversal: AssociationTraversal, ?root_ids: Array[untyped], ?start_at: untyped, ?live_records: Array[untyped]) -> void
-    def initialize: (untyped, root_versions: Array[untyped], tree: AssociationTree, traversal: AssociationTraversal, ?root_ids: Array[untyped], ?start_at: untyped, ?live_records: Array[untyped]) -> void
+    # : (untyped, root_versions: Array[untyped], tree: AssociationTree, traversal: AssociationTraversal, ?root_ids: Array[untyped], ?start_at: untyped, ?end_at: untyped, ?live_records: Array[untyped]) -> void
+    def initialize: (untyped, root_versions: Array[untyped], tree: AssociationTree, traversal: AssociationTraversal, ?root_ids: Array[untyped], ?start_at: untyped, ?end_at: untyped, ?live_records: Array[untyped]) -> void
 
     # : () -> PreparedHistory
     def call: () -> PreparedHistory

data/sig/generated/paper_trail_diff/prepared_record_index.rbs

@@ -13,6 +13,9 @@ module PaperTrailDiff
     # : (untyped, Hash[untyped, untyped]) -> PreparedRecordState
     def self.from_attributes: (untyped, Hash[untyped, untyped]) -> PreparedRecordState
 
+    # Mirrors PaperTrail's reifier, which writes attributes directly. Mass
+    # assignment would route reconstructed state through application-defined
+    # attribute writers and reify a different record than the version stored.
     # : () -> untyped
     def instantiate: () -> untyped
 
@@ -73,16 +76,25 @@ module PaperTrailDiff
 
     @states: Hash[untyped, PreparedRecordState?]
 
+    @transaction_positions: Hash[untyped, Integer]
+
     @version_positions: Hash[String, Integer]
 
     # : (Integer) -> PreparedRecordState?
     def state_after: (Integer) -> PreparedRecordState?
 
-    # : (untyped, untyped) -> bool
-    def eligible?: (untyped, untyped) -> bool
+    # A version is eligible when it is at or after the boundary, or shares the
+    # boundary's transaction. The first is monotonic over the chronological
+    # list and the second is indexed, so neither rescans a long history once
+    # per boundary.
+    # : (untyped) -> Integer?
+    def boundary_index: (untyped) -> Integer?
 
-    # : (untyped, untyped) -> bool
-    def same_transaction?: (untyped, untyped) -> bool
+    # : (untyped) -> Integer?
+    def transaction_index: (untyped) -> Integer?
+
+    # : () -> Hash[untyped, Integer]
+    def build_transaction_positions: () -> Hash[untyped, Integer]
 
     # : (untyped) -> PreparedRecordState?
     def state_for: (untyped) -> PreparedRecordState?
@@ -90,8 +102,8 @@ module PaperTrailDiff
 
   # Request-scoped scalar history loaded once per model identity.
   class PreparedRecordIndex
-    # : (untyped, ?live_records: Array[untyped]) -> void
-    def initialize: (untyped, ?live_records: Array[untyped]) -> void
+    # : (untyped, ?end_at: untyped, ?live_records: Array[untyped]) -> void
+    def initialize: (untyped, ?end_at: untyped, ?live_records: Array[untyped]) -> void
 
     # : (untyped, Array[untyped]) -> void
     def load: (untyped, Array[untyped]) -> void
@@ -110,6 +122,8 @@ module PaperTrailDiff
 
     private
 
+    @end_time: untyped
+
     @seeded_live_records: Hash[Array[String], untyped]
 
     @series: Hash[Array[String], PreparedRecordSeries]
@@ -118,6 +132,10 @@ module PaperTrailDiff
 
     @state_loader: PreparedVersionStateLoader
 
+    # Callers bound the range with either a version or a bare timestamp.
+    # : (untyped) -> untyped
+    def boundary_time: (untyped) -> untyped
+
     # : (untyped, untyped) -> Array[String]
     def identity: (untyped, untyped) -> Array[String]
 
@@ -127,9 +145,24 @@ module PaperTrailDiff
     # : (untyped, untyped, Hash[String, Array[untyped]], Hash[String, untyped]) -> void
     def add_series: (untyped, untyped, Hash[String, Array[untyped]], Hash[String, untyped]) -> void
 
+    # A PaperTrail version is a pre-change snapshot, so the state at the last
+    # selected boundary can only live in the next version after it. One
+    # trailing version per identity is retained, rather than every version
+    # recorded between the requested range and the present.
     # : (untyped, Array[untyped]) -> Array[untyped]
     def versions_for: (untyped, Array[untyped]) -> Array[untyped]
 
+    # In range, or the earliest version after it, resolved in the same query
+    # rather than with a window function or one query per identity.
+    # : (untyped) -> untyped
+    def window_condition: (untyped) -> untyped
+
+    # : (untyped) -> untyped
+    def first_after_range: (untyped) -> untyped
+
+    # : (untyped, untyped) -> untyped
+    def preceding_trailing_version: (untyped, untyped) -> untyped
+
     # : (untyped, Array[untyped]) -> Array[untyped]
     def available_live_records: (untyped, Array[untyped]) -> Array[untyped]
 

data/sig/generated/paper_trail_diff/snapshot.rbs

@@ -36,6 +36,24 @@ module PaperTrailDiff
       def index: (Array[RecordSnapshot]) -> CollectionIdentityIndex
     end
 
+    # Identifies one snapshot for internal carry-forward. A transition cannot
+    # hold its origin without retaining every earlier snapshot at that path,
+    # and `object_id` is only guaranteed unique among live objects, so Ruby may
+    # hand a collected snapshot's id to a later one.
+    class SerialSequence
+      # : () -> void
+      def initialize: () -> void
+
+      # : () -> Integer
+      def next_serial: () -> Integer
+
+      @counter: Integer
+
+      @mutex: Thread::Mutex
+    end
+
+    SERIALS: untyped
+
     # : (Symbol) -> bool
     def self.collection_kind?: (Symbol) -> bool
 
@@ -43,6 +61,8 @@ module PaperTrailDiff
 
     attr_reader records: Array[RecordSnapshot]
 
+    attr_reader serial: Integer
+
     # : (kind: Symbol, records: Array[RecordSnapshot], ?identity_index_cache: untyped, ?transition: CollectionTransition?) -> void
     def initialize: (kind: Symbol, records: Array[RecordSnapshot], ?identity_index_cache: untyped, ?transition: CollectionTransition?) -> void
 

data/sig/generated/paper_trail_diff/snapshot_normalizer.rbs

@@ -39,6 +39,8 @@ module PaperTrailDiff
 
     private
 
+    @excluded_attributes: Hash[Array[untyped], Array[String]]
+
     @ignore_policy: IgnorePolicy
 
     @pool: SnapshotPool
@@ -55,9 +57,15 @@ module PaperTrailDiff
     # : (untyped, Array[untyped], String) -> snapshot_attributes
     def normalized_attributes: (untyped, Array[untyped], String) -> snapshot_attributes
 
+    # Every input is fixed for one model class at one selected path, and the
+    # path's structural columns are recorded before its records normalize, so
+    # this is resolved once instead of per record per boundary.
     # : (untyped, Array[untyped], String) -> Array[String]
     def excluded_attributes: (untyped, Array[untyped], String) -> Array[String]
 
+    # : (untyped, Array[untyped], String) -> Array[String]
+    def build_excluded_attributes: (untyped, Array[untyped], String) -> Array[String]
+
     # : (Array[untyped]) -> Array[String]
     def relationship_columns: (Array[untyped]) -> Array[String]