paper_trail_diff 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4d60569584c3d30bd35c62c1f0f699fd8859545d81f873c926dfdd8268aed3df
-  data.tar.gz: 4961a77099927fff3476641b0409cb234e1f398e9b84e9cb3cc9e11b2d580064
+  metadata.gz: fac7dbbad6368383d2b73f4c5acbdcabb1599da6c096a5c8363327a8602a1298
+  data.tar.gz: 7657cc9ae4b3e8f7d9f1026ac06fb93b6571ba7258bca66183b84053bb8469c0
 SHA512:
-  metadata.gz: 2cf13bffaca3d199b2332b0e3d1c7c7c00ef7c6f82a4c9e5a75c51f376889ff57c60e1bfab1f578a7122e972698318d2720bce5f8da2755abea50aebf6e7083e
-  data.tar.gz: a071cd71f7fb766105eda1e018991ed8030885822da23382404797984b265818c0012378aea5912a507fb7bc24e9294331201b0cf1918860df3d9613476d580d
+  metadata.gz: adadf85c15151889247d0791ffc944731c781c6dc3f4d23b4a04fa046e489b74f2a6501a16fb53386e6c80c3fae4d6c583d4b91db198bfbe8919a3a19eaf1a4e
+  data.tar.gz: 2a3bf4422b73c513981b519d04f0c556574f75ebc08963fab606f872c2428acac2455869675318ae75d8f71bddeb208e952642eeafedae7131b4745b5f36f534

data/CHANGELOG.md

