paper_trail_diff 0.7.1 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a84116670d1dd65a6cf569a266ccc8587a9eab4e65d38cf84df485c26d33d9dc
-  data.tar.gz: 2c8ddb0fd1b2203e644f3c50ed24da33ed25cb4c4240665eab85368cd4534f22
+  metadata.gz: 41f2b97428f5dc66c22e29bb1a01cdda0beb1ad29eafe5f86ce8809fb1c61bc0
+  data.tar.gz: 9f6ef5ebef159decfaf875b6df4e6341f6243c9431085b65a67987baa674191f
 SHA512:
-  metadata.gz: 3e32ecbedd636456388129cc664cf688b0aa909d5c05b45124eb1a6bd82dabbffa96557fe5efc946e93fe459234d3c4c5ce9af11f39228ddab55228f5a53e2f9
-  data.tar.gz: 1b29680ab942334fd98ce5cc0a4f2bc823fd180b258282e8be2c07ba784c9c3b5aa9edc76e0e118fec3baabcfbc94344c208aef116702874c0eb4dd226cddcac
+  metadata.gz: 28d69434ddf8c9886f1785dc665a54040c38721e1aae84738f50668f2cf677cd39f8a3f9870cc06f3627a0c9f134b935a26dceb2f50c2eff8634bd2dc52bbc8f
+  data.tar.gz: 704c54404a71a76a9deaa6f3e7d03b425763fdce010b240f8e24e4a293d8656c448a11bcf0e5eabcf6e3d0c2c7bb83b6d277acad83e27a7a749bdb1f0116edf5

data/CHANGELOG.md

