paper_trail_diff 0.12.0 → 0.13.1

data/sig/generated/paper_trail_diff/nested_comparator.rbs

@@ -24,11 +24,15 @@ module PaperTrailDiff
   # one of them, so absence is its own value rather than nil.
   class NestedComparator
     # Stands in for a key that was not there at all.
-    ABSENT: untyped
+    class Absent
+      # : () -> String
+      def inspect: () -> String
 
-    def inspect: () -> untyped
+      # : () -> String
+      def to_s: () -> String
+    end
 
-    def to_s: () -> untyped
+    ABSENT: untyped
 
     # : (untyped, untyped) -> nested_changes
     def self.call: (untyped, untyped) -> nested_changes
@@ -60,14 +64,18 @@ module PaperTrailDiff
     # : (Hash[untyped, untyped], Hash[untyped, untyped], Array[String], nested_changes) -> void
     def walk: (Hash[untyped, untyped], Hash[untyped, untyped], Array[String], nested_changes) -> void
 
+    # : (Hash[untyped, untyped]) -> Hash[String, untyped]
+    def normalize_keys: (Hash[untyped, untyped]) -> Hash[String, untyped]
+
     # Two arrays are a membership change; anything else is a change to the
     # value as a whole, including an array facing something that is not one.
     # : (untyped, untyped) -> nested_change
     def change_for: (untyped, untyped) -> nested_change
 
-    # Sorted so a report reads the same twice, and stringified because a hash
-    # loaded from JSON and one built in Ruby can key the same field differently.
-    # : (Hash[untyped, untyped], Hash[untyped, untyped]) -> Array[untyped]
-    def keys: (Hash[untyped, untyped], Hash[untyped, untyped]) -> Array[untyped]
+    # Sorted so a report reads the same twice. Both hashes are already keyed by
+    # strings, because a hash loaded from JSON and one built in Ruby can key the
+    # same field differently.
+    # : (Hash[String, untyped], Hash[String, untyped]) -> Array[String]
+    def keys: (Hash[String, untyped], Hash[String, untyped]) -> Array[String]
   end
 end

data/sig/generated/paper_trail_diff/paper_trail_adapter.rbs

@@ -9,8 +9,8 @@ module PaperTrailDiff
     # The only thing a wall-clock window can close on besides a later version.
     CLOSE_ON_CURRENT: ::Symbol
 
-    # : (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
+    # : (associations: Array[String | Symbol], ignore: ignore_option, ?reload_live_endpoints: bool, ?allow_expensive: bool) -> void
+    def initialize: (associations: Array[String | Symbol], ignore: ignore_option, ?reload_live_endpoints: bool, ?allow_expensive: bool) -> void
 
     # : (untyped, untyped) -> Diff
     def compare: (untyped, untyped) -> Diff
@@ -29,18 +29,32 @@ module PaperTrailDiff
     def analyze: (untyped, from: untyped, to: untyped, within: untyped, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool, ?group: Symbol?) -> Analysis
 
     # Analyzes many roots over one shared range, preparing their history once.
-    # : (Array[untyped], within: untyped, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?) -> Hash[identity, Analysis]
-    def analyze_many: (Array[untyped], within: untyped, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?) -> Hash[identity, Analysis]
+    # : (Array[untyped], within: untyped, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool, ?group: Symbol?) -> Hash[identity, Analysis]
+    def analyze_many: (Array[untyped], within: untyped, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool, ?group: Symbol?) -> Hash[identity, Analysis]
 
     # Selects the roots from a relation before running the ordinary batch, so a
     # caller reporting on a population does not have to rediscover which of its
     # members changed. The roots the relation could not reach come back named
     # rather than dropped -- see `PaperTrailDiff.analyze_scope`.
-    # : (untyped, limit: Integer?, within: untyped, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?) -> ScopedAnalysis
-    def analyze_scope: (untyped, limit: Integer?, within: untyped, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?) -> ScopedAnalysis
+    # : (untyped, limit: Integer?, within: untyped, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool, ?group: Symbol?, ?historical_filter: untyped, ?max_filter_versions: Integer, ?include_deleted: bool) -> ScopedAnalysis
+    def analyze_scope: (untyped, limit: Integer?, within: untyped, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool, ?group: Symbol?, ?historical_filter: untyped, ?max_filter_versions: Integer, ?include_deleted: bool) -> ScopedAnalysis
 
     private
 
