paper_trail_diff 0.14.0 → 0.15.0

data/sig/generated/paper_trail_diff/historical_snapshot_store.rbs

@@ -1,13 +1,16 @@
 # Generated from lib/paper_trail_diff/historical_snapshot_store.rb with RBS::Inline
 
 module PaperTrailDiff
-  # Reconstructs and caches immutable historical snapshots for one adapter configuration.
+  # Reconstructs and caches immutable historical snapshots for one adapter
+  # configuration. It keeps the histories batches prepare, by root version;
+  # one prepared for a single root goes back to the caller, who passes it to
+  # every read for that root.
   class HistoricalSnapshotStore
     # : (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, ?end_at: untyped) -> void
-    def prepare: (untyped, Array[untyped], ?start_at: untyped, ?end_at: untyped) -> void
+    # : (untyped, Array[untyped], ?start_at: untyped, ?end_at: untyped) -> PreparedHistory?
+    def prepare: (untyped, Array[untyped], ?start_at: untyped, ?end_at: untyped) -> PreparedHistory?
 
     # : (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
@@ -18,37 +21,29 @@ module PaperTrailDiff
     # : (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?
+    # `history` is the one `prepare` returned for this root, if any.
+    # : (untyped, untyped, ?history: PreparedHistory?) -> RecordSnapshot?
+    def call: (untyped, untyped, ?history: PreparedHistory?) -> RecordSnapshot?
 
-    # : (untyped, untyped) -> RecordSnapshot?
-    def uncached: (untyped, untyped) -> RecordSnapshot?
+    # : (untyped, untyped, ?history: PreparedHistory?) -> RecordSnapshot?
+    def uncached: (untyped, untyped, ?history: PreparedHistory?) -> RecordSnapshot?
 
-    # : (untyped, untyped, tree: AssociationTree, normalizer: SnapshotNormalizer) -> RecordSnapshot?
-    def custom: (untyped, untyped, tree: AssociationTree, normalizer: SnapshotNormalizer) -> RecordSnapshot?
+    # : (untyped, untyped, tree: AssociationTree, normalizer: SnapshotNormalizer, ?history: PreparedHistory?) -> RecordSnapshot?
+    def custom: (untyped, untyped, tree: AssociationTree, normalizer: SnapshotNormalizer, ?history: PreparedHistory?) -> RecordSnapshot?
 
-    # : (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 ]
+    # : (untyped, habtm_version: untyped, ?history: PreparedHistory?) -> untyped
+    def association_reader: (untyped, habtm_version: untyped, ?history: PreparedHistory?) -> untyped
 
     private
 
     @live_graph_collector: LiveGraphCollector
 
+    @live_roots: Hash[identity, untyped]
+
     @normalizer: SnapshotNormalizer
 
     @prepared_histories: Hash[Array[untyped], PreparedHistory]
 
-    @prepared_history: PreparedHistory?
-
     @prepared_snapshotter: PreparedSnapshotBuilder
 
     @preparer: untyped
@@ -59,6 +54,10 @@ module PaperTrailDiff
 
     @tree: AssociationTree
 
+    # A batch's history for the version wins over the one a caller passes.
+    # : (untyped, PreparedHistory?) -> PreparedHistory?
+    def history_for: (untyped, PreparedHistory?) -> PreparedHistory?
+
     # : (untyped) -> Array[untyped]
     def context_key: (untyped) -> Array[untyped]
 
@@ -68,14 +67,20 @@ module PaperTrailDiff
     # : (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?
+    # : (untyped, untyped, tree: AssociationTree, normalizer: SnapshotNormalizer, history: PreparedHistory?) -> RecordSnapshot?
+    def snapshot_from_version: (untyped, untyped, tree: AssociationTree, normalizer: SnapshotNormalizer, history: PreparedHistory?) -> RecordSnapshot?
+
+    # : (untyped, untyped, tree: AssociationTree, normalizer: SnapshotNormalizer, history: PreparedHistory?) -> RecordSnapshot?
+    def snapshot_from_live_root: (untyped, untyped, tree: AssociationTree, normalizer: SnapshotNormalizer, history: PreparedHistory?) -> RecordSnapshot?
 