@@ -3,6 +3,82 @@
 All notable changes to this project will be documented in this file. The
 project follows [Semantic Versioning](https://semver.org/).
 
+## [0.4.0] - 2026-08-11
+
+### Added
+
+- Close an activity timeline that ends at the root's own `destroy` version with
+  a step into a new `kind: :destroyed` boundary, reporting the record's removal
+  as a `record_presence_change` to `nil`. `ActivityBoundary` gains a
+  `destroyed?` predicate, so consumers branching only on `version?` should
+  handle the third kind. `compare`, `timeline`, and `analyze`'s endpoint diff
+  are unchanged.
+- Accept a `within:` window whose last selected mutation is the root's own
+  destruction, which no later root version can follow, instead of raising
+  `IncompleteTimeRangeError` for a range that could never be satisfied. A
+  destruction outside the window remains reconstruction context only.
+- Accept `:first` and `:last` as `from:` and `to:` boundaries on `timeline`,
+  `activity_timeline`, and `analyze`, resolved without depending on the order
+  the `versions` association happens to use. A record with no versions resolves
+  to an empty timeline rather than raising, so listing pages need no special
+  case.
+
+### Removed
+
+- Reject two version endpoints given in reverse chronological order with the
+  new `PaperTrailDiff::ReversedEndpointsError`, in `compare` and
+  `compare_many`. A transposed pair silently produced the inverse diff, and a
+  result carries no direction that would reveal it. A current-record endpoint
+  may still appear on either side.
+
+### Fixed
+
+- Rebuild prepared scalar state with direct attribute writes so a model that
+  overrides an attribute writer reconstructs the state PaperTrail recorded
+  instead of reapplying the override.
+
+### Changed
+
+- Order collection `added`, `removed`, and `changed` results naturally within
+  one id type instead of by the printed form, so numeric ids sort `2` before
+  `10`. Ordering remains deterministic and total for mixed id types.
+- Resolve a boundary's prepared record state by chronological search and an
+  indexed boundary transaction instead of scanning a record's versions, so
+  timelines over long single-record histories stay linear in their step count.
+- Bound prepared scalar history at the selected range plus one trailing version
+  per identity, instead of every version recorded between the range and the
+  present, so a short range early in a long history no longer pays for the
+  history after it.
+- Document that `timeline` and `analyze(activity: true)` produce the same
+  root-checkpoint steps through different reconstruction strategies, and when
+  each one is cheaper.
+- Borrow a connection through `with_connection` where Active Record provides
+  it, so applications that opt into deprecating permanent checkouts no longer
+  see a deprecation warning from association candidate selection.
+- Identify carried-forward collection snapshots and per-pass reification by
+  an owned serial and by record identity, rather than by `object_id`, which
+  Ruby only guarantees to be unique among live objects.
+- Retain activity-event routes for every event type a timeline visits, rather
+  than only the most recent one, so interleaved descendant types stop
+  rediscovering the same routes.
+- Resolve excluded attributes once per model class and selected path, and key
+  historical child identities instead of rescanning them.
+
+## [0.3.1] - 2026-08-10
+
+### Fixed
+
+- Preserve immutable activity snapshots for nested events that do not match a
+  selected child record, instead of reporting a false change.
+
+### Changed
+
+- Split activity-event reconstruction, route discovery, relationship matching,
+  collection mutation, and `belongs_to` target application into focused
+  internal collaborators without changing result shapes.
+- Reuse immutable activity-event routes and cached branch components across
+  repeated event types to reduce timeline allocation overhead.
+
 ## [0.3.0] - 2026-08-10
 
 ### Added

data/README.md

@@ -1,5 +1,14 @@
 # paper_trail_diff
 
+> [!WARNING]
+> **Experimental software and AI disclosure:** This gem is experimental and may
+> contain incomplete behavior, reconstruction errors, performance problems, or
+> breaking changes. AI-assisted coding tools made significant contributions to
+> its design, implementation, tests, and documentation under maintainer
+> direction. AI involvement is not a substitute for independent review: audit
+> the code and validate it against your own PaperTrail history before relying on
+> it in production, compliance, security, or other high-stakes workflows.
+
 `paper_trail_diff` adds structured endpoint, checkpoint-timeline, and activity
 comparisons to
 [PaperTrail](https://github.com/paper-trail-gem/paper_trail). It returns immutable
@@ -35,12 +44,84 @@ PaperTrail.config.track_associations = true
 All associated models whose historical state is compared must use
 `has_paper_trail`.
 
+## How PaperTrail records state
+
+Almost everything else in this README follows from one property of PaperTrail,
+so it is worth being precise about it first: **a version stores the state that
+existed _before_ the event that created it.** A version is a record of what was
+overwritten, not of what was written.
+
+Take an article created as `"Draft"`, then updated to `"Published"`, then to
+`"Final"`:
+
+```text
+        v1              v2                v3            (no version)
+     "create"        "update"          "update"
+         |               |                 |                 |
+   ──────●───────────────●─────────────────●─────────────────●──────▶ time
+         |               |                 |                 |
+         └─── "Draft" ───┘                 |                 |
+              stored in v2                 |                 |
+                         └─ "Published" ───┘                 |
+                              stored in v3                   |
+                                           └──── "Final" ────┘
+                                             only in the table
+```
+
+Each state is stored by the version at the *end* of the interval it was live
+for. Three consequences run through the rest of this document:
+
+- **A `create` version reifies to `nil`.** Nothing preceded it. Comparing it
+  with a later state reports a structured `record_presence_change` rather than
+  inventing scalar changes.
+- **The newest state has no version at all.** It exists only in the table. A
+  fully historical result therefore needs a version *later* than the last change
+  it should reveal, which is why a `within:` window can raise
+  `IncompleteTimeRangeError`, and why `activity_timeline(..., to: article)`
+  exists for ending at current state instead.
+- **A change is visible between two boundaries**, never "at" one. This is why
+  both timeline APIs return steps rather than events.
+
+The [Quickstart](QUICKSTART.md) walks through the same idea against a real
+console session.
+
+## Choosing an entry point
+
+| You need | Call |
+| --- | --- |
+| The net difference between two endpoints | `compare` |
+| The same, for many records in one pass | `compare_many` |
+| One step per version of the root record | `timeline` |
+| One step per version of the root *or a selected child* | `activity_timeline` |
+| A net difference and a timeline from one history pass | `analyze` |
+
+`timeline` and `activity_timeline` differ only in which recorded versions
+become boundaries. Given an article with two comment edits between two article
+versions:
+
+```text
+recorded versions   A1        C1      C2        A2      A = Article version
+                    |         |       |         |       C = Comment version
+                ────●─────────●───────●─────────●────▶ time
+                    |         |       |         |
+timeline            └───────── 1 step ──────────┘
+                    both comment changes land inside that one step
+
+activity_timeline   └── 1 ────┴── 2 ──┴─── 3 ───┘
+                    each recorded version becomes its own boundary
+```
+
+Both report the same underlying data: a `timeline` step still contains every
+selected association, because it has to describe what changed beneath the root.
+They differ in how finely that change is split, and in what the reconstruction
+costs. That cost trade-off is covered under
+[choosing a reconstruction strategy](#choosing-between-timeline-and-analyzeactivity-true).
+
 ## Compare two endpoints
 
-PaperTrail stores an object's state before each recorded event. `compare`
-accepts two explicit endpoints: each may be a PaperTrail version or a clean,
-persisted model instance representing current database state. It reports only
-their net difference:
+`compare` accepts two explicit endpoints: each may be a PaperTrail version or a
+clean, persisted model instance representing current database state. It reports
+only their net difference:
 
 ```ruby
 diff = PaperTrailDiff.compare(article.versions[1], article.versions[4])
@@ -60,10 +141,21 @@ diff.to_h
 
 Intermediate edits do not affect `compare`. If a title changes and later
 returns to its original value, endpoint comparison reports no title change.
-A `create` version reifies to `nil`; comparing it with a record state produces
-a structured `record_presence_change` instead of fake scalar changes. For
-ordinary updates, `record_presence_change` is `nil`, meaning the root record is
-present at both endpoints; scalar changes remain under `attributes`.
+
+`record_presence_change` reports whether the root record *existed* at each
+endpoint, and is `nil` for the ordinary case where it existed at both. It is
+populated when one endpoint reifies to `nil` — most often a `create` version,
+whose pre-change state is the absence of the record — and it then carries whole
+`RecordSnapshot` values rather than fake scalar changes from `nil`.
+
+Destroying the root record is not reported this way, and the reason follows
+from the [pre-change model](#how-papertrail-records-state): the state *at* a
+`destroy` version is the state immediately before the deletion, so the record
+is still present there. A comparison ending at a `destroy` version reports that
+last edit, not the deletion. Deleting a *selected child* is reported normally,
+as a `removed` member of its parent's collection, and `activity_timeline`
+reports a destroyed root through a
+[closing removal step](#closing-a-destroyed-root).
 
 Pass the record explicitly when the desired endpoint is current state:
 
@@ -75,10 +167,18 @@ diff = PaperTrailDiff.compare(
 )
 ```
 
-Version and record endpoints may appear in either order. Current state is never
-inferred. The record must be persisted, not destroyed, and free of unsaved
-attribute changes. The gem reloads it unscoped before normalization, so stale
-association caches and in-memory edits are not compared. Use a database
+Two version endpoints must be given in chronological order. A transposed pair
+produces the inverse diff, which is easy to do by accident and impossible to
+detect afterwards because a result carries no direction of its own, so it
+raises `PaperTrailDiff::ReversedEndpointsError` instead. Nothing is lost by
+this: the two orders differ only in which side of each change is `from`.
+
+A current-record endpoint is exempt and may appear on either side, because it
+is self-evidently the live state and placing it first is a deliberate reverse
+comparison. Current state is never inferred. The record must be persisted, not
+destroyed, and free of unsaved attribute changes. The gem reloads it unscoped
+before normalization, so stale association caches and in-memory edits are not
+compared. Use a database
 transaction with an appropriate isolation level when several live association
 queries must represent one atomic application snapshot.
 
@@ -87,17 +187,30 @@ preload each explicitly selected live association path across the batch. Each
 entry has the same endpoints and options as `compare`; results are returned in
 input order as a frozen hash keyed by `[item_type, item_id]` strings:
 
+Endpoints are still supplied by the caller, so look them up in bulk too —
+otherwise the per-root queries this API removes come straight back. Two
+queries resolve the earliest version of every root, whatever the batch size:
+
+```ruby
+orders = Order.where(id: order_ids).to_a
+
+earliest_ids = PaperTrail::Version
+  .where(item_type: "Order", item_id: orders.map(&:id))
+  .group(:item_id)
+  .minimum(:id)
+first_versions = PaperTrail::Version
+  .where(id: earliest_ids.values)
+  .index_by(&:item_id)
+```
+
 ```ruby
 diffs = PaperTrailDiff.compare_many(
-  [
-    { from: first_versions.fetch(order_a.id), to: order_a },
-    { from: first_versions.fetch(order_b.id), to: order_b }
-  ],
+  orders.map { |order| { from: first_versions.fetch(order.id), to: order } },
   associations: [:line_items],
   ignore: []
 )
 
-diffs.fetch(["Order", order_a.id.to_s]) # => PaperTrailDiff::Diff
+diffs.fetch(["Order", orders.first.id.to_s]) # => PaperTrailDiff::Diff
 ```
 
 Root identities must be unique within one call. Historical reconstruction for
@@ -116,7 +229,8 @@ must observe one atomic snapshot.
 already owns a consistent, fully preloaded graph may opt out:
 
 ```ruby
-orders = Order.where(id: ids).preload(line_items: :product).to_a
+orders = Order.where(id: order_ids).preload(line_items: :product).to_a
+# `first_versions` is the same bulk endpoint lookup shown above.
 
 diffs = PaperTrailDiff.compare_many(
   orders.map do |order|
@@ -173,8 +287,28 @@ end
 
 ## Build a root-checkpoint timeline
 
-`timeline` accepts two version objects from the supplied record's history. The
-range is inclusive, must be chronological, and produces one `Step` for each
+`timeline` accepts two version objects from the supplied record's history, or
+the symbols `:first` and `:last` when the range is simply the record's whole
+recorded history:
+
+```ruby
+steps = PaperTrailDiff.timeline(article, from: :first, to: :last)
+```
+
+`:first` and `:last` are resolved by the gem, independently of the order the
+`versions` association happens to use, so a caller never has to know it is
+sorted. They work anywhere a version does, including mixed with an explicit
+one (`from: :first, to: some_version`) and on `activity_timeline` and
+`analyze`. A record with no versions has no boundaries to resolve; that is an
+empty history rather than a bad request, so the result is an empty timeline
+instead of an error — which is usually what an index page wants.
+
+Combine `from: :first` with `to: article` for the fullest activity view of a
+live record: the whole recorded history, ending at current state. See
+[activity timelines](#build-an-activity-timeline) for why that end differs from
+`to: :last`.
+
+The range is inclusive, must be chronological, and produces one `Step` for each
 adjacent pair:
 
 ```ruby
@@ -196,7 +330,7 @@ steps.first.to_h
 
 Both timeline types expose `from_boundary`, `to_boundary`, `diff`, and
 `empty?`. A historical boundary has `event`, `whodunnit`, `record`,
-`recorded_at`, `version?`, and `current?` readers. Checkpoint `Step` objects
+`recorded_at`, `version?`, `current?`, and `destroyed?` readers. Checkpoint `Step` objects
 also retain their original `from_version` and `to_version` for callers that
 need custom PaperTrail metadata. Existing `Step#to_h` and
 `ActivityBoundary#to_h` shapes remain unchanged; use the readers for the new
@@ -226,7 +360,9 @@ steps.reject(&:empty?)
 ```
 
 Pass the record explicitly as `to:` to include current state without creating a
-final root checkpoint:
+final root checkpoint. This is not the same as `to: :last`: descendant
+mutations recorded after the record's final root version fall outside a
+version-bounded range, so only a live end reports them.
 
 ```ruby
 steps = PaperTrailDiff.activity_timeline(
@@ -259,6 +395,46 @@ 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.
 
+### Closing a destroyed root
+
+A `destroy` version is the one boundary whose following state needs no later
+version: the event itself says the record is gone. When an activity timeline
+ends at the root's own `destroy` version, it therefore closes with one more
+step, from that version to a `kind: :destroyed` boundary, whose diff is a
+`record_presence_change` from the record's final state to `nil`:
+
+```ruby
+steps = PaperTrailDiff.activity_timeline(
+  article,
+  from: article.versions.first,
+  to: article.versions.last # a destroy version
+)
+
+removal = steps.last
+removal.to_boundary.destroyed?                  # => true
+removal.to_boundary.kind                        # => :destroyed
+removal.diff.record_presence_change.from        # the state it was deleted in
+removal.diff.record_presence_change.to          # => nil
+```
+
+The removal step's `from_boundary` is the ordinary `kind: :version` boundary
+for the same destroy version, since that boundary still holds the record.
+Boundaries therefore have three kinds — `:version`, `:current`, and
+`:destroyed` — so a consumer that branches on `version?` alone should also
+handle `destroyed?`.
+
+`analyze(activity: true)` reports the same closing step in its
+`activity_timeline`. Its `diff` and `timeline` keep their `compare` and
+`timeline` semantics and do not report the deletion.
+
+A `within:` window behaves the same way. A window whose last selected mutation
+is the root's destruction needs no later root version, because none can ever
+exist, so it closes on the removal instead of raising
+`IncompleteTimeRangeError`. When the destruction falls *outside* the window it
+remains ordinary reconstruction context and is not reported as a selected
+mutation. The same relaxation lets the plain `timeline` accept such a window,
+though it still reports only the edits.
+
 Live-ended HABTM activity is rejected with
 `PaperTrailDiff::UnsupportedLiveActivityError`. HABTM join rows have no model
 versions, so the gem cannot reliably split their membership mutations into
@@ -306,7 +482,9 @@ If the window contains a relevant mutation but no later root version exists,
 the call raises `PaperTrailDiff::IncompleteTimeRangeError`. Create a root
 checkpoint after the reporting window before running historical analysis. The
 gem does not silently substitute current database state. A root-only window
-with no selected mutation returns a frozen empty timeline.
+with no selected mutation returns a frozen empty timeline. The one exception is
+a window that closes on the root's own destruction, which no later version can
+ever follow; see [closing a destroyed root](#closing-a-destroyed-root).
 
 Time ranges and explicit `from:`/`to:` endpoints are mutually exclusive.
 Malformed, open-ended, or reversed ranges raise
@@ -343,6 +521,37 @@ work is performed. `analyze` accepts explicit historical versions or
 `within:`, but not a current-record endpoint; use the standalone
 `activity_timeline(..., to: article)` API when the final boundary must be live.
 
+### Choosing between `timeline` and `analyze(activity: true)`
+
+`analysis.timeline` and `timeline` return the same root-checkpoint steps for the
+same range. They are two reconstruction strategies for one result, not two
+levels of detail: a `timeline` step covers only root version boundaries, but
+each of its snapshots still contains every selected association, because a step
+must report what changed underneath the root as well.
+
+The one behavioural difference is at the edge of a `within:` window. Selected
+descendants can move inside a window that contains no root version at all, so
+the activity form requires a root boundary it can reconstruct from and raises
+`IncompleteTimeRangeError` when there is none. `timeline` has no activity view
+to anchor and returns no steps for that window.
+
+The strategies differ in what that costs:
+
+- `timeline` reconstructs the whole selected graph independently at every root
+  boundary, so it costs roughly *root versions x selected graph size*. It is
+  insensitive to how much descendant activity happened in between.
+- `analyze(activity: true)` reconstructs once and then advances that snapshot
+  through each recorded mutation, so it costs roughly *one reconstruction +
+  total events*. It is insensitive to how wide the selected graph is.
+
+Neither dominates. Reconstructing once per checkpoint wins when a few root
+versions span very heavy descendant churn; advancing incrementally wins when
+the selected graph is wide and descendant activity is comparable to root
+activity. As a rule of thumb, prefer `analyze(activity: true)` when selected
+associations are wide, and `timeline` when descendant events greatly outnumber
+root versions. Measure with `ActiveSupport::Notifications` on a representative
+history rather than a seeded example if the choice matters.
+
 `timeline`, `activity_timeline`, and both forms of `analyze` prepare the selected
 historical range once. The loader walks only the explicit association paths and
 builds an immutable temporal index of scalar states, relationship candidates,
@@ -378,12 +587,13 @@ retain the general comparator and traversal fallback.
 Activity event loading is bounded to the selected range. Association identity
 discovery retains one indexed checkpoint for members present at the starting
 boundary, then considers later association activity and current members; it no
-longer materializes every pre-range association row. Prepared scalar state also
-retains later successor versions for selected identities because a PaperTrail
-version is a pre-change snapshot and may be the only correct state for an
-earlier boundary. Memory therefore scales with relevant selected history, not
-only with the number of returned steps. Keep requested paths and ranges
-intentional. An activity timeline must also emit a diff for every selected
+longer materializes every pre-range association row. Because a PaperTrail
+version is a pre-change snapshot, the state at a range's final boundary can
+live only in the next version after it, so prepared scalar state retains one
+trailing version per selected identity. It does not retain the rest of the
+history recorded after the range, so a short range early in a long history
+costs the same as the same range in a short one. Keep requested paths and
+ranges intentional. An activity timeline must also emit a diff for every selected
 event. Repeated events within one wide collection still copy the frozen records
 array when producing each immutable snapshot, so they can do pointer-copying
 work proportional to the number of events times the collection width even when
@@ -617,6 +827,29 @@ when join attributes or join mutations must appear as first-class history.
 
 ## Result objects
 
+Every level of a result separates the same two kinds of change in the same way:
+
+| | a record appears or disappears | a record stays and its fields change |
+| --- | --- | --- |
+| the root record | `record_presence_change` | `attributes`, `associations` |
+| `has_many`, HABTM | `added`, `removed` | `changed` |
+| `belongs_to`, `has_one` | `relationship` | `changed` |
+
+The left column carries whole `RecordSnapshot` values; the right column carries
+field-level `ValueChange` deltas. That split is deliberate. A record that has
+just appeared has no previous value for any of its fields, so reporting one
+`nil` to value change per attribute would both add noise and blur the
+difference between "this field was edited" and "this record did not exist".
+
+The consequence is that reading a result tree directly means branching on which
+column applies: a created record's state is under
+`record_presence_change.to.attributes`, an edited record's is under
+`attributes`. Consumers that would rather not branch should use
+[`each_entry`](#traverse-result-trees), which flattens both into one stream —
+an edit arrives as `attribute_changed` carrying a `ValueChange`, and a created
+record's fields arrive as `attribute_included` entries carrying values with
+`state: :after`.
+
 The public result types are:
 
 - `PaperTrailDiff::Diff`
@@ -636,7 +869,9 @@ The public result types are:
 - `PaperTrailDiff::DiagnosticIssue`
 
 They expose readers, are frozen after construction, and provide deterministic
-`to_h` output. Structural hash keys are symbols; attribute and association
+`to_h` output. Collection results are ordered by record identity: by type, then
+naturally within one id type, so numeric ids sort `2` before `10`. Mixed or
+unusual id types still order totally rather than raising. Structural hash keys are symbols; attribute and association
 names are strings. Attribute values retain their Ruby types. `RecordChange#record`
 is a `RecordReference` with `type` and `id` readers. `TraversalEntry#record` and
 `#association` return the final components of their corresponding paths. `Step`
@@ -662,6 +897,10 @@ and PT-AT can reconstruct. In particular:
 - HABTM membership is limited to the join snapshots PT-AT recorded in
   `version_associations`; historical target attributes require versioned target
   models, otherwise PT-AT may return live target state;
+- `compare`, `timeline`, and `analyze`'s endpoint diff do not report the root
+  record's destruction, because the state recorded at a `destroy` version is the
+  state before the deletion; `activity_timeline` closes on a `:destroyed`
+  boundary instead, and a selected child's removal is reported by its parent;
 - `timeline` and `analyze` are bounded by root versions; `activity_timeline`
   adds recorded descendant boundaries and may terminate at an explicitly passed
   current record, while a fully historical result still requires a later root

data/lib/paper_trail_diff/activity_belongs_to_event_applier.rb

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

data/lib/paper_trail_diff/activity_boundary.rb

@@ -37,6 +37,22 @@ module PaperTrailDiff
           recorded_at: captured_at
         )
       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)
+        new(
+          kind: :destroyed,
+          version_id: version.id,
+          item_type: version.item_type,
+          item_id: version.item_id,
+          recorded_at: version.created_at,
+          event: version.event,
+          whodunnit: version.whodunnit
+        )
+      end
     end
 
     #: (kind: Symbol, version_id: untyped, item_type: untyped, item_id: untyped, recorded_at: untyped, ?event: untyped, ?whodunnit: untyped) -> void
@@ -70,6 +86,11 @@ module PaperTrailDiff
       kind == :current
     end
 
+    #: () -> bool
+    def destroyed?
+      kind == :destroyed
+    end
+
     #: () -> Hash[Symbol, untyped]
     def to_h
       {