+    # : (Array[comparison_input], preparer: untyped) -> ComparisonBatch
+    def comparison_batch: (Array[comparison_input], preparer: untyped) -> ComparisonBatch
+
+    # : (Array[untyped]) -> Hash[identity, untyped]
+    def load_batch_endpoints: (Array[untyped]) -> Hash[identity, untyped]
+
+    # : (untyped, historical: bool) -> void
+    def prepare_batch_model: (untyped, historical: bool) -> void
+
+    @batch_safety: BatchSafety
+
+    # : (untyped, Array[Array[String]], Hash[Symbol, untyped]) -> Hash[Array[String], Analysis?]
+    def analyze_deleted: (untyped, Array[Array[String]], Hash[Symbol, untyped]) -> Hash[Array[String], Analysis?]
+
     @activity_snapshotter: ActivitySnapshotProvider
 
     @association_tree: AssociationTree
@@ -74,21 +88,31 @@ module PaperTrailDiff
     # : (untyped, untyped) -> void
     def notify_ambiguous_association_boundary: (untyped, untyped) -> void
 
-    # `close_on:` names what ends a wall-clock window, so it is meaningless for a
-    # range whose endpoints the caller already gave explicitly.
+    # A window with nothing recorded after its last change ends at the live
+    # record, which holds the state that change produced -- whether the window
+    # ended a moment ago or long before. `close_on: :current` asked for this
+    # before it was the default and is still accepted. It names what ends a
+    # wall-clock window, so it is meaningless for explicit endpoints.
     # : (Symbol?, untyped) -> bool
     def close_on_current?: (Symbol?, untyped) -> bool
 
-    # A destroyed root has no current state to close on, and its own destroy
-    # version already terminates the history.
+    # With neither a window nor endpoints, a range is the record's whole
+    # history through its current saved state; a missing endpoint takes that
+    # side of the same default.
+    # : (untyped, untyped, untyped, untyped) -> [untyped, untyped]
+    def default_range: (untyped, untyped, untyped, untyped) -> [ untyped, untyped ]
+
+    # Only a saved row has current state to close on. A destroyed root's own
+    # destroy version already terminates its history, and a reified or unsaved
+    # instance stands for a state that is not in the table.
     # : (untyped, Symbol?, untyped) -> untyped
     def live_endpoint_for: (untyped, Symbol?, untyped) -> untyped
 
     # : () -> void
     def build_snapshotters: () -> void
 
-    # : (bool) -> BatchedRootAnalyzer
-    def batched_root_analyzer: (bool) -> BatchedRootAnalyzer
+    # : (bool, within: untyped, snapshots: bool, group: Symbol?) -> BatchedRootAnalyzer
+    def batched_root_analyzer: (bool, within: untyped, snapshots: bool, group: Symbol?) -> BatchedRootAnalyzer
 
     # : () -> HistoricalSnapshotStore
     def build_historical_store: () -> HistoricalSnapshotStore
@@ -99,9 +123,6 @@ module PaperTrailDiff
     # : (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped, ?live_endpoint: untyped, ?snapshots: bool, ?group: Symbol?) -> ActivityTimelineBuilder
     def activity_builder: (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped, ?live_endpoint: untyped, ?snapshots: bool, ?group: Symbol?) -> ActivityTimelineBuilder
 
-    # : (untyped) -> void
-    def reject_live_habtm_activity!: (untyped) -> void
-
     # : (untyped) -> RecordSnapshot?
     def snapshot_for_endpoint: (untyped) -> RecordSnapshot?
 

data/sig/generated/paper_trail_diff/prepared_activity_index.rbs