@@ -3,6 +3,53 @@
 All notable changes to this project will be documented in this file. The
 project follows [Semantic Versioning](https://semver.org/).
 
+## [0.8.0] - 2026-08-12
+
+### Added
+
+- Accept `snapshots: true` on `activity_timeline` and `analyze(activity: true)`,
+  retaining the reconstructed states each step was compared between as
+  `ActivityStep#from_snapshot` and `#to_snapshot`. A diff names what changed; a
+  renderer that has to name an unchanged field of a changed record needed the
+  whole state and had no way to reach it, so consumers were rebuilding it from
+  the version table by hand — slower, and easy to get wrong in ways that stay
+  quiet. The gem already builds these states to compute each diff and discarded
+  them, so the option costs no extra queries. Off by default because each one
+  holds the whole selected graph.
+- Add `examples/demo.rb`, a self-contained tour that needs no application: it
+  builds an in-memory database, writes a small multi-author history, and prints
+  an endpoint diff, a checkpoint timeline, per-person attribution across a
+  nested record, and one person's changes alone. It runs standalone, inside a
+  project, or under `bundle exec`, fetching what it needs on first run.
+
+- Raise `PaperTrailDiff::AmbiguousVersionOrderError` when versions sharing a
+  timestamp have ids that cannot order them. Ordering falls back to the id when
+  timestamps tie, which recovers the real sequence only while ids increase with
+  insertion; a UUID version id does not, and a MySQL `datetime` column stores
+  whole seconds, so the two together are ordinary rather than exotic. The gem
+  previously returned a plausible-looking timeline with steps in the wrong
+  order and others dropped. `diagnose` reports the same condition as an error
+  so it can be caught before a run rather than after a wrong answer.
+- Document the model and schema shapes the suite covers: single-table
+  inheritance (results are keyed by the base class, so build keys with
+  `Endpoint.identity`), non-integer primary keys, and a custom version class
+  via `has_paper_trail versions: { class_name: }`.
+
+### Changed
+
+- Create the models it uses in the quickstart. It declared `has_paper_trail` on
+  an `Article` and then used `Comment` without ever generating either, so
+  following it in a new application failed on a missing table at the first
+  console step.
+- Run `diagnose`'s version-order check whether or not `associations:` are
+  selected, so a report never answers `ok?` having inspected nothing. Document
+  that `ok?` means no errors among the checks that ran.
+
+### Fixed
+
+- Cover `Analysis#to_h(snapshots: true)` with specs. It was shipped in 0.6.0
+  with no test at all.
+
 ## [0.7.1] - 2026-08-11
 
 ### Fixed

data/QUICKSTART.md

@@ -4,6 +4,18 @@ This guide gets `paper_trail_diff` running in a Rails application and shows the
 smallest useful examples. Ruby 3.1 or newer and PaperTrail 16 or 17 are
 supported.
 
+Every command and console snippet below is meant to be run in order against a
+scratch application, so nothing here assumes models you already have:
+
+```console
+rails new diff-demo --minimal
+cd diff-demo
+```
+
+**Just want to see it work?** [`examples/demo.rb`](examples/demo.rb) is a single
+self-contained file — no application, no migrations, nothing to undo. Download
+it anywhere and run `ruby demo.rb`; it fetches what it needs on first run.
+
 ## 1. Install the gem
 
 From the Rails application directory:
@@ -21,6 +33,13 @@ reified state rather than a PaperTrail changeset.
 
 ## 2. Version a model
 
+Create the model this guide uses, then declare it versioned:
+
+```console
+bin/rails generate model Article title:string
+bin/rails db:migrate
+```
+
 ```ruby
 # app/models/article.rb
 class Article < ApplicationRecord
@@ -195,8 +214,14 @@ bin/rails db:migrate
 ```
 
 The generator creates `version_associations` and enables
-`PaperTrail.config.track_associations`. Every model whose historical state is
-needed must be versioned:
+`PaperTrail.config.track_associations`. This section also needs a second model:
+
+```console
+bin/rails generate model Comment article:references body:string
+bin/rails db:migrate
+```
+
+Every model whose historical state is needed must be versioned:
 
 ```ruby
 class Article < ApplicationRecord

data/README.md

@@ -21,7 +21,15 @@ available when
 
 Ruby 3.1 or newer and PaperTrail 16 or 17 are supported.
 
-New to the gem? Start with the copyable [Quickstart](QUICKSTART.md).
+New to the gem? Run [`examples/demo.rb`](examples/demo.rb) to see it work in
+about ten seconds — one self-contained file, no application and no migrations,
+which fetches what it needs on first run:
+
+```console
+ruby demo.rb
+```
+
+Then start with the copyable [Quickstart](QUICKSTART.md).
 
 ## Installation
 
@@ -83,7 +91,38 @@ for. Three consequences run through the rest of this document:
   both timeline APIs return steps rather than events.
 
 The [Quickstart](QUICKSTART.md) walks through the same idea against a real
-console session.
+console session, creating the models it uses as it goes.
+
+## Which models and schemas work
+
+Anything `has_paper_trail` tracks, including these, which are covered by the
+test suite rather than assumed:
+
+- **Single-table inheritance.** Results are keyed by the *base* class, matching
+  what PaperTrail writes to `item_type`. Analyzing a `Book < Publication`
+  produces the key `["Publication", "12"]`, so `results.fetch(["Book", ...])`
+  raises `KeyError`. Build keys with `PaperTrailDiff::Endpoint.identity(record)`
+  rather than by hand.
+- **Non-integer primary keys** on the tracked model, such as a UUID column.
+- **A custom version class**, via `has_paper_trail versions: { class_name: }`.
+  Nothing here references `PaperTrail::Version` directly.
+
+### Versions that cannot be ordered
+
+Versions are ordered by `created_at`, falling back to the id when timestamps
+tie. That fallback recovers the real sequence only while ids increase with
+insertion. An autoincrement id does; a **UUID version id does not**.
+
+So two conditions together are unsafe: version ids that are not sequential,
+*and* versions sharing a timestamp — which is ordinary on a MySQL `datetime`
+column, since it stores whole seconds. The order is then unrecoverable, and
+rather than report a plausible-looking history in the wrong order the gem
+raises `PaperTrailDiff::AmbiguousVersionOrderError` naming both versions.
+`diagnose` reports the same condition as an error, so a caller can check before
+running rather than after a surprise.
+
+Either half alone is fine. Sequential ids order tied timestamps correctly, and
+distinct timestamps never reach the fallback.
 
 ## Choosing an entry point
 
@@ -549,6 +588,35 @@ boundary. Passing `to: article` is what removes the need to touch the parent
 after an ordinary versioned child mutation; current state is still never
 implicit.
 
+### Reading the state behind a step
+
+A step's diff carries what changed. A renderer often needs what did *not* — to
+say whose comment was edited, it needs the comment's author, which the diff has
+no reason to mention. `snapshots: true` retains the reconstructed states each
+step was compared between:
+
+```ruby
+steps = PaperTrailDiff.activity_timeline(
+  article, from: :first, to: article, associations: [:comments], snapshots: true
+)
+
+step = steps.reject(&:empty?).last
+step.from_snapshot.associations["comments"].records.first.attributes["author"]
+```
+
+The gem already builds these states to compute each diff and otherwise discards
+them, so asking for them costs no extra queries. Reconstructing them yourself
+from the version table means reimplementing boundary ordering, and getting it
+wrong is quiet rather than loud.
+
+They are off by default because each one holds the whole selected graph, and
+retaining one per step keeps the entire timeline's graph alive. A step whose
+`from_boundary` is a `create` version has a `nil` `from_snapshot`: the record
+did not exist yet, which is the answer rather than a missing one.
+
+`analyze(activity: true, snapshots: true)` populates the same fields on the
+`activity_timeline` it returns.
+
 ### Closing a destroyed root
 
 A `destroy` version is the one boundary whose following state needs no later
@@ -975,6 +1043,12 @@ report.errors.map(&:code)
 report.warnings.map(&:code)
 ```
 
+`ok?` means no *errors* were found among the checks that ran, not that every
+possible hazard was ruled out. Association checks need `associations:` to have
+something to inspect; without it only the version-order check runs, which is
+why that one runs whether or not associations are selected — an unorderable
+history corrupts a scalar timeline just as thoroughly.
+
 Diagnostics are read-only guidance, not proof that arbitrary old data is
 complete. HABTM endpoints without transaction-backed association snapshots fail
 loudly with `PaperTrailDiff::IncompleteAssociationHistoryError` during normal

data/lib/paper_trail_diff/activity_boundary.rb

@@ -108,12 +108,35 @@ module PaperTrailDiff
     attr_reader :from_boundary #: ActivityBoundary
     attr_reader :to_boundary #: ActivityBoundary
     attr_reader :diff #: Diff
+    # The reconstructed states this step was compared between, present only when
+    # a caller asked for them. A diff carries what changed; a renderer that has
+    # to name an unchanged field of a changed record needs the whole state, and
+    # rebuilding it from the version table by hand is both slower and easy to
+    # get wrong.
+    attr_reader :from_snapshot #: RecordSnapshot?
+    attr_reader :to_snapshot #: RecordSnapshot?
 
-    #: (from_boundary: ActivityBoundary, to_boundary: ActivityBoundary, diff: Diff) -> void
-    def initialize(from_boundary:, to_boundary:, diff:)
+    # Compares two reconstructed states and keeps them only when asked, which is
+    # every caller's shape: the diff always comes from the pair, the pair itself
+    # is retained on request.
+    #: (from_boundary: ActivityBoundary, to_boundary: ActivityBoundary, from_snapshot: RecordSnapshot?, to_snapshot: RecordSnapshot?, retain: bool) -> ActivityStep
+    def self.between(from_boundary:, to_boundary:, from_snapshot:, to_snapshot:, retain:)
+      new(
+        from_boundary: from_boundary,
+        to_boundary: to_boundary,
+        diff: Engine.compare(from_snapshot, to_snapshot),
+        from_snapshot: (from_snapshot if retain),
+        to_snapshot: (to_snapshot if retain)
+      )
+    end
+
+    #: (from_boundary: ActivityBoundary, to_boundary: ActivityBoundary, diff: Diff, ?from_snapshot: RecordSnapshot?, ?to_snapshot: RecordSnapshot?) -> void
+    def initialize(from_boundary:, to_boundary:, diff:, from_snapshot: nil, to_snapshot: nil)
       @from_boundary = from_boundary
       @to_boundary = to_boundary
       @diff = diff
+      @from_snapshot = from_snapshot
+      @to_snapshot = to_snapshot
       freeze
     end
 

data/lib/paper_trail_diff/activity_history.rb

@@ -26,13 +26,16 @@ module PaperTrailDiff
 
   # Builds activity steps while retaining root snapshots for combined analysis.
   class ActivityHistoryBuilder
-    #: (Array[untyped], Array[ActivityEvent], untyped, ?current: untyped, ?include_step: untyped) -> void
-    def initialize(root_versions, events, snapshotter, current: nil, include_step: nil)
+    #: (Array[untyped], Array[ActivityEvent], untyped, ?current: untyped, ?include_step: untyped, ?snapshots: bool) -> void
+    def initialize( # rubocop:disable Metrics/ParameterLists
+      root_versions, events, snapshotter, current: nil, include_step: nil, snapshots: false
+    )
       @root_versions = root_versions
       @events = events
       @snapshotter = snapshotter
       @current = current
       @include_step = include_step
+      @snapshots = snapshots
     end
 
     #: () -> ActivityHistory
@@ -54,6 +57,7 @@ module PaperTrailDiff
     # @rbs @snapshotter: untyped
     # @rbs @current: untyped
     # @rbs @include_step: untyped
+    # @rbs @snapshots: bool
     # @rbs @steps: Array[ActivityStep]
     # @rbs @root_snapshots: Hash[Array[untyped], RecordSnapshot?]
     # @rbs @first_snapshot: RecordSnapshot?
@@ -110,10 +114,9 @@ module PaperTrailDiff
       previous_boundary = @previous_boundary
       return unless previous_boundary
 
-      @steps << ActivityStep.new(
-        from_boundary: previous_boundary,
-        to_boundary: boundary,
-        diff: Engine.compare(@previous_snapshot, snapshot)
+      @steps << ActivityStep.between(
+        from_boundary: previous_boundary, to_boundary: boundary,
+        from_snapshot: @previous_snapshot, to_snapshot: snapshot, retain: @snapshots
       )
       @selected_last_snapshot = snapshot
     end

data/lib/paper_trail_diff/activity_timeline_builder.rb

@@ -4,8 +4,9 @@
 module PaperTrailDiff
   # Compares adjacent root and selected-descendant activity boundaries.
   class ActivityTimelineBuilder
-    #: (untyped, range: TimelineRange, tree: AssociationTree, snapshotter: untyped) -> void
-    def initialize(record, range:, tree:, snapshotter:)
+    #: (untyped, range: TimelineRange, tree: AssociationTree, snapshotter: untyped, ?snapshots: bool) -> void
+    def initialize(record, range:, tree:, snapshotter:, snapshots: false)
+      @snapshots = snapshots
       @record = record
       @from = range.from
       @to = range.to
@@ -49,6 +50,7 @@ module PaperTrailDiff
     # @rbs @range: TimelineRange
     # @rbs @tree: AssociationTree
     # @rbs @snapshotter: untyped
+    # @rbs @snapshots: bool
 
     #: () -> Array[ActivityStep]
     def no_steps
@@ -150,10 +152,10 @@ module PaperTrailDiff
       previous_event = events.last
       previous_boundary = ActivityBoundary.from_version(previous_event.version) if previous_event
       if final_boundary && previous_boundary
-        steps << ActivityStep.new(
-          from_boundary: previous_boundary,
-          to_boundary: final_boundary,
-          diff: Engine.compare(history.last_snapshot, final_snapshot)
+        steps << ActivityStep.between(
+          from_boundary: previous_boundary, to_boundary: final_boundary,
+          from_snapshot: history.last_snapshot, to_snapshot: final_snapshot,
+          retain: @snapshots
         )
       end
       steps.freeze
@@ -175,7 +177,8 @@ module PaperTrailDiff
         root_versions,
         events,
         @snapshotter,
-        current: current
+        current: current,
+        snapshots: @snapshots
       ).call
     end
 
@@ -201,7 +204,8 @@ module PaperTrailDiff
         @record,
         range: @range,
         tree: @tree,
-        snapshotter: @snapshotter
+        snapshotter: @snapshotter,
+        snapshots: @snapshots
       )
     end
   end

data/lib/paper_trail_diff/diagnostics.rb

@@ -76,7 +76,11 @@ module PaperTrailDiff
     #: () -> DiagnosticReport
     def call
       model_class = validated_model_class
-      return DiagnosticReport.new(issues: []) if @tree.empty?
+      # 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
+      return DiagnosticReport.new(issues: @issues) if @tree.empty?
 
       unless association_tracking_available?
         add_error(:association_tracking_unavailable, tracking_unavailable_message)
@@ -132,6 +136,31 @@ 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) }
+    end
+
     #: (untyped) -> void
     def inspect_checkpoint_timestamp(model_class)
       return if synchronized_timestamp_disabled?(model_class)

