paper_trail_diff 0.3.0 → 0.4.0

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,8 +6,8 @@ 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

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]
 

data/sig/generated/paper_trail_diff/time_activity_timeline_builder.rbs

@@ -22,8 +22,25 @@ module PaperTrailDiff
 
     @tree: AssociationTree
 
-    # : () -> [ActivityHistory, Array[untyped]]
-    def history_and_versions: () -> [ ActivityHistory, Array[untyped] ]
+    # : () -> [ActivityHistory, Array[untyped], ActivityStep?]
+    def history_and_versions: () -> [ ActivityHistory, Array[untyped], ActivityStep? ]
+
+    # : (Array[untyped], Array[ActivityEvent]) -> ActivityHistory
+    def build_history: (Array[untyped], Array[ActivityEvent]) -> ActivityHistory
+
+    # : (ActivityHistory, ActivityStep?) -> Array[ActivityStep]
+    def activity_steps: (ActivityHistory, ActivityStep?) -> Array[ActivityStep]
+
+    # : (Array[ActivityEvent]) -> Array[ActivityEvent]
+    def selected_events: (Array[ActivityEvent]) -> Array[ActivityEvent]
+
+    # The window's last selected mutation is the root's own destruction, so the
+    # timeline closes on the absence it leaves rather than on a later boundary.
+    # : (ActivityHistory, ActivityEvent?) -> ActivityStep?
+    def closing_step: (ActivityHistory, ActivityEvent?) -> ActivityStep?
+
+    # : (ActivityEvent?) -> bool
+    def terminal_destroy?: (ActivityEvent?) -> bool
 
     # : (Array[untyped]) -> void
     def prepare_history: (Array[untyped]) -> void
@@ -31,16 +48,10 @@ module PaperTrailDiff
     # : (Array[untyped]) -> Array[ActivityEvent]
     def collect_events: (Array[untyped]) -> Array[ActivityEvent]
 
-    # : (Array[ActivityEvent]) -> bool
-    def time_events?: (Array[ActivityEvent]) -> bool
+    # : (Array[ActivityEvent], Array[ActivityEvent]) -> bool
+    def time_events?: (Array[ActivityEvent], Array[ActivityEvent]) -> bool
 
     # : (ActivityEvent, Array[ActivityEvent]) -> bool
     def later_event?: (ActivityEvent, Array[ActivityEvent]) -> bool
-
-    # : (Array[untyped], Hash[Array[untyped], RecordSnapshot?]) -> Array[Step]
-    def root_steps: (Array[untyped], Hash[Array[untyped], RecordSnapshot?]) -> Array[Step]
-
-    # : (untyped) -> Array[untyped]
-    def version_key: (untyped) -> Array[untyped]
   end
 end

data/sig/generated/paper_trail_diff/time_version_range.rbs

@@ -18,6 +18,13 @@ module PaperTrailDiff
     # : () -> untyped
     def versions_relation: () -> untyped
 
+    # A window closing on the record's own destruction needs no later version:
+    # the destroy reveals the preceding mutation and nothing can follow it, so
+    # demanding a checkpoint that can never be written would reject the range
+    # permanently.
+    # : (Array[untyped]) -> bool
+    def terminal_destroy?: (Array[untyped]) -> bool
+
     # : (untyped) -> untyped
     def trailing_version: (untyped) -> untyped
 

data/sig/generated/paper_trail_diff/timeline_range.rbs

@@ -3,6 +3,8 @@
 module PaperTrailDiff
   # Chooses explicit-version or wall-clock selection for one timeline request.
   class TimelineRange
+    BOUNDARY_SYMBOLS: untyped
+
     attr_reader from: untyped
 
     attr_reader to: untyped
@@ -12,6 +14,11 @@ module PaperTrailDiff
     # : (untyped, from: untyped, to: untyped, within: untyped) -> void
     def initialize: (untyped, from: untyped, to: untyped, within: untyped) -> void
 
+    # A record with no versions has no first or last boundary to resolve, which
+    # is an empty history rather than a bad request.
+    # : () -> bool
+    def unresolved?: () -> bool
+
     # : (?context_required: bool) -> Array[untyped]
     def select: (?context_required: bool) -> Array[untyped]
 
@@ -30,8 +37,30 @@ module PaperTrailDiff
 
     @record: untyped
 
+    @requested_from: untyped
+
+    @requested_to: untyped
+
     @to: untyped
 
+    # : () -> Array[untyped]
+    def empty_versions: () -> Array[untyped]
+
+    # : (untyped) -> bool
+    def symbolic?: (untyped) -> bool
+
+    # Resolving `:first` and `:last` here keeps callers from depending on the
+    # order PaperTrail happens to give its versions association, which a caller
+    # is also free to reorder.
+    # : (untyped) -> untyped
+    def resolve: (untyped) -> untyped
+
+    # : () -> untyped
+    def ordered_versions: () -> untyped
+
+    # : () -> untyped
+    def versions_relation: () -> untyped
+
     # : (untyped) -> TimeRange?
     def build_time_range: (untyped) -> TimeRange?
 

data/sig/generated/paper_trail_diff/version_association_candidate_scope.rbs

@@ -17,14 +17,27 @@ module PaperTrailDiff
 
     @version_class: untyped
 