@@ -0,0 +1,56 @@
+# Generated from lib/paper_trail_diff/prepared_activity_index.rb with RBS::Inline
+
+module PaperTrailDiff
+  # Shares association event discovery across every root in a prepared graph.
+  class PreparedActivityIndex
+    # : (PreparedRecordIndex, Array[untyped], start_at: untyped, end_at: untyped) -> void
+    def initialize: (PreparedRecordIndex, Array[untyped], start_at: untyped, end_at: untyped) -> void
+
+    # : (untyped, Array[untyped]) -> void
+    def register: (untyped, Array[untyped]) -> void
+
+    # : (untyped, Array[untyped]) -> Array[untyped]
+    def versions: (untyped, Array[untyped]) -> Array[untyped]
+
+    # : (untyped, Array[untyped], untyped, ActivityRange) -> Array[untyped]
+    def child_ids: (untyped, Array[untyped], untyped, ActivityRange) -> Array[untyped]
+
+    # : (untyped, Array[untyped], untyped, ?transactions: bool) -> Array[untyped]
+    def association_rows: (untyped, Array[untyped], untyped, ?transactions: bool) -> Array[untyped]
+
+    private
+
+    @children: Hash[Array[String], untyped]
+
+    @nodes: Hash[String, Array[untyped]]
+
+    @range: ActivityRange
+
+    @records: PreparedRecordIndex
+
+    @roots: Hash[Array[String], Array[untyped]]
+
+    @rows: Hash[Array[String], Hash[String, Array[untyped]]]
+
+    # : (untyped, Array[untyped], untyped, ActivityRange) -> Array[untyped]
+    def historical_ids: (untyped, Array[untyped], untyped, ActivityRange) -> Array[untyped]
+
+    # : (untyped) -> Array[untyped]
+    def node_ids: (untyped) -> Array[untyped]
+
+    # : (untyped, untyped) -> untyped
+    def child_rows: (untyped, untyped) -> untyped
+
+    # Mirrors VersionAssociationCandidateScope's before-window rule. The loaded
+    # series includes changes to other owners too, so an old membership cannot
+    # survive a later pre-window reassignment just because that owner is absent.
+    # : (untyped, Array[untyped], ActivityRange) -> bool
+    def eligible_child?: (untyped, Array[untyped], ActivityRange) -> bool
+
+    # : (untyped, untyped, bool) -> Hash[String, Array[untyped]]
+    def load_association_rows: (untyped, untyped, bool) -> Hash[String, Array[untyped]]
+
+    # : (Array[untyped], bool) -> Array[untyped]
+    def version_ids: (Array[untyped], bool) -> Array[untyped]
+  end
+end

data/sig/generated/paper_trail_diff/prepared_edge_loader.rbs

@@ -46,6 +46,9 @@ module PaperTrailDiff
     # : (untyped, Array[untyped], untyped, String) -> Hash[String, Array[untyped]]
     def historical_child_ids: (untyped, Array[untyped], untyped, String) -> Hash[String, Array[untyped]]
 
+    # : (untyped, Array[Array[untyped]]) -> Array[Array[untyped]]
+    def typed_child_ids: (untyped, Array[Array[untyped]]) -> Array[Array[untyped]]
+
     # : (untyped, Array[untyped], untyped, String) -> untyped
     def historical_child_relation: (untyped, Array[untyped], untyped, String) -> untyped
 
@@ -55,9 +58,6 @@ module PaperTrailDiff
     # : (untyped, Array[untyped], untyped, String) -> Hash[String, Array[untyped]]
     def live_child_ids: (untyped, Array[untyped], untyped, String) -> Hash[String, Array[untyped]]
 
-    # : (untyped, untyped) -> untyped
-    def target_class: (untyped, untyped) -> untyped
-
     # : (Hash[String, Hash[Symbol, untyped]], untyped, untyped) -> void
     def add_identity: (Hash[String, Hash[Symbol, untyped]], untyped, untyped) -> void
 

data/sig/generated/paper_trail_diff/prepared_history.rbs

@@ -3,10 +3,12 @@
 module PaperTrailDiff
   # Batched record states and relationship candidates for one activity range.
   class PreparedHistory
+    attr_reader activity_index: PreparedActivityIndex?
+
     DIRECT_RESOLVERS: untyped
 
-    # : (PreparedRecordIndex) -> void
-    def initialize: (PreparedRecordIndex) -> void
+    # : (PreparedRecordIndex, ?activity_index: PreparedActivityIndex?) -> void
+    def initialize: (PreparedRecordIndex, ?activity_index: PreparedActivityIndex?) -> void
 
     # : (untyped, untyped, Hash[String, Hash[Symbol, untyped]]) -> void
     def merge_edge: (untyped, untyped, Hash[String, Hash[Symbol, untyped]]) -> void
