paper_trail_diff 0.13.0 → 0.13.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a4e484cc975317987834dd585f1bc5432985575c66b473b1db5c31b3feb4995d
-  data.tar.gz: 127f6d1e5ae63a839be293ea22beb6493108b90f3cbc71d34bdf1814613a54ab
+  metadata.gz: dfe7bccfe2f013af725d6ac92c772d357127d5a0c14cae72fac0000cb58fad62
+  data.tar.gz: 308cc912a32875582ff8e083ec52016d4ca586ee75f3b0e36172360d2600b01d
 SHA512:
-  metadata.gz: 9d65a4239a738367dd8b0536670b2f00cecfae7283db328c87308323fd19d8080fa13eed2a8910d7a0e67a2380f286c65d1b4c943a72bd1903f3d1695b2dfc18
-  data.tar.gz: f316b5892247e31b58a2531dd86073c812327e27bd36f5d4f020efd47d543e280b94ab513467d58a6445173106b89c1378716df471077ee7f1e35fe4bd0999d9
+  metadata.gz: e948b33a959fc8ffdd00d7468819917f126b961c3daa4548f38260315dabab6fa36cddd9019b171c6aad306eae2b09485568591d5f2f07d42ba9a661e93bfd32
+  data.tar.gz: 2ea2cae4b3147f1c4655e79d2ebe2a68202e991f61227718990ec9dcdce38e631f0122ae6fe510aac217ae15f54c1e223095e28148c08944614698a73c3c42dd

data/CHANGELOG.md