+    # Only quoting helpers are needed, so the connection is borrowed for the
+    # duration of building the condition rather than checked out permanently,
+    # which Active Record 7.2 and newer can deprecate. Active Record 7.1 has no
+    # `with_connection` and reaches the same connection through the accessor.
+    # : () { (untyped) -> String } -> String
+    def with_connection: () { (untyped) -> String } -> String
+
     # : () -> String
     def candidate_condition: () -> String
 
-    # : (String, String) -> String
-    def activity_condition: (String, String) -> String
+    # : (untyped) -> String
+    def condition_sql: (untyped) -> String
+
+    # : (untyped, String, String) -> Hash[Symbol, String]
+    def quoted_columns: (untyped, String, String) -> Hash[Symbol, String]
+
+    # : (Hash[Symbol, String], String, untyped) -> String
+    def activity_condition: (Hash[Symbol, String], String, untyped) -> String
 
-    # : (String, String) -> String
-    def column: (String, String) -> String
+    # : (untyped, String, String) -> String
+    def column: (untyped, String, String) -> String
 
     # : (String) -> String
     def compact_sql: (String) -> String

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: paper_trail_diff
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Alex Williams
@@ -43,13 +43,23 @@ files:
 - QUICKSTART.md
 - README.md
 - lib/paper_trail_diff.rb
+- lib/paper_trail_diff/activity_belongs_to_event_applier.rb
 - lib/paper_trail_diff/activity_boundary.rb
 - lib/paper_trail_diff/activity_child_candidate_loader.rb
+- lib/paper_trail_diff/activity_collection_event_applier.rb
+- lib/paper_trail_diff/activity_collection_record_updater.rb
+- lib/paper_trail_diff/activity_collection_route_change.rb
+- lib/paper_trail_diff/activity_collection_route_updater.rb
 - lib/paper_trail_diff/activity_event.rb
+- lib/paper_trail_diff/activity_event_record_normalizer.rb
+- lib/paper_trail_diff/activity_event_record_resolver.rb
+- lib/paper_trail_diff/activity_event_route_finder.rb
 - lib/paper_trail_diff/activity_event_snapshot_refresher.rb
 - lib/paper_trail_diff/activity_history.rb
 - lib/paper_trail_diff/activity_range.rb
+- lib/paper_trail_diff/activity_relationship.rb
 - lib/paper_trail_diff/activity_root_snapshot_refresher.rb
+- lib/paper_trail_diff/activity_root_steps.rb
 - lib/paper_trail_diff/activity_snapshot_delta.rb
 - lib/paper_trail_diff/activity_snapshot_sequence.rb
 - lib/paper_trail_diff/activity_timeline_builder.rb
@@ -101,13 +111,23 @@ files:
 - lib/paper_trail_diff/version_association_candidate_scope.rb
 - lib/paper_trail_diff/version_range.rb
 - sig/generated/paper_trail_diff.rbs
+- sig/generated/paper_trail_diff/activity_belongs_to_event_applier.rbs
 - sig/generated/paper_trail_diff/activity_boundary.rbs
 - sig/generated/paper_trail_diff/activity_child_candidate_loader.rbs
+- sig/generated/paper_trail_diff/activity_collection_event_applier.rbs
+- sig/generated/paper_trail_diff/activity_collection_record_updater.rbs
+- sig/generated/paper_trail_diff/activity_collection_route_change.rbs
+- sig/generated/paper_trail_diff/activity_collection_route_updater.rbs
 - sig/generated/paper_trail_diff/activity_event.rbs
+- sig/generated/paper_trail_diff/activity_event_record_normalizer.rbs
+- sig/generated/paper_trail_diff/activity_event_record_resolver.rbs
+- sig/generated/paper_trail_diff/activity_event_route_finder.rbs
 - sig/generated/paper_trail_diff/activity_event_snapshot_refresher.rbs
 - sig/generated/paper_trail_diff/activity_history.rbs
 - sig/generated/paper_trail_diff/activity_range.rbs
+- sig/generated/paper_trail_diff/activity_relationship.rbs
 - sig/generated/paper_trail_diff/activity_root_snapshot_refresher.rbs
+- sig/generated/paper_trail_diff/activity_root_steps.rbs
 - sig/generated/paper_trail_diff/activity_snapshot_delta.rbs
 - sig/generated/paper_trail_diff/activity_snapshot_sequence.rbs
 - sig/generated/paper_trail_diff/activity_timeline_builder.rbs
@@ -164,11 +184,11 @@ licenses:
 metadata:
   allowed_push_host: https://rubygems.org
   bug_tracker_uri: https://github.com/aheathwilliams/paper_trail_diff/issues
-  changelog_uri: https://github.com/aheathwilliams/paper_trail_diff/blob/v0.3.0/CHANGELOG.md
-  documentation_uri: https://github.com/aheathwilliams/paper_trail_diff/blob/v0.3.0/README.md
+  changelog_uri: https://github.com/aheathwilliams/paper_trail_diff/blob/v0.4.0/CHANGELOG.md
+  documentation_uri: https://github.com/aheathwilliams/paper_trail_diff/blob/v0.4.0/README.md
   homepage_uri: https://github.com/aheathwilliams/paper_trail_diff
   rubygems_mfa_required: 'true'
-  source_code_uri: https://github.com/aheathwilliams/paper_trail_diff/tree/v0.3.0
+  source_code_uri: https://github.com/aheathwilliams/paper_trail_diff/tree/v0.4.0
 rdoc_options: []
 require_paths:
 - lib