@@ -23,6 +25,12 @@ module PaperTrailDiff
     # : (untyped, untyped, untyped) -> [Hash[untyped, untyped], Hash[untyped, untyped]]?
     def record_transition: (untyped, untyped, untyped) -> [ Hash[untyped, untyped], Hash[untyped, untyped] ]?
 
+    # : (untyped, untyped, untyped, ?direct: bool) -> [bool, untyped]
+    def record_after: (untyped, untyped, untyped, ?direct: bool) -> [ bool, untyped ]
+
+    # : (PreparedRecordState, untyped, untyped) -> [bool, Array[PreparedRecordState]]
+    def snapshot_states: (PreparedRecordState, untyped, untyped) -> [ bool, Array[PreparedRecordState] ]
+
     # : (untyped, untyped, untyped, habtm_boundary: untyped) -> [bool, Array[untyped]]
     def resolve: (untyped, untyped, untyped, habtm_boundary: untyped) -> [ bool, Array[untyped] ]
 
@@ -34,14 +42,13 @@ module PaperTrailDiff
 
     @records: PreparedRecordIndex
 
+    @state_reader: PreparedStateAssociationReader
+
     @unsupported: Hash[Array[String], bool]
 
     # : (untyped, untyped) -> bool
     def supported?: (untyped, untyped) -> bool
 
-    # : (untyped) -> bool
-    def default_scoped?: (untyped) -> bool
-
     # : (untyped, untyped, untyped, untyped) -> Array[untyped]?
     def direct_records: (untyped, untyped, untyped, untyped) -> Array[untyped]?
 
@@ -51,9 +58,6 @@ module PaperTrailDiff
     # : (untyped, untyped, untyped, untyped) -> Array[untyped]
     def resolve_children: (untyped, untyped, untyped, untyped) -> Array[untyped]
 
-    # : (untyped, untyped, untyped, untyped) -> Array[untyped]?
-    def resolve_habtm: (untyped, untyped, untyped, untyped) -> Array[untyped]?
-
     # : (untyped, untyped, untyped) -> Array[untyped]?
     def belongs_to_records: (untyped, untyped, untyped) -> Array[untyped]?
 
@@ -78,9 +82,6 @@ module PaperTrailDiff
     # : (untyped) -> String?
     def scalar_foreign_key: (untyped) -> String?
 
-    # : (untyped, untyped) -> untyped
-    def belongs_to_class: (untyped, untyped) -> untyped
-
     # : (untyped, untyped) -> Array[String]
     def owner_types: (untyped, untyped) -> Array[String]
 
@@ -92,8 +93,5 @@ module PaperTrailDiff
 
     # : (untyped, untyped) -> Array[String]
     def edge_key: (untyped, untyped) -> Array[String]
-
-    # : (Hash[String, Hash[Symbol, untyped]], Hash[String, Hash[Symbol, untyped]]) -> Hash[String, Hash[Symbol, untyped]]
-    def merge_groups: (Hash[String, Hash[Symbol, untyped]], Hash[String, Hash[Symbol, untyped]]) -> Hash[String, Hash[Symbol, untyped]]
   end
 end

data/sig/generated/paper_trail_diff/prepared_history_loader.rbs

@@ -23,6 +23,8 @@ module PaperTrailDiff
 
     @root_ids: Array[untyped]
 
+    @root_versions: Array[untyped]
+
     @traversal: AssociationTraversal
 
     @tree: AssociationTree

data/sig/generated/paper_trail_diff/prepared_record_index.rbs

@@ -23,6 +23,12 @@ module PaperTrailDiff
 
     # : (untyped, Hash[untyped, untyped]) -> void
     def initialize_attributes: (untyped, Hash[untyped, untyped]) -> void
+
+    # A live fallback and a version decoded from history must agree on what
+    # the stored history could represent, or the gap between them reads as a
+    # change.
+    # : (untyped, Hash[untyped, untyped]) -> Hash[untyped, untyped]
+    def stored_attributes: (untyped, Hash[untyped, untyped]) -> Hash[untyped, untyped]
   end
 
   # Extracts a version's scalar state without constructing a disposable AR object.
@@ -62,9 +68,19 @@ module PaperTrailDiff
     # : (untyped) -> untyped
     def record_before: (untyped) -> untyped
 
