paper_trail_diff 0.1.0

data/lib/paper_trail_diff.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+require 'paper_trail'
+
+require_relative 'paper_trail_diff/version'
+require_relative 'paper_trail_diff/support'
+require_relative 'paper_trail_diff/errors'
+require_relative 'paper_trail_diff/configuration'
+require_relative 'paper_trail_diff/endpoint'
+require_relative 'paper_trail_diff/association_traversal'
+require_relative 'paper_trail_diff/association_discovery'
+require_relative 'paper_trail_diff/diagnostics'
+require_relative 'paper_trail_diff/snapshot'
+require_relative 'paper_trail_diff/value_objects'
+require_relative 'paper_trail_diff/engine'
+require_relative 'paper_trail_diff/historical_association_reifier'
+require_relative 'paper_trail_diff/prepared_record_index'
+require_relative 'paper_trail_diff/prepared_history'
+require_relative 'paper_trail_diff/prepared_edge_loader'
+require_relative 'paper_trail_diff/prepared_history_loader'
+require_relative 'paper_trail_diff/prepared_association_reifier'
+require_relative 'paper_trail_diff/live_association_reader'
+require_relative 'paper_trail_diff/snapshot_normalizer'
+require_relative 'paper_trail_diff/historical_snapshot_store'
+require_relative 'paper_trail_diff/timeline_snapshot_provider'
+require_relative 'paper_trail_diff/activity_event_snapshot_refresher'
+require_relative 'paper_trail_diff/activity_root_snapshot_refresher'
+require_relative 'paper_trail_diff/branch_snapshot_refresher'
+require_relative 'paper_trail_diff/step'
+require_relative 'paper_trail_diff/activity_boundary'
+require_relative 'paper_trail_diff/analysis'
+require_relative 'paper_trail_diff/version_range'
+require_relative 'paper_trail_diff/timeline_builder'
+require_relative 'paper_trail_diff/activity_range'
+require_relative 'paper_trail_diff/activity_event'
+require_relative 'paper_trail_diff/activity_version_collector'
+require_relative 'paper_trail_diff/activity_snapshot_sequence'
+require_relative 'paper_trail_diff/activity_timeline_builder'
+require_relative 'paper_trail_diff/paper_trail_adapter'
+
+# @rbs!
+#   module PaperTrailDiff
+#     type snapshot_attributes = Hash[untyped, untyped]
+#     type snapshot_associations = Hash[untyped, AssociationSnapshot]
+#     type attribute_changes = Hash[String, ValueChange]
+#     type association_diff = ToOneAssociationDiff | CollectionAssociationDiff
+#     type association_diffs = Hash[String, association_diff]
+#     type association_snapshots = Hash[String, AssociationSnapshot]
+#     type identity = Array[untyped]
+#     type ignore_option = Array[String | Symbol] | Hash[String | Symbol, untyped]
+#     type reference_key = :type | :id | "type" | "id"
+#   end
+
+# Structured version comparison for PaperTrail.
+module PaperTrailDiff
+  DEFAULT_IGNORED_ATTRIBUTES = ['updated_at'].freeze
+  SUPPORTED_ASSOCIATION_MACROS = %i[
+    belongs_to
+    has_one
+    has_many
+    has_and_belongs_to_many
+  ].freeze
+
+  class << self
+    # Compares net state between explicit PaperTrail-version or current-record endpoints.
+    #: (untyped, untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option) -> Diff
+    def compare(from_version, to_version, associations: [], ignore: DEFAULT_IGNORED_ATTRIBUTES)
+      PaperTrailAdapter.new(associations: associations, ignore: ignore).compare(
+        from_version,
+        to_version
+      )
+    end
+
+    # Compares every adjacent reconstructed state in an inclusive version range.
+    #: (untyped, from: untyped, to: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option) -> Array[Step]
+    def timeline(record, from:, to:, associations: [], ignore: DEFAULT_IGNORED_ATTRIBUTES)
+      PaperTrailAdapter.new(associations: associations, ignore: ignore).timeline(
+        record,
+        from: from,
+        to: to
+      )
+    end
+
+    # Compares adjacent root and selected-descendant activity boundaries.
+    #: (untyped, from: untyped, to: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option) -> Array[ActivityStep]
+    def activity_timeline(record, from:, to:, associations: [], ignore: DEFAULT_IGNORED_ATTRIBUTES)
+      PaperTrailAdapter.new(associations: associations, ignore: ignore).activity_timeline(
+        record,
+        from: from,
+        to: to
+      )
+    end
+
+    # Builds an endpoint diff and root-checkpoint timeline while normalizing each version once.
+    #: (untyped, from: untyped, to: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?activity: bool) -> Analysis
+    def analyze( # rubocop:disable Metrics/ParameterLists
+      record,
+      from:,
+      to:,
+      associations: [],
+      ignore: DEFAULT_IGNORED_ATTRIBUTES,
+      activity: false
+    )
+      PaperTrailAdapter.new(associations: associations, ignore: ignore).analyze(
+        record,
+        from: from,
+        to: to,
+        activity: activity
+      )
+    end
+
+    # Returns the association macros this release can normalize.
+    #: () -> Array[Symbol]
+    def supported_association_macros
+      SUPPORTED_ASSOCIATION_MACROS
+    end
+
+    # Discovers supported, finite association paths for a model or record.
+    #: (untyped, ?max_depth: Integer) -> Array[AssociationDescriptor]
+    def association_paths(model_or_record, max_depth: 1)
+      AssociationDiscovery.new(model_or_record, max_depth: max_depth).call
+    end
+
+    # Reports known reconstruction hazards without mutating application state.
+    #: (untyped, untyped, ?associations: Array[String | Symbol]) -> DiagnosticReport
+    def diagnose(from_version, to_version, associations: [])
+      HistoryDiagnostics.new(from_version, to_version, associations: associations).call
+    end
+  end
+end

