paper_trail_diff 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 41f2b97428f5dc66c22e29bb1a01cdda0beb1ad29eafe5f86ce8809fb1c61bc0
-  data.tar.gz: 9f6ef5ebef159decfaf875b6df4e6341f6243c9431085b65a67987baa674191f
+  metadata.gz: 1ee80500dbeb48421e7b0e0766a5f5559b73aa71528360a5f1a16866f9e6ccfa
+  data.tar.gz: 6692d3fd2d725918e16da15b4d39312b5e1a42deba3aa8e50a269abfd9fc6bd9
 SHA512:
-  metadata.gz: 28d69434ddf8c9886f1785dc665a54040c38721e1aae84738f50668f2cf677cd39f8a3f9870cc06f3627a0c9f134b935a26dceb2f50c2eff8634bd2dc52bbc8f
-  data.tar.gz: 704c54404a71a76a9deaa6f3e7d03b425763fdce010b240f8e24e4a293d8656c448a11bcf0e5eabcf6e3d0c2c7bb83b6d277acad83e27a7a749bdb1f0116edf5
+  metadata.gz: f809075c65c923ca0dd828e8337477d8461dfa13b2de537a9f99548f0826f867379a33c8bf4a5061476dabd1685829adc5ab21e07052a4d40ebfff4736a44946
+  data.tar.gz: 6212fab6601c900b2701a9401e7e9b66c5236f12da0340788f0641efef759340a29ea6f95e7b51d86c2792d847f5553db8f30d7c96e4370e37ceec0b8a227656

data/CHANGELOG.md