-    # : (untyped, untyped, tree: AssociationTree, normalizer: SnapshotNormalizer) -> RecordSnapshot?
-    def snapshot_from_live_root: (untyped, untyped, tree: AssociationTree, normalizer: SnapshotNormalizer) -> RecordSnapshot?
+    # Rebuilding a version's associations writes them onto the record, so each
+    # snapshot gets its own copy of a batch's loaded row, built from the row's
+    # stored values without a query.
+    # : (untyped) -> untyped
+    def live_root: (untyped) -> untyped
 
-    # : (untyped, untyped, tree: AssociationTree, normalizer: SnapshotNormalizer, habtm_version: untyped) -> RecordSnapshot?
-    def normalize: (untyped, untyped, tree: AssociationTree, normalizer: SnapshotNormalizer, habtm_version: untyped) -> RecordSnapshot?
+    # : (untyped, untyped, tree: AssociationTree, normalizer: SnapshotNormalizer, habtm_version: untyped, history: PreparedHistory?) -> RecordSnapshot?
+    def normalize: (untyped, untyped, tree: AssociationTree, normalizer: SnapshotNormalizer, habtm_version: untyped, history: PreparedHistory?) -> RecordSnapshot?
 
     # : (untyped, untyped) -> Array[untyped]
     def snapshot_key: (untyped, untyped) -> Array[untyped]

data/sig/generated/paper_trail_diff/live_endpoint_batch_loader.rbs

@@ -39,21 +39,6 @@ module PaperTrailDiff
     # : () -> untyped
     def active_record_preloader: () -> untyped
 
-    # The preloader applies a limit or offset to all owners' records at once,
-    # not to each owner's, so such an association is loaded per record. A
-    # has_one is no exception. Through a part with a limit, an offset or a
-    # has_one cut, the preloader keeps what the part alone would load, while
-    # the through's own query keeps the part's conditions only.
-    # : (untyped, untyped) -> bool
-    def batch_safe?: (untyped, untyped) -> bool
-
-    # : (untyped) -> bool
-    def cut_part?: (untyped) -> bool
-
-    # Every part a through passes, at any depth.
-    # : (untyped) -> Array[untyped]
-    def through_parts: (untyped) -> Array[untyped]
-
     # : (Array[untyped], untyped) -> Array[untyped]
     def load_individually: (Array[untyped], untyped) -> Array[untyped]
 

data/sig/generated/paper_trail_diff/nested_comparator.rbs

@@ -43,6 +43,7 @@ module PaperTrailDiff
     # Returns the changed paths, or an empty hash when the pair is not two
     # structures this can look inside. An empty result therefore means "nothing
     # to report at this depth", and the caller still has the whole-value change.
+    # Two arrays at the top are one membership change, at the empty path.
     # : () -> nested_changes
     def call: () -> nested_changes
 
@@ -52,14 +53,16 @@ module PaperTrailDiff
 
     @to_value: untyped
 
-    # Both sides have to be readable as a Hash for a nested answer to mean
-    # anything. A column that held text on one side and JSON on the other
-    # changed wholesale, and saying so is the accurate report.
-    # : () -> [Hash[untyped, untyped]?, Hash[untyped, untyped]?]
-    def structures: () -> [ Hash[untyped, untyped]?, Hash[untyped, untyped]? ]
+    # Both sides have to be readable as the same kind of structure for a
+    # nested answer to mean anything. A column that held text on one side and
+    # JSON on the other changed wholesale, and saying so is the accurate report.
+    # : () -> [untyped, untyped]
+    def structures: () -> [ untyped, untyped ]
 