data/sig/generated/paper_trail_diff/activity_boundary.rbs

@@ -0,0 +1,43 @@
+# Generated from lib/paper_trail_diff/activity_boundary.rb with RBS::Inline
+
+module PaperTrailDiff
+  # Immutable metadata identifying one historical or current activity boundary.
+  class ActivityBoundary
+    attr_reader kind: Symbol
+
+    attr_reader version_id: untyped
+
+    attr_reader item_type: String
+
+    attr_reader item_id: untyped
+
+    attr_reader recorded_at: untyped
+
+    # : (untyped) -> ActivityBoundary
+    def self.from_version: (untyped) -> ActivityBoundary
+
+    # : (untyped, captured_at: untyped) -> ActivityBoundary
+    def self.current: (untyped, captured_at: untyped) -> ActivityBoundary
+
+    # : (kind: Symbol, version_id: untyped, item_type: untyped, item_id: untyped, recorded_at: untyped) -> void
+    def initialize: (kind: Symbol, version_id: untyped, item_type: untyped, item_id: untyped, recorded_at: untyped) -> void
+
+    # : () -> Hash[Symbol, untyped]
+    def to_h: () -> Hash[Symbol, untyped]
+  end
+
+  # One adjacent transition in a descendant-aware activity timeline.
+  class ActivityStep
+    attr_reader from_boundary: ActivityBoundary
+
+    attr_reader to_boundary: ActivityBoundary
+
+    attr_reader diff: Diff
+
+    # : (from_boundary: ActivityBoundary, to_boundary: ActivityBoundary, diff: Diff) -> void
+    def initialize: (from_boundary: ActivityBoundary, to_boundary: ActivityBoundary, diff: Diff) -> void
+
+    # : () -> Hash[Symbol, untyped]
+    def to_h: () -> Hash[Symbol, untyped]
+  end
+end

data/sig/generated/paper_trail_diff/activity_event.rbs