+    # : (untyped) -> PreparedRecordState?
+    def state_before: (untyped) -> PreparedRecordState?
+
+    # A handled nil is known absence, not permission to query the current row.
+    # : (untyped, ?direct: bool) -> [bool, untyped]
+    def record_after: (untyped, ?direct: bool) -> [ bool, untyped ]
+
     # : () -> Array[untyped]
     def records: () -> Array[untyped]
 
+    # : () -> Array[PreparedRecordState]
+    def states: () -> Array[PreparedRecordState]
+
     # : (untyped) -> [Hash[untyped, untyped], Hash[untyped, untyped]]?
     def transition: (untyped) -> [ Hash[untyped, untyped], Hash[untyped, untyped] ]?
 
@@ -87,6 +103,11 @@ module PaperTrailDiff
     # 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.
+    #
+    # "At or after" is decided by the version order rather than the timestamp
+    # alone. A version written in the same instant as the boundary but before
+    # it already took effect there; reading its pre-change state would put the
+    # boundary on the wrong side of a change it follows.
     # : (untyped) -> Integer?
     def boundary_index: (untyped) -> Integer?
 
@@ -108,20 +129,42 @@ module PaperTrailDiff
     # : (untyped, Array[untyped]) -> void
     def load: (untyped, Array[untyped]) -> void
 
+    # : (untyped, Array[untyped], Array[untyped]) -> void
+    def seed: (untyped, Array[untyped], Array[untyped]) -> void
+
     # : (untyped, untyped, untyped) -> untyped
     def record_before: (untyped, untyped, untyped) -> untyped
 
+    # : (untyped, untyped, untyped) -> [bool, PreparedRecordState?]
+    def snapshot_state_before: (untyped, untyped, untyped) -> [ bool, PreparedRecordState? ]
+
     # : (untyped, untyped, untyped) -> [Hash[untyped, untyped], Hash[untyped, untyped]]?
     def transition: (untyped, untyped, untyped) -> [ Hash[untyped, untyped], Hash[untyped, untyped] ]?
 
+    # : (untyped, untyped, untyped, ?direct: bool) -> [bool, untyped]
+    def record_after: (untyped, untyped, untyped, ?direct: bool) -> [ bool, untyped ]
+
     # : (untyped, Array[untyped]) -> Array[untyped]
     def records_for: (untyped, Array[untyped]) -> Array[untyped]
 
+    # : (untyped, Array[untyped], String) -> Array[untyped]
+    def attribute_values_for: (untyped, Array[untyped], String) -> Array[untyped]
+
+    # : (untyped, untyped) -> Array[untyped]
+    def versions_for_id: (untyped, untyped) -> Array[untyped]
+
     # : (untyped, untyped) -> bool
     def loaded?: (untyped, untyped) -> bool
 
     private
 
+    # : (untyped, String) -> bool
+    def generated_reader?: (untyped, String) -> bool
+
+    @direct_loader: DirectRecordStateLoader
+
+    @direct_states: Hash[PreparedRecordState, PreparedRecordState?]
+
     @end_time: untyped
 
     @seeded_live_records: Hash[Array[String], untyped]
@@ -157,12 +200,6 @@ module PaperTrailDiff
     # : (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/prepared_snapshot_builder.rbs

@@ -0,0 +1,24 @@
+# Generated from lib/paper_trail_diff/prepared_snapshot_builder.rb with RBS::Inline
+
+module PaperTrailDiff
+  # Normalizes supported recorded graphs without historical ActiveRecord instances.
+  class PreparedSnapshotBuilder
+    # : (AssociationTraversal) -> void
+    def initialize: (AssociationTraversal) -> void
+
+    # : (untyped, untyped, tree: AssociationTree, normalizer: SnapshotNormalizer, history: PreparedHistory?) -> [bool, RecordSnapshot?]
+    def call: (untyped, untyped, tree: AssociationTree, normalizer: SnapshotNormalizer, history: PreparedHistory?) -> [ bool, RecordSnapshot? ]
+
+    private
+
+    @loader: DirectRecordStateLoader
+
+    @traversal: AssociationTraversal
+
+    # : (PreparedRecordState, untyped, AssociationTree, SnapshotNormalizer, PreparedHistory?, path: String, ?incoming: untyped) -> [bool, RecordSnapshot?]
+    def build: (PreparedRecordState, untyped, AssociationTree, SnapshotNormalizer, PreparedHistory?, path: String, ?incoming: untyped) -> [ bool, RecordSnapshot? ]
+
+    # : (PreparedRecordState, untyped, untyped, AssociationTree, SnapshotNormalizer, PreparedHistory, String) -> [bool, AssociationSnapshot?]
+    def association: (PreparedRecordState, untyped, untyped, AssociationTree, SnapshotNormalizer, PreparedHistory, String) -> [ bool, AssociationSnapshot? ]
+  end
+end

