paper_trail_diff 0.3.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4d60569584c3d30bd35c62c1f0f699fd8859545d81f873c926dfdd8268aed3df
-  data.tar.gz: 4961a77099927fff3476641b0409cb234e1f398e9b84e9cb3cc9e11b2d580064
+  metadata.gz: 6aa099f4051971c69ed9b957e68ed4acca7e3cdde7c97efd2cb9a1af90d91dd1
+  data.tar.gz: 67ef88d6978b8b559a1a156f52aaea97a6535c71ec04df5d913f062114ec7a43
 SHA512:
-  metadata.gz: 2cf13bffaca3d199b2332b0e3d1c7c7c00ef7c6f82a4c9e5a75c51f376889ff57c60e1bfab1f578a7122e972698318d2720bce5f8da2755abea50aebf6e7083e
-  data.tar.gz: a071cd71f7fb766105eda1e018991ed8030885822da23382404797984b265818c0012378aea5912a507fb7bc24e9294331201b0cf1918860df3d9613476d580d
+  metadata.gz: d916bf31322056bc95bfe39d7640207f2ddc6b30f154ca8e517b4615558ae728b1642f01040bb793ff1f258b3b77113ab6564f6f24daae9a23b09114ec7a6dca
+  data.tar.gz: b39856d07d0d335d12f7e1855b67f07b2a84443ff799f48a77e9b6a41609547310927fe8b8b69e32add5fbb30711982af3b125a80a40a59b1185a6ae8d1eb4fb

data/CHANGELOG.md