@@ -0,0 +1,64 @@
+# Generated from lib/paper_trail_diff/activity_event.rb with RBS::Inline
+
+module PaperTrailDiff
+  # Internal activity boundary plus the selected root branches affected by its event.
+  class ActivityEvent
+    attr_reader version: untyped
+
+    attr_reader branches: Array[String]?
+
+    # : (version: untyped, branches: Array[String]?) -> void
+    def initialize: (version: untyped, branches: Array[String]?) -> void
+
+    # : () -> bool
+    def root?: () -> bool
+  end
+
+  # Accumulates each version once while retaining every selected root branch.
+  class ActivityEventRegistry
+    def initialize: () -> untyped
+
+    # : (Array[untyped], ?branch: String?) -> void
+    def add: (Array[untyped], ?branch: String?) -> void
+
+    # : () -> Array[ActivityEvent]
+    def to_a: () -> Array[ActivityEvent]
+
+    private
+
+    @events: Hash[Array[untyped], Hash[Symbol, untyped]]
+
+    # : (Hash[Symbol, untyped]?, String?) -> Array[String]?
+    def merged_branches: (Hash[Symbol, untyped]?, String?) -> Array[String]?
+  end
+
+  # Resolves the branch union that PT-AT exposes atomically for one transaction.
+  class ActivityTransactionGroups
+    # : (Array[ActivityEvent]) -> void
+    def initialize: (Array[ActivityEvent]) -> void
+
+    # : (ActivityEvent) -> Array[String]?
+    def branches_for: (ActivityEvent) -> Array[String]?
+
+    # : (ActivityEvent) -> bool
+    def isolated?: (ActivityEvent) -> bool
+
+    private
+
+    @branches: Hash[Array[untyped], Array[String]?]
+
+    @group_sizes: Hash[Array[untyped], Integer]
+
+    # : (Hash[Array[untyped], Array[ActivityEvent]]) -> Hash[Array[untyped], Array[String]?]
+    def build_groups: (Hash[Array[untyped], Array[ActivityEvent]]) -> Hash[Array[untyped], Array[String]?]
+
+    # : (Array[ActivityEvent]) -> Hash[Array[untyped], Array[ActivityEvent]]
+    def grouped_events: (Array[ActivityEvent]) -> Hash[Array[untyped], Array[ActivityEvent]]
+
+    # : (Array[ActivityEvent]) -> Array[String]?
+    def group_branches: (Array[ActivityEvent]) -> Array[String]?
+
+    # : (ActivityEvent) -> Array[untyped]?
+    def transaction_key: (ActivityEvent) -> Array[untyped]?
+  end
+end

data/sig/generated/paper_trail_diff/activity_event_snapshot_refresher.rbs