-    # : (untyped) -> Hash[untyped, untyped]?
-    def structure: (untyped) -> Hash[untyped, untyped]?
+    # A string is read as JSON; anything else, or JSON that is neither an
+    # object nor an array, is left for #call to decline.
+    # : (untyped) -> untyped
+    def structure: (untyped) -> untyped
 
     # : (Hash[untyped, untyped], Hash[untyped, untyped], Array[String], nested_changes) -> void
     def walk: (Hash[untyped, untyped], Hash[untyped, untyped], Array[String], nested_changes) -> void

data/sig/generated/paper_trail_diff/paper_trail_adapter.rbs

@@ -6,11 +6,10 @@ module PaperTrailDiff
   # the only place allowed to know about both PaperTrail and the pure engine.
   # Reconstruction logic lives in the collaborators it wires together.
   class PaperTrailAdapter
-    # 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, ?allow_expensive: bool) -> void
-    def initialize: (associations: Array[String | Symbol], ignore: ignore_option, ?reload_live_endpoints: bool, ?allow_expensive: bool) -> void
+    # `recorded_changes:` reads what each activity boundary's version recorded.
+    # `allow_approximate:` accepts association paths read with PT-AT.
+    # : (associations: association_option, ignore: ignore_option, ?reload_live_endpoints: bool, ?recorded_changes: bool, ?allow_approximate: bool) -> void
+    def initialize: (associations: association_option, ignore: ignore_option, ?reload_live_endpoints: bool, ?recorded_changes: bool, ?allow_approximate: bool) -> void
 
     # : (untyped, untyped) -> Diff
     def compare: (untyped, untyped) -> Diff
@@ -19,44 +18,49 @@ module PaperTrailDiff
     # : (Array[comparison_input]) -> comparison_results
     def compare_many: (Array[comparison_input]) -> comparison_results
 
-    # : (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped, ?close_on: Symbol?) -> Array[Step]
-    def timeline: (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped, ?close_on: Symbol?) -> Array[Step]
+    # : (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped) -> Array[Step]
+    def timeline: (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped) -> Array[Step]
 
-    # : (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool, ?group: Symbol?) -> Array[ActivityStep]
-    def activity_timeline: (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool, ?group: Symbol?) -> Array[ActivityStep]
+    # : (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped, ?snapshots: bool, ?group: Symbol?) -> Array[ActivityStep]
+    def activity_timeline: (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped, ?snapshots: bool, ?group: Symbol?) -> Array[ActivityStep]
 