@@ -3,6 +3,21 @@
 All notable changes to this project will be documented in this file. The
 project follows [Semantic Versioning](https://semver.org/).
 
+## [0.3.1] - 2026-08-10
+
+### Fixed
+
+- Preserve immutable activity snapshots for nested events that do not match a
+  selected child record, instead of reporting a false change.
+
+### Changed
+
+- Split activity-event reconstruction, route discovery, relationship matching,
+  collection mutation, and `belongs_to` target application into focused
+  internal collaborators without changing result shapes.
+- Reuse immutable activity-event routes and cached branch components across
+  repeated event types to reduce timeline allocation overhead.
+
 ## [0.3.0] - 2026-08-10
 
 ### Added

data/README.md

@@ -1,5 +1,14 @@
 # paper_trail_diff
 
+> [!WARNING]
+> **Experimental software and AI disclosure:** This gem is experimental and may
+> contain incomplete behavior, reconstruction errors, performance problems, or
+> breaking changes. AI-assisted coding tools made significant contributions to
+> its design, implementation, tests, and documentation under maintainer
+> direction. AI involvement is not a substitute for independent review: audit
+> the code and validate it against your own PaperTrail history before relying on
+> it in production, compliance, security, or other high-stakes workflows.
+
 `paper_trail_diff` adds structured endpoint, checkpoint-timeline, and activity
 comparisons to
 [PaperTrail](https://github.com/paper-trail-gem/paper_trail). It returns immutable

data/lib/paper_trail_diff/activity_belongs_to_event_applier.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # Applies selected non-polymorphic belongs-to target updates to a snapshot.
+  class ActivityBelongsToEventApplier
+    #: (route_finder: ActivityEventRouteFinder, record_resolver: ActivityEventRecordResolver, record_normalizer: ActivityEventRecordNormalizer) -> void
+    def initialize(route_finder:, record_resolver:, record_normalizer:)
+      @route_finder = route_finder
+      @record_resolver = record_resolver
+      @record_normalizer = record_normalizer
+    end
+
+    #: (untyped, untyped, RecordSnapshot, AssociationTree, SnapshotNormalizer, untyped) -> [bool, RecordSnapshot?]
+    def call( # rubocop:disable Metrics/ParameterLists
+      root_endpoint,
+      context_endpoint,
+      previous,
+      tree,
+      normalizer,
+      version
+    )
+      return [false, nil] unless %w[update destroy].include?(version.event.to_s)
+
+      routes = @route_finder.belongs_to_routes(
+        endpoint_model_class(root_endpoint), tree, version.item_type.to_s
+      )
+      return [false, nil] if routes.empty?
+
+      snapshot = previous
+      routes.each do |route|
+        replacement = normalized_route_record(
+          route, version, normalizer, root_endpoint, context_endpoint
+        )
+        snapshot, = replace_route(snapshot, route, version, replacement)
+      end
+      [true, snapshot]
+    end
+
+    private
+
+    # @rbs @route_finder: ActivityEventRouteFinder
+    # @rbs @record_resolver: ActivityEventRecordResolver
+    # @rbs @record_normalizer: ActivityEventRecordNormalizer
+
+    #: (Array[untyped], untyped, SnapshotNormalizer, untyped, untyped) -> RecordSnapshot?
+    def normalized_route_record(route, version, normalizer, root_endpoint, context_endpoint)
+      record = @record_resolver.record_after(version)
+      return unless record
+
+      _name, reflection, subtree, path = route.last
+      @record_normalizer.call(
+        record,
+        reflection: reflection,
+        subtree: subtree,
+        path: path,
+        normalizer: normalizer,
+        root_endpoint: root_endpoint,
+        context_endpoint: context_endpoint
+      )
+    end
+
+    #: (RecordSnapshot, Array[untyped], untyped, RecordSnapshot?, ?depth: Integer) -> [RecordSnapshot, bool]
+    def replace_route(snapshot, route, version, replacement, depth: 0)
+      name, _reflection, _subtree, = route.fetch(depth)
+      association = snapshot.associations.fetch(name)
+      records, changed = replacement_records(
+        association.records, route, version, replacement, depth
+      )
+      return [snapshot, false] unless changed
+
+      updated_association = AssociationSnapshot.new(kind: association.kind, records: records)
+      [replace_association(snapshot, name, updated_association), true]
+    end
+
+    #: (Array[RecordSnapshot], Array[untyped], untyped, RecordSnapshot?, Integer) -> [Array[RecordSnapshot], bool]
+    def replacement_records(records, route, version, replacement, depth)
+      return replace_existing_target(records, version, replacement) if depth == route.length - 1
+
+      changed = false
+      updated = records.map do |record|
+        result, record_changed = replace_route(
+          record, route, version, replacement, depth: depth + 1
+        )
+        changed ||= record_changed
+        result
+      end.freeze
+      [updated, changed]
+    end
+
+    #: (Array[RecordSnapshot], untyped, RecordSnapshot?) -> [Array[RecordSnapshot], bool]
+    def replace_existing_target(records, version, replacement)
+      index = records.index do |record|
+        record.id.to_s == version.item_id.to_s &&
+          record.type.to_s == replacement_type(version, replacement)
+      end
+      return [records, false] unless index
+
+      updated = records.dup
+      replacement ? updated[index] = replacement : updated.delete_at(index)
+      [updated.freeze, true]
+    end
+
+    #: (RecordSnapshot, String, AssociationSnapshot) -> RecordSnapshot
+    def replace_association(snapshot, name, association)
+      RecordSnapshot.new(
+        type: snapshot.type,
+        id: snapshot.id,
+        attributes: snapshot.attributes,
+        associations: snapshot.associations.merge(name => association)
+      )
+    end
+
+    #: (untyped, RecordSnapshot?) -> String
+    def replacement_type(version, replacement)
+      return replacement.type.to_s if replacement
+
+      Endpoint.model_class(version).name.to_s
+    end
+
+    #: (untyped) -> untyped
+    def endpoint_model_class(endpoint)
+      Endpoint.version?(endpoint) ? Endpoint.model_class(endpoint) : endpoint.class
+    end
+  end
+end

data/lib/paper_trail_diff/activity_collection_event_applier.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # Applies a safe collection event across every selected route for its record type.
+  class ActivityCollectionEventApplier
+    #: (record_resolver: ActivityEventRecordResolver, record_normalizer: ActivityEventRecordNormalizer, route_updater: ActivityCollectionRouteUpdater, relationship: ActivityRelationship) -> void
+    def initialize(record_resolver:, record_normalizer:, route_updater:, relationship:)
+      @record_resolver = record_resolver
+      @record_normalizer = record_normalizer
+      @route_updater = route_updater
+      @relationship = relationship
+    end
+
+    #: (Array[Array[untyped]], untyped, ActivitySnapshotDelta?) -> bool
+    def safe?(routes, version, delta)
+      !unsafe_through_membership_event?(routes, version) &&
+        !unsafe_nested_membership_delta?(routes, delta)
+    end
+
+    #: (untyped, untyped, RecordSnapshot, SnapshotNormalizer, Array[Array[untyped]], untyped, ActivitySnapshotDelta?) -> [bool, RecordSnapshot]
+    def call( # rubocop:disable Metrics/ParameterLists
+      root_endpoint,
+      context_endpoint,
+      previous,
+      normalizer,
+      routes,
+      version,
+      delta
+    )
+      fallback_record = [] #: Array[untyped]
+      endpoints = [root_endpoint, context_endpoint]
+      snapshot = routes.reduce(previous) do |current, route|
+        apply_route(
+          current, route, version, delta, fallback_record, normalizer, endpoints
+        )
+      end
+      [true, snapshot]
+    end
+
+    private
+
+    # @rbs @record_resolver: ActivityEventRecordResolver
+    # @rbs @record_normalizer: ActivityEventRecordNormalizer
+    # @rbs @route_updater: ActivityCollectionRouteUpdater
+    # @rbs @relationship: ActivityRelationship
+
+    #: (RecordSnapshot, Array[untyped], untyped, ActivitySnapshotDelta?, Array[untyped], SnapshotNormalizer, Array[untyped]) -> RecordSnapshot
+    def apply_route( # rubocop:disable Metrics/ParameterLists
+      snapshot, route, version, delta, fallback_record, normalizer, endpoints
+    )
+      record, replacement = route_event_state(
+        snapshot, route, version, delta, fallback_record, normalizer, endpoints
+      )
+      change = ActivityCollectionRouteChange.new(
+        route: route,
+        version: version,
+        record: record,
+        replacement: replacement
+      )
+      @route_updater.call(snapshot, change).fetch(0)
+    end
+
+    #: (Array[Array[untyped]], untyped) -> bool
+    def unsafe_through_membership_event?(routes, version)
+      return false if version.event.to_s == 'update'
+
+      routes.any? do |route|
+        route.first(route.length - 1).any? do |entry|
+          entry.fetch(1).options[:through]
+        end
+      end
+    end
+
+    #: (Array[Array[untyped]], ActivitySnapshotDelta?) -> bool
+    def unsafe_nested_membership_delta?(routes, delta)
+      return false unless delta
+
+      routes.any? do |route|
+        route.length > 1 && delta.relationship_changed?(route.last.fetch(1))
+      end
+    end
+
+    #: (RecordSnapshot, Array[untyped], untyped, ActivitySnapshotDelta?, Array[untyped], SnapshotNormalizer, Array[untyped]) -> [untyped, RecordSnapshot?]
+    def route_event_state( # rubocop:disable Metrics/ParameterLists
+      snapshot, route, version, delta, fallback_record, normalizer, endpoints
+    )
+      existing = existing_delta_record(snapshot, route, version, delta) if delta
+      return [delta, delta.apply(existing)] if delta && existing
+
+      fallback_record << @record_resolver.record_after(version) if fallback_record.empty?
+      record = fallback_record.first
+      return [record, nil] unless record
+
+      [record, normalized_event_record(record, route, normalizer, endpoints)]
+    end
+
+    #: (untyped, Array[untyped], SnapshotNormalizer, Array[untyped]) -> RecordSnapshot?
+    def normalized_event_record(record, route, normalizer, endpoints)
+      _name, reflection, subtree, path = route.last
+      @record_normalizer.call(
+        record,
+        reflection: reflection,
+        subtree: subtree,
+        path: path,
+        normalizer: normalizer,
+        root_endpoint: endpoints.fetch(0),
+        context_endpoint: endpoints.fetch(1)
+      )
+    end
+
+    #: (RecordSnapshot, Array[untyped], untyped, ActivitySnapshotDelta?) -> RecordSnapshot?
+    def existing_delta_record(snapshot, route, version, delta)
+      return unless delta && route.length.between?(1, 2)
+
+      owner = route.length == 1 ? snapshot : nested_delta_owner(snapshot, route, delta)
+      return unless owner
+
+      association = owner.associations.fetch(route.last.fetch(0))
+      position = association.position_for_id(version.item_id)
+      association.records.fetch(position) if position
+    end
+
+    #: (RecordSnapshot, Array[untyped], ActivitySnapshotDelta) -> RecordSnapshot?
+    def nested_delta_owner(snapshot, route, delta)
+      parent_name = route.first.fetch(0)
+      reflection = route.last.fetch(1)
+      association = snapshot.associations.fetch(parent_name)
+      owner_id = @relationship.owner_id(delta, reflection, state: :before)
+      position = association.position_for_id(owner_id)
+      return unless position
+
+      owner = association.records.fetch(position)
+      owner if @relationship.member_of_owner?(delta, reflection, owner, state: :before)
+    end
+  end
+end

data/lib/paper_trail_diff/activity_collection_record_updater.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # Applies one event to the leaf records of a collection association snapshot.
+  class ActivityCollectionRecordUpdater
+    #: (ActivityRelationship) -> void
+    def initialize(relationship)
+      @relationship = relationship
+    end
+
+    #: (AssociationSnapshot, ActivityCollectionRouteChange, untyped, RecordSnapshot) -> RecordSnapshot?
+    def event_child(association, change, reflection, owner)
+      version = change.version
+      record = change.record
+      replacement = change.replacement
+      return unless record
+
+      unless record.is_a?(ActivitySnapshotDelta)
+        return replacement if @relationship.member_of_owner?(record, reflection, owner)
+
+        return
+      end
+      unless record.relationship_changed?(reflection)
+        return replacement if association.position_for_id(version.item_id)
+
+        return
+      end
+
+      replacement if @relationship.member_of_owner?(record, reflection, owner)
+    end
+
+    #: (AssociationSnapshot, untyped, RecordSnapshot?) -> [Array[RecordSnapshot], RecordSnapshot?, RecordSnapshot?, bool]
+    def call(association, version, replacement)
+      records = association.records
+      position = association.position(replacement_type(version, replacement), version.item_id)
+      return [records, nil, nil, true] unless replacement || position
+
+      before = records.fetch(position) if position
+      updated = replacement_records(records, position, replacement)
+      [updated, before, replacement, !before.nil? && !replacement.nil?]
+    end
+
+    #: (untyped, RecordSnapshot?) -> String
+    def replacement_type(version, replacement)
+      return replacement.type.to_s if replacement
+
+      Endpoint.model_class(version).name.to_s
+    end
+
+    private
+
+    # @rbs @relationship: ActivityRelationship
+
+    #: (Array[RecordSnapshot], Integer?, RecordSnapshot?) -> Array[RecordSnapshot]
+    def replacement_records(records, position, replacement)
+      updated = records.dup
+      if replacement
+        position ? updated[position] = replacement : updated << replacement
+      else
+        position ||= raise(ConfigurationError, 'missing collection event identity')
+        updated.delete_at(position)
+      end
+      updated.freeze
+    end
+  end
+end

data/lib/paper_trail_diff/activity_collection_route_change.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # Carries one collection event through recursive immutable route replacement.
+  class ActivityCollectionRouteChange
+    attr_reader :route #: Array[untyped]
+    attr_reader :version #: untyped
+    attr_reader :record #: untyped
+    attr_reader :replacement #: RecordSnapshot?
+
+    #: (route: Array[untyped], version: untyped, record: untyped, replacement: RecordSnapshot?) -> void
+    def initialize(route:, version:, record:, replacement:)
+      @route = route
+      @version = version
+      @record = record
+      @replacement = replacement
+      freeze
+    end
+  end
+end

data/lib/paper_trail_diff/activity_collection_route_updater.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # Replaces a collection event record along one explicit immutable snapshot route.
+  class ActivityCollectionRouteUpdater
+    #: (pool: SnapshotPool, relationship: ActivityRelationship) -> void
+    def initialize(pool:, relationship:)
+      @pool = pool
+      @relationship = relationship
+      @record_updater = ActivityCollectionRecordUpdater.new(relationship)
+    end
+
+    #: (RecordSnapshot, ActivityCollectionRouteChange, ?depth: Integer) -> [RecordSnapshot, bool]
+    def call(snapshot, change, depth: 0) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+      name, _reflection, _subtree, path = change.route.fetch(depth)
+      association = snapshot.associations.fetch(name)
+      transition = updated_records(association, snapshot, change, depth)
+      records, before, after, membership_preserved, changed = transition
+      return [snapshot, false] unless changed
+
+      updated_association = @pool.association(
+        path,
+        association.transition_to(
+          records,
+          before: before,
+          after: after,
+          membership_preserved: membership_preserved
+        )
+      )
+      updated_snapshot = replace_association(snapshot, name, updated_association)
+      parent_path = depth.zero? ? '' : change.route.fetch(depth - 1).fetch(3)
+      updated_snapshot = @pool.record(parent_path, updated_snapshot) unless parent_path.empty?
+      [updated_snapshot, true]
+    end
+
+    private
+
+    # @rbs @pool: SnapshotPool
+    # @rbs @relationship: ActivityRelationship
+    # @rbs @record_updater: ActivityCollectionRecordUpdater
+
+    #: (AssociationSnapshot, RecordSnapshot, ActivityCollectionRouteChange, Integer) -> [Array[RecordSnapshot], RecordSnapshot?, RecordSnapshot?, bool, bool]
+    def updated_records(association, owner, change, depth)
+      return leaf_records(association, owner, change) if depth == change.route.length - 1
+
+      targeted = targeted_parent(association, change, depth)
+      if targeted
+        records, before, after, changed = targeted
+        return [records, before, after, true, changed]
+      end
+
+      recursive_records(association, change, depth)
+    end
+
+    #: (AssociationSnapshot, RecordSnapshot, ActivityCollectionRouteChange) -> [Array[RecordSnapshot], RecordSnapshot?, RecordSnapshot?, bool, bool]
+    def leaf_records(association, owner, change)
+      reflection = change.route.last.fetch(1)
+      child = @record_updater.event_child(association, change, reflection, owner)
+      records, before, after, preserved = @record_updater.call(
+        association, change.version, child
+      )
+      [records, before, after, preserved, !records.equal?(association.records)]
+    end
+
+    #: (AssociationSnapshot, ActivityCollectionRouteChange, Integer) -> [Array[RecordSnapshot], RecordSnapshot?, RecordSnapshot?, bool]?
+    def targeted_parent(association, change, depth)
+      return unless depth == change.route.length - 2
+
+      reflection = change.route.fetch(depth + 1).fetch(1)
+      position = nested_owner_position(association, reflection, change)
+      return unless position
+
+      before = association.records.fetch(position)
+      after, changed = call(before, change, depth: depth + 1)
+      targeted_parent_replacement(association.records, position, before, after, changed)
+    end
+
+    #: (AssociationSnapshot, ActivityCollectionRouteChange, Integer) -> [Array[RecordSnapshot], RecordSnapshot?, RecordSnapshot?, bool, bool]
+    def recursive_records(association, change, depth)
+      state = [nil, nil, false] #: [RecordSnapshot?, RecordSnapshot?, bool]
+      records = association.records.map do |child|
+        updated, child_changed = call(child, change, depth: depth + 1)
+        state = recursive_transition(state, child, updated, child_changed)
+        updated
+      end.freeze
+      [records, state.fetch(0), state.fetch(1), true, state.fetch(2)]
+    end
+
+    #: ([RecordSnapshot?, RecordSnapshot?, bool], RecordSnapshot, RecordSnapshot, bool) -> [RecordSnapshot?, RecordSnapshot?, bool]
+    def recursive_transition(state, child, updated, child_changed)
+      return state unless child_changed
+      return [nil, nil, true] if state.fetch(2)
+
+      [child, updated, true]
+    end
+
+    #: (Array[RecordSnapshot], Integer, RecordSnapshot, RecordSnapshot, bool) -> [Array[RecordSnapshot], RecordSnapshot?, RecordSnapshot?, bool]
+    def targeted_parent_replacement(records, position, before, after, changed)
+      return [records, nil, nil, false] unless changed
+
+      updated = records.dup
+      updated[position] = after
+      [updated.freeze, before, after, true]
+    end
+
+    #: (AssociationSnapshot, untyped, ActivityCollectionRouteChange) -> Integer?
+    def nested_owner_position(association, reflection, change)
+      membership_record = change.record || change.version.reify(dup: true)
+      return unless membership_record
+      return if membership_record.is_a?(ActivitySnapshotDelta) &&
+                membership_record.relationship_changed?(reflection)
+
+      owner_id = @relationship.owner_id(membership_record, reflection, state: :after)
+      association.position_for_id(owner_id)
+    end
+
+    #: (RecordSnapshot, String, AssociationSnapshot) -> RecordSnapshot
+    def replace_association(snapshot, name, association)
+      RecordSnapshot.new(
+        type: snapshot.type,
+        id: snapshot.id,
+        attributes: snapshot.attributes,
+        associations: snapshot.associations.merge(name => association)
+      )
+    end
+  end
+end

data/lib/paper_trail_diff/activity_event_record_normalizer.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # Normalizes one event record with the historical reader for its boundary.
+  class ActivityEventRecordNormalizer
+    #: (?association_reader: untyped) -> void
+    def initialize(association_reader: nil)
+      @association_reader = association_reader || method(:historical_reader)
+    end
+
+    #: (untyped, reflection: untyped, subtree: AssociationTree, path: String, normalizer: SnapshotNormalizer, root_endpoint: untyped, context_endpoint: untyped) -> RecordSnapshot?
+    def call( # rubocop:disable Metrics/ParameterLists
+      record,
+      reflection:,
+      subtree:,
+      path:,
+      normalizer:,
+      root_endpoint:,
+      context_endpoint:
+    )
+      boundary = Endpoint.version?(root_endpoint) ? root_endpoint : context_endpoint
+      reifier = @association_reader.call(context_endpoint, habtm_version: boundary)
+      normalizer.call_child(
+        record,
+        tree: subtree,
+        path: path,
+        incoming: reflection,
+        reifier: reifier
+      )
+    end
+
+    private
+
+    # @rbs @association_reader: untyped
+
+    #: (untyped, habtm_version: untyped) -> HistoricalAssociationReifier
+    def historical_reader(context_endpoint, habtm_version:)
+      HistoricalAssociationReifier.new(context_endpoint, habtm_version: habtm_version)
+    end
+  end
+end