@@ -0,0 +1,98 @@
+# Generated from lib/paper_trail_diff/activity_event_snapshot_refresher.rb with RBS::Inline
+
+module PaperTrailDiff
+  # Applies safe descendant event deltas without rebuilding an entire selected branch.
+  # rubocop:disable Metrics/ClassLength
+  class ActivityEventSnapshotRefresher
+    RECORD_AFTER_HANDLERS: untyped
+
+    # : (traversal: AssociationTraversal, pool: SnapshotPool, components: untyped, ?association_reader: untyped) -> void
+    def initialize: (traversal: AssociationTraversal, pool: SnapshotPool, components: untyped, ?association_reader: untyped) -> void
+
+    # : (untyped, untyped, RecordSnapshot, Array[String], ActivityEvent?) -> [bool, RecordSnapshot?]
+    def call: (untyped, untyped, RecordSnapshot, Array[String], ActivityEvent?) -> [ bool, RecordSnapshot? ]
+
+    private
+
+    @association_reader: untyped
+
+    @components: untyped
+
+    @pool: SnapshotPool
+
+    @traversal: AssociationTraversal
+
+    # : (Array[Array[untyped]], untyped) -> bool
+    def unsafe_through_membership_event?: (Array[Array[untyped]], untyped) -> bool
+
+    # : (untyped, untyped, RecordSnapshot, SnapshotNormalizer, Array[Array[untyped]], untyped) -> [bool, RecordSnapshot]
+    def collection_target_snapshot: (untyped, untyped, RecordSnapshot, SnapshotNormalizer, Array[Array[untyped]], untyped) -> [ bool, RecordSnapshot ]
+
+    # : (untyped, AssociationTree, String, ?path: String) -> Array[Array[untyped]]
+    def direct_collection_routes: (untyped, AssociationTree, String, ?path: String) -> Array[Array[untyped]]
+
+    # : (RecordSnapshot, Array[untyped], untyped, untyped, RecordSnapshot?, ?depth: Integer) -> [RecordSnapshot, bool]
+    def replace_collection_route: (RecordSnapshot, Array[untyped], untyped, untyped, RecordSnapshot?, ?depth: Integer) -> [ RecordSnapshot, bool ]
+
+    # : (untyped, untyped, RecordSnapshot, AssociationTree, SnapshotNormalizer, untyped) -> [bool, RecordSnapshot?]
+    def belongs_to_target_snapshot: (untyped, untyped, RecordSnapshot, AssociationTree, SnapshotNormalizer, untyped) -> [ bool, RecordSnapshot? ]
+
+    # : (untyped, AssociationTree, String, ?path: String) -> Array[Array[untyped]]
+    def belongs_to_routes: (untyped, AssociationTree, String, ?path: String) -> Array[Array[untyped]]
+
+    # : (Array[untyped], untyped, SnapshotNormalizer, untyped, untyped) -> RecordSnapshot?
+    def normalized_route_record: (Array[untyped], untyped, SnapshotNormalizer, untyped, untyped) -> RecordSnapshot?
+
+    # : (RecordSnapshot, Array[untyped], untyped, RecordSnapshot?, ?depth: Integer) -> [RecordSnapshot, bool]
+    def replace_route: (RecordSnapshot, Array[untyped], untyped, RecordSnapshot?, ?depth: Integer) -> [ RecordSnapshot, bool ]
+
+    # : (Array[RecordSnapshot], untyped, RecordSnapshot?) -> Array[RecordSnapshot]
+    def replace_existing_target: (Array[RecordSnapshot], untyped, RecordSnapshot?) -> Array[RecordSnapshot]
+
+    # : (untyped) -> untyped
+    def record_after: (untyped) -> untyped
+
+    # PaperTrail create/update versions contain deserialized change pairs, so
+    # their post-event records need no successor query.
+    # : (untyped) -> untyped
+    def changed_record_after: (untyped) -> untyped
+
+    # : (untyped) -> untyped
+    def created_record_after: (untyped) -> untyped
+
+    # : (untyped) -> untyped
+    def updated_record_after: (untyped) -> untyped
+
+    # : (untyped, untyped) -> Hash[untyped, untyped]
+    def after_attributes: (untyped, untyped) -> Hash[untyped, untyped]
+
+    # : (untyped, untyped) -> untyped
+    def apply_changes: (untyped, untyped) -> untyped
+
+    # Mirrors PaperTrail's changeset deserialization without resolving
+    # +version.item+, which would issue one live-record query per event.
+    # : (untyped, untyped) -> untyped
+    def deserialized_changeset: (untyped, untyped) -> untyped
+
+    # : (untyped, untyped, untyped) -> untyped
+    def standard_changeset: (untyped, untyped, untyped) -> untyped
+
+    # : (untyped, untyped, RecordSnapshot) -> bool
+    def member_of_owner?: (untyped, untyped, RecordSnapshot) -> bool
+
+    # : (untyped, untyped, AssociationTree, String, SnapshotNormalizer, untyped, untyped) -> RecordSnapshot?
+    def normalize_event_record: (untyped, untyped, AssociationTree, String, SnapshotNormalizer, untyped, untyped) -> RecordSnapshot?
+
+    # : (untyped, habtm_version: untyped) -> HistoricalAssociationReifier
+    def historical_reader: (untyped, habtm_version: untyped) -> HistoricalAssociationReifier
+
+    # : (Array[RecordSnapshot], untyped, RecordSnapshot?) -> Array[RecordSnapshot]
+    def replace_collection_record: (Array[RecordSnapshot], untyped, RecordSnapshot?) -> Array[RecordSnapshot]
+
+    # : (untyped, RecordSnapshot?) -> String
+    def replacement_type: (untyped, RecordSnapshot?) -> String
+
+    # : (untyped) -> untyped
+    def endpoint_model_class: (untyped) -> untyped
+  end
+end

data/sig/generated/paper_trail_diff/activity_range.rbs

@@ -0,0 +1,36 @@
+# Generated from lib/paper_trail_diff/activity_range.rb with RBS::Inline
+
+module PaperTrailDiff
+  # Tests activity versions against a historical-version or wall-clock range end.
+  class ActivityRange
+    # : (untyped, untyped) -> void
+    def initialize: (untyped, untyped) -> void
+
+    # : (untyped) -> bool
+    def include?: (untyped) -> bool
+
+    # Narrows an Active Record version relation by timestamp. Exact tie-breaking
+    # remains in #include? so this works for integer, UUID, and custom version IDs.
+    # : (untyped) -> untyped
+    def scope: (untyped) -> untyped
+
+    private
+
+    @end_boundary: untyped
+
+    @end_key: Array[untyped]?
+
+    @start_key: Array[untyped]
+
+    @start_version: untyped
+
+    # : (untyped, Array[untyped]) -> bool
+    def before_end?: (untyped, Array[untyped]) -> bool
+
+    # : () -> untyped
+    def end_time: () -> untyped
+
+    # : (Array[untyped], Array[untyped]) -> bool
+    def key_before_or_equal?: (Array[untyped], Array[untyped]) -> bool
+  end
+end

