paper_trail_diff 0.3.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6aa099f4051971c69ed9b957e68ed4acca7e3cdde7c97efd2cb9a1af90d91dd1
-  data.tar.gz: 67ef88d6978b8b559a1a156f52aaea97a6535c71ec04df5d913f062114ec7a43
+  metadata.gz: a4d3c1e15ef20c4e3d05f5c0442d7e55cd0eb811a15766d2119a3cf35b2e729c
+  data.tar.gz: 4cc8dceb10e7aa71f1feb7d9fcc3917040bec4b2cc69641b4b3817d6761aad94
 SHA512:
-  metadata.gz: d916bf31322056bc95bfe39d7640207f2ddc6b30f154ca8e517b4615558ae728b1642f01040bb793ff1f258b3b77113ab6564f6f24daae9a23b09114ec7a6dca
-  data.tar.gz: b39856d07d0d335d12f7e1855b67f07b2a84443ff799f48a77e9b6a41609547310927fe8b8b69e32add5fbb30711982af3b125a80a40a59b1185a6ae8d1eb4fb
+  metadata.gz: 3887a515ee90f1c14b890a21d4a91b4892f4097b74c9ec27f136fd8476f01cd285c0a310a03b0c528e709cdca299bca2e243522844d09a86d272c043e48879b1
+  data.tar.gz: a1390db78cc31cbf20420fd18b536ad8cd826de4927943cbdddc08b7a31f9dad5f81acee77db97059f044ad435bd3170e54f8ef2ccd5c68f3e256bfa5d848642

data/CHANGELOG.md

@@ -3,6 +3,87 @@
 All notable changes to this project will be documented in this file. The
 project follows [Semantic Versioning](https://semver.org/).
 
+## [0.5.0] - 2026-08-11
+
+### Added
+
+- Add `analyze_many`, which analyzes many roots over one shared `within:` window,
+  or over each root's whole history when the window is omitted, selecting their
+  versions and preparing their history once for the batch. Query cost is flat in
+  the number of roots for the endpoint diff and checkpoint timeline; descendant
+  event discovery under `activity: true` remains per-root. A root with no
+  versions in range returns an empty `Analysis`, and roots are supplied as live
+  records so a root deleted inside the window cannot be included.
+- Accept `:first` and `:last` as `compare_many` endpoints, resolved against the
+  record the pair's other endpoint names, in two queries per model class rather
+  than one lookup per root. A root with no recorded history compares as an empty
+  `Diff`, and an unanchored `{ from: :first, to: :last }` raises.
+- Accept `reload_live_endpoints:` on `activity_timeline`, which reads live state
+  whenever `to:` is a current record but previously had no way to reuse an
+  already-preloaded graph. `timeline` and `analyze` are bounded by versions and
+  never read live state, so the option is deliberately absent there.
+
+## [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

data/README.md

@@ -44,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])
@@ -69,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:
 
@@ -84,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.
 
@@ -96,19 +187,47 @@ 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
+```
+
+Endpoints may also be given as `:first` or `:last`, resolved against the record
+the pair's other endpoint names. That replaces the lookup above entirely, and
+resolves every root in two queries per model class rather than one per root:
+
+```ruby
+diffs = PaperTrailDiff.compare_many(
+  orders.map { |order| { from: :first, to: order } },
+  associations: [:line_items]
+)
 ```
 
+A symbol carries no identity of its own, so `{ from: :first, to: :last }` raises
+rather than guessing. A root with no recorded history resolves to an empty
+`Diff`, matching how the timeline APIs answer the same question.
+
 Root identities must be unique within one call. Historical reconstruction for
 ordinary versioned, unscoped association paths is also prepared across the
 collection. Paths that require the existing point-in-time PT-AT fallback retain
@@ -121,11 +240,14 @@ must observe one atomic snapshot.
 
 ### Reuse already-preloaded current endpoints
 
-`compare` and `compare_many` reload current endpoints by default. A caller that
-already owns a consistent, fully preloaded graph may opt out:
+`compare`, `compare_many`, and `activity_timeline(..., to: record)` reload
+current endpoints by default. A caller that already owns a consistent, fully
+preloaded graph may opt out. The option has no effect on `timeline` or
+`analyze`, which are bounded by versions and never read live state:
 
 ```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|
@@ -180,10 +302,67 @@ ActiveSupport::Notifications.subscribed(callback, "sql.active_record") do
 end
 ```
 
+## Analyze many records over one window
+
+`analyze_many` answers "what changed for these records during this period" for a
+whole collection, selecting every root's versions and preparing their selected
+association history once for the batch:
+
+```ruby
+results = PaperTrailDiff.analyze_many(
+  Order.where(status: "open").to_a,
+  within: Time.zone.parse("2026-08-01")...Time.zone.parse("2026-09-01"),
+  associations: [:line_items]
+)
+
+results.fetch(["Order", order.id.to_s]).diff      # net change across the window
+results.fetch(["Order", order.id.to_s]).timeline  # its checkpoint steps
+```
+
+Results are a frozen hash keyed by `[item_type, item_id]` strings, and each
+value is the same `Analysis` that `analyze` returns for one record. A root with
+no versions inside the window gets an empty `Analysis` rather than raising, so a
+listing page needs no special case. Root identities must be unique.
+
+Omit `within:` to analyze each root's whole recorded history instead, which is
+the batched equivalent of `analyze(record, from: :first, to: :last)`. Explicit
+version endpoints are not accepted, because a single pair cannot mean the same
+thing for every root.
+
+Query cost is flat in the number of roots for the diff and timeline views:
+selecting versions and preparing history are both shared across the batch. On a
+twenty-root batch that is 7 queries against 120 for the same work done one
+record at a time. Passing `activity: true` also works and returns the same
+results, but discovering descendant events is inherently per-root, so that view
+batches far less.
+
+Roots are supplied as live records, so a root deleted inside the window cannot
+be included; use `activity_timeline` for a history that ends in a deletion.
+
 ## 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
@@ -205,7 +384,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
@@ -235,7 +414,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(
@@ -268,6 +449,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
@@ -315,7 +536,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
@@ -352,6 +575,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,
@@ -387,12 +641,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
@@ -626,6 +881,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`
@@ -645,7 +923,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`
@@ -671,6 +951,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_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
       {