data/sig/generated/paper_trail_diff/prepared_state_association_reader.rbs

@@ -0,0 +1,33 @@
+# Generated from lib/paper_trail_diff/prepared_state_association_reader.rb with RBS::Inline
+
+module PaperTrailDiff
+  # Reads plain direct edges without creating AR records for their members.
+  class PreparedStateAssociationReader
+    # : (PreparedRecordIndex, untyped) -> void
+    def initialize: (PreparedRecordIndex, untyped) -> void
+
+    # : (PreparedRecordState, untyped, untyped) -> [bool, Array[PreparedRecordState]]
+    def call: (PreparedRecordState, untyped, untyped) -> [ bool, Array[PreparedRecordState] ]
+
+    private
+
+    @edges: untyped
+
+    @records: PreparedRecordIndex
+
+    # : (untyped) -> bool
+    def supported?: (untyped) -> bool
+
+    # : (PreparedRecordState, untyped, untyped) -> [bool, Array[PreparedRecordState]]
+    def children: (PreparedRecordState, untyped, untyped) -> [ bool, Array[PreparedRecordState] ]
+
+    # : (untyped, PreparedRecordState) -> Array[untyped]
+    def ids_for: (untyped, PreparedRecordState) -> Array[untyped]
+
+    # : (PreparedRecordState, PreparedRecordState, untyped) -> bool
+    def member?: (PreparedRecordState, PreparedRecordState, untyped) -> bool
+
+    # : (PreparedRecordState, untyped, untyped) -> bool
+    def matching_type?: (PreparedRecordState, untyped, untyped) -> bool
+  end
+end

data/sig/generated/paper_trail_diff/root_version_plan.rbs

@@ -32,6 +32,11 @@ module PaperTrailDiff
     # version present only to reveal what the last of them produced.
     attr_reader mutations: Array[untyped]
 
+    # Whether a wall-clock window closes on the root's own destruction. Its
+    # final state is then the absence the destroy left, just as a window
+    # closing on current state ends at the live record.
+    attr_reader closes_on_destroy: bool
+
     # Adjacent boundaries, which is what an unfiltered range reports.
     # : (Array[untyped], ?context_version: untyped) -> RootVersionPlan
     def self.contiguous: (Array[untyped], ?context_version: untyped) -> RootVersionPlan
@@ -39,12 +44,20 @@ module PaperTrailDiff
     # : () -> RootVersionPlan
     def self.empty: () -> RootVersionPlan
 
-    # : (versions: Array[untyped], steps: Array[[untyped, untyped]], ?context_version: untyped, ?reconstruction_versions: Array[untyped]?, ?mutations: Array[untyped]?, ?closing_record: untyped) -> void
-    def initialize: (versions: Array[untyped], steps: Array[[ untyped, untyped ]], ?context_version: untyped, ?reconstruction_versions: Array[untyped]?, ?mutations: Array[untyped]?, ?closing_record: untyped) -> void
+    # No root version to report or replay: only descendants moved, and the
+    # live record is the root's state throughout.
+    # : (untyped) -> RootVersionPlan
+    def self.closing_on: (untyped) -> RootVersionPlan
+
+    # : (versions: Array[untyped], steps: Array[[untyped, untyped]], ?context_version: untyped, ?reconstruction_versions: Array[untyped]?, ?mutations: Array[untyped]?, ?closing_record: untyped, ?closes_on_destroy: bool) -> void
+    def initialize: (versions: Array[untyped], steps: Array[[ untyped, untyped ]], ?context_version: untyped, ?reconstruction_versions: Array[untyped]?, ?mutations: Array[untyped]?, ?closing_record: untyped, ?closes_on_destroy: bool) -> void
 
     # : () -> bool
     def empty?: () -> bool
 
+    # : () -> RootVersionPlan
+    def closing_on_destroy: () -> RootVersionPlan
+
     # What the range's final state is read from, which is the live record when
     # the window closes on current state and the last version otherwise.
     # : () -> untyped