-    # : (untyped, from: untyped, to: untyped, within: untyped, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool, ?group: Symbol?) -> Analysis
-    def analyze: (untyped, from: untyped, to: untyped, within: untyped, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool, ?group: Symbol?) -> Analysis
+    # : (untyped, from: untyped, to: untyped, within: untyped, ?activity: bool, ?version_scope: untyped, ?snapshots: bool, ?group: Symbol?) -> Analysis
+    def analyze: (untyped, from: untyped, to: untyped, within: untyped, ?activity: bool, ?version_scope: untyped, ?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?, ?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]
+    # : (Array[untyped], within: untyped, ?activity: bool, ?version_scope: untyped, ?snapshots: bool, ?group: Symbol?) -> Hash[identity, Analysis]
+    def analyze_many: (Array[untyped], within: untyped, ?activity: bool, ?version_scope: untyped, ?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?, ?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
+    # : (untyped, limit: Integer?, within: untyped, ?activity: bool, ?version_scope: untyped, ?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, ?snapshots: bool, ?group: Symbol?, ?historical_filter: untyped, ?max_filter_versions: Integer, ?include_deleted: bool) -> ScopedAnalysis
 
     private
 
-    # Selecting by activity reads association history, so it must be available
-    # before the first selection query rather than once analysis starts.
-    # : (untyped, bool) -> void
-    def check_scope: (untyped, bool) -> void
+    # : (bool, bool, Symbol?) -> ActivityView
+    def activity_view: (bool, bool, Symbol?) -> ActivityView
+
+    # : (untyped) -> Hash[Symbol, untyped]
+    def model_payload: (untyped) -> Hash[Symbol, untyped]
+
+    # : (Array[untyped], within: untyped, activity: bool, version_scope: untyped, view: ActivityView) -> Hash[identity, Analysis]
+    def analyze_batch: (Array[untyped], within: untyped, activity: bool, version_scope: untyped, view: ActivityView) -> Hash[identity, Analysis]
+
+    # Analysis reads association history, so a request it would refuse is
+    # refused before the first selection query rather than once analysis starts.
+    # : (untyped) -> void
+    def check_scope: (untyped) -> void
 
     # : (Array[comparison_input], preparer: untyped) -> ComparisonBatch
     def comparison_batch: (Array[comparison_input], preparer: untyped) -> ComparisonBatch
 
+    # Refused before the current records load, rather than once analysis starts.
     # : (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?]
 
@@ -74,6 +78,8 @@ module PaperTrailDiff
 
     @normalizer: SnapshotNormalizer
 
+    @recorded: IgnorePolicy?
+
     @snapshot_pool: SnapshotPool
 
     @timeline_snapshotter: TimelineSnapshotProvider
@@ -82,24 +88,19 @@ module PaperTrailDiff
 
     @traversal_preparer: TraversalPreparer
 
-    # : (untyped, from: untyped, to: untyped, within: untyped, version_scope: untyped, live_endpoint: untyped, ?snapshots: bool, ?group: Symbol?) -> Analysis
-    def analyze_activity: (untyped, from: untyped, to: untyped, within: untyped, version_scope: untyped, live_endpoint: untyped, ?snapshots: bool, ?group: Symbol?) -> Analysis
-
-    # Association membership is resolved by timestamp, so endpoints sharing one
-    # cannot be told apart and any association change between them is invisible.
-    # The result may still be correct -- nothing associated may have changed --
-    # and the gem cannot tell which, since not seeing the change is the symptom.
-    # So it reports the condition and leaves the judgement to the application.
+    # The result may still be correct -- nothing the path reaches may have
+    # changed -- and the gem cannot tell which, since not seeing the change is
+    # the symptom. So it reports the condition and leaves the judgement to the
+    # application.
     # : (untyped, untyped) -> void
     def notify_ambiguous_association_boundary: (untyped, untyped) -> void
 
-    # 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
+    # Loaded history orders two versions that share a timestamp by id, but
+    # PT-AT places association changes by timestamp alone, so only a path it
+    # reads can lose a change between them. A request the preparer refuses
+    # raises here, before anything is reported.
+    # : (untyped, untyped) -> bool
+    def ambiguous_association_boundary?: (untyped, untyped) -> bool
 
     # With neither a window nor endpoints, a range is the record's whole
     # history through its current saved state; a missing endpoint takes that
@@ -107,26 +108,30 @@ module PaperTrailDiff
     # : (untyped, untyped, untyped, untyped) -> [untyped, untyped]
     def default_range: (untyped, untyped, untyped, untyped) -> [ untyped, untyped ]
 
+    # 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. Explicit endpoints name their own end.
     # 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
+    # : (untyped, untyped) -> untyped
+    def live_endpoint_for: (untyped, untyped) -> untyped
 
     # : () -> void
     def build_snapshotters: () -> void
 
-    # : (bool, within: untyped, snapshots: bool, group: Symbol?) -> BatchedRootAnalyzer
-    def batched_root_analyzer: (bool, within: untyped, snapshots: bool, group: Symbol?) -> BatchedRootAnalyzer
+    # : (bool, within: untyped, view: ActivityView) -> BatchedRootAnalyzer
+    def batched_root_analyzer: (bool, within: untyped, view: ActivityView) -> BatchedRootAnalyzer
 
     # : () -> HistoricalSnapshotStore
     def build_historical_store: () -> HistoricalSnapshotStore
 
-    # : () -> ActivitySnapshotProvider
-    def build_activity_snapshotter: () -> ActivitySnapshotProvider
+    # Refreshes one root's snapshots, reading with the history prepared for it.
+    # : (PreparedActivitySnapshots) -> BranchSnapshotRefresher
+    def branch_refresher: (PreparedActivitySnapshots) -> BranchSnapshotRefresher
 
-    # : (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, from: untyped, to: untyped, within: untyped, version_scope: untyped, live_endpoint: untyped, view: ActivityView) -> ActivityTimelineBuilder
+    def activity_builder: (untyped, from: untyped, to: untyped, within: untyped, version_scope: untyped, live_endpoint: untyped, view: ActivityView) -> ActivityTimelineBuilder
 
     # : (untyped) -> RecordSnapshot?
     def snapshot_for_endpoint: (untyped) -> RecordSnapshot?
@@ -134,11 +139,8 @@ module PaperTrailDiff
     # : (untyped) -> RecordSnapshot?
     def historical_snapshot: (untyped) -> RecordSnapshot?
 
-    # : (untyped) -> RecordSnapshot?
-    def uncached_historical_snapshot: (untyped) -> RecordSnapshot?
-
-    # : (untyped, untyped) -> RecordSnapshot?
-    def snapshot_at: (untyped, untyped) -> RecordSnapshot?
+    # : (untyped, untyped, ?history: PreparedHistory?) -> RecordSnapshot?
+    def snapshot_at: (untyped, untyped, ?history: PreparedHistory?) -> RecordSnapshot?
 
     # : (untyped) -> RecordSnapshot
     def live_snapshot: (untyped) -> RecordSnapshot

data/sig/generated/paper_trail_diff/preloaded_endpoint_batch_loader.rbs

@@ -1,7 +1,8 @@
 # Generated from lib/paper_trail_diff/preloaded_endpoint_batch_loader.rb with RBS::Inline
 
 module PaperTrailDiff
-  # Validates and reuses caller-owned live records without issuing association queries.
+  # Validates and reuses caller-owned live records, reading again only the
+  # associations a preload of many records cannot have loaded correctly.
   class PreloadedEndpointBatchLoader
     # : (tree: AssociationTree, traversal: AssociationTraversal) -> void
     def initialize: (tree: AssociationTree, traversal: AssociationTraversal) -> void
@@ -20,5 +21,12 @@ module PaperTrailDiff
 
     # : (untyped, AssociationTree, String, untyped) -> void
     def validate_association: (untyped, AssociationTree, String, untyped) -> void
+
+    # Preloading many records applies a limit or offset to all of them
+    # together, so what a caller preloaded cannot be trusted: one record keeps
+    # another's share, or none. Such an association is read again for each
+    # record, as reloading reads it.
+    # : (untyped) -> void
+    def read_alone: (untyped) -> void
   end
 end

data/sig/generated/paper_trail_diff/prepared_history.rbs

@@ -74,6 +74,11 @@ module PaperTrailDiff
     # : (Hash[Symbol, untyped], untyped) -> Array[untyped]
     def child_ids_for: (Hash[Symbol, untyped], untyped) -> Array[untyped]
 
+    # PT-AT records a checkpoint's membership as it is when the checkpoint is
+    # saved, so a tag attached earlier in the checkpoint's own transaction is a
+    # member there, unlike other associations, which a version reads as they
+    # were before its transaction. A member created in that transaction has no
+    # earlier state, so it is read as it was created.
     # : (untyped, untyped, untyped, untyped, bool) -> Array[untyped]?
     def habtm_records: (untyped, untyped, untyped, untyped, bool) -> Array[untyped]?
 

data/sig/generated/paper_trail_diff/prepared_record_index.rbs

@@ -68,6 +68,12 @@ module PaperTrailDiff
     # : (untyped) -> untyped
     def record_before: (untyped) -> untyped
 
+    # A record created in the boundary's own transaction has no state before
+    # it, yet a HABTM checkpoint saved later in that transaction records it as
+    # a member. Such a member is read as it was created.
+    # : (untyped) -> untyped
+    def record_created_in: (untyped) -> untyped
+
     # : (untyped) -> PreparedRecordState?
     def state_before: (untyped) -> PreparedRecordState?
 
@@ -90,8 +96,8 @@ module PaperTrailDiff
     # : (untyped) -> Array[PreparedRecordState]
     def states_around: (untyped) -> Array[PreparedRecordState]
 
-    # : (untyped) -> [Hash[untyped, untyped], Hash[untyped, untyped]]?
-    def transition: (untyped) -> [ Hash[untyped, untyped], Hash[untyped, untyped] ]?
+    # : (untyped) -> [PreparedRecordState, PreparedRecordState]?
+    def transition: (untyped) -> [ PreparedRecordState, PreparedRecordState ]?
 
     private
 
@@ -144,9 +150,15 @@ module PaperTrailDiff
     # : (untyped, untyped, untyped) -> untyped
     def record_before: (untyped, untyped, untyped) -> untyped
 
+    # : (untyped, untyped, untyped) -> untyped
+    def record_created_in: (untyped, untyped, untyped) -> untyped
+
     # : (untyped, untyped, untyped) -> [bool, PreparedRecordState?]
     def snapshot_state_before: (untyped, untyped, untyped) -> [ bool, PreparedRecordState? ]
 
+    # Typed as a reified record's attributes are. A JSON or JSONB `object`
+    # column stores times and dates as strings, which PaperTrail does not cast
+    # back, and the transition is carried into snapshots built from records.
     # : (untyped, untyped, untyped) -> [Hash[untyped, untyped], Hash[untyped, untyped]]?
     def transition: (untyped, untyped, untyped) -> [ Hash[untyped, untyped], Hash[untyped, untyped] ]?
 
@@ -173,6 +185,11 @@ module PaperTrailDiff
 
     private
 
+    # A model whose records need their own initialization is cast by
+    # instantiating it, as reify does.
+    # : (PreparedRecordState) -> Hash[untyped, untyped]
+    def typed_attributes: (PreparedRecordState) -> Hash[untyped, untyped]
+
     # : (untyped, String) -> bool
     def generated_reader?: (untyped, String) -> bool
 

data/sig/generated/paper_trail_diff/root_version_selection.rbs

@@ -13,6 +13,8 @@ module PaperTrailDiff
     # An error is a specification, so it names the way out as well as the wall.
     # A window ending at the present can never gain a later version, which makes
     # "write a checkpoint afterwards" impossible advice on its own.
+    # A window closes on the current record when it reaches the present, so
+    # this is raised only when there is none to read.
     INCOMPLETE: ::String
 
     # : (in_range: Array[untyped], selected: Array[untyped], after_range: untyped, windowed: bool, ?context_required: bool, ?filtered: bool, ?live_endpoint: untyped) -> void

data/sig/generated/paper_trail_diff/scope_condition.rbs

@@ -13,6 +13,9 @@ module PaperTrailDiff
     # ranking alone.
     RELATION_VALUES: untyped
 
+    # Relation parts that load or shape rows without choosing them.
+    LOADING_VALUES: untyped
+
     # Types whose stored values compare in Ruby as the database compares them,
     # named rather than referenced so that loading needs no Active Model.
     VALUE_TYPES: untyped
@@ -47,6 +50,15 @@ module PaperTrailDiff
     # : (untyped, ?untyped, ?ranked: bool) -> ScopeCondition?
     def self.build: (untyped, ?untyped, ?ranked: bool) -> ScopeCondition?
 
+    # A relation's own where clause, default scope included, read as
+    # conditions on stored attributes; nil when it cannot be. Its order,
+    # limit, and offset choose a page of current rows rather than membership,
+    # and loading or selecting columns changes neither, so they are left out.
+    # A single-table subclass's type condition is left to the caller, as for
+    # an association.
+    # : (untyped, untyped) -> ScopeCondition?
+    def self.for_relation: (untyped, untyped) -> ScopeCondition?
+
     # nil when the relation picks its members by conditions alone.
     # : (untyped, untyped, untyped) -> ScopeRanking?
     def self.ranking: (untyped, untyped, untyped) -> ScopeRanking?
@@ -78,6 +90,8 @@ module PaperTrailDiff
     # : (untyped, Array[untyped], ?ScopeRanking?) -> void
     def initialize: (untyped, Array[untyped], ?ScopeRanking?) -> void
 
+    # SQL admits a row only when its condition is true, not when it is
+    # unknown.
     # : (Hash[String, untyped]) -> bool
     def matches?: (Hash[String, untyped]) -> bool
 
@@ -91,8 +105,10 @@ module PaperTrailDiff
     # : (Array[untyped]) -> Array[untyped]
     def rank: (Array[untyped]) -> Array[untyped]
 
-    # SQL compares NULL with nothing, so only an IS NULL test, an equality
-    # with nil, matches it.
+    # SQL's three values: a comparison with NULL is unknown (nil) rather than
+    # false, except an IS NULL or IS NOT NULL test, an equality with nil, which
+    # is always known. Unknown matters only under NOT, which leaves it
+    # unknown where false would become true.
     COMPARISONS: untyped
 
     private
@@ -103,8 +119,20 @@ module PaperTrailDiff
 
     @ranking: ScopeRanking?
 
-    # : (Array[untyped], Hash[String, untyped]) -> bool
-    def evaluate: (Array[untyped], Hash[String, untyped]) -> bool
+    # true, false, or nil for unknown.
+    # : (Array[untyped], Hash[String, untyped]) -> bool?
+    def evaluate: (Array[untyped], Hash[String, untyped]) -> bool?
+
+    # False if any part is, otherwise unknown if any part is.
+    # : (Array[bool?]) -> bool?
+    def all: (Array[bool?]) -> bool?
+
+    # True if any part is, otherwise unknown if any part is.
+    # : (Array[bool?]) -> bool?
+    def any: (Array[bool?]) -> bool?
+
+    # : (bool?) -> bool?
+    def negate: (bool?) -> bool?
 
     # The form the database holds, as the scope's own values were cast.
     # : (String, Hash[String, untyped]) -> untyped
@@ -146,6 +174,7 @@ module PaperTrailDiff
       # : (untyped) -> Array[untyped]
       def comparison: (untyped) -> Array[untyped]
 
+      # Whether a value is NULL compares alike on every type.
       # : (Symbol, untyped) -> Array[untyped]
       def binary: (Symbol, untyped) -> Array[untyped]
 
@@ -158,12 +187,17 @@ module PaperTrailDiff
       def list: (Symbol, untyped, Array[untyped]) -> Array[untyped]
 
       # Ruby comparison stands in for SQL only on the record's own column of
-      # a type both compare alike.
-      # : (untyped) -> String
-      def column: (untyped) -> String
+      # a type both compare alike. Whether a value is NULL, any column's
+      # type compares alike.
+      # : (untyped, ?null_test: bool) -> String
+      def column: (untyped, ?null_test: bool) -> String
+
+      # : (String, untyped) -> bool
+      def comparable?: (String, untyped) -> bool
 
-      # : (String) -> bool
-      def comparable?: (String) -> bool
+      # PostgreSQL's citext is text that compares without regard to case.
+      # : (untyped) -> bool
+      def exact_text?: (untyped) -> bool
 
       # An enum compares the values it stores, which its subtype describes. A
       # wrapper such as a serialized or encrypted type is none of these.

data/sig/generated/paper_trail_diff/scope_ranking.rbs

@@ -13,6 +13,10 @@ module PaperTrailDiff
 
     ENUM_TYPE: ::String
 
+    # Rails wraps a time-zone-aware attribute's type, by default every
+    # datetime's, in this delegator; the time it stores is the wrapped type's.
+    TIME_ZONE_TYPE: ::String
+
     # Integers, booleans and dates sort alike everywhere. Strings follow a
     # collation, so they are not read.
     ORDER_TYPES: untyped
@@ -67,6 +71,10 @@ module PaperTrailDiff
     # : (untyped, String) -> bool
     def self.orderable?: (untyped, String) -> bool
 
+    # The type of the value a column stores, under an enum or time zone wrapper.
+    # : (untyped) -> untyped
+    def self.stored_type: (untyped) -> untyped
+
     # Active Record truncates a time to its column's precision before writing
     # it, so history holds the stored value when it keeps that many digits.
     # Times the type stores in UTC sort as the instants they name; local

data/sig/generated/paper_trail_diff/scoped_analysis.rbs

@@ -29,6 +29,12 @@ module PaperTrailDiff
     # : (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
 
+    # Each root's change rows, keyed as `analyses` is: the roots that still
+    # exist, then the deleted ones that have history to report. A deleted root
+    # without destroy history has no rows and is left out.
+    # : () -> Hash[Array[String], Array[ChangeRow]]
+    def change_rows: () -> Hash[Array[String], Array[ChangeRow]]
+
     # Two elements, not three: `roots` is reached by name so that existing
     # destructuring keeps working.
     # : () -> [Hash[Array[String], Analysis], Array[Array[String]]]

data/sig/generated/paper_trail_diff/scoped_analysis_builder.rbs

@@ -9,11 +9,16 @@ module PaperTrailDiff
     # : () -> ScopedAnalysis
     def call: () -> ScopedAnalysis
 
+    private
+
+    # : (ScopedRootSelection::Result, Array[Array[String]], Hash[Array[String], Analysis?]) -> ScopedAnalysis
+    def analysis: (ScopedRootSelection::Result, Array[Array[String]], Hash[Array[String], Analysis?]) -> ScopedAnalysis
+
     @analyzer: untyped
 
     @deleted_analyzer: untyped
 
-    @include_deleted: bool
+    @deleted_filter: DeletedRootFilter?
 
     @limit: Integer
 

data/sig/generated/paper_trail_diff/scoped_root_selection.rbs

@@ -71,6 +71,12 @@ module PaperTrailDiff
     # : (Array[AssociationActivitySelection::source]) -> Array[AssociationActivitySelection::Query]?
     def subqueries: (Array[AssociationActivitySelection::source]) -> Array[AssociationActivitySelection::Query]?
 
+    # Which candidates still have a row is asked without the relation's
+    # conditions, so that "filtered out" and "no longer exists" stay
+    # separable. A filter then reads the history of the relation's records
+    # only, whose order and page choose among those that match, and of the
+    # deleted ones, which no relation can test. Those it lists, as without a
+    # filter, but does not count toward `limit:`.
     # : (Array[String]) -> Result
     def plucked_selection: (Array[String]) -> Result
 
@@ -113,10 +119,8 @@ module PaperTrailDiff
     # : () -> Array[String]
     def versioned_ids: () -> Array[String]
 
-    # Which of those candidates still have a row, asked without the relation's
-    # conditions so that "filtered out" and "no longer exists" stay separable.
-    # : (Array[String]) -> Array[String]
-    def live_ids: (Array[String]) -> Array[String]
+    # : (untyped, Array[String]) -> Array[String]
+    def ids_in: (untyped, Array[String]) -> Array[String]
 
     # Deduplicate records rather than adding SQL DISTINCT: an otherwise valid
     # relation may order by joined columns or select a PostgreSQL json column.