@@ -3,6 +3,37 @@
 All notable changes to this project will be documented in this file. The
 project follows [Semantic Versioning](https://semver.org/).
 
+## [0.13.1] - 2026-10-28
+
+### Fixed
+
+- A collection transition whose before and after records have different
+  identities reports the before record as removed and the after record as
+  added. It used to report nothing. No current caller builds one, but
+  `AssociationSnapshot#transition_to` accepts it.
+- A record with a composite primary key, read from prepared history, gets the
+  same id as when it is read live: the key's values. It was `nil`.
+
+### Changed
+
+- `RecordSnapshot.new` requires `type:` to be a String and raises
+  `ArgumentError` otherwise. It used to convert any value with `to_s`.
+
+### Development
+
+- Mutation testing gives each mutation 60 seconds instead of mutant's 5-second
+  default. Mutant counts a timeout as a kill, so mutations no spec caught were
+  reported as caught. With the longer limit, 123 surfaced in
+  `CollectionComparator` and `CollectionIdentityIndex`; each class now has a
+  unit spec, and all of them are caught.
+- Mutation testing also covers `SnapshotNormalizer`, `SnapshotPool`,
+  `TimelineRange`, `RootVersionPlan`, and `HistoricalFilter`, each with a unit
+  spec of its own; all 4,040 mutations across the nine classes are caught.
+  Versions are ordered by time and then id through one shared helper.
+- The full mutation run moves to a nightly workflow that runs only when `main`
+  has an untested commit, so a later push no longer cancels it. Pull requests
+  still mutate the methods they change.
+
 ## [0.13.0] - 2026-10-28
 
 ### Breaking changes

data/docs/testing.md

@@ -39,12 +39,35 @@ variant here when a bug turns out to depend on a schema or configuration.
 
 ## Mutation testing
 
-[Mutant](https://github.com/mbj/mutant) changes the comparison code one
-expression at a time and expects a spec to fail each time. A change that every
-spec still passes is behavior nothing checks. `mutant.yml` lists the classes it
-mutates: `Engine`, `CollectionComparator`, `CollectionIdentityIndex`, and
-`NestedComparator`, which decide what counts as a change. It runs the
-association suite, which reaches all of their paths.
+[Mutant](https://github.com/mbj/mutant) changes the library one expression at
+a time and expects a spec to fail each time. A change that every spec still
+passes is behavior nothing checks. `mutant.yml` lists the classes it mutates:
+
+- what counts as a change: `Engine`, `CollectionComparator`,
+  `CollectionIdentityIndex`, and `NestedComparator`;
+- which columns are compared: `SnapshotNormalizer` and `SnapshotPool`;
+- which history a range or filter reads: `TimelineRange`, `RootVersionPlan`,
+  and `HistoricalFilter`.
+
+The specs for the classes that read the database use tables of their own
+(`spec/support/filter_database.rb`, `spec/support/normalizer_database.rb`), so
+they run in both the core and the association suite.
+
+Mutant does not run every spec for every mutation. It runs the specs whose
+description names the mutated class (`RSpec.describe PaperTrailDiff::Engine`),
+and only falls back to wider names such as `PaperTrailDiff` when none does. A
+spec named after a behavior, as most integration specs are, never runs. So
+each mutated class has a unit spec of its own that catches every mutation in
+it, and a class added to `mutant.yml` needs one too.
+
+Mutant counts a mutation that runs past its time limit as caught, so
+`mutant.yml` sets the limit well above the time the whole suite takes. With
+mutant's 5-second default, mutations no spec caught were reported as caught.
+
+In CI, a pull request mutates only the methods it changes. The full set runs
+nightly in `.github/workflows/mutation.yml`, and only when `main` has a commit
+that has not passed yet. Start it by hand from the Actions tab with "Run
+workflow".
 
 Mutant needs Ruby 3.3 or newer, so it has its own bundle:
 
@@ -63,8 +86,8 @@ BUNDLE_GEMFILE=gemfiles/mutant.gemfile mise exec -- bundle exec mutant run --sin
 
 When a mutation survives, either add the spec that would catch it, or, if the
 mutated code means the same thing, simplify the code to that form. Reserve a
-`mutant:disable` comment for a method whose mutations all mean the same thing,
-and say why next to it. Mutant forks a worker per CPU; `spec/support/mutant_hooks.rb`
+`mutant:disable` comment for a method whose surviving mutations all mean the
+same thing as the code, and say why next to it. Mutant forks a worker per CPU; `spec/support/mutant_hooks.rb`
 gives each worker its own copy of the SQLite fixture database.
 
 ## Test clock

data/lib/paper_trail_diff/batched_root_versions.rb

@@ -125,7 +125,7 @@ module PaperTrailDiff
 
     #: (untyped) -> Array[untyped]
     def ordered(relation)
-      relation.reorder(created_at: :asc, id: :asc).to_a
+      VersionQuery.chronological(relation).to_a
     end
 
     #: (untyped, untyped) -> Array[String]

data/lib/paper_trail_diff/collection_comparator.rb

@@ -28,25 +28,21 @@ module PaperTrailDiff
     # @rbs @to: AssociationSnapshot
     # @rbs @record_comparer: untyped
 
+    # A transition names the one record that changed between adjacent
+    # snapshots. With matching identities it is an update; otherwise the
+    # before record left and the after record joined.
     #: (CollectionTransition) -> CollectionAssociationDiff
     def transition_difference(transition)
       @from.validate_unique_identities!
       @to.validate_unique_identities!
       before = transition.before
       after = transition.after
-      changed = compare_transition_records(before, after)
-      difference(
-        added: before.nil? && after ? [after] : [],
-        removed: after.nil? && before ? [before] : [],
-        changed: changed ? [changed] : []
-      )
-    end
-
-    #: (RecordSnapshot?, RecordSnapshot?) -> RecordChange?
-    def compare_transition_records(before, after)
-      return unless before && after && before.identity == after.identity
+      if before && after && before.identity == after.identity
+        change = @record_comparer.call(before, after)
+        return difference(added: [], removed: [], changed: change ? [change] : [])
+      end
 
-      @record_comparer.call(before, after)
+      difference(added: [after].compact, removed: [before].compact, changed: [])
     end
 
     #: () -> Array[RecordChange]?
@@ -70,17 +66,16 @@ module PaperTrailDiff
 
     #: (Array[RecordSnapshot], Array[RecordSnapshot]) -> Array[[RecordSnapshot, RecordSnapshot]]?
     def collect_aligned_pairs(from_records, to_records)
-      seen = {} #: Hash[identity, bool]
+      seen = Set.new #: Set[identity]
       changed = [] #: Array[[RecordSnapshot, RecordSnapshot]]
       index = 0
       while index < from_records.length
         from_record = from_records.fetch(index)
         to_record = to_records.fetch(index)
         identity = from_record.identity
-        raise_duplicate_identity!(identity) if seen.key?(identity)
+        raise_duplicate_identity!(identity) unless seen.add?(identity)
         return unless identity == to_record.identity
 
-        seen[identity] = true
         changed << [from_record, to_record] unless from_record.equal?(to_record)
         index += 1
       end
@@ -148,21 +143,24 @@ module PaperTrailDiff
     # result is rendered.
     #: (identity) -> Array[untyped]
     def sortable_identity(identity)
-      [identity.fetch(0), *sortable_id(identity.fetch(1))]
+      [identity.fetch(0), sortable_id(identity.fetch(1))]
     end
 
+    # Only the order of the group numbers matters, so moving the lowest one
+    # down or the highest one up changes nothing; the spec checks the order.
+    # mutant:disable
     #: (untyped) -> Array[untyped]
     def sortable_id(id)
       case id
-      when Numeric then [0, id, '']
-      when String, Symbol then [1, 0, id.to_s]
-      else [2, 0, id.inspect]
+      when Numeric then [0, id]
+      when String, Symbol then [1, id.to_s]
+      else [2, id.inspect]
       end
     end
 
     #: (identity) -> void
     def raise_duplicate_identity!(identity)
-      raise ArgumentError, "duplicate record identity: #{identity.inspect}"
+      raise ArgumentError, "duplicate record identity: #{identity}"
     end
   end
 end

data/lib/paper_trail_diff/collection_identity_index.rb

@@ -6,19 +6,16 @@ module PaperTrailDiff
   class CollectionIdentityIndex
     #: (Array[untyped]) -> void
     def initialize(records)
-      @positions = {} #: Hash[Array[untyped], Integer]
+      @identities = Set.new #: Set[Array[untyped]]
       @serialized_positions = {} #: Hash[Array[String], Integer]
       @id_positions = {} #: Hash[String, Integer?]
       records.each_with_index { |record, index| register(record, index) }
-      @positions.freeze
-      @serialized_positions.freeze
-      @id_positions.freeze
       freeze
     end
 
-    #: (untyped, untyped) -> Integer?
+    #: (String, untyped) -> Integer?
     def position(type, id)
-      @serialized_positions[[type.to_s, id.to_s]]
+      @serialized_positions[[type, id.to_s]]
     end
 
     #: (untyped) -> Integer?
@@ -28,26 +25,25 @@ module PaperTrailDiff
 
     private
 
-    # @rbs @positions: Hash[Array[untyped], Integer]
+    # @rbs @identities: Set[Array[untyped]]
     # @rbs @serialized_positions: Hash[Array[String], Integer]
     # @rbs @id_positions: Hash[String, Integer?]
 
     #: (untyped, Integer) -> void
     def register(record, index)
       identity = record.identity
-      if @positions.key?(identity)
-        raise ArgumentError, "duplicate record identity: #{identity.inspect}"
+      unless @identities.add?(identity)
+        raise ArgumentError, "duplicate record identity: #{identity}"
       end
 
-      @positions[identity] = index
-      @serialized_positions[[record.type.to_s, record.id.to_s]] = index
+      @serialized_positions[[record.type, record.id.to_s]] = index
       register_id(record.id, index)
     end
 
     #: (untyped, Integer) -> void
     def register_id(id, index)
       key = id.to_s
-      @id_positions[key] = @id_positions.key?(key) ? nil : index
+      @id_positions[key] = (index unless @id_positions.key?(key))
     end
   end
 end

data/lib/paper_trail_diff/deleted_analysis_batch.rb

@@ -64,9 +64,10 @@ module PaperTrailDiff
 
     #: () -> Array[untyped]
     def destroy_versions
-      versions = @model.paper_trail.version_class.where(
+      destroys = @model.paper_trail.version_class.where(
         item_type: @model.base_class.name, item_id: @identities.map(&:last), event: 'destroy'
-      ).reorder(created_at: :asc, id: :asc)
+      )
+      versions = VersionQuery.chronological(destroys)
       versions.group_by { |version| version.item_id.to_s }.values.map do |history|
         Support.chronological_sort(history).last
       end

data/lib/paper_trail_diff/historical_filter.rb

@@ -69,7 +69,7 @@ module PaperTrailDiff
 
     #: (untyped) -> Integer
     def validate_budget(value)
-      return value if value.is_a?(Integer) && value.positive?
+      return value if value.instance_of?(Integer) && value.positive?
 
       raise ConfigurationError, 'max_filter_versions: must be a positive Integer'
     end
@@ -80,13 +80,13 @@ module PaperTrailDiff
                                                         item_id: ids)
       range = @time_range
       relation = range.scope(relation) if range
-      versions = relation.reorder(created_at: :asc, id: :asc)
-                         .limit(@max_versions - @loaded + 1).to_a
+      # One past the remaining budget is enough to know it was exceeded.
+      versions = VersionQuery.chronological(relation).limit(@max_versions - @loaded + 1)
       account_versions!(versions.length)
       versions.group_by { |version| version.item_id.to_s }
     end
 
-    #: (Array[untyped], untyped) -> bool
+    #: (Array[untyped], untyped) -> boolish
     def held?(versions, closing)
       return true if versions.any? { |version| matches?(version) }
       return false unless closing
@@ -97,9 +97,7 @@ module PaperTrailDiff
     # What each candidate held after its last change in the window.
     #: (Array[String], Hash[String, Array[untyped]]) -> Hash[String, untyped]
     def closing_states(ids, versions)
-      open = ids.reject { |id| versions.fetch(id, []).last&.event.to_s == 'destroy' }
-      return {} if open.empty?
-
+      open = ids.reject { |id| versions.fetch(id, []).last&.event == 'destroy' }
       trailing = trailing_versions(open)
       trailing.merge(live_records(open - trailing.keys))
     end
@@ -118,15 +116,12 @@ module PaperTrailDiff
 
     #: (Array[String]) -> Hash[String, untyped]
     def live_records(ids)
-      return {} if ids.empty?
-
-      @model.base_class.unscoped.where(@model.primary_key => ids).to_a
-            .to_h { |record| [record.id.to_s, record] }
+      @model.unscoped.where(@model.primary_key => ids).to_h { |record| [record.id.to_s, record] }
     end
 
-    #: (untyped) -> bool
+    #: (untyped) -> boolish
     def record_matches?(record)
-      return !!@predicate.call(record) unless @predicate.is_a?(Hash)
+      return @predicate.call(record) unless @predicate.instance_of?(Hash)
 
       @predicate.all? { |name, expected| record.attributes.fetch(name) == expected }
     end
@@ -141,16 +136,16 @@ module PaperTrailDiff
             'narrow the window or explicitly increase the version budget'
     end
 
-    #: (untyped) -> bool
+    #: (untyped) -> boolish
     def matches?(version)
-      if @predicate.is_a?(Hash)
+      if @predicate.instance_of?(Hash)
         return false unless version.object
 
         return attributes_match?(version)
       end
 
       state = version.reify(dup: true)
-      !!(state && @predicate.call(state))
+      state && @predicate.call(state)
     end
 
     #: (untyped) -> bool
@@ -167,7 +162,7 @@ module PaperTrailDiff
                 "historical_filter: #{name} was not recorded in version #{version.id}"
         end
 
-        state.model_class.type_for_attribute(name).cast(state.attributes.fetch(name)) == expected
+        state.attributes.fetch(name) == expected
       end
     end
 

data/lib/paper_trail_diff/root_version_plan.rb

@@ -72,7 +72,7 @@ module PaperTrailDiff
       @steps = steps.freeze
       @context_version = context_version
       @mutations = (mutations || default_mutations).freeze
-      @mutation_keys = Set.new(@mutations.map { |version| key(version) }).freeze
+      @mutation_keys = key_set(@mutations)
       freeze
     end
 
@@ -114,6 +114,15 @@ module PaperTrailDiff
       @versions.reject { |version| key(version) == context }
     end
 
+    # A Set only makes the lookup in `mutation?` fast; an Array would answer the
+    # same, which is why mutant leaves this alone.
+    # mutant:disable
+    #: (Array[untyped]) -> Set[Array[untyped]]
+    def key_set(versions)
+      Set.new(versions.map { |version| key(version) })
+    end
+
+    # By class name, so a version still matches after its class is reloaded.
     #: (untyped) -> Array[untyped]
     def key(version)
       [version.class.name, version.id]

data/lib/paper_trail_diff/snapshot.rb

@@ -171,7 +171,11 @@ module PaperTrailDiff
 
     #: (type: String, id: untyped, attributes: snapshot_attributes, ?associations: snapshot_associations) -> void
     def initialize(type:, id:, attributes:, associations: {})
-      @type = Support.immutable_copy(type.to_s)
+      unless type.is_a?(String)
+        raise ArgumentError, "record type must be a String, not #{type.inspect}"
+      end
+
+      @type = Support.immutable_copy(type)
       @id = Support.immutable_copy(id)
       @identity = [@type, @id].freeze
       @attributes = normalize_hash(attributes)

data/lib/paper_trail_diff/snapshot_normalizer.rb

@@ -21,9 +21,7 @@ module PaperTrailDiff
     #: (String, AssociationSnapshot) -> AssociationSnapshot
     def association(path, snapshot)
       previous = @associations[path]
-      if previous && previous.kind == snapshot.kind && previous.records == snapshot.records
-        return previous
-      end
+      return previous if previous && same_association?(previous, snapshot)
 
       @associations[path] = snapshot
     end
@@ -38,10 +36,14 @@ module PaperTrailDiff
       left.attributes == right.attributes &&
         left.associations.keys == right.associations.keys &&
         left.associations.all? do |name, association|
-          other = right.associations[name]
-          other && association.kind == other.kind && association.records == other.records
+          same_association?(association, right.associations.fetch(name))
         end
     end
+
+    #: (AssociationSnapshot, AssociationSnapshot) -> bool
+    def same_association?(left, right)
+      left.kind == right.kind && left.records == right.records
+    end
   end
 
   # Converts an ActiveRecord graph into immutable, persistence-independent snapshots.
@@ -53,11 +55,13 @@ module PaperTrailDiff
       @traversal = traversal
       @pool = pool
       @structural_columns = {} #: Hash[String, Array[String]]
-      @excluded_attributes = {} #: Hash[Array[untyped], Array[String]]
+      @excluded_attributes = {} #: Hash[Array[untyped], Array[String?]]
     end
 
     #: (untyped, reifier: untyped) -> RecordSnapshot?
     def call(record, reifier:)
+      return unless record
+
       reflections = reflections_for(record, @tree, '')
       normalize_record(record, @tree, '', reifier, reflections)
     end
@@ -76,7 +80,7 @@ module PaperTrailDiff
     # Normalizes scalar attributes without traversing or loading associations.
     #: (untyped, tree: AssociationTree, path: String) -> snapshot_attributes
     def attributes_for(record, tree:, path:)
-      if record.is_a?(PreparedRecordState)
+      if record.instance_of?(PreparedRecordState)
         return from_state(record, tree: tree,
                                   path: path).attributes
       end
@@ -94,7 +98,7 @@ module PaperTrailDiff
       excluded = @excluded_attributes[[model, path]] ||=
         build_excluded_attributes(model, reflections, path)
       snapshot = RecordSnapshot.new(
-        type: model.name, id: state.attributes[model.primary_key],
+        type: model.name, id: state_id(model, state),
         attributes: state.attributes.except(*excluded), associations: associations
       )
       pool_state(path, snapshot)
@@ -102,6 +106,14 @@ module PaperTrailDiff
 
     private
 
+    # The id a live record of the same row reports: one value, or one per
+    # column of a composite key.
+    #: (untyped, PreparedRecordState) -> untyped
+    def state_id(model, state)
+      key = model.primary_key
+      key.instance_of?(Array) ? state.attributes.fetch_values(*key) : state.attributes.fetch(key)
+    end
+
     #: (String, RecordSnapshot) -> RecordSnapshot
     def pool_state(path, snapshot)
       path.empty? ? snapshot : @pool.record(path, snapshot)
@@ -112,12 +124,10 @@ module PaperTrailDiff
     # @rbs @traversal: AssociationTraversal
     # @rbs @pool: SnapshotPool
     # @rbs @structural_columns: Hash[String, Array[String]]
-    # @rbs @excluded_attributes: Hash[Array[untyped], Array[String]]
+    # @rbs @excluded_attributes: Hash[Array[untyped], Array[String?]]
 
-    #: (untyped, AssociationTree, String, untyped, Array[untyped]) -> RecordSnapshot?
+    #: (untyped, AssociationTree, String, untyped, Array[untyped]) -> RecordSnapshot
     def normalize_record(record, tree, path, reifier, reflections)
-      return unless record
-
       snapshot = RecordSnapshot.new(
         type: record.class.name,
         id: record.id,
@@ -129,7 +139,7 @@ module PaperTrailDiff
 
     #: (untyped, Array[untyped], String) -> snapshot_attributes
     def normalized_attributes(record, reflections, path)
-      attributes = record.attributes.dup
+      attributes = record.attributes
       excluded_attributes(record, reflections, path).each { |name| attributes.delete(name) }
       StoredTimePrecision.apply(attributes, StoredTimePrecision.digits(record.class))
     end
@@ -137,23 +147,20 @@ module PaperTrailDiff
     # 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]
+    #: (untyped, Array[untyped], String) -> Array[String?]
     def excluded_attributes(record, reflections, path)
       model_class = record.class
       @excluded_attributes[[model_class, path]] ||=
         build_excluded_attributes(model_class, reflections, path)
     end
 
-    #: (untyped, Array[untyped], String) -> Array[String]
+    #: (untyped, Array[untyped], String) -> Array[String?]
     def build_excluded_attributes(model_class, reflections, path)
-      primary_key = model_class.primary_key #: untyped
-      primary_keys = primary_key.is_a?(Array) ? primary_key : [primary_key]
-      # @type var primary_keys: Array[untyped]
-      primary_keys = primary_keys.map { |key| key.to_s } # rubocop:disable Style/SymbolProc
+      primary_keys = Array(model_class.primary_key) #: Array[String]
       ignored = @ignore_policy.attributes_for(path)
       structural = @structural_columns.fetch(path, [])
-      (primary_keys + ignored + skipped_columns(model_class) +
-        relationship_columns(reflections) + structural).uniq.freeze
+      primary_keys + ignored + skipped_columns(model_class) +
+        relationship_columns(reflections) + structural
     end
 
     # `has_paper_trail skip:` columns are never written to a version, so history
@@ -163,18 +170,17 @@ module PaperTrailDiff
     def skipped_columns(model_class)
       return [] unless Support.versioned?(model_class)
 
-      entries = Array(model_class.paper_trail_options[:skip]) #: Array[untyped]
-      entries.flat_map do |entry|
-        entry.is_a?(Hash) ? entry.keys.map(&:to_s) : [entry.to_s]
-      end
+      # PaperTrail stores these as strings, or hashes keyed by strings.
+      entries = model_class.paper_trail_options.fetch(:skip) #: Array[untyped]
+      entries.flat_map { |entry| entry.instance_of?(Hash) ? entry.keys : entry }
     end
 
-    #: (Array[untyped]) -> Array[String]
+    # A non-polymorphic reflection has no foreign type, so it adds nil, which
+    # excludes nothing.
+    #: (Array[untyped]) -> Array[String?]
     def relationship_columns(reflections)
       reflections.select { |reflection| reflection.macro == :belongs_to }.flat_map do |reflection|
-        columns = [reflection.foreign_key.to_s]
-        columns << reflection.foreign_type.to_s if reflection.polymorphic?
-        columns
+        [reflection.foreign_key, reflection.foreign_type]
       end
     end
 
@@ -182,27 +188,20 @@ module PaperTrailDiff
     def normalize_associations(record, tree, path, reifier, reflections)
       reflections.to_h do |reflection|
         name = reflection.name.to_s
-        subtree = tree.child(name)
-        raise ConfigurationError, "missing traversal subtree: #{name}" unless subtree
-
-        [name, association_snapshot(record, reflection, subtree, path, reifier)]
+        [name, association_snapshot(record, reflection, tree.children.fetch(name), path, reifier)]
       end
     end
 
     #: (untyped, untyped, AssociationTree, String, untyped) -> AssociationSnapshot
-    def association_snapshot( # rubocop:disable Metrics/AbcSize
+    def association_snapshot(
       record,
       reflection,
       subtree,
       path,
       reifier
     )
-      associated = record.public_send(reflection.name)
-      records = if AssociationSnapshot.collection_kind?(reflection.macro)
-                  associated.to_a
-                else
-                  Array(associated).compact
-                end
+      # A reified history can hold a member PaperTrail could not rebuild.
+      records = Array(record.public_send(reflection.name)).compact
       child_path = Support.association_path(path, reflection.name.to_s)
       @structural_columns[child_path] ||= @traversal.incoming_relationship_columns(reflection)
       snapshot = AssociationSnapshot.new(
@@ -214,10 +213,9 @@ module PaperTrailDiff
 
     #: (Array[untyped], AssociationTree, String, untyped) -> Array[RecordSnapshot]
     def normalize_children(records, tree, path, reifier)
-      reflections_by_class = {} #: Hash[String, Array[untyped]]
-      records.filter_map do |child|
-        type = child.class.name
-        reflections = reflections_by_class[type] ||= reflections_for(child, tree, path)
+      reflections_by_class = {} #: Hash[untyped, Array[untyped]]
+      records.map do |child|
+        reflections = reflections_by_class[child.class] ||= reflections_for(child, tree, path)
         reifier.reify(child, reflections) unless reflections.empty?
         normalize_record(child, tree, path, reifier, reflections)
       end
@@ -225,8 +223,6 @@ module PaperTrailDiff
 
     #: (untyped, AssociationTree, String) -> Array[untyped]
     def reflections_for(record, tree, path)
-      return [] unless record
-
       @traversal.reflections_for(record.class, tree, path: path)
     end
   end

data/lib/paper_trail_diff/time_range.rb

@@ -53,8 +53,7 @@ module PaperTrailDiff
       first_after = VersionQuery.no_earlier_version(table) do |earlier|
         after_end(earlier[:created_at])
       end
-      versions = trailing_scope(relation).where(first_after)
-                                         .reorder(created_at: :asc, id: :asc).to_a
+      versions = VersionQuery.chronological(trailing_scope(relation).where(first_after)).to_a
       first = {} #: Hash[String, untyped]
       versions.each { |version| first[version.item_id.to_s] ||= version }
       first

data/lib/paper_trail_diff/time_version_range.rb

@@ -37,7 +37,7 @@ module PaperTrailDiff
 
     #: (untyped) -> untyped
     def trailing_version(relation)
-      @time_range.trailing_scope(relation).reorder(created_at: :asc, id: :asc).first
+      VersionQuery.chronological(@time_range.trailing_scope(relation)).first
     end
 
     #: (Array[untyped]) -> Array[untyped]

data/lib/paper_trail_diff/timeline_range.rb

@@ -30,10 +30,11 @@ module PaperTrailDiff
     end
 
     # A record with no versions has no first boundary to resolve, which
-    # is an empty history rather than a bad request.
+    # is an empty history rather than a bad request. Both endpoints are
+    # required, so only `:first` can resolve to nothing; a window has none.
     #: () -> bool
     def unresolved?
-      (symbolic?(@requested_from) && @from.nil?) || (symbolic?(@requested_to) && @to.nil?)
+      !time? && (@from.nil? || @to.nil?)
     end
 
     # A batch may have selected these versions already, in which case reselecting
@@ -97,7 +98,7 @@ module PaperTrailDiff
 
     #: (untyped) -> bool
     def symbolic?(boundary)
-      boundary.is_a?(Symbol)
+      boundary.instance_of?(Symbol)
     end
 
     # Resolving `:first` here keeps callers from depending on the
@@ -118,7 +119,7 @@ module PaperTrailDiff
 
     #: () -> untyped
     def ordered_versions
-      Endpoint.versions(@record).reorder(created_at: :asc, id: :asc)
+      VersionQuery.chronological(Endpoint.versions(@record))
     end
 
     #: (untyped) -> TimeRange?

data/lib/paper_trail_diff/version.rb

@@ -2,5 +2,5 @@
 # rbs_inline: enabled
 
 module PaperTrailDiff
-  VERSION = '0.13.0'
+  VERSION = '0.13.1'
 end

data/lib/paper_trail_diff/version_query.rb

@@ -2,10 +2,18 @@
 # rbs_inline: enabled
 
 module PaperTrailDiff
-  # Arel conditions shared by the version queries that need one row per item.
+  # Query pieces shared by version lookups.
   module VersionQuery
     module_function
 
+    # Oldest first. Ids break ties between versions written in the same
+    # instant, and the timestamp comes first because ids need not follow time:
+    # a UUID key does not.
+    #: (untyped) -> untyped
+    def chronological(relation)
+      relation.reorder(created_at: :asc, id: :asc)
+    end
+
     # Keeps each item's earliest version among those the block also accepts:
     # no other version of the same item that the block accepts is earlier. A
     # correlated NOT EXISTS stays portable where window functions are not.

data/sig/generated/paper_trail_diff/collection_comparator.rbs

@@ -17,12 +17,12 @@ module PaperTrailDiff
 
     @to: AssociationSnapshot
 
+    # A transition names the one record that changed between adjacent
+    # snapshots. With matching identities it is an update; otherwise the
+    # before record left and the after record joined.
     # : (CollectionTransition) -> CollectionAssociationDiff
     def transition_difference: (CollectionTransition) -> CollectionAssociationDiff
 
-    # : (RecordSnapshot?, RecordSnapshot?) -> RecordChange?
-    def compare_transition_records: (RecordSnapshot?, RecordSnapshot?) -> RecordChange?
-
     # : () -> Array[RecordChange]?
     def aligned_changes: () -> Array[RecordChange]?
 
@@ -57,6 +57,9 @@ module PaperTrailDiff
     # : (identity) -> Array[untyped]
     def sortable_identity: (identity) -> Array[untyped]
 
+    # Only the order of the group numbers matters, so moving the lowest one
+    # down or the highest one up changes nothing; the spec checks the order.
+    # mutant:disable
     # : (untyped) -> Array[untyped]
     def sortable_id: (untyped) -> Array[untyped]
 

data/sig/generated/paper_trail_diff/collection_identity_index.rbs

@@ -6,8 +6,8 @@ module PaperTrailDiff
     # : (Array[untyped]) -> void
     def initialize: (Array[untyped]) -> void
 
-    # : (untyped, untyped) -> Integer?
-    def position: (untyped, untyped) -> Integer?
+    # : (String, untyped) -> Integer?
+    def position: (String, untyped) -> Integer?
 
     # : (untyped) -> Integer?
     def position_for_id: (untyped) -> Integer?
@@ -16,7 +16,7 @@ module PaperTrailDiff
 
     @id_positions: Hash[String, Integer?]
 
-    @positions: Hash[Array[untyped], Integer]
+    @identities: Set[Array[untyped]]
 
     @serialized_positions: Hash[Array[String], Integer]
 

data/sig/generated/paper_trail_diff/historical_filter.rbs

@@ -44,8 +44,8 @@ module PaperTrailDiff
     # : (Array[String]) -> Hash[String, Array[untyped]]
     def candidate_versions: (Array[String]) -> Hash[String, Array[untyped]]
 
-    # : (Array[untyped], untyped) -> bool
-    def held?: (Array[untyped], untyped) -> bool
+    # : (Array[untyped], untyped) -> boolish
+    def held?: (Array[untyped], untyped) -> boolish
 
     # What each candidate held after its last change in the window.
     # : (Array[String], Hash[String, Array[untyped]]) -> Hash[String, untyped]
@@ -57,14 +57,14 @@ module PaperTrailDiff
     # : (Array[String]) -> Hash[String, untyped]
     def live_records: (Array[String]) -> Hash[String, untyped]
 
-    # : (untyped) -> bool
-    def record_matches?: (untyped) -> bool
+    # : (untyped) -> boolish
+    def record_matches?: (untyped) -> boolish
 
     # : (Integer) -> void
     def account_versions!: (Integer) -> void
 
-    # : (untyped) -> bool
-    def matches?: (untyped) -> bool
+    # : (untyped) -> boolish
+    def matches?: (untyped) -> boolish
 
     # : (untyped) -> bool
     def attributes_match?: (untyped) -> bool

data/sig/generated/paper_trail_diff/root_version_plan.rbs

@@ -73,6 +73,13 @@ module PaperTrailDiff
     # : () -> Array[untyped]
     def default_mutations: () -> Array[untyped]
 
+    # A Set only makes the lookup in `mutation?` fast; an Array would answer the
+    # same, which is why mutant leaves this alone.
+    # mutant:disable
+    # : (Array[untyped]) -> Set[Array[untyped]]
+    def key_set: (Array[untyped]) -> Set[Array[untyped]]
+
+    # By class name, so a version still matches after its class is reloaded.
     # : (untyped) -> Array[untyped]
     def key: (untyped) -> Array[untyped]
   end

data/sig/generated/paper_trail_diff/snapshot_normalizer.rbs

@@ -19,6 +19,9 @@ module PaperTrailDiff
 
     # : (RecordSnapshot, RecordSnapshot) -> bool
     def equivalent_record?: (RecordSnapshot, RecordSnapshot) -> bool
+
+    # : (AssociationSnapshot, AssociationSnapshot) -> bool
+    def same_association?: (AssociationSnapshot, AssociationSnapshot) -> bool
   end
 
   # Converts an ActiveRecord graph into immutable, persistence-independent snapshots.
@@ -43,10 +46,15 @@ module PaperTrailDiff
 
     private
 
+    # The id a live record of the same row reports: one value, or one per
+    # column of a composite key.
+    # : (untyped, PreparedRecordState) -> untyped
+    def state_id: (untyped, PreparedRecordState) -> untyped
+
     # : (String, RecordSnapshot) -> RecordSnapshot
     def pool_state: (String, RecordSnapshot) -> RecordSnapshot
 
-    @excluded_attributes: Hash[Array[untyped], Array[String]]
+    @excluded_attributes: Hash[Array[untyped], Array[String?]]
 
     @ignore_policy: IgnorePolicy
 
@@ -58,8 +66,8 @@ module PaperTrailDiff
 
     @tree: AssociationTree
 
-    # : (untyped, AssociationTree, String, untyped, Array[untyped]) -> RecordSnapshot?
-    def normalize_record: (untyped, AssociationTree, String, untyped, Array[untyped]) -> RecordSnapshot?
+    # : (untyped, AssociationTree, String, untyped, Array[untyped]) -> RecordSnapshot
+    def normalize_record: (untyped, AssociationTree, String, untyped, Array[untyped]) -> RecordSnapshot
 
     # : (untyped, Array[untyped], String) -> snapshot_attributes
     def normalized_attributes: (untyped, Array[untyped], String) -> snapshot_attributes
@@ -67,11 +75,11 @@ module PaperTrailDiff
     # 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 excluded_attributes: (untyped, Array[untyped], String) -> Array[String?]
 
-    # : (untyped, Array[untyped], String) -> Array[String]
-    def build_excluded_attributes: (untyped, Array[untyped], String) -> Array[String]
+    # : (untyped, Array[untyped], String) -> Array[String?]
+    def build_excluded_attributes: (untyped, Array[untyped], String) -> Array[String?]
 
     # `has_paper_trail skip:` columns are never written to a version, so history
     # holds only their defaults. Compared with a live row they would report a
@@ -79,8 +87,10 @@ module PaperTrailDiff
     # : (untyped) -> Array[String]
     def skipped_columns: (untyped) -> Array[String]
 
-    # : (Array[untyped]) -> Array[String]
-    def relationship_columns: (Array[untyped]) -> Array[String]
+    # A non-polymorphic reflection has no foreign type, so it adds nil, which
+    # excludes nothing.
+    # : (Array[untyped]) -> Array[String?]
+    def relationship_columns: (Array[untyped]) -> Array[String?]
 
     # : (untyped, AssociationTree, String, untyped, Array[untyped]) -> Hash[String, AssociationSnapshot]
     def normalize_associations: (untyped, AssociationTree, String, untyped, Array[untyped]) -> Hash[String, AssociationSnapshot]

data/sig/generated/paper_trail_diff/timeline_range.rbs

@@ -19,7 +19,8 @@ module PaperTrailDiff
     def initialize: (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped, ?plan: RootVersionPlan?, ?live_endpoint: untyped) -> void
 
     # A record with no versions has no first boundary to resolve, which
-    # is an empty history rather than a bad request.
+    # is an empty history rather than a bad request. Both endpoints are
+    # required, so only `:first` can resolve to nothing; a window has none.
     # : () -> bool
     def unresolved?: () -> bool
 

data/sig/generated/paper_trail_diff/version_query.rbs

@@ -1,8 +1,14 @@
 # Generated from lib/paper_trail_diff/version_query.rb with RBS::Inline
 
 module PaperTrailDiff
-  # Arel conditions shared by the version queries that need one row per item.
+  # Query pieces shared by version lookups.
   module VersionQuery
+    # Oldest first. Ids break ties between versions written in the same
+    # instant, and the timestamp comes first because ids need not follow time:
+    # a UUID key does not.
+    # : (untyped) -> untyped
+    def self?.chronological: (untyped) -> untyped
+
     # Keeps each item's earliest version among those the block also accepts:
     # no other version of the same item that the block accepts is earlier. A
     # correlated NOT EXISTS stays portable where window functions are not.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: paper_trail_diff
 version: !ruby/object:Gem::Version
-  version: 0.13.0
+  version: 0.13.1
 platform: ruby
 authors:
 - Alex Williams
@@ -238,11 +238,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.13.0/CHANGELOG.md
-  documentation_uri: https://github.com/aheathwilliams/paper_trail_diff/blob/v0.13.0/README.md
+  changelog_uri: https://github.com/aheathwilliams/paper_trail_diff/blob/v0.13.1/CHANGELOG.md
+  documentation_uri: https://github.com/aheathwilliams/paper_trail_diff/blob/v0.13.1/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.13.0
+  source_code_uri: https://github.com/aheathwilliams/paper_trail_diff/tree/v0.13.1
 rdoc_options: []
 require_paths:
 - lib