@@ -3,6 +3,24 @@
 All notable changes to this project will be documented in this file. The
 project follows [Semantic Versioning](https://semver.org/).
 
+## [0.9.0] - 2026-08-14
+
+### Added
+
+- Report versions that share a timestamp, which hides any association change
+  between them: PT-AT records membership per version but resolves it by
+  timestamp, so such a pair is indistinguishable even when sequential ids order
+  it correctly. `diagnose` reports `:tied_version_timestamps` as a warning when
+  `associations:` are selected, and a comparison in that state emits
+  `ambiguous_association_boundary.paper_trail_diff`. It warns rather than
+  raising because the result may be perfectly correct — if nothing associated
+  changed, nothing was lost — and the gem cannot distinguish the cases, since
+  not seeing the change is the symptom.
+
+### Changed
+
+- Link the demo application from the README now that it is public.
+
 ## [0.8.0] - 2026-08-12
 
 ### Added

data/README.md

@@ -29,7 +29,10 @@ which fetches what it needs on first run:
 ruby demo.rb
 ```
 
-Then start with the copyable [Quickstart](QUICKSTART.md).
+Then start with the copyable [Quickstart](QUICKSTART.md), or browse
+[the demo application](https://github.com/aheathwilliams/paper_trail_summary_test_app)
+— a small Rails app that installs a published release and exercises scalar,
+nested, through-association, and HABTM history against it.
 
 ## Installation
 
@@ -124,6 +127,31 @@ running rather than after a surprise.
 Either half alone is fine. Sequential ids order tied timestamps correctly, and
 distinct timestamps never reach the fallback.
 
+### Association changes across a shared timestamp
+
+Sequential ids recover the *order* of tied versions, but not their association
+state. PT-AT records association membership per version and resolves it by
+timestamp, so two versions sharing one are indistinguishable for that purpose:
+**an association change between them is invisible.** It is not reported as
+absent — the association simply does not appear in the diff.
+
+Unlike an unorderable sequence this is not always wrong. If nothing associated
+changed between the two versions, the result is correct, and the gem cannot
+tell the two cases apart, because not seeing the change is the symptom. So it
+does not raise. Instead:
+
+- `diagnose` reports `:tied_version_timestamps` as a **warning** whenever
+  `associations:` are selected and versions in range share a timestamp.
+- a comparison in that state emits
+  `ambiguous_association_boundary.paper_trail_diff` through ActiveSupport
+  notifications, carrying the two version ids and the shared timestamp. Nothing
+  is logged; subscribe if you want it surfaced.
+
+Writing several versions inside one clock tick is easy to do — a service object
+that touches a record and its children in quick succession will manage it — so
+this is worth checking before trusting an association history. Recording
+versions at sub-second precision separates them.
+
 ## Choosing an entry point
 
 | You need | Call |

data/lib/paper_trail_diff/diagnostics.rb

@@ -79,7 +79,7 @@ module PaperTrailDiff
       # Runs whether or not associations are selected: unorderable versions
       # corrupt a scalar timeline just as surely, and a report that inspected
       # nothing has no business answering `ok?`.
-      inspect_version_order
+      inspect_version_sequence
       return DiagnosticReport.new(issues: @issues) if @tree.empty?
 
       unless association_tracking_available?
@@ -136,29 +136,13 @@ module PaperTrailDiff
       inspect_transaction_metadata(paths)
     end
 
-    # Ordering falls back to the id when timestamps tie, which only recovers the
-    # real sequence for ids that increase with insertion. Reported before a run
-    # rather than after a wrong answer.
     #: () -> void
-    def inspect_version_order
-      pair = Support.ambiguous_pair(ordered_range_versions)
-      return unless pair
-
-      add_error(:ambiguous_version_order, Support.ambiguous_message(pair), nil, pair.first.id)
-    rescue StandardError
-      nil
-    end
-
-    #: () -> Array[untyped]
-    def ordered_range_versions
-      bounds = [@from_version.created_at, @to_version.created_at].compact.sort
-      return [] unless bounds.length == 2
-
-      @from_version.class
-                   .where(item_type: @from_version.item_type, item_id: @from_version.item_id)
-                   .where(created_at: bounds.first..bounds.last)
-                   .to_a
-                   .sort_by { |version| Support.chronological_version_key(version) }
+    def inspect_version_sequence
+      @issues.concat(
+        VersionSequenceDiagnostics.new(
+          @from_version, @to_version, associations_selected: !@tree.empty?
+        ).call
+      )
     end
 
     #: (untyped) -> void

data/lib/paper_trail_diff/instrumentation.rb

@@ -19,6 +19,14 @@ module PaperTrailDiff
       )
     end
 
+    # Reports a condition rather than timing work: nothing failed, but the
+    # result may be incomplete and only the application can judge that.
+    #: (String | Symbol, Hash[Symbol, untyped]) -> void
+    def notify(event, payload)
+      instrument(event, payload) { nil }
+      nil
+    end
+
     #: (association_paths: Array[String], reload_live_endpoints: bool) -> Hash[Symbol, untyped]
     def comparison_payload(association_paths:, reload_live_endpoints:)
       {

data/lib/paper_trail_diff/paper_trail_adapter.rb

@@ -33,6 +33,7 @@ module PaperTrailDiff
       payload = @instrumentation_payload.merge(comparison_count: 1)
       Instrumentation.instrument('compare', payload) do
         Endpoint.validate_pair!(from_endpoint, to_endpoint)
+        notify_ambiguous_association_boundary(from_endpoint, to_endpoint)
         Engine.compare(snapshot_for_endpoint(from_endpoint), snapshot_for_endpoint(to_endpoint))
       end
     end
@@ -141,6 +142,27 @@ module PaperTrailDiff
       ).analyze
     end
 
+    # Association membership is resolved by timestamp, so endpoints sharing one
+    # cannot be told apart and any association change between them is invisible.
+    # The result may still be correct -- nothing associated may have changed --
+    # and the gem cannot tell which, since not seeing the change is the symptom.
+    # So it reports the condition and leaves the judgement to the application.
+    #: (untyped, untyped) -> void
+    def notify_ambiguous_association_boundary(from_endpoint, to_endpoint)
+      return if @association_tree.empty?
+      return unless Endpoint.version?(from_endpoint) && Endpoint.version?(to_endpoint)
+      return unless from_endpoint.created_at == to_endpoint.created_at
+
+      Instrumentation.notify(
+        'ambiguous_association_boundary',
+        @instrumentation_payload.merge(
+          item_type: from_endpoint.item_type.to_s,
+          version_ids: [from_endpoint.id, to_endpoint.id].freeze,
+          recorded_at: from_endpoint.created_at
+        )
+      )
+    end
+
     # `close_on:` names what ends a wall-clock window, so it is meaningless for a
     # range whose endpoints the caller already gave explicitly.
     #: (Symbol?, untyped) -> bool

data/lib/paper_trail_diff/support.rb

@@ -72,6 +72,15 @@ module PaperTrailDiff
       end
     end
 
+    # Versions sharing a timestamp, whether or not their ids order them. PT-AT
+    # indexes association membership per version but resolves it by timestamp,
+    # so association state cannot be told apart across such a pair even when the
+    # scalar sequence is perfectly recoverable.
+    #: (Array[untyped]) -> Array[untyped]?
+    def tied_timestamp_pair(versions)
+      versions.each_cons(2).find { |left, right| left.created_at == right.created_at }
+    end
+
     #: (untyped) -> bool
     def sequential_id?(id)
       id.is_a?(Integer) || id.to_s.match?(/\A\d+\z/)

data/lib/paper_trail_diff/version.rb

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

data/lib/paper_trail_diff/version_sequence_diagnostics.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # Checks the recorded sequence itself, before any question of association
+  # setup: whether the versions can be ordered at all, and whether timestamps
+  # they share hide changes that ordering alone cannot recover.
+  class VersionSequenceDiagnostics
+    #: (untyped, untyped, ?associations_selected: bool) -> void
+    def initialize(from_version, to_version, associations_selected: false)
+      @from_version = from_version
+      @to_version = to_version
+      @associations_selected = associations_selected
+    end
+
+    #: () -> Array[DiagnosticIssue]
+    def call
+      versions = ordered_range_versions
+      issues = [] #: Array[DiagnosticIssue?]
+      issues << unorderable(versions)
+      issues << tied_timestamps(versions) if @associations_selected
+      issues.compact
+    rescue StandardError
+      []
+    end
+
+    private
+
+    # @rbs @from_version: untyped
+    # @rbs @to_version: untyped
+    # @rbs @associations_selected: bool
+
+    # Ordering falls back to the id when timestamps tie, which only recovers the
+    # real sequence for ids that increase with insertion. Reported before a run
+    # rather than after a wrong answer.
+    #: (Array[untyped]) -> DiagnosticIssue?
+    def unorderable(versions)
+      pair = Support.ambiguous_pair(versions)
+      return unless pair
+
+      DiagnosticIssue.new(
+        severity: :error,
+        code: :ambiguous_version_order,
+        message: Support.ambiguous_message(pair),
+        version_id: pair.first.id
+      )
+    end
+
+    # Association membership is recorded per version but resolved by timestamp,
+    # so a tie hides any association change across that pair. Unlike an
+    # unorderable sequence this is not always wrong: if nothing associated
+    # changed between them the result is correct, and the gem cannot tell which
+    # it is, because not seeing the change is the symptom. So it warns.
+    #: (Array[untyped]) -> DiagnosticIssue?
+    def tied_timestamps(versions)
+      pair = Support.tied_timestamp_pair(versions)
+      return unless pair
+
+      left, right = pair
+      DiagnosticIssue.new(
+        severity: :warning,
+        code: :tied_version_timestamps,
+        message: "versions #{left.id.inspect} and #{right.id.inspect} share the timestamp " \
+                 "#{left.created_at.inspect}, so association changes between them cannot " \
+                 'be detected; record versions at sub-second precision to separate them',
+        version_id: left.id
+      )
+    end
+
+    #: () -> Array[untyped]
+    def ordered_range_versions
+      bounds = [@from_version.created_at, @to_version.created_at].compact.sort
+      return [] unless bounds.length == 2
+
+      @from_version.class
+                   .where(item_type: @from_version.item_type, item_id: @from_version.item_id)
+                   .where(created_at: bounds.first..bounds.last)
+                   .to_a
+                   .sort_by { |version| Support.chronological_version_key(version) }
+    end
+  end
+end

data/lib/paper_trail_diff.rb

@@ -65,6 +65,7 @@ require_relative 'paper_trail_diff/activity_root_steps'
 require_relative 'paper_trail_diff/analysis_batch'
 require_relative 'paper_trail_diff/batched_root_analyzer'
 require_relative 'paper_trail_diff/version_range'
+require_relative 'paper_trail_diff/version_sequence_diagnostics'
 require_relative 'paper_trail_diff/time_range'
 require_relative 'paper_trail_diff/time_version_range'
 require_relative 'paper_trail_diff/timeline_range'

data/sig/generated/paper_trail_diff/diagnostics.rbs

@@ -67,14 +67,8 @@ module PaperTrailDiff
     # : (Array[Array[untyped]]) -> void
     def inspect_habtm: (Array[Array[untyped]]) -> void
 
-    # Ordering falls back to the id when timestamps tie, which only recovers the
-    # real sequence for ids that increase with insertion. Reported before a run
-    # rather than after a wrong answer.
     # : () -> void
-    def inspect_version_order: () -> void
-
-    # : () -> Array[untyped]
-    def ordered_range_versions: () -> Array[untyped]
+    def inspect_version_sequence: () -> void
 
     # : (untyped) -> void
     def inspect_checkpoint_timestamp: (untyped) -> void

data/sig/generated/paper_trail_diff/instrumentation.rbs

@@ -6,6 +6,11 @@ module PaperTrailDiff
     # : (String | Symbol, Hash[Symbol, untyped]) { () -> untyped } -> untyped
     def self?.instrument: (String | Symbol, Hash[Symbol, untyped]) { () -> untyped } -> untyped
 
+    # Reports a condition rather than timing work: nothing failed, but the
+    # result may be incomplete and only the application can judge that.
+    # : (String | Symbol, Hash[Symbol, untyped]) -> void
+    def self?.notify: (String | Symbol, Hash[Symbol, untyped]) -> void
+
     # : (association_paths: Array[String], reload_live_endpoints: bool) -> Hash[Symbol, untyped]
     def self?.comparison_payload: (association_paths: Array[String], reload_live_endpoints: bool) -> Hash[Symbol, untyped]
   end

data/sig/generated/paper_trail_diff/paper_trail_adapter.rbs

@@ -59,6 +59,14 @@ module PaperTrailDiff
     # : (untyped, from: untyped, to: untyped, within: untyped, version_scope: untyped, live_endpoint: untyped, ?snapshots: bool) -> Analysis
     def analyze_activity: (untyped, from: untyped, to: untyped, within: untyped, version_scope: untyped, live_endpoint: untyped, ?snapshots: bool) -> Analysis
 
+    # Association membership is resolved by timestamp, so endpoints sharing one
+    # cannot be told apart and any association change between them is invisible.
+    # The result may still be correct -- nothing associated may have changed --
+    # and the gem cannot tell which, since not seeing the change is the symptom.
+    # So it reports the condition and leaves the judgement to the application.
+    # : (untyped, untyped) -> void
+    def notify_ambiguous_association_boundary: (untyped, untyped) -> void
+
     # `close_on:` names what ends a wall-clock window, so it is meaningless for a
     # range whose endpoints the caller already gave explicitly.
     # : (Symbol?, untyped) -> bool

data/sig/generated/paper_trail_diff/support.rbs

@@ -25,6 +25,13 @@ module PaperTrailDiff
     # : (Array[untyped]) -> Array[untyped]?
     def self?.ambiguous_pair: (Array[untyped]) -> Array[untyped]?
 
+    # Versions sharing a timestamp, whether or not their ids order them. PT-AT
+    # indexes association membership per version but resolves it by timestamp,
+    # so association state cannot be told apart across such a pair even when the
+    # scalar sequence is perfectly recoverable.
+    # : (Array[untyped]) -> Array[untyped]?
+    def self?.tied_timestamp_pair: (Array[untyped]) -> Array[untyped]?
+
     # : (untyped) -> bool
     def self?.sequential_id?: (untyped) -> bool
 

data/sig/generated/paper_trail_diff/version_sequence_diagnostics.rbs

@@ -0,0 +1,39 @@
+# Generated from lib/paper_trail_diff/version_sequence_diagnostics.rb with RBS::Inline
+
+module PaperTrailDiff
+  # Checks the recorded sequence itself, before any question of association
+  # setup: whether the versions can be ordered at all, and whether timestamps
+  # they share hide changes that ordering alone cannot recover.
+  class VersionSequenceDiagnostics
+    # : (untyped, untyped, ?associations_selected: bool) -> void
+    def initialize: (untyped, untyped, ?associations_selected: bool) -> void
+
+    # : () -> Array[DiagnosticIssue]
+    def call: () -> Array[DiagnosticIssue]
+
+    private
+
+    @associations_selected: bool
+
+    @from_version: untyped
+
+    @to_version: untyped
+
+    # Ordering falls back to the id when timestamps tie, which only recovers the
+    # real sequence for ids that increase with insertion. Reported before a run
+    # rather than after a wrong answer.
+    # : (Array[untyped]) -> DiagnosticIssue?
+    def unorderable: (Array[untyped]) -> DiagnosticIssue?
+
+    # Association membership is recorded per version but resolved by timestamp,
+    # so a tie hides any association change across that pair. Unlike an
+    # unorderable sequence this is not always wrong: if nothing associated
+    # changed between them the result is correct, and the gem cannot tell which
+    # it is, because not seeing the change is the symptom. So it warns.
+    # : (Array[untyped]) -> DiagnosticIssue?
+    def tied_timestamps: (Array[untyped]) -> DiagnosticIssue?
+
+    # : () -> Array[untyped]
+    def ordered_range_versions: () -> Array[untyped]
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: paper_trail_diff
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.9.0
 platform: ruby
 authors:
 - Alex Williams
@@ -118,6 +118,7 @@ files:
 - lib/paper_trail_diff/version_association_candidate_scope.rb
 - lib/paper_trail_diff/version_range.rb
 - lib/paper_trail_diff/version_scope_filter.rb
+- lib/paper_trail_diff/version_sequence_diagnostics.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
@@ -194,17 +195,18 @@ files:
 - sig/generated/paper_trail_diff/version_association_candidate_scope.rbs
 - sig/generated/paper_trail_diff/version_range.rbs
 - sig/generated/paper_trail_diff/version_scope_filter.rbs
+- sig/generated/paper_trail_diff/version_sequence_diagnostics.rbs
 homepage: https://github.com/aheathwilliams/paper_trail_diff
 licenses:
 - MIT
 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.8.0/CHANGELOG.md
-  documentation_uri: https://github.com/aheathwilliams/paper_trail_diff/blob/v0.8.0/README.md
+  changelog_uri: https://github.com/aheathwilliams/paper_trail_diff/blob/v0.9.0/CHANGELOG.md
+  documentation_uri: https://github.com/aheathwilliams/paper_trail_diff/blob/v0.9.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.8.0
+  source_code_uri: https://github.com/aheathwilliams/paper_trail_diff/tree/v0.9.0
 rdoc_options: []
 require_paths:
 - lib