data/sig/generated/paper_trail_diff/activity_root_snapshot_refresher.rbs

@@ -0,0 +1,54 @@
+# Generated from lib/paper_trail_diff/activity_root_snapshot_refresher.rb with RBS::Inline
+
+module PaperTrailDiff
+  # Advances scalar-only root events while retaining already reconstructed associations.
+  class ActivityRootSnapshotRefresher
+    # : (tree: AssociationTree, traversal: AssociationTraversal, normalizer: SnapshotNormalizer, record_after: untyped, changeset: untyped, partial_snapshotter: untyped) -> void
+    def initialize: (tree: AssociationTree, traversal: AssociationTraversal, normalizer: SnapshotNormalizer, record_after: untyped, changeset: untyped, partial_snapshotter: untyped) -> void
+
+    # : (untyped, untyped, RecordSnapshot?, ActivityEvent) -> [bool, RecordSnapshot?]
+    def call: (untyped, untyped, RecordSnapshot?, ActivityEvent) -> [ bool, RecordSnapshot? ]
+
+    private
+
+    @changeset: untyped
+
+    @normalizer: SnapshotNormalizer
+
+    @partial_snapshotter: untyped
+
+    @record_after: untyped
+
+    @relationship_reflections: Hash[String, Array[untyped]]
+
+    @traversal: AssociationTraversal
+
+    @tree: AssociationTree
+
+    @unsupported_branches: Hash[String, Array[String]]
+
+    # : (RecordSnapshot, untyped, untyped) -> snapshot_attributes?
+    def advanced_attributes: (RecordSnapshot, untyped, untyped) -> snapshot_attributes?
+
+    # : (untyped, untyped) -> Array[String]
+    def branches_to_refresh: (untyped, untyped) -> Array[String]
+
+    # : (untyped) -> Array[String]
+    def unsupported_branches: (untyped) -> Array[String]
+
+    # : (untyped) -> bool
+    def direct_versioned_reflection?: (untyped) -> bool
+
+    # : (RecordSnapshot, untyped) -> bool
+    def same_record?: (RecordSnapshot, untyped) -> bool
+
+    # : (untyped, untyped) -> Array[String]
+    def changed_relationship_branches: (untyped, untyped) -> Array[String]
+
+    # : (untyped) -> Array[untyped]
+    def root_relationship_reflections: (untyped) -> Array[untyped]
+
+    # : (untyped) -> Array[String]
+    def relationship_columns: (untyped) -> Array[String]
+  end
+end

data/sig/generated/paper_trail_diff/activity_snapshot_sequence.rbs

