paper_trail_diff 0.14.0 → 0.15.0

data/docs/testing.md

@@ -8,7 +8,7 @@ mise exec -- bundle exec rake
 ```
 
 The default task runs the core specs without PT-AT loaded, the association specs
-in a separate process, RuboCop (with the rubocop-performance and rubocop-rspec
+and the [oracle checks](#oracle-checks) each in a separate process, RuboCop (with the rubocop-performance and rubocop-rspec
 plugins), generated-signature verification, and Steep.
 Ruby blocks in the README, quickstart, and API reference marked with
 `<!-- executable:... -->` run inside those specs, so documented examples stay
@@ -37,6 +37,49 @@ history, with integer and string `versions.item_id`, YAML and JSON history, and
 a `has_paper_trail skip:` column. When one fails, its seed reproduces it. Add a
 variant here when a bug turns out to depend on a schema or configuration.
 
+## Oracle checks
+
+The consistency checks compare gem methods with each other, so a bug they
+share passes. `spec/oracle` compares them with the truth instead:
+
+1. A seeded generator (`spec/support/oracle.rb`) makes random edits to an
+   article graph, one transaction each: root edits and checkpoints, comments
+   and replies created, edited, moved, and deleted, an author, a profile, and
+   authorships with their authors. Some transactions write several versions.
+2. After each transaction it records the live state, keyed by the versions
+   that transaction wrote, so every version names the state just before it.
+   The state comes from the gem's current-record path, which is plain Active
+   Record, and is checked against an independent read of each association.
+3. Every endpoint pair, every timeline step, every activity step (grouped and
+   not), and windows through `analyze`, `analyze_many`, and `analyze_scope`
+   are compared with the recorded states. Two windows that meet between
+   transactions, or inside one, must report each step once, as the window
+   spanning both does, through both `activity_timeline` and `analyze_many`.
+
+Two more generators cover other shapes. `scoped_membership_spec.rb` moves
+notes in and out of scoped associations (conditions, order, limit, and
+offset) and compares the members at every version with Active Record's own
+answer. `tree_history_spec.rb` edits a tree of one model, so a root can sit
+inside another root's tree, with children whose attributes are encrypted,
+serialized, enums stored as strings, custom types, decimals, and JSON. It reads
+the expected states with plain Active Record, not through the gem.
+
+```console
+mise exec -- bundle exec rake spec_oracle
+ORACLE_SEEDS=1..200 ORACLE_STEPS=40 mise exec -- bundle exec rake spec_oracle
+```
+
+The default seeds keep the run to a few seconds; `rake spec` includes it, so
+the database jobs run it too. Mutant does not, because it would slow every
+mutation. A failure prints its seed and the transactions it made. To fix one,
+reproduce it with that seed, reduce it to the few edits that matter, and add
+that as a named spec beside the code it covers, so the cause is readable
+without the generator.
+
+When a bug turns out to depend on a schema, configuration, or kind of edit,
+add it to the generator or as a new context, so the whole class of bug stays
+covered.
+
 ## Mutation testing
 
 [Mutant](https://github.com/mbj/mutant) changes the library one expression at
@@ -51,8 +94,10 @@ passes is behavior nothing checks. `mutant.yml` lists the classes it mutates:
 - which versions a batch or filter reads: `BatchedRootVersions`,
   `DeletedAnalysisBatch`, and `HistoricalFilter`;
 - what a version recorded: `RecordedChanges`;
+- how a step flattens into rows: `ChangeRow` and `ChangeRows`;
 - which records a scope or report selects: `ScopedRootSelection`,
-  `AssociationActivitySelection`, and `AssociationActivityEdge`;
+  `AssociationActivitySelection`, `AssociationActivityEdge`, and
+  `DeletedRootFilter`;
 - which children and targets a record had at each point:
   `PreparedHistoryLoader`, `PreparedEdgeLoader`,
   `ActivityTargetCandidateLoader`, and `PreparedActivityIndex`;
@@ -60,10 +105,11 @@ passes is behavior nothing checks. `mutant.yml` lists the classes it mutates:
   query reads: `ActivityRange` and `VersionAssociationCandidateScope`;
 - what activity a record shows: `ActivityTimelineBuilder` and
   `ActivityTransactionGrouper`;
-- which association paths a request accepts: `AssociationTraversal`;
+- which association paths a request accepts: `AssociationTraversal` and
+  `AssociationKey`;
 - whether a transaction's HABTM members are one record's:
   `HabtmTransactionOwners`;
-- which association paths a batch refuses: `BatchSafety`;
+- which association paths history cannot read exactly: `ApproximatePaths`;
 - which records an association scope admits, and how it ranks them:
   `ScopeCondition` and `ScopeRanking`.
 
@@ -79,7 +125,10 @@ description names the mutated class (`RSpec.describe PaperTrailDiff::Engine`),
 falling 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.
+and a class added to `mutant.yml` needs one too. A spec named after a
+behavior can still name the class it checks with metadata, as the activity
+window specs do: `RSpec.describe 'Activity over a window', mutant_expression:
+'PaperTrailDiff::ActivityTimelineBuilder'`.
 
 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
@@ -122,8 +171,10 @@ they resynchronize, which made window-based specs fail at random.
 `spec/support/monotonic_clock.rb` therefore makes `Time.now` strictly
 increasing, in whole microseconds, for the test process. ActiveRecord
 timestamps, PaperTrail's `created_at`, and windows built from `Time.now` all
-read it, so they stay consistent however the host clock moves. It affects only
-the test process; the gem itself reads the ordinary clock.
+read it, so they stay consistent however the host clock moves. The benchmark
+workload, `benchmark/support/workload.rb`, loads it too, because a step back
+could date a root's destroy before its last update. It affects only the specs
+and the benchmark; the gem itself reads the ordinary clock.
 
 ## Other databases locally
 
@@ -158,6 +209,11 @@ PaperTrail's default YAML serializer, the fixtures explicitly permit
 `ActiveRecord.yaml_column_permitted_classes` configuration. The gem does not
 change an application's YAML configuration.
 
+PT-AT compares version times through SQL text, which SQL Server's adapter
+writes as `datetime` values, up to 1/300 s off. So on SQL Server the
+association specs keep their versions 5 ms apart, or the specs that compare
+the gem with PT-AT would fail whenever versions were saved closer together.
+
 The CI service configuration is in `.github/workflows/ci.yml`. PostgreSQL and
 MySQL create the named database during container initialization. The SQL Server
 jobs create it explicitly after the service passes its health check.

data/lib/paper_trail_diff/activity_boundary.rb

@@ -17,9 +17,20 @@ module PaperTrailDiff
     # report one save as one step rather than as its parts.
     attr_reader :transaction_id #: untyped
 
+    # @rbs @recorded_changes: untyped
+
+    # Stands for recorded changes nobody asked to read, which differs from a
+    # version that recorded nothing (nil).
+    NOT_READ = Object.new.freeze
+    NOT_READ_MESSAGE = 'recorded changes were not read; pass recorded_changes: true'
+    private_constant :NOT_READ, :NOT_READ_MESSAGE
+
     class << self
-      #: (untyped) -> ActivityBoundary
-      def from_version(version)
+      # `recorded:` names the attributes to leave out of the version's recorded
+      # changes, or is nil when they were not asked for. Reading them decodes
+      # `object_changes`, which a caller who does not want them should not pay.
+      #: (untyped, ?recorded: Array[String]?) -> ActivityBoundary
+      def from_version(version, recorded: nil)
         new(
           kind: :version,
           version_id: version.id,
@@ -28,26 +39,29 @@ module PaperTrailDiff
           recorded_at: version.created_at,
           event: version.event,
           whodunnit: version.whodunnit,
-          transaction_id: transaction_id(version)
+          transaction_id: VersionBoundary.transaction_id(version),
+          recorded_changes: recorded_changes(version, recorded)
         )
       end
 
-      #: (untyped, captured_at: untyped) -> ActivityBoundary
-      def current(record, captured_at:)
+      # The current record has no version, so it recorded nothing.
+      #: (untyped, captured_at: untyped, ?recorded: Array[String]?) -> ActivityBoundary
+      def current(record, captured_at:, recorded: nil)
         new(
           kind: :current,
           version_id: nil,
           item_type: record.class.base_class.name,
           item_id: record.id,
-          recorded_at: captured_at
+          recorded_at: captured_at,
+          recorded_changes: recorded.nil? ? NOT_READ : nil
         )
       end
 
       # The state a `destroy` version leaves behind. A version records the state
       # before its own event, so the boundary built from a destroy version still
       # holds the record; this one is the absence that follows it.
-      #: (untyped) -> ActivityBoundary
-      def destroyed(version)
+      #: (untyped, ?recorded: Array[String]?) -> ActivityBoundary
+      def destroyed(version, recorded: nil)
         new(
           kind: :destroyed,
           version_id: version.id,
@@ -56,20 +70,24 @@ module PaperTrailDiff
           recorded_at: version.created_at,
           event: version.event,
           whodunnit: version.whodunnit,
-          transaction_id: transaction_id(version)
+          transaction_id: VersionBoundary.transaction_id(version),
+          recorded_changes: recorded_changes(version, recorded)
         )
       end
 
-      # A custom version class need not carry the column, and PaperTrail leaves
-      # it nil outside a transaction. Both read as "no transaction here", which
-      # groups with nothing.
-      #: (untyped) -> untyped
-      def transaction_id(version)
-        version.transaction_id if version.respond_to?(:transaction_id)
+      private
+
+      #: (untyped, Array[String]?) -> untyped
+      def recorded_changes(version, ignore)
+        return NOT_READ if ignore.nil?
+
+        RecordedChanges.call(version, ignore: ignore)
       end
     end
 
-    #: (kind: Symbol, version_id: untyped, item_type: untyped, item_id: untyped, recorded_at: untyped, ?event: untyped, ?whodunnit: untyped, ?transaction_id: untyped) -> void
+    # `recorded_changes:` takes what `PaperTrailDiff.recorded_changes` returns
+    # for the version; leave it out when they were not read.
+    #: (kind: Symbol, version_id: untyped, item_type: untyped, item_id: untyped, recorded_at: untyped, ?event: untyped, ?whodunnit: untyped, ?transaction_id: untyped, ?recorded_changes: untyped) -> void
     def initialize( # rubocop:disable Metrics/ParameterLists
       kind:,
       version_id:,
@@ -78,7 +96,8 @@ module PaperTrailDiff
       recorded_at:,
       event: nil,
       whodunnit: nil,
-      transaction_id: nil
+      transaction_id: nil,
+      recorded_changes: NOT_READ
     )
       @kind = kind
       @version_id = Support.immutable_copy(version_id)
@@ -88,10 +107,29 @@ module PaperTrailDiff
       @event = Support.immutable_copy(event&.to_s)
       @whodunnit = Support.immutable_copy(whodunnit)
       @transaction_id = Support.immutable_copy(transaction_id)
+      @recorded_changes = recorded_changes
       @record = RecordReference.new(type: @item_type, id: @item_id)
       freeze
     end
 
+    # What PaperTrail recorded with this boundary's version, as
+    # `PaperTrailDiff.recorded_changes` returns it: nil when nothing was
+    # recorded, and always nil for the current record, which has no version.
+    # Raises unless the timeline was built with `recorded_changes: true`, so a
+    # forgotten option cannot pass for a version that recorded nothing.
+    #: () -> Hash[String, ValueChange]?
+    def recorded_changes
+      raise ConfigurationError, NOT_READ_MESSAGE unless recorded_changes?
+
+      @recorded_changes
+    end
+
+    # Whether this boundary's recorded changes were read.
+    #: () -> bool
+    def recorded_changes?
+      !NOT_READ.equal?(@recorded_changes)
+    end
+
     #: () -> bool
     def version?
       kind == :version
@@ -115,11 +153,14 @@ module PaperTrailDiff
         item_type: item_type,
         item_id: item_id,
         recorded_at: recorded_at
-      }
+      } #: Hash[Symbol, untyped]
       return value unless metadata
 
-      value.merge(event: event, whodunnit: whodunnit, transaction_id: transaction_id,
-                  record: record.to_h)
+      value.merge!(event: event, whodunnit: whodunnit, transaction_id: transaction_id,
+                   record: record.to_h)
+      return value unless recorded_changes?
+
+      value.merge(recorded_changes: @recorded_changes&.transform_values(&:to_h))
     end
   end
 
@@ -135,28 +176,35 @@ module PaperTrailDiff
     # get wrong.
     attr_reader :from_snapshot #: RecordSnapshot?
     attr_reader :to_snapshot #: RecordSnapshot?
+    # The events whose changes this step reports, in the order they happened.
+    # That is `source_boundary` alone, unless the step is a transaction group,
+    # which holds every event in it: an attribution that names only the first
+    # would credit the rest of the save to whoever opened it.
+    attr_reader :sources #: Array[ActivityBoundary]
 
     # 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:)
+    #: (from_boundary: ActivityBoundary, to_boundary: ActivityBoundary, from_snapshot: RecordSnapshot?, to_snapshot: RecordSnapshot?, retain: bool, ?sources: Array[ActivityBoundary]?) -> ActivityStep
+    def self.between(from_boundary:, to_boundary:, from_snapshot:, to_snapshot:, retain:, sources: nil) # rubocop:disable Metrics/ParameterLists, Layout/LineLength
       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)
+        to_snapshot: (to_snapshot if retain),
+        sources: sources
       )
     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: ActivityBoundary, to_boundary: ActivityBoundary, diff: Diff, ?from_snapshot: RecordSnapshot?, ?to_snapshot: RecordSnapshot?, ?sources: Array[ActivityBoundary]?) -> void
+    def initialize(from_boundary:, to_boundary:, diff:, from_snapshot: nil, to_snapshot: nil, sources: nil) # rubocop:disable Metrics/ParameterLists, Layout/LineLength
       @from_boundary = from_boundary
       @to_boundary = to_boundary
       @diff = diff
       @from_snapshot = from_snapshot
       @to_snapshot = to_snapshot
+      @sources = (sources || [from_boundary]).dup.freeze
       freeze
     end
 
@@ -170,13 +218,22 @@ module PaperTrailDiff
     #: () -> ActivityBoundary
     def source_boundary = from_boundary
 
+    # The diff as flat rows, each attributed to `source_boundary`.
+    #: () -> Array[ChangeRow]
+    def change_rows
+      ChangeRows.call(diff, source: source_boundary)
+    end
+
+    # `metadata: true` also lists `sources`, since who made a change is
+    # metadata as much as the source boundary's own author is.
     #: (?metadata: bool, ?snapshots: bool) -> Hash[Symbol, untyped]
     def to_h(metadata: false, snapshots: false)
       value = {
         from: from_boundary.to_h(metadata: metadata),
         to: to_boundary.to_h(metadata: metadata),
         diff: diff.to_h
-      }
+      } #: Hash[Symbol, untyped]
+      value[:sources] = sources.map { |source| source.to_h(metadata: true) } if metadata
       return value unless snapshots
 
       value.merge(from_snapshot: from_snapshot&.to_h, to_snapshot: to_snapshot&.to_h)

data/lib/paper_trail_diff/activity_child_candidate_loader.rb

@@ -62,7 +62,8 @@ module PaperTrailDiff
 
     #: (untyped) -> untyped
     def historical_relation(version_class)
-      @parent_class.paper_trail.version_association_class.joins(:version).where(
+      associations = @parent_class.paper_trail.version_association_class
+      VersionTable.joined(associations, version_class).where(
         foreign_key_name: @reflection.foreign_key.to_s,
         foreign_key_id: @parent_ids,
         foreign_type: parent_types

data/lib/paper_trail_diff/activity_event.rb

@@ -7,10 +7,11 @@ module PaperTrailDiff
     attr_reader :version #: untyped
     attr_reader :branches #: Array[String]?
 
-    #: (version: untyped, branches: Array[String]?) -> void
-    def initialize(version:, branches:)
+    #: (version: untyped, branches: Array[String]?, ?join: bool) -> void
+    def initialize(version:, branches:, join: false)
       @version = version
       @branches = branches ? branches.map(&:to_s).uniq.sort.freeze : nil
+      @join = join
       freeze
     end
 
@@ -18,6 +19,15 @@ module PaperTrailDiff
     def root?
       branches.nil?
     end
+
+    # Whether the version is of a through's join row, which links the root to
+    # a target without being one.
+    #: () -> bool
+    def join?
+      @join
+    end
+
+    # @rbs @join: bool
   end
 
   # Accumulates each version once while retaining every selected root branch.
@@ -26,14 +36,15 @@ module PaperTrailDiff
       @events = {} #: Hash[Array[untyped], Hash[Symbol, untyped]]
     end
 
-    #: (Array[untyped], ?branch: String?) -> void
-    def add(versions, branch: nil)
+    #: (Array[untyped], ?branch: String?, ?join: bool) -> void
+    def add(versions, branch: nil, join: false)
       versions.each do |version|
         key = [version.class.name, version.id]
         existing = @events[key]
         @events[key] = {
           version: version,
-          branches: merged_branches(existing, branch)
+          branches: merged_branches(existing, branch),
+          join: join || existing&.fetch(:join) || false
         }
       end
     end
@@ -43,7 +54,8 @@ module PaperTrailDiff
       @events.values.map do |event|
         ActivityEvent.new(
           version: event.fetch(:version),
-          branches: event.fetch(:branches)
+          branches: event.fetch(:branches),
+          join: event.fetch(:join)
         )
       end
     end
@@ -64,6 +76,28 @@ module PaperTrailDiff
 
   # Resolves the branch union that PT-AT exposes atomically for one transaction.
   class ActivityTransactionGroups
+    # A range ending at a version ends at the state before that version's
+    # transaction: PT-AT rebuilds its associations without the changes saved
+    # alongside it. A descendant version from that transaction, such as the
+    # child update behind a `touch: true` parent version, is therefore past the
+    # end. Kept, it would open a step whose change the closing state cannot
+    # show, and that change would be reported nowhere. A range ending at a time
+    # has no transaction to stop before.
+    #: (Array[ActivityEvent], untyped) -> Array[ActivityEvent]
+    def self.before_closing(events, range_end)
+      key = transaction_key(range_end)
+      return events unless key
+
+      events.reject { |event| !event.root? && transaction_key(event.version) == key }.freeze
+    end
+
+    # A version without a transaction shares one with nothing.
+    #: (untyped) -> Array[untyped]?
+    def self.transaction_key(version)
+      transaction_id = VersionBoundary.transaction_id(version)
+      [version.class.name, transaction_id] if transaction_id
+    end
+
     #: (Array[ActivityEvent]) -> void
     def initialize(events)
       groups = grouped_events(events)
@@ -119,10 +153,7 @@ module PaperTrailDiff
 
     #: (ActivityEvent) -> Array[untyped]?
     def transaction_key(event)
-      version = event.version
-      return unless version.respond_to?(:transaction_id) && version.transaction_id
-
-      [version.class.name, version.transaction_id]
+      self.class.transaction_key(event.version)
     end
   end
 end

data/lib/paper_trail_diff/activity_history.rb

@@ -30,22 +30,26 @@ module PaperTrailDiff
 
   # Builds activity steps while retaining root snapshots for combined analysis.
   class ActivityHistoryBuilder
-    #: (Array[untyped], Array[ActivityEvent], untyped, ?current: untyped, ?include_step: untyped, ?snapshots: bool) -> void
+    # `closing` is the snapshot after the last event when the range closes on
+    # the current record. Any other range ends at a root event, or at events
+    # after a window whose steps are not reported, so nothing reads it.
+    #: (Array[untyped], Array[ActivityEvent], untyped, view: ActivityView, ?current: untyped, ?include_step: untyped, ?closing: RecordSnapshot?) -> void
     def initialize( # rubocop:disable Metrics/ParameterLists
-      root_versions, events, snapshotter, current: nil, include_step: nil, snapshots: false
+      root_versions, events, snapshotter, view:, current: nil, include_step: nil, closing: nil
     )
       @root_versions = root_versions
       @events = events
       @snapshotter = snapshotter
+      @view = view
       @current = current
       @include_step = include_step
-      @snapshots = snapshots
+      @closing = closing
     end
 
     #: () -> ActivityHistory
     def call
       reset
-      sequence.each { |event, snapshot| consume(event, snapshot) }
+      filter.call(sequence) { |event, snapshot, kept| consume(event, snapshot, kept) }
       ActivityHistory.new(
         steps: @steps,
         root_snapshots: @root_snapshots,
@@ -63,7 +67,8 @@ module PaperTrailDiff
     # @rbs @snapshotter: untyped
     # @rbs @current: untyped
     # @rbs @include_step: untyped
-    # @rbs @snapshots: bool
+    # @rbs @view: ActivityView
+    # @rbs @closing: RecordSnapshot?
     # @rbs @steps: Array[ActivityStep]
     # @rbs @root_snapshots: Hash[Array[untyped], RecordSnapshot?]
     # @rbs @first_snapshot: RecordSnapshot?
@@ -71,6 +76,7 @@ module PaperTrailDiff
     # @rbs @selected_last_snapshot: RecordSnapshot?
     # @rbs @previous_boundary: ActivityBoundary?
     # @rbs @previous_event: ActivityEvent?
+    # @rbs @passed_reported: bool
 
     #: () -> void
     def reset
@@ -82,6 +88,12 @@ module PaperTrailDiff
       @selected_last_snapshot = nil
       @previous_boundary = nil
       @previous_event = nil
+      @passed_reported = false
+    end
+
+    #: () -> ActivityTreeFilter
+    def filter
+      ActivityTreeFilter.new(@events, reported: @include_step, closing: @closing)
     end
 
     #: () -> ActivitySnapshotSequence
@@ -94,17 +106,30 @@ module PaperTrailDiff
       )
     end
 
-    #: (ActivityEvent, RecordSnapshot?) -> void
-    def consume(event, snapshot)
+    # A left-out event bounds nothing. A reported step it would have opened
+    # still moves the reported range's end past it, to the next boundary.
+    #: (ActivityEvent, RecordSnapshot?, bool) -> void
+    def consume(event, snapshot, kept)
       capture_first(snapshot)
-      boundary = ActivityBoundary.from_version(event.version)
+      return pass(event) unless kept
+
+      boundary = ActivityBoundary.from_version(
+        event.version, recorded: @view.recorded_attributes(root: event.root?)
+      )
       @root_snapshots[version_key(event.version)] = snapshot if event.root?
       append_step(boundary, snapshot) if @previous_boundary
+      @selected_last_snapshot = snapshot if @passed_reported
+      @passed_reported = false
       @previous_boundary = boundary
       @previous_event = event
       @previous_snapshot = snapshot
     end
 
+    #: (ActivityEvent) -> void
+    def pass(event)
+      @passed_reported = true if !@include_step || @include_step.call(event)
+    end
+
     #: (RecordSnapshot?) -> void
     def capture_first(snapshot)
       return if @first_snapshot_seen
@@ -122,7 +147,7 @@ module PaperTrailDiff
 
       @steps << ActivityStep.between(
         from_boundary: previous_boundary, to_boundary: boundary,
-        from_snapshot: @previous_snapshot, to_snapshot: snapshot, retain: @snapshots
+        from_snapshot: @previous_snapshot, to_snapshot: snapshot, retain: @view.retain?
       )
       @selected_last_snapshot = snapshot
     end

data/lib/paper_trail_diff/activity_range.rb

@@ -14,6 +14,8 @@ module PaperTrailDiff
                      Support.chronological_version_key(start_boundary)
                    end
       @start_time = Endpoint.version?(start_boundary) ? start_boundary.created_at : start_boundary
+      # A time has no transaction.
+      @opening_transaction = ActivityTransactionGroups.transaction_key(start_boundary)
       @end_time = Endpoint.version?(end_boundary) ? end_boundary.created_at : end_boundary
       @end_key = if Endpoint.version?(end_boundary)
                    Support.chronological_version_key(end_boundary)
@@ -26,11 +28,16 @@ module PaperTrailDiff
       after_start?(version, key) && before_end?(version, key)
     end
 
-    # Narrows an Active Record version relation by timestamp. Exact tie-breaking
-    # remains in #include? so this works for integer, UUID, and custom version IDs.
+    # Narrows an Active Record version relation by timestamp, and to the
+    # start's transaction. Exact tie-breaking remains in #include? so this
+    # works for integer, UUID, and custom version IDs.
     #: (untyped) -> untyped
     def scope(relation)
-      relation.where(created_at: @start_time..end_time)
+      in_time = relation.where(created_at: @start_time..end_time)
+      opening = @opening_transaction
+      return in_time unless opening
+
+      in_time.or(relation.where(transaction_id: opening.last))
     end
 
     #: () -> bool
@@ -58,9 +65,17 @@ module PaperTrailDiff
     # @rbs @start_key: Array[untyped]?
     # @rbs @start_time: untyped
     # @rbs @end_key: Array[untyped]?
+    # @rbs @opening_transaction: Array[untyped]?
 
+    # A range starting at a version starts before that version's transaction,
+    # where PT-AT reads its associations. A version saved earlier in it, such
+    # as the child update behind a `touch: true` parent version, is a change
+    # inside the range.
     #: (untyped, Array[untyped]) -> bool
     def after_start?(version, key)
+      opening = @opening_transaction
+      return true if opening && ActivityTransactionGroups.transaction_key(version) == opening
+
       start_key = @start_key
       return key_before_or_equal?(start_key, key) if start_key