data/lib/paper_trail_diff/errors.rb

@@ -29,6 +29,9 @@ module PaperTrailDiff
   # Raised when an in-range mutation has no later root boundary for reconstruction.
   class IncompleteTimeRangeError < InvalidTimelineRangeError; end
 
+  # Raised when versions sharing a timestamp cannot be ordered by their ids.
+  class AmbiguousVersionOrderError < Error; end
+
   # Raised when a requested ActiveRecord association does not exist.
   class UnknownAssociationError < Error; end
 

data/lib/paper_trail_diff/paper_trail_adapter.rb

@@ -67,8 +67,8 @@ module PaperTrailDiff
       ).build
     end
 
-    #: (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped, ?close_on: Symbol?) -> Array[ActivityStep]
-    def activity_timeline(record, from:, to:, within:, version_scope: nil, close_on: nil) # rubocop:disable Metrics/ParameterLists
+    #: (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool) -> Array[ActivityStep]
+    def activity_timeline(record, from:, to:, within:, version_scope: nil, close_on: nil, snapshots: false) # rubocop:disable Metrics/ParameterLists, Layout/LineLength
       payload = @instrumentation_payload.merge(model_type: record.class.base_class.name.to_s)
       Instrumentation.instrument('activity_timeline', payload) do
         @traversal_preparer.call(record.class, historical: true)