@@ -0,0 +1,71 @@
+# Generated from lib/paper_trail_diff/activity_snapshot_sequence.rb with RBS::Inline
+
+module PaperTrailDiff
+  # Optional full/partial snapshot operations consumed by the activity sequence.
+  class ActivitySnapshotProvider
+    # : (snapshotter: untyped, refresher: untyped, preparer: untyped) -> void
+    def initialize: (snapshotter: untyped, refresher: untyped, preparer: untyped) -> void
+
+    # : (untyped, Array[untyped]) -> void
+    def prepare: (untyped, Array[untyped]) -> void
+
+    # : (untyped, untyped) -> RecordSnapshot?
+    def call: (untyped, untyped) -> RecordSnapshot?
+
+    # : (untyped, untyped, RecordSnapshot?, Array[String], event: ActivityEvent, isolated: bool) -> RecordSnapshot?
+    def refresh: (untyped, untyped, RecordSnapshot?, Array[String], event: ActivityEvent, isolated: bool) -> RecordSnapshot?
+
+    # : (untyped, untyped, RecordSnapshot?, event: ActivityEvent) -> RecordSnapshot?
+    def advance_root: (untyped, untyped, RecordSnapshot?, event: ActivityEvent) -> RecordSnapshot?
+
+    @preparer: untyped
+
+    @refresher: untyped
+
+    @snapshotter: untyped
+  end
+
+  # Builds chronological snapshots, refreshing only branches affected by prior events.
+  class ActivitySnapshotSequence
+    # : (Array[untyped], Array[ActivityEvent], untyped, ?current: untyped) -> void
+    def initialize: (Array[untyped], Array[ActivityEvent], untyped, ?current: untyped) -> void
+
+    # : () -> Array[RecordSnapshot?]
+    def call: () -> Array[RecordSnapshot?]
+
+    # : () { (ActivityEvent, RecordSnapshot?) -> void } -> void
+    def each: () { (ActivityEvent, RecordSnapshot?) -> void } -> void
+
+    private
+
+    @current: untyped
+
+    @events: Array[ActivityEvent]
+
+    @root_endpoints: Hash[untyped, untyped]
+
+    @root_versions: Array[untyped]
+
+    @snapshotter: untyped
+
+    @transaction_groups: ActivityTransactionGroups
+
+    # : (ActivityEvent, ActivityEvent, RecordSnapshot?) -> RecordSnapshot?
+    def transition_snapshot: (ActivityEvent, ActivityEvent, RecordSnapshot?) -> RecordSnapshot?
+
+    # : (ActivityEvent) -> bool
+    def incremental_root?: (ActivityEvent) -> bool
+
+    # : (ActivityEvent, ActivityEvent, RecordSnapshot?) -> RecordSnapshot?
+    def advance_root: (ActivityEvent, ActivityEvent, RecordSnapshot?) -> RecordSnapshot?
+
+    # : (ActivityEvent) -> RecordSnapshot?
+    def full_snapshot: (ActivityEvent) -> RecordSnapshot?
+
+    # : (untyped) -> untyped
+    def root_endpoint: (untyped) -> untyped
+
+    # : () -> Hash[untyped, untyped]
+    def build_root_endpoints: () -> Hash[untyped, untyped]
+  end
+end

data/sig/generated/paper_trail_diff/activity_timeline_builder.rbs