@@ -60,6 +73,13 @@ module PaperTrailDiff
     # : () -> Array[untyped]
     def default_mutations: () -> Array[untyped]
 
+    # A Set only makes the lookup in `mutation?` fast; an Array would answer the
+    # same, which is why mutant leaves this alone.
+    # mutant:disable
+    # : (Array[untyped]) -> Set[Array[untyped]]
+    def key_set: (Array[untyped]) -> Set[Array[untyped]]
+
+    # By class name, so a version still matches after its class is reloaded.
     # : (untyped) -> Array[untyped]
     def key: (untyped) -> Array[untyped]
   end

data/sig/generated/paper_trail_diff/root_version_selection.rbs

@@ -44,7 +44,9 @@ module PaperTrailDiff
     def contiguous_plan: (untyped) -> RootVersionPlan
 
     # An activity view still needs a root to reconstruct from even when no root
-    # version falls inside the window, because descendants may have moved.
+    # version falls inside the window, because descendants may have moved. With
+    # no later version, a window closing on current state reads the root from
+    # the live record, which is then its state throughout the window.
     # : () -> RootVersionPlan
     def without_selection: () -> RootVersionPlan
 
@@ -83,6 +85,11 @@ module PaperTrailDiff
     # : () -> untyped
     def revealing_version: () -> untyped
 
+    # A window with nothing after its last selected mutation can only close on
+    # that mutation being the record's destruction.
+    # : (untyped) -> bool
+    def closes_on_destroy?: (untyped) -> bool
+
     # A range closing on the record's own destruction needs no later version:
     # nothing can follow it, so demanding one would reject the range forever.
     # : () -> bool

data/sig/generated/paper_trail_diff/scoped_analysis.rbs

@@ -16,9 +16,21 @@ module PaperTrailDiff
 
     attr_reader unreachable: Array[Array[String]]
 
-    # : (analyses: Hash[Array[String], Analysis], unreachable: Array[Array[String]]) -> void
-    def initialize: (analyses: Hash[Array[String], Analysis], unreachable: Array[Array[String]]) -> void
+    # The live records the selection loaded, in the order it loaded them. The
+    # gem already has them; withholding them only makes a caller query the same
+    # rows again to attach its own presentation data. A destroyed root has no
+    # record to hand back, so `roots` and `unreachable` stay complementary.
+    attr_reader roots: Array[untyped]
 
+    # Requested missing-root analyses, kept separate because live SQL conditions
+    # cannot prove which deleted rows matched. nil means no destroy history.
+    attr_reader deleted: Hash[Array[String], Analysis?]
+
+    # : (analyses: Hash[Array[String], Analysis], unreachable: Array[Array[String]], ?roots: Array[untyped], ?deleted: Hash[Array[String], Analysis?]) -> void
+    def initialize: (analyses: Hash[Array[String], Analysis], unreachable: Array[Array[String]], ?roots: Array[untyped], ?deleted: Hash[Array[String], Analysis?]) -> void
+
+    # Two elements, not three: `roots` is reached by name so that existing
+    # destructuring keeps working.
     # : () -> [Hash[Array[String], Analysis], Array[Array[String]]]
     def to_ary: () -> [ Hash[Array[String], Analysis], Array[Array[String]] ]
   end

data/sig/generated/paper_trail_diff/scoped_analysis_builder.rbs

@@ -0,0 +1,22 @@
+# Generated from lib/paper_trail_diff/scoped_analysis_builder.rb with RBS::Inline
+
+module PaperTrailDiff
+  # Selects both populations and checks their shared ceiling before analysis.
+  class ScopedAnalysisBuilder
+    # : (untyped, limit: Integer?, within: untyped, historical_filter: untyped, max_filter_versions: Integer, include_deleted: bool, analyzer: untyped, deleted_analyzer: untyped) -> void
+    def initialize: (untyped, limit: Integer?, within: untyped, historical_filter: untyped, max_filter_versions: Integer, include_deleted: bool, analyzer: untyped, deleted_analyzer: untyped) -> void
+
+    # : () -> ScopedAnalysis
+    def call: () -> ScopedAnalysis
+
+    @analyzer: untyped
+
+    @deleted_analyzer: untyped
+
+    @include_deleted: bool
+
+    @limit: Integer
+
+    @selection: ScopedRootSelection
+  end
+end