@@ -76,21 +76,21 @@ module PaperTrailDiff
         reject_live_habtm_activity!(record.class) if Endpoint.record?(to) || live
         steps = activity_builder(
           record, from: from, to: to, within: within, version_scope: version_scope,
-                  live_endpoint: live
+                  live_endpoint: live, snapshots: snapshots
         ).build
         payload[:step_count] = steps.length
         steps
       end
     end
 
-    #: (untyped, from: untyped, to: untyped, within: untyped, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?) -> Analysis
-    def analyze(record, from:, to:, within:, activity: false, version_scope: nil, close_on: nil) # rubocop:disable Metrics/ParameterLists
+    #: (untyped, from: untyped, to: untyped, within: untyped, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool) -> Analysis
+    def analyze(record, from:, to:, within:, activity: false, version_scope: nil, close_on: nil, snapshots: false) # rubocop:disable Metrics/ParameterLists, Layout/LineLength
       @traversal_preparer.call(record.class, historical: true)
       live = live_endpoint_for(record, close_on, within)
       if activity
         return analyze_activity(
-          record, from: from, to: to, within: within,
-                  version_scope: version_scope, live_endpoint: live
+          record, from: from, to: to, within: within, version_scope: version_scope,
+                  live_endpoint: live, snapshots: snapshots
         )
       end
 
@@ -132,12 +132,12 @@ module PaperTrailDiff
     # @rbs @timeline_snapshotter: TimelineSnapshotProvider
     # @rbs @activity_snapshotter: ActivitySnapshotProvider
 
-    #: (untyped, from: untyped, to: untyped, within: untyped, version_scope: untyped, live_endpoint: untyped) -> Analysis
-    def analyze_activity(record, from:, to:, within:, version_scope:, live_endpoint:) # rubocop:disable Metrics/ParameterLists
+    #: (untyped, from: untyped, to: untyped, within: untyped, version_scope: untyped, live_endpoint: untyped, ?snapshots: bool) -> Analysis
+    def analyze_activity(record, from:, to:, within:, version_scope:, live_endpoint:, snapshots: false) # rubocop:disable Metrics/ParameterLists, Layout/LineLength
       reject_live_habtm_activity!(record.class) if live_endpoint
       activity_builder(
-        record, from: from, to: to, within: within,
-                version_scope: version_scope, live_endpoint: live_endpoint
+        record, from: from, to: to, within: within, version_scope: version_scope,
+                live_endpoint: live_endpoint, snapshots: snapshots
       ).analyze
     end
 
@@ -212,8 +212,8 @@ module PaperTrailDiff
       )
     end
 
-    #: (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped, ?live_endpoint: untyped) -> ActivityTimelineBuilder
-    def activity_builder(record, from:, to:, within:, version_scope: nil, live_endpoint: nil) # rubocop:disable Metrics/ParameterLists
+    #: (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped, ?live_endpoint: untyped, ?snapshots: bool) -> ActivityTimelineBuilder
+    def activity_builder(record, from:, to:, within:, version_scope: nil, live_endpoint: nil, snapshots: false) # rubocop:disable Metrics/ParameterLists, Layout/LineLength
       ActivityTimelineBuilder.new(
         record,
         range: TimelineRange.new(
@@ -221,7 +221,8 @@ module PaperTrailDiff
                   live_endpoint: live_endpoint
         ),
         tree: @association_tree,
-        snapshotter: @activity_snapshotter
+        snapshotter: @activity_snapshotter,
+        snapshots: snapshots
       )
     end
 

data/lib/paper_trail_diff/prepared_record_index.rb

@@ -109,7 +109,7 @@ module PaperTrailDiff
 
     #: (versions: Array[untyped], live: PreparedRecordState?, ?state_loader: PreparedVersionStateLoader) -> void
     def initialize(versions:, live:, state_loader: PreparedVersionStateLoader.new)
-      @versions = versions.sort_by { |version| Support.chronological_version_key(version) }.freeze
+      @versions = Support.chronological_sort(versions).freeze
       @version_positions = @versions.each_with_index.to_h do |version, index|
         [version.id.to_s, index]
       end.freeze

data/lib/paper_trail_diff/root_version_selection.rb

@@ -134,8 +134,7 @@ module PaperTrailDiff
 
     #: (Array[untyped]) -> Array[untyped]
     def chronological(versions)
-      versions.uniq { |version| [version.class.name, version.id] }
-              .sort_by { |version| Support.chronological_version_key(version) }
+      Support.chronological_sort(versions.uniq { |version| [version.class.name, version.id] })
     end
 
     #: (untyped) -> untyped

data/lib/paper_trail_diff/support.rb

@@ -51,6 +51,41 @@ module PaperTrailDiff
       [version.created_at, version.id.to_s.rjust(32, '0')]
     end
 
+    # Ordering falls back to the id whenever timestamps tie, which recovers the
+    # real order only while ids increase with insertion. An autoincrement id
+    # does; a UUID does not, so a tie between UUID-keyed versions is genuinely
+    # unorderable and any timeline built from it would be fiction.
+    #: (Array[untyped]) -> Array[untyped]
+    def chronological_sort(versions)
+      sorted = versions.sort_by { |version| chronological_version_key(version) }
+      ambiguous = ambiguous_pair(sorted)
+      return sorted unless ambiguous
+
+      raise AmbiguousVersionOrderError, ambiguous_message(ambiguous)
+    end
+
+    #: (Array[untyped]) -> Array[untyped]?
+    def ambiguous_pair(sorted)
+      sorted.each_cons(2).find do |left, right|
+        left.created_at == right.created_at &&
+          !(sequential_id?(left.id) && sequential_id?(right.id))
+      end
+    end
+
+    #: (untyped) -> bool
+    def sequential_id?(id)
+      id.is_a?(Integer) || id.to_s.match?(/\A\d+\z/)
+    end
+
+    #: (Array[untyped]) -> String
+    def ambiguous_message(pair)
+      left, right = pair
+      "versions #{left.id.inspect} and #{right.id.inspect} share the timestamp " \
+        "#{left.created_at.inspect} and have ids that do not order them, so their " \
+        'sequence cannot be recovered; record versions at sub-second precision or ' \
+        'with sequential ids'
+    end
+
     #: (untyped, untyped) -> Integer
     def compare_versions(left, right)
       chronological_version_key(left) <=> chronological_version_key(right) ||

data/lib/paper_trail_diff/time_activity_timeline_builder.rb

@@ -4,8 +4,9 @@
 module PaperTrailDiff
   # Builds activity views for mutations selected by a wall-clock range.
   class TimeActivityTimelineBuilder
-    #: (untyped, range: TimelineRange, tree: AssociationTree, snapshotter: untyped) -> void
-    def initialize(record, range:, tree:, snapshotter:)
+    #: (untyped, range: TimelineRange, tree: AssociationTree, snapshotter: untyped, ?snapshots: bool) -> void
+    def initialize(record, range:, tree:, snapshotter:, snapshots: false)
+      @snapshots = snapshots
       @record = record
       @range = range
       @tree = tree
@@ -40,6 +41,7 @@ module PaperTrailDiff
     # @rbs @range: TimelineRange
     # @rbs @tree: AssociationTree
     # @rbs @snapshotter: untyped
+    # @rbs @snapshots: bool
 
     #: () -> [ActivityHistory, RootVersionPlan, ActivityStep?, RecordSnapshot?, untyped]
     def history_and_versions
@@ -89,7 +91,8 @@ module PaperTrailDiff
         root_versions,
         events,
         @snapshotter,
-        include_step: ->(event) { @range.include?(event.version) }
+        include_step: ->(event) { @range.include?(event.version) },
+        snapshots: @snapshots
       ).call
     end
 
@@ -129,10 +132,11 @@ module PaperTrailDiff
     #: (ActivityHistory, ActivityEvent) -> ActivityStep
     def destroyed_step(history, event)
       version = event.version
-      ActivityStep.new(
+      ActivityStep.between(
         from_boundary: ActivityBoundary.from_version(version),
         to_boundary: ActivityBoundary.destroyed(version),
-        diff: Engine.compare(history.root_snapshots[ActivityRootSteps.version_key(version)], nil)
+        from_snapshot: history.root_snapshots[ActivityRootSteps.version_key(version)],
+        to_snapshot: nil, retain: @snapshots
       )
     end
 
@@ -144,10 +148,10 @@ module PaperTrailDiff
       previous = history.steps.last&.to_boundary
       return unless previous
 
-      ActivityStep.new(
+      ActivityStep.between(
         from_boundary: previous,
         to_boundary: ActivityBoundary.current(record, captured_at: captured_at),
-        diff: Engine.compare(history.last_snapshot, snapshot)
+        from_snapshot: history.last_snapshot, to_snapshot: snapshot, retain: @snapshots
       )
     end
 

data/lib/paper_trail_diff/time_version_range.rb

@@ -56,7 +56,7 @@ module PaperTrailDiff
 
     #: (Array[untyped]) -> Array[untyped]
     def ordered(versions)
-      versions.sort_by { |version| Support.chronological_version_key(version) }
+      Support.chronological_sort(versions)
     end
   end
 end

data/lib/paper_trail_diff/timeline_snapshot_provider.rb

@@ -4,8 +4,8 @@
 module PaperTrailDiff
   # Gives TimelineBuilder one-argument access to a range-prepared snapshot store.
   class TimelineSnapshotProvider
-    #: (HistoricalSnapshotStore, ?live_snapshotter: untyped) -> void
-    def initialize(store, live_snapshotter: nil)
+    #: (HistoricalSnapshotStore, live_snapshotter: untyped) -> void
+    def initialize(store, live_snapshotter:)
       @store = store
       @live_snapshotter = live_snapshotter
     end
@@ -28,10 +28,7 @@ module PaperTrailDiff
 
     #: (untyped) -> RecordSnapshot?
     def live_snapshot(record)
-      snapshotter = @live_snapshotter
-      raise InvalidTimelineRangeError, 'live endpoints are unavailable here' unless snapshotter
-
-      snapshotter.call(record)
+      @live_snapshotter.call(record)
     end
 
     # @rbs @store: HistoricalSnapshotStore

data/lib/paper_trail_diff/version.rb

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

data/lib/paper_trail_diff/version_range.rb

@@ -96,7 +96,7 @@ module PaperTrailDiff
 
     #: (Array[untyped]) -> Array[untyped]
     def ordered(versions)
-      versions.sort_by { |version| Support.chronological_version_key(version) }
+      Support.chronological_sort(versions)
     end
 
     #: (untyped, untyped, boundary: Symbol) -> void

data/lib/paper_trail_diff.rb

@@ -169,7 +169,7 @@ module PaperTrailDiff # rubocop:disable Metrics/ModuleLength
     # Compares adjacent root and selected-descendant activity boundaries.
     # `reload_live_endpoints:` applies only when `to:` is a current record; the
     # other range forms never read live state.
-    #: (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?reload_live_endpoints: bool, ?version_scope: untyped, ?close_on: Symbol?) -> Array[ActivityStep]
+    #: (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?reload_live_endpoints: bool, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool) -> Array[ActivityStep]
     def activity_timeline( # rubocop:disable Metrics/ParameterLists
       record,
       from: nil,
@@ -179,7 +179,8 @@ module PaperTrailDiff # rubocop:disable Metrics/ModuleLength
       ignore: DEFAULT_IGNORED_ATTRIBUTES,
       reload_live_endpoints: true,
       version_scope: nil,
-      close_on: nil
+      close_on: nil,
+      snapshots: false
     )
       PaperTrailAdapter.new(
         associations: associations,
@@ -191,12 +192,13 @@ module PaperTrailDiff # rubocop:disable Metrics/ModuleLength
         to: to,
         within: within,
         version_scope: version_scope,
-        close_on: close_on
+        close_on: close_on,
+        snapshots: snapshots
       )
     end
 
     # Builds an endpoint diff and root-checkpoint timeline while normalizing each version once.
-    #: (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?) -> Analysis
+    #: (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool) -> Analysis
     def analyze( # rubocop:disable Metrics/ParameterLists
       record,
       from: nil,
@@ -206,7 +208,8 @@ module PaperTrailDiff # rubocop:disable Metrics/ModuleLength
       ignore: DEFAULT_IGNORED_ATTRIBUTES,
       activity: false,
       version_scope: nil,
-      close_on: nil
+      close_on: nil,
+      snapshots: false
     )
       PaperTrailAdapter.new(associations: associations, ignore: ignore).analyze(
         record,
@@ -215,7 +218,8 @@ module PaperTrailDiff # rubocop:disable Metrics/ModuleLength
         within: within,
         activity: activity,
         version_scope: version_scope,
-        close_on: close_on
+        close_on: close_on,
+        snapshots: snapshots
       )
     end
 

data/sig/generated/paper_trail_diff/activity_boundary.rbs

@@ -55,8 +55,23 @@ module PaperTrailDiff
 
     attr_reader diff: Diff
 
-    # : (from_boundary: ActivityBoundary, to_boundary: ActivityBoundary, diff: Diff) -> void
-    def initialize: (from_boundary: ActivityBoundary, to_boundary: ActivityBoundary, diff: Diff) -> void
+    # The reconstructed states this step was compared between, present only when
+    # a caller asked for them. A diff carries what changed; a renderer that has
+    # to name an unchanged field of a changed record needs the whole state, and
+    # rebuilding it from the version table by hand is both slower and easy to
+    # get wrong.
+    attr_reader from_snapshot: RecordSnapshot?
+
+    attr_reader to_snapshot: RecordSnapshot?
+
+    # Compares two reconstructed states and keeps them only when asked, which is
+    # every caller's shape: the diff always comes from the pair, the pair itself
+    # is retained on request.
+    # : (from_boundary: ActivityBoundary, to_boundary: ActivityBoundary, from_snapshot: RecordSnapshot?, to_snapshot: RecordSnapshot?, retain: bool) -> ActivityStep
+    def self.between: (from_boundary: ActivityBoundary, to_boundary: ActivityBoundary, from_snapshot: RecordSnapshot?, to_snapshot: RecordSnapshot?, retain: bool) -> ActivityStep
+
+    # : (from_boundary: ActivityBoundary, to_boundary: ActivityBoundary, diff: Diff, ?from_snapshot: RecordSnapshot?, ?to_snapshot: RecordSnapshot?) -> void
+    def initialize: (from_boundary: ActivityBoundary, to_boundary: ActivityBoundary, diff: Diff, ?from_snapshot: RecordSnapshot?, ?to_snapshot: RecordSnapshot?) -> void
 
     # : () -> bool
     def empty?: () -> bool

data/sig/generated/paper_trail_diff/activity_history.rbs

@@ -20,8 +20,8 @@ module PaperTrailDiff
 
   # Builds activity steps while retaining root snapshots for combined analysis.
   class ActivityHistoryBuilder
-    # : (Array[untyped], Array[ActivityEvent], untyped, ?current: untyped, ?include_step: untyped) -> void
-    def initialize: (Array[untyped], Array[ActivityEvent], untyped, ?current: untyped, ?include_step: untyped) -> void
+    # : (Array[untyped], Array[ActivityEvent], untyped, ?current: untyped, ?include_step: untyped, ?snapshots: bool) -> void
+    def initialize: (Array[untyped], Array[ActivityEvent], untyped, ?current: untyped, ?include_step: untyped, ?snapshots: bool) -> void
 
     # : () -> ActivityHistory
     def call: () -> ActivityHistory
@@ -48,6 +48,8 @@ module PaperTrailDiff
 
     @selected_last_snapshot: RecordSnapshot?
 
+    @snapshots: bool
+
     @snapshotter: untyped
 
     @steps: Array[ActivityStep]

data/sig/generated/paper_trail_diff/activity_timeline_builder.rbs

@@ -3,8 +3,8 @@
 module PaperTrailDiff
   # Compares adjacent root and selected-descendant activity boundaries.
   class ActivityTimelineBuilder
-    # : (untyped, range: TimelineRange, tree: AssociationTree, snapshotter: untyped) -> void
-    def initialize: (untyped, range: TimelineRange, tree: AssociationTree, snapshotter: untyped) -> void
+    # : (untyped, range: TimelineRange, tree: AssociationTree, snapshotter: untyped, ?snapshots: bool) -> void
+    def initialize: (untyped, range: TimelineRange, tree: AssociationTree, snapshotter: untyped, ?snapshots: bool) -> void
 
     # : () -> Array[ActivityStep]
     def build: () -> Array[ActivityStep]
@@ -21,6 +21,8 @@ module PaperTrailDiff
 
     @record: untyped
 
+    @snapshots: bool
+
     @snapshotter: untyped
 
     @to: untyped

data/sig/generated/paper_trail_diff/diagnostics.rbs

@@ -67,6 +67,15 @@ 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]
+
     # : (untyped) -> void
     def inspect_checkpoint_timestamp: (untyped) -> void
 

data/sig/generated/paper_trail_diff/errors.rbs

@@ -37,6 +37,10 @@ module PaperTrailDiff
   class IncompleteTimeRangeError < InvalidTimelineRangeError
   end
 
+  # Raised when versions sharing a timestamp cannot be ordered by their ids.
+  class AmbiguousVersionOrderError < Error
+  end
+
   # Raised when a requested ActiveRecord association does not exist.
   class UnknownAssociationError < Error
   end

data/sig/generated/paper_trail_diff/paper_trail_adapter.rbs

@@ -22,11 +22,11 @@ module PaperTrailDiff
     # : (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped, ?close_on: Symbol?) -> Array[Step]
     def timeline: (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped, ?close_on: Symbol?) -> Array[Step]
 
-    # : (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped, ?close_on: Symbol?) -> Array[ActivityStep]
-    def activity_timeline: (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped, ?close_on: Symbol?) -> Array[ActivityStep]
+    # : (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool) -> Array[ActivityStep]
+    def activity_timeline: (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool) -> Array[ActivityStep]
 
-    # : (untyped, from: untyped, to: untyped, within: untyped, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?) -> Analysis
-    def analyze: (untyped, from: untyped, to: untyped, within: untyped, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?) -> Analysis
+    # : (untyped, from: untyped, to: untyped, within: untyped, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool) -> Analysis
+    def analyze: (untyped, from: untyped, to: untyped, within: untyped, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool) -> Analysis
 
     # Analyzes many roots over one shared range, preparing their history once.
     # : (Array[untyped], within: untyped, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?) -> Hash[identity, Analysis]
@@ -56,8 +56,8 @@ module PaperTrailDiff
 
     @traversal_preparer: TraversalPreparer
 
-    # : (untyped, from: untyped, to: untyped, within: untyped, version_scope: untyped, live_endpoint: untyped) -> Analysis
-    def analyze_activity: (untyped, from: untyped, to: untyped, within: untyped, version_scope: untyped, live_endpoint: untyped) -> Analysis
+    # : (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
 
     # `close_on:` names what ends a wall-clock window, so it is meaningless for a
     # range whose endpoints the caller already gave explicitly.
@@ -81,8 +81,8 @@ module PaperTrailDiff
     # : () -> ActivitySnapshotProvider
     def build_activity_snapshotter: () -> ActivitySnapshotProvider
 
-    # : (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped, ?live_endpoint: untyped) -> ActivityTimelineBuilder
-    def activity_builder: (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped, ?live_endpoint: untyped) -> ActivityTimelineBuilder
+    # : (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped, ?live_endpoint: untyped, ?snapshots: bool) -> ActivityTimelineBuilder
+    def activity_builder: (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped, ?live_endpoint: untyped, ?snapshots: bool) -> ActivityTimelineBuilder
 
     # : (untyped) -> void
     def reject_live_habtm_activity!: (untyped) -> void

data/sig/generated/paper_trail_diff/support.rbs

@@ -15,6 +15,22 @@ module PaperTrailDiff
     # : (untyped) -> Array[untyped]
     def self?.chronological_version_key: (untyped) -> Array[untyped]
 
+    # Ordering falls back to the id whenever timestamps tie, which recovers the
+    # real order only while ids increase with insertion. An autoincrement id
+    # does; a UUID does not, so a tie between UUID-keyed versions is genuinely
+    # unorderable and any timeline built from it would be fiction.
+    # : (Array[untyped]) -> Array[untyped]
+    def self?.chronological_sort: (Array[untyped]) -> Array[untyped]
+
+    # : (Array[untyped]) -> Array[untyped]?
+    def self?.ambiguous_pair: (Array[untyped]) -> Array[untyped]?
+
+    # : (untyped) -> bool
+    def self?.sequential_id?: (untyped) -> bool
+
+    # : (Array[untyped]) -> String
+    def self?.ambiguous_message: (Array[untyped]) -> String
+
     # : (untyped, untyped) -> Integer
     def self?.compare_versions: (untyped, untyped) -> Integer
 

data/sig/generated/paper_trail_diff/time_activity_timeline_builder.rbs

@@ -3,8 +3,8 @@
 module PaperTrailDiff
   # Builds activity views for mutations selected by a wall-clock range.
   class TimeActivityTimelineBuilder
-    # : (untyped, range: TimelineRange, tree: AssociationTree, snapshotter: untyped) -> void
-    def initialize: (untyped, range: TimelineRange, tree: AssociationTree, snapshotter: untyped) -> void
+    # : (untyped, range: TimelineRange, tree: AssociationTree, snapshotter: untyped, ?snapshots: bool) -> void
+    def initialize: (untyped, range: TimelineRange, tree: AssociationTree, snapshotter: untyped, ?snapshots: bool) -> void
 
     # : () -> Array[ActivityStep]
     def build: () -> Array[ActivityStep]
@@ -18,6 +18,8 @@ module PaperTrailDiff
 
     @record: untyped
 
+    @snapshots: bool
+
     @snapshotter: untyped
 
     @tree: AssociationTree

data/sig/generated/paper_trail_diff/timeline_snapshot_provider.rbs

@@ -3,8 +3,8 @@
 module PaperTrailDiff
   # Gives TimelineBuilder one-argument access to a range-prepared snapshot store.
   class TimelineSnapshotProvider
-    # : (HistoricalSnapshotStore, ?live_snapshotter: untyped) -> void
-    def initialize: (HistoricalSnapshotStore, ?live_snapshotter: untyped) -> void
+    # : (HistoricalSnapshotStore, live_snapshotter: untyped) -> void
+    def initialize: (HistoricalSnapshotStore, live_snapshotter: untyped) -> void
 
     # : (untyped, Array[untyped]) -> void
     def prepare: (untyped, Array[untyped]) -> void

data/sig/generated/paper_trail_diff.rbs

@@ -23,12 +23,12 @@ module PaperTrailDiff
   # Compares adjacent root and selected-descendant activity boundaries.
   # `reload_live_endpoints:` applies only when `to:` is a current record; the
   # other range forms never read live state.
-  # : (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?reload_live_endpoints: bool, ?version_scope: untyped, ?close_on: Symbol?) -> Array[ActivityStep]
-  def self.activity_timeline: (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?reload_live_endpoints: bool, ?version_scope: untyped, ?close_on: Symbol?) -> Array[ActivityStep]
+  # : (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?reload_live_endpoints: bool, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool) -> Array[ActivityStep]
+  def self.activity_timeline: (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?reload_live_endpoints: bool, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool) -> Array[ActivityStep]
 
   # Builds an endpoint diff and root-checkpoint timeline while normalizing each version once.
-  # : (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?) -> Analysis
-  def self.analyze: (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?) -> Analysis
+  # : (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool) -> Analysis
+  def self.analyze: (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool) -> Analysis
 
   # Analyzes many roots over one shared time window, preparing their selected
   # history once for the batch instead of once per record. Roots with no

metadata

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