@@ -0,0 +1,61 @@
+# Generated from lib/paper_trail_diff/activity_timeline_builder.rb with RBS::Inline
+
+module PaperTrailDiff
+  # Compares adjacent root and selected-descendant activity boundaries.
+  class ActivityTimelineBuilder
+    # : (untyped, from: untyped, to: untyped, tree: AssociationTree, snapshotter: untyped) -> void
+    def initialize: (untyped, from: untyped, to: untyped, tree: AssociationTree, snapshotter: untyped) -> void
+
+    # : () -> Array[ActivityStep]
+    def build: () -> Array[ActivityStep]
+
+    # Builds all three version-bounded views from one activity snapshot pass.
+    # : () -> Analysis
+    def analyze: () -> Analysis
+
+    private
+
+    @from: untyped
+
+    @record: untyped
+
+    @snapshotter: untyped
+
+    @to: untyped
+
+    @tree: AssociationTree
+
+    # : () -> Array[ActivityStep]
+    def build_between_versions: () -> Array[ActivityStep]
+
+    # : () -> Array[ActivityStep]
+    def build_to_current: () -> Array[ActivityStep]
+
+    # : () -> [RecordSnapshot?, untyped]
+    def capture_current: () -> [ RecordSnapshot?, untyped ]
+
+    # : () -> void
+    def validate_current_range!: () -> void
+
+    # : (Array[untyped], ?range_end: untyped) -> Array[ActivityEvent]
+    def collect_events: (Array[untyped], ?range_end: untyped) -> Array[ActivityEvent]
+
+    # : (Array[untyped]) -> void
+    def prepare_history: (Array[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) -> [Array[ActivityStep], Hash[Array[untyped], RecordSnapshot?], RecordSnapshot?]
+    def event_history: (Array[untyped], Array[ActivityEvent], ?current: untyped) -> [ Array[ActivityStep], Hash[Array[untyped], RecordSnapshot?], RecordSnapshot? ]
+
+    # : (Array[untyped], Hash[Array[untyped], RecordSnapshot?], Array[ActivityStep]) -> Analysis
+    def build_analysis: (Array[untyped], Hash[Array[untyped], RecordSnapshot?], Array[ActivityStep]) -> Analysis
+
+    # : (Array[untyped], Array[RecordSnapshot?]) -> Array[Step]
+    def build_root_steps: (Array[untyped], Array[RecordSnapshot?]) -> Array[Step]
+
+    # : (untyped) -> Array[untyped]
+    def version_key: (untyped) -> Array[untyped]
+  end
+end

data/sig/generated/paper_trail_diff/activity_version_collector.rbs

@@ -0,0 +1,71 @@
+# Generated from lib/paper_trail_diff/activity_version_collector.rb with RBS::Inline
+
+module PaperTrailDiff
+  # Collects root and selected-descendant versions relevant to one root history range.
+  class ActivityVersionCollector
+    # : (untyped, root_versions: Array[untyped], tree: AssociationTree, traversal: AssociationTraversal, ?range_end: untyped) -> void
+    def initialize: (untyped, root_versions: Array[untyped], tree: AssociationTree, traversal: AssociationTraversal, ?range_end: untyped) -> void
+
+    # : () -> Array[ActivityEvent]
+    def call: () -> Array[ActivityEvent]
+
+    private
+
+    @range: ActivityRange
+
+    @record: untyped
+
+    @registry: ActivityEventRegistry
+
+    @root_versions: Array[untyped]
+
+    @traversal: AssociationTraversal
+
+    @tree: AssociationTree
+
+    # : (untyped, Array[untyped], AssociationTree, path: String, branch: String?) -> void
+    def collect_tree: (untyped, Array[untyped], AssociationTree, path: String, branch: String?) -> void
+
+    # : (Hash[Symbol, untyped], untyped, AssociationTree, String, String) -> void
+    def collect_reflection: (Hash[Symbol, untyped], untyped, AssociationTree, String, String) -> void
+
+    # : (Hash[Symbol, untyped], untyped, String) -> Hash[String, untyped]
+    def edge_groups: (Hash[Symbol, untyped], untyped, String) -> Hash[String, untyped]
+
+    # : (Hash[Symbol, untyped], untyped, String) -> Hash[String, untyped]
+    def through_groups: (Hash[Symbol, untyped], untyped, String) -> Hash[String, untyped]
+
+    # : (untyped, Array[untyped], untyped) -> Hash[String, untyped]
+    def belongs_to_groups: (untyped, Array[untyped], untyped) -> Hash[String, untyped]
+
+    # : (untyped, Array[untyped], untyped) -> Hash[String, untyped]
+    def direct_child_groups: (untyped, Array[untyped], untyped) -> Hash[String, untyped]
+
+    # : (untyped, Array[untyped], untyped) -> Hash[String, untyped]
+    def habtm_groups: (untyped, Array[untyped], untyped) -> Hash[String, untyped]
+
+    # : (Array[untyped], untyped) -> Hash[String, untyped]
+    def identity_groups: (Array[untyped], untyped) -> Hash[String, untyped]
+
+    # : (untyped, Array[untyped]) -> Hash[Symbol, untyped]
+    def group: (untyped, Array[untyped]) -> Hash[Symbol, untyped]
+
+    # : (Hash[String, untyped], Hash[String, untyped]) -> void
+    def merge_groups!: (Hash[String, untyped], Hash[String, untyped]) -> void
+
+    # : (untyped, Array[untyped]) -> Array[untyped]
+    def versions_for: (untyped, Array[untyped]) -> Array[untyped]
+
+    # : (untyped, untyped) -> untyped
+    def target_class: (untyped, untyped) -> untyped
+
+    # : (untyped) -> Array[String?]
+    def related_parent_types: (untyped) -> Array[String?]
+
+    # : (untyped) -> bool
+    def in_range?: (untyped) -> bool
+
+    # : (String, String) -> String
+    def join_path: (String, String) -> String
+  end
+end

data/sig/generated/paper_trail_diff/analysis.rbs

@@ -0,0 +1,18 @@
+# Generated from lib/paper_trail_diff/analysis.rb with RBS::Inline
+
+module PaperTrailDiff
+  # Endpoint and root-checkpoint timeline results built from one normalized history.
+  class Analysis
+    attr_reader diff: Diff
+
+    attr_reader timeline: Array[Step]
+
+    attr_reader activity_timeline: Array[ActivityStep]?
+
+    # : (diff: Diff, timeline: Array[Step], ?activity_timeline: Array[ActivityStep]?) -> void
+    def initialize: (diff: Diff, timeline: Array[Step], ?activity_timeline: Array[ActivityStep]?) -> void
+
+    # : () -> Hash[Symbol, untyped]
+    def to_h: () -> Hash[Symbol, untyped]
+  end
+end