paper_trail_diff 0.15.0 → 0.16.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (61) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +159 -1
  3. data/README.md +1 -1
  4. data/docs/performance.md +9 -0
  5. data/docs/reference.md +142 -28
  6. data/docs/testing.md +23 -3
  7. data/lib/paper_trail_diff/activity_collection_event_applier.rb +33 -1
  8. data/lib/paper_trail_diff/activity_event_route_finder.rb +31 -0
  9. data/lib/paper_trail_diff/activity_event_snapshot_refresher.rb +12 -1
  10. data/lib/paper_trail_diff/activity_root_snapshot_refresher.rb +43 -25
  11. data/lib/paper_trail_diff/activity_timeline_builder.rb +6 -0
  12. data/lib/paper_trail_diff/analysis.rb +25 -6
  13. data/lib/paper_trail_diff/analysis_batch.rb +2 -2
  14. data/lib/paper_trail_diff/batched_root_analyzer.rb +6 -0
  15. data/lib/paper_trail_diff/branch_snapshot_refresher.rb +19 -16
  16. data/lib/paper_trail_diff/deleted_analysis_batch.rb +7 -3
  17. data/lib/paper_trail_diff/deleted_root_filter.rb +30 -8
  18. data/lib/paper_trail_diff/diagnostics.rb +7 -5
  19. data/lib/paper_trail_diff/paper_trail_adapter.rb +96 -59
  20. data/lib/paper_trail_diff/prepared_activity_index.rb +16 -12
  21. data/lib/paper_trail_diff/prepared_history.rb +11 -5
  22. data/lib/paper_trail_diff/prepared_history_loader.rb +1 -3
  23. data/lib/paper_trail_diff/prepared_record_index.rb +6 -2
  24. data/lib/paper_trail_diff/read_snapshot.rb +77 -0
  25. data/lib/paper_trail_diff/scope_condition.rb +85 -15
  26. data/lib/paper_trail_diff/scope_ranking.rb +11 -12
  27. data/lib/paper_trail_diff/scoped_analysis_builder.rb +17 -7
  28. data/lib/paper_trail_diff/scoped_root_selection.rb +11 -4
  29. data/lib/paper_trail_diff/time_range.rb +7 -6
  30. data/lib/paper_trail_diff/timeline_builder.rb +6 -0
  31. data/lib/paper_trail_diff/transaction_cut.rb +100 -41
  32. data/lib/paper_trail_diff/version.rb +1 -1
  33. data/lib/paper_trail_diff/version_boundary.rb +4 -2
  34. data/lib/paper_trail_diff/version_sequence_diagnostics.rb +4 -1
  35. data/lib/paper_trail_diff.rb +7 -5
  36. data/sig/generated/paper_trail_diff/activity_collection_event_applier.rbs +13 -0
  37. data/sig/generated/paper_trail_diff/activity_event_route_finder.rbs +14 -0
  38. data/sig/generated/paper_trail_diff/activity_event_snapshot_refresher.rbs +6 -0
  39. data/sig/generated/paper_trail_diff/activity_root_snapshot_refresher.rbs +21 -10
  40. data/sig/generated/paper_trail_diff/activity_timeline_builder.rbs +4 -0
  41. data/sig/generated/paper_trail_diff/analysis.rbs +17 -5
  42. data/sig/generated/paper_trail_diff/batched_root_analyzer.rbs +4 -0
  43. data/sig/generated/paper_trail_diff/branch_snapshot_refresher.rbs +6 -0
  44. data/sig/generated/paper_trail_diff/deleted_analysis_batch.rbs +3 -0
  45. data/sig/generated/paper_trail_diff/deleted_root_filter.rbs +11 -3
  46. data/sig/generated/paper_trail_diff/paper_trail_adapter.rbs +10 -0
  47. data/sig/generated/paper_trail_diff/prepared_activity_index.rbs +11 -4
  48. data/sig/generated/paper_trail_diff/prepared_history.rbs +6 -1
  49. data/sig/generated/paper_trail_diff/prepared_record_index.rbs +2 -1
  50. data/sig/generated/paper_trail_diff/read_snapshot.rbs +43 -0
  51. data/sig/generated/paper_trail_diff/scope_condition.rbs +39 -7
  52. data/sig/generated/paper_trail_diff/scope_ranking.rbs +6 -6
  53. data/sig/generated/paper_trail_diff/scoped_analysis_builder.rbs +9 -2
  54. data/sig/generated/paper_trail_diff/scoped_root_selection.rbs +8 -3
  55. data/sig/generated/paper_trail_diff/time_range.rbs +4 -3
  56. data/sig/generated/paper_trail_diff/timeline_builder.rbs +4 -0
  57. data/sig/generated/paper_trail_diff/transaction_cut.rbs +46 -14
  58. data/sig/generated/paper_trail_diff/version_boundary.rbs +2 -0
  59. data/sig/generated/paper_trail_diff/version_sequence_diagnostics.rbs +3 -0
  60. data/sig/generated/paper_trail_diff.rbs +2 -2
  61. metadata +7 -5
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 4cc17a3d2f233d6f9bcc44605687ef4cabf1611f957ad41d0471b35236b8ab8d
4
- data.tar.gz: e123b779da0c52350cb05b4ed18f8585626d8cbcf45e3c737cfe43777f7bcf14
3
+ metadata.gz: 31ad8d55dab710a7295d5c6fef92918fee436492e35ec6fa785f49de025c2994
4
+ data.tar.gz: 04c4f17548bcda07300bb857dc6194b698f907bb1b71db06e61dbb3037e533dd
5
5
  SHA512:
6
- metadata.gz: 65f32e4a83fd05ba8cfece667be5842d41f9452ae84f49f495ff8ad0051b87c76ebddfb07c1a99c09227689eaa393286ca0737042bf6b6f7c6dffea0b77039bf
7
- data.tar.gz: 217119550346fc0eed08759dd20aa1a2fb53bd71dde161e43ef1243f191159fc7c1225924a6c39059dda8e2df4c4b17f0f1abed694938a2824a89e722e88e0d7
6
+ metadata.gz: 6a2cbc59fa7e53d31b78b1f0d5863519e1c72063718791323b938f73668ee53ddb19f6ac5cdf4d72b656dc6ec5c154e26485994da2ac90a6141d67928668c4ed
7
+ data.tar.gz: 7700f7863dcd954cea284ea1564def6a1d4b2a8679dd49a01bf618cf36333b6aba8c7e83b32cc7f2c481c81701ef5127c899c8cb9ce551c6379cc608273dfc68
data/CHANGELOG.md CHANGED
@@ -3,10 +3,168 @@
3
3
  All notable changes to this project will be documented in this file. The
4
4
  project follows [Semantic Versioning](https://semver.org/).
5
5
 
6
+ ## [0.16.0] - 2026-11-01
7
+
8
+ ### Changed
9
+
10
+ - `include_deleted:` reads the deleted records' `destroy` versions 500
11
+ records per query, as `unreachable`'s test below does, instead of in one
12
+ query for all of them.
13
+
14
+ - The reference says what `from_snapshot` holds at the start of a window,
15
+ under `version_scope:`, and for a record created inside the range, and how
16
+ to read a record at one version from an analysis rather than by decoding
17
+ `version.object`, which skips the casting the gem applies.
18
+
19
+ - `analyze_scope` and `report` with `version_scope:` select a record by its
20
+ own versions only when the filter keeps one of them in the window. A record
21
+ whose versions there it all dropped was selected anyway, with an empty
22
+ analysis, and counted toward `limit:`. A change on a requested association
23
+ still selects a record, as before.
24
+
25
+ - `report` and `analyze_scope` list in `unreachable` only the deleted records
26
+ whose state when destroyed meets the relation's conditions, also without
27
+ `include_deleted:`, whenever those conditions can be read. A report on
28
+ `Article.where(account_id: account.id)` listed every account's deleted
29
+ articles there, and one on `Article.none` listed some too. A relation whose
30
+ conditions cannot be read, such as one with SQL text, lists every deleted
31
+ record of the model as before.
32
+
33
+ ### Added
34
+
35
+ - `report` accepts `version_scope:`, as `analyze_scope` does, to report only
36
+ some changes, such as those made by people rather than by background jobs.
37
+
38
+ - `Analysis#window` is the time window an analysis covers: the `within:` or
39
+ `since:` range, or that range with an edge moved back to where a crossing
40
+ transaction began. Check steps against it rather than against the range you
41
+ passed, which the first step of a moved window starts before. It is `nil`
42
+ without a window.
43
+
44
+ - A `moved_window.paper_trail_diff` notification reports each window edge that
45
+ moved, with the requested and the moved window. A move far longer than a
46
+ transaction takes means the versions' times were changed after saving, as in
47
+ a test that rewrote some versions' `created_at` and not the others saved in
48
+ the same transaction. The reference shows how to give versions fixed times
49
+ in tests.
50
+
51
+ - Association scopes and `include_deleted:` relations read ranges, such as
52
+ `where(position: 2..)` or `where(created_at: 1.day.ago..)`, and Arel's `gt`,
53
+ `gteq`, `lt`, and `lteq`, on integer, integer enum, date, and datetime
54
+ columns. Such a scope was read through PT-AT, which needs
55
+ `allow_approximate: true`, and such a relation raised `ConfigurationError`
56
+ under `include_deleted: true`.
57
+
58
+ - `include_deleted: true` accepts `Article.none`, which keeps no deleted
59
+ record, instead of raising `ConfigurationError`. Authorization scopes often
60
+ return `none`.
61
+
62
+ ### Fixed
63
+
64
+ - Batch methods with `within:` or `since:` look for transactions that cross
65
+ the window's edges in one statement per 500 records. 0.15.0 wrote a
66
+ separate lookup for each record into the statement, which SQL Server took
67
+ about a second to compile per 200 records, so a report on 10,800 records
68
+ spent nearly two minutes there. On 1.4 million versions, 0.15.0 failed for
69
+ 10,800 records on SQL Server, whose query processor ran out of internal
70
+ resources, and took 13.6 and 10.2 seconds on PostgreSQL and MySQL. Those
71
+ edges now take about 6 seconds on SQL Server and about 1.5 on PostgreSQL
72
+ and MySQL.
73
+
74
+ - On PostgreSQL and MySQL (through mysql2 or trilogy), and adapters built on
75
+ them such as PostGIS, each call reads its history and live rows in one
76
+ REPEATABLE READ transaction on the database of the model and its versions.
77
+ A comment that
78
+ committed between two statements of an activity read could make it raise an
79
+ internal `KeyError`, and one statement could see a row that another did not.
80
+ A call now reflects the database as of its first statement, so a commit
81
+ during the call appears in the next call. Each call adds two or three
82
+ transaction statements on those databases. A call made inside a transaction
83
+ of your own keeps that transaction's isolation level. SQLite and SQL Server
84
+ are unchanged.
85
+
86
+ - Activity reports a change to a root's `belongs_to` key in the step of the
87
+ root version that made it, also when `object_changes` leaves the key out:
88
+ under `has_paper_trail only:` or `ignore:` that do not list it, or when
89
+ `update_columns`, `update_all`, or a save with versioning off wrote it. The
90
+ root kept its old target until a later event read the branch again, so the
91
+ change was credited to whoever saved that, two windows that met between
92
+ the two reported it in neither, and `analyze(activity: true).timeline`
93
+ differed from `timeline`.
94
+
95
+ - Activity reads a child or a `belongs_to` target whose key changed without a
96
+ version, such as a comment moved by `update_columns`, or by any save under
97
+ `has_paper_trail only:` or `ignore:` that leave the key out. In a past
98
+ window or a range that ends at a version, the record had no events: it
99
+ joined at an arbitrary later step, or was left out of the window's diff,
100
+ and a reviewer set this way kept its later renames out of activity.
101
+
102
+ - `analyze_many`, and the `deleted` analyses of `analyze_scope`, give a record
103
+ with nothing in the window an `activity_timeline` of `nil` unless
104
+ `activity: true` was passed, as `analyze` does, so its `change_rows` raises
105
+ `ConfigurationError` as for any other record. It was `[]`, so code that read
106
+ `change_rows` without asking for activity passed while nothing changed.
107
+
108
+ - An STI root that changes class names its new class in the activity
109
+ snapshots after the change, not its old one, and a subclass root's
110
+ snapshot is carried from one of its versions to the next instead of being
111
+ rebuilt at each one.
112
+
113
+ - Activity reports a change to a key that a child's own `belongs_to`
114
+ follows, such as a comment's `reviewer_id` under `comments.reviewer`, in
115
+ the step of the child's update. The child kept its old target until its
116
+ next edit, or a root version, read the branch again, so the change showed
117
+ up in a later step, credited to whoever saved that, and a window that
118
+ held only the change reported nothing.
119
+
120
+ - Activity removes a `has_many :through` member when its join record moves
121
+ to another owner or points at another record, also when a path below the
122
+ through reads that join model again, as `contributors.authorships` does.
123
+ The update changed only the copy under that path, so the through kept the
124
+ member until another event read the branch again.
125
+
126
+ - A HABTM member created in a checkpoint's transaction appears in activity
127
+ from its creation on, as in 0.14.0. Since 0.15.0, which counts such a
128
+ member at the checkpoint, it appeared in every step back to the previous
129
+ root version, before it existed and before members attached earlier. A
130
+ range that ends at the checkpoint still ends with it, as `compare` does.
131
+
132
+ ### Development
133
+
134
+ - `spec/oracle/replay_differential_spec.rb` replays generated histories
135
+ with activity's incremental snapshots and with a full snapshot at every
136
+ event, under `has_paper_trail only:` and `ignore:` and with keys written
137
+ without a version, and fails on any difference. It found the first two
138
+ bugs above.
139
+
140
+ - The through oracle renames a team at most once per transaction. A second
141
+ rename made it expect a version to read the state before its transaction,
142
+ which made `ORACLE_SEEDS=40..49` fail on seed 45 without a bug. The scoped
143
+ membership oracle covers range scopes.
144
+
145
+ - Two oracle generators compare rebuilt history with plain Active Record:
146
+ `spec/oracle/through_history_spec.rb` for every kind of `has_many :through`,
147
+ and `spec/oracle/habtm_history_spec.rb` for HABTM membership between
148
+ checkpoints. They found the three activity bugs above.
149
+
150
+ - Specs check that a range orders versions by time when their ids run the
151
+ other way, and that an STI subclass's selection names only its own
152
+ destroyed rows. A stub of the versions association these specs relied on
153
+ stopped reaching the gem when it began reading versions from the version
154
+ class, which left six mutations alive in a full mutation run.
155
+
6
156
  ## [0.15.0] - 2026-10-31
7
157
 
8
158
  ### Breaking changes
9
159
 
160
+ - A `within:` or `since:` window, and a range that starts at a version, can
161
+ begin earlier than asked: an edge inside a transaction moves back to where
162
+ the transaction began, as the two entries under Fixed describe. The first
163
+ step of such a range has a `from_boundary` before the time or version you
164
+ passed, so code that drops steps outside the range it asked for loses that
165
+ step. (This entry was added after release; 0.15.0 listed the change only
166
+ under Fixed.)
167
+
10
168
  - An association whose model keeps its versions, or its PT-AT version
11
169
  associations, in different tables than its owner's raises
12
170
  `UnsupportedAssociationError` in every method, and `association_paths`
@@ -246,7 +404,7 @@ project follows [Semantic Versioning](https://semver.org/).
246
404
  credited to that change's author, and the window ending there left it out;
247
405
  when the article saved first, its version was in one window and the comment
248
406
  edit in the other. Each root's edges move back to the transaction's start,
249
- read in a fixed number of queries per batch.
407
+ read in a fixed number of queries per 200 records.
250
408
 
251
409
  - `activity_timeline`, and `analyze` with `activity: true`, no longer report a
252
410
  child version saved in the same transaction as the root version that ends
data/README.md CHANGED
@@ -160,7 +160,7 @@ rows = report.analyses.map do |identity, analysis|
160
160
  }
161
161
  end
162
162
 
163
- report.unreachable # Model names and IDs for records no longer in the database
163
+ report.unreachable # Model names and IDs of selected records no longer in the database
164
164
  report.deleted # Reports for those records, or nil when destroy history is missing
165
165
  ```
166
166
 
data/docs/performance.md CHANGED
@@ -33,6 +33,10 @@ for one association, at 1, 5, and 20 records:
33
33
  The last four rows grow with the number of records, for the reasons in
34
34
  [what costs a query per record](#what-costs-a-query-per-record).
35
35
 
36
+ The counts leave out transaction statements. On PostgreSQL and MySQL each call
37
+ also runs in one snapshot transaction, which adds two or three statements per
38
+ call whatever its size. See [limitations](reference.md#limitations).
39
+
36
40
  ## What still grows
37
41
 
38
42
  Flat query counts do not make a report's cost flat:
@@ -53,6 +57,11 @@ Flat query counts do not make a report's cost flat:
53
57
  version of the root rather than per change, does less.
54
58
  - **`snapshots: true` and `recorded_changes: true` cost memory and time.** Ask
55
59
  for them only when you use them.
60
+ - **Each edge of a window takes one or two statements per 500 records.** A
61
+ report with `within:` or `since:` looks for transactions that cross either
62
+ edge.
63
+ On 1.4 million versions, 10,800 records took about 6 s on SQL Server and
64
+ 1.5 s on PostgreSQL and MySQL.
56
65
 
57
66
  ## Database indexes
58
67
 
data/docs/reference.md CHANGED
@@ -76,7 +76,12 @@ Six things follow from this:
76
76
  changes the values the record's next version stores, or its current row. The
77
77
  gem reads the result of a change from there, so the write appears in the step
78
78
  for that record's previous recorded change and is attributed to its author.
79
- Ending a range at a version leaves out only the writes after it.
79
+ Ending a range at a version leaves out only the writes after it. A column
80
+ that `has_paper_trail only:` or `ignore:` leaves out of `object_changes` is
81
+ read the same way, so a key saved with a version is that version's change.
82
+ Rails updates `counter_cache` columns like this, so a parent's count changes
83
+ in the step of the parent's previous change; pass the column in `ignore:` to
84
+ leave it out.
80
85
  [`recorded_changes`](#what-a-version-recorded) reads what a version itself
81
86
  recorded, and activity steps can [include it](#what-each-event-recorded-recorded_changes-true).
82
87
  - **A record created without a version looks as if it always existed.** A
@@ -136,8 +141,9 @@ PaperTrailDiff.timeline(article, within: 1.week.ago..Time.current)
136
141
 
137
142
  - `from:` defaults to `:first`, the record's earliest version.
138
143
  - `to:` defaults to the record itself, meaning its current state. Pass a
139
- version instead for a result that never changes when the record is edited
140
- again.
144
+ version instead to anchor the result there. It does not change when the
145
+ record is edited again, unless a transaction that stamped changes before that
146
+ version commits after it; see [version order](#version-order).
141
147
  - A version stands for the state before its transaction, since PT-AT rebuilds
142
148
  associations as they were before it. Child changes saved in the same
143
149
  transaction, such as the update behind a `touch: true` parent version, fall
@@ -175,6 +181,34 @@ or a `report` with `since:` after an earlier report, show each change exactly
175
181
  once, credited to the transaction that made it. Each root moves its own edges,
176
182
  so in a batch two roots can start a few moments apart.
177
183
 
184
+ `analysis.window` is the window an `Analysis` covers after any such move, as a
185
+ Ruby range. It is `nil` when `within:` or `since:` was not given. Every step of
186
+ the analysis is inside it, so to check a step against the window, use
187
+ `analysis.window` rather than the range you passed: a step at the start of a
188
+ moved window begins before the time you asked for.
189
+
190
+ ```ruby
191
+ analysis = PaperTrailDiff.analyze_many(articles, within: window, activity: true).values.first
192
+ analysis.window # => window, or one that starts earlier
193
+ ```
194
+
195
+ Each move emits a `moved_window.paper_trail_diff` notification whose payload
196
+ has `item_type`, `item_id`, the `requested` range, and the moved `window`. In
197
+ history saved by your application, an edge moves back by the time one
198
+ transaction took, usually well under a second. A move of minutes or days
199
+ means a transaction ran that long, or that the versions' times were changed
200
+ after they were saved, as a test might do; see
201
+ [writing history in tests](#writing-history-in-tests).
202
+
203
+ A closed window can still change. PaperTrail stamps a version's `created_at`
204
+ when it builds the version, inside its transaction, and the transaction commits
205
+ later. A transaction that stamped a change inside the window and committed
206
+ after the window was read adds that change to it. Wait longer than your longest
207
+ transaction after the window ends before you rely on it, so that every
208
+ transaction that could have written in the window has committed. A report
209
+ through now is final only for changes older than that delay. The gem cannot see
210
+ open transactions, so it cannot tell when a window has settled.
211
+
178
212
  To show what the window's last change produced, the gem reads the state just
179
213
  before the next change after the window:
180
214
 
@@ -218,7 +252,7 @@ PaperTrailDiff.timeline(article, within: window, version_scope: user_edits)
218
252
  ```
219
253
 
220
254
  It is accepted by `timeline`, `activity_timeline`, `analyze`, `analyze_many`,
221
- and `analyze_scope`.
255
+ `analyze_scope`, and `report`.
222
256
 
223
257
  - Each reported change is compared with the version right after it, even if
224
258
  that version is filtered out. So each step shows exactly what that one change
@@ -232,6 +266,11 @@ and `analyze_scope`.
232
266
  - It looks at the root record's versions only. Someone who only edited comments
233
267
  has no root versions to select. To find one person's changes, including to
234
268
  associations, see [one person's changes](#one-persons-changes).
269
+ - In `analyze_scope` and `report`, it also chooses which records are selected:
270
+ a record's own versions select it only when the filter keeps one of them in
271
+ the window. A record whose versions there it all drops would have nothing to
272
+ report, so it is left out. A change on a requested association still selects
273
+ a record, whoever made it.
235
274
  - `activity_timeline` uses the filter to decide where the range starts and
236
275
  ends, but still lists every step inside it. Dropping one would move its
237
276
  change into a neighboring step and credit the wrong person.
@@ -438,6 +477,10 @@ PaperTrailDiff.activity_timeline(article, associations: [:comments], group: :tra
438
477
  lists every event in the transaction, each with its own author, except
439
478
  those of records that were outside the tree before and after it.
440
479
  - Versions without a `transaction_id` are never grouped.
480
+ - A savepoint that rolls back can split one transaction into more than one
481
+ group. PT-AT clears the transaction id when the savepoint rolls back, so the
482
+ versions the transaction saves afterwards form a separate group. Releasing
483
+ the savepoint keeps one group.
441
484
  - Also accepted by `analyze`, `analyze_many`, and `analyze_scope` with
442
485
  `activity: true`, and by `report`.
443
486
 
@@ -577,10 +620,22 @@ analysis.timeline # the same steps timeline returns
577
620
  analysis.activity_timeline # nil unless activity: true
578
621
  analysis.from_snapshot # the full state at the start (nil before creation)
579
622
  analysis.to_snapshot # the full state at the end
623
+ analysis.window # the time window it covers, or nil without within:
580
624
  analysis.to_h(snapshots: true, metadata: true)
581
625
  ```
582
626
 
583
627
  - It accepts the same ranges as `timeline`.
628
+ - `from_snapshot` is the record as it was when the range began: before the
629
+ first change in a window, or before the change of the version you passed as
630
+ `from:`. With `version_scope:`, a window begins at the first change the
631
+ filter keeps. It is `nil` when the record was created inside the range; the
632
+ state right after it was created is then the first activity step's
633
+ `to_snapshot`, which `snapshots: true` keeps.
634
+ - To read the record at one version, with its values typed and its
635
+ associations, take `from_snapshot` from a range that starts there:
636
+ `PaperTrailDiff.analyze(article, from: version, to: article).from_snapshot`.
637
+ Don't decode `version.object` yourself; the gem casts what PaperTrail
638
+ stores, which a `json` column or an enum leaves in another form.
584
639
  - When nothing in the range is reported, the analysis is empty: an empty
585
640
  `diff` and timelines, and `nil` for `from_snapshot` and `to_snapshot`. Here
586
641
  `nil` means no state was read, not that the record did not exist; reading
@@ -657,7 +712,7 @@ recently":
657
712
  report = PaperTrailDiff.report(Article.all, since: 1.day.ago, limit: 100)
658
713
  ```
659
714
 
660
- It accepts `associations:`, `ignore:`, `snapshots:`, `group:`,
715
+ It accepts `associations:`, `ignore:`, `version_scope:`, `snapshots:`, `group:`,
661
716
  `recorded_changes:`, `include_deleted:`, `historical_filter:`, `max_filter_versions:`,
662
717
  and `allow_approximate:`.
663
718
 
@@ -670,7 +725,9 @@ and `allow_approximate:`.
670
725
  both. Nested paths count at every level, and a `has_many :through` counts its
671
726
  join rows too. Without `activity: true`, an analysis compares a record's own
672
727
  versions and cannot show a change to its associations alone, so only a
673
- record's own version selects it.
728
+ record's own version selects it. With
729
+ [`version_scope:`](#reporting-only-some-changes-version_scope), only the
730
+ record's own versions that the filter keeps select it.
674
731
  - **An analysis can still be empty.** A record is selected by any version on its
675
732
  paths, but its analysis compares only the state you requested. A join row
676
733
  whose role changed, or a version that touched only ignored columns, selects a
@@ -695,19 +752,22 @@ and `allow_approximate:`.
695
752
 
696
753
  A relation's conditions read the table, and a deleted record has no row.
697
754
  Records that changed in the window but no longer exist are listed in
698
- `unreachable`, including those selected by a change to their associations. It
699
- is not paginated and, without `include_deleted:`, does not mean those records
700
- matched the relation.
755
+ `unreachable`, including those selected by a change to their associations,
756
+ when the state each held when it was destroyed meets the relation's
757
+ conditions. That test needs conditions it can read, as `include_deleted:`
758
+ below does; for any other relation, such as one with SQL text or a join,
759
+ `unreachable` lists every such record of the model, whatever the relation. It
760
+ is not paginated.
701
761
 
702
762
  `include_deleted: true` tests each of them against the relation's conditions,
703
- as it stood when it was destroyed, and keeps only those that match. So a
704
- report on `Article.where(account_id: account.id)` returns that account's
705
- deletions, not every account's. The relation's conditions must be plain
706
- conditions on the model's own columns, as a [readable association
707
- scope's](#costly-associations) must; anything else, such as a join or SQL
708
- text, raises `ConfigurationError`. Its order, limit, and offset are ignored
709
- here, since they choose a page of existing rows. A record whose destroy
710
- PaperTrail did not record has no state to test and stays listed.
763
+ as it stood when it was destroyed, and keeps only those that match. So a report
764
+ on `Article.where(account_id: account.id)` returns that account's deletions,
765
+ not every account's. The relation's conditions must be plain conditions on the
766
+ model's own columns, as a [readable association scope's](#costly-associations)
767
+ must, ranges included; anything else, such as a join or SQL text, raises
768
+ `ConfigurationError`. `Article.none` keeps none. Its order, limit, and offset
769
+ are ignored here, since they choose a page of existing rows. A record whose
770
+ destroy PaperTrail did not record has no state to test and stays listed.
711
771
 
712
772
  It then analyzes the kept records from their `destroy` versions and returns the
713
773
  results in `deleted`, keyed the same way. A value is `nil` when no `destroy`
@@ -791,6 +851,11 @@ MySQL and SQL Server compare strings without regard to case or trailing spaces
791
851
  by default, which the gem cannot repeat, and neither is PostgreSQL's
792
852
  `citext`.
793
853
 
854
+ Ranges, such as `where(position: 2..)` or `where(created_at: 1.day.ago...)`,
855
+ and Arel's `gt`, `gteq`, `lt`, and `lteq`, are read on the columns an order
856
+ can sort by, below: integer, integer enum, date, and datetime columns, with
857
+ the same conditions on a datetime's precision.
858
+
794
859
  A `limit` or `offset`, and the order of a `has_one`, are read the same way
795
860
  when the order is total and the gem can repeat it:
796
861
 
@@ -827,12 +892,12 @@ join records fills two places, as in the query. A `has_one :through` whose
827
892
  own scope or whose parts have a limit, an offset, or a `has_one` order is not
828
893
  read.
829
894
 
830
- The gem cannot read the rest: a `limit` or `offset` whose order is not total
831
- or sorts by another column type (strings follow a collation) or by a datetime
895
+ The gem cannot read the rest: a `limit` or `offset` whose order is not total or
896
+ sorts by another column type (strings follow a collation) or by a datetime
832
897
  history cannot rank exactly, scopes that take the owner
833
- (`->(article) { ... }`), scopes written as SQL strings or ranges, scopes that
834
- join or select, and conditions on other column types or other tables, such as
835
- a string column on MySQL. For these it asks PT-AT, which costs queries per
898
+ (`->(article) { ... }`), scopes written as SQL strings, ranges on other column
899
+ types, scopes that join or select, and conditions on other column types or
900
+ other tables, such as a string column on MySQL. For these it asks PT-AT, which costs queries per
836
901
  record and is approximate: PT-AT rebuilds an association from its current
837
902
  members, swapping in their older versions, and never checks the scope against
838
903
  them. A record that entered the scope since is reported as a member it was
@@ -989,8 +1054,10 @@ another record with the same HABTM also saved a version (see the
989
1054
  is when saved, including a member attached or created earlier in the same
990
1055
  transaction. A change it captures is credited to the step before it, so its
991
1056
  author is whoever saved the version before the checkpoint, unless that is a
992
- checkpoint the same person saved just before the change. Don't save the
993
- instance that made the HABTM change again; it records the old membership.
1057
+ checkpoint the same person saved just before the change. A member created in
1058
+ the checkpoint's transaction is reported in the step of its creation instead,
1059
+ or, when the range ends at the checkpoint, in the step before it. Don't save
1060
+ the instance that made the HABTM change again; it records the old membership.
994
1061
 
995
1062
  ### Files from ActiveStorage
996
1063
 
@@ -1325,6 +1392,13 @@ common. `diagnose` reports this as an error.
1325
1392
  backwards, or servers whose clocks disagree, can record a later change with an
1326
1393
  earlier time. Keep server clocks synchronized.
1327
1394
 
1395
+ Versions are ordered by when they were stamped, not by when their transactions
1396
+ committed. A transaction stamps its versions while it is open, so one that
1397
+ commits last can still sort first. The gem cannot see commit order. A report
1398
+ can therefore show a state the database never held, and a result for an earlier
1399
+ version or a closed window can change once that transaction commits.
1400
+ [Time windows](#time-windows) explains how to settle a report.
1401
+
1328
1402
  Association changes between versions with the same timestamp are placed using
1329
1403
  the same order. A few association shapes fall back to PT-AT's own reifier, which
1330
1404
  uses timestamps only: a path history reads only approximately, which takes
@@ -1350,6 +1424,32 @@ precision was never recorded and cannot be reported. A `json` or `jsonb`
1350
1424
  column also returns times and dates as strings, which PaperTrail leaves as
1351
1425
  they are; the gem casts them back to the attribute's type.
1352
1426
 
1427
+ ### Writing history in tests
1428
+
1429
+ To give versions fixed times in a test, save them at those times with
1430
+ `travel_to`:
1431
+
1432
+ ```ruby
1433
+ travel_to(Time.zone.local(2026, 8, 15, 9, 1)) do
1434
+ PaperTrail.request(whodunnit: "alice") { article.update!(title: "Published") }
1435
+ end
1436
+ ```
1437
+
1438
+ If you change `created_at` after saving instead, change every version saved
1439
+ in the same transaction, not only the ones you check. PT-AT gives all of
1440
+ them the same `transaction_id`, including versions of other models saved by
1441
+ callbacks. A version left at the time the test ran makes that transaction
1442
+ seem to last from your chosen time until today. A window edge in between
1443
+ then moves back to the transaction's start (see [Time windows](#time-windows)),
1444
+ and the window can lose the changes the test expects.
1445
+
1446
+ ```ruby
1447
+ def set_version_time(version, time)
1448
+ same = version.transaction_id && { transaction_id: version.transaction_id }
1449
+ PaperTrail::Version.where(same || { id: version.id }).update_all(created_at: time)
1450
+ end
1451
+ ```
1452
+
1353
1453
  ## Instrumentation
1354
1454
 
1355
1455
  The gem never logs. It emits `ActiveSupport::Notifications` events you can
@@ -1362,6 +1462,7 @@ subscribe to:
1362
1462
  - `load_live_endpoints.paper_trail_diff`
1363
1463
  - `prepare_history.paper_trail_diff`
1364
1464
  - `ambiguous_association_boundary.paper_trail_diff`
1465
+ - `moved_window.paper_trail_diff`, when a [window edge moves](#time-windows)
1365
1466
 
1366
1467
  ```ruby
1367
1468
  ActiveSupport::Notifications.subscribe(/\.paper_trail_diff\z/) do |name, start, finish, _id, payload|
@@ -1369,8 +1470,8 @@ ActiveSupport::Notifications.subscribe(/\.paper_trail_diff\z/) do |name, start,
1369
1470
  end
1370
1471
  ```
1371
1472
 
1372
- Payloads contain counts, model names, association paths, and options, never
1373
- record data. To see the SQL for one call, subscribe to `sql.active_record`
1473
+ Payloads contain counts, model names, ids, times, association paths, and
1474
+ options, never record data. To see the SQL for one call, subscribe to `sql.active_record`
1374
1475
  around it with `ActiveSupport::Notifications.subscribed`.
1375
1476
 
1376
1477
  ## Errors
@@ -1409,8 +1510,21 @@ Results can only be as complete as the history PaperTrail and PT-AT recorded.
1409
1510
  [how PaperTrail stores history](#how-papertrail-stores-history).
1410
1511
  - Deleted versions, schema changes, and serializer changes can affect how old
1411
1512
  versions read.
1412
- - Several queries against the current record are not one database snapshot.
1413
- Use a transaction with a suitable isolation level if that matters.
1513
+ - Each call reads its history and live rows in one snapshot on PostgreSQL and
1514
+ MySQL (through mysql2 or trilogy), and on adapters built on them such as
1515
+ PostGIS, so a commit that lands during the call is seen by none of its
1516
+ statements. The snapshot covers the database of the record's model and its
1517
+ versions; an associated model on another database is read outside it. A
1518
+ call made inside a transaction of your own
1519
+ keeps that transaction's isolation level. To make the whole call see one
1520
+ snapshot, start that transaction at `REPEATABLE READ` or stricter. SQLite and
1521
+ SQL Server take no snapshot, so a commit during a call can appear in some of
1522
+ its statements and not others. A long call holds its snapshot until it ends:
1523
+ on PostgreSQL that can keep VACUUM from reclaiming old row versions, and on
1524
+ MySQL it keeps undo history.
1525
+ - A savepoint that rolls back can split one transaction into several
1526
+ transaction groups; see
1527
+ [one step per transaction group](#one-step-per-transaction-group-transaction).
1414
1528
  - HABTM membership history exists only where PT-AT recorded it in a
1415
1529
  transaction, and only for the root record without a scope: a scoped HABTM,
1416
1530
  or one below the root, raises `UnsupportedAssociationError`, and a transaction that another record with
data/docs/testing.md CHANGED
@@ -56,13 +56,33 @@ share passes. `spec/oracle` compares them with the truth instead:
56
56
  transactions, or inside one, must report each step once, as the window
57
57
  spanning both does, through both `activity_timeline` and `analyze_many`.
58
58
 
59
- Two more generators cover other shapes. `scoped_membership_spec.rb` moves
59
+ Four more generators cover other shapes. `scoped_membership_spec.rb` moves
60
60
  notes in and out of scoped associations (conditions, order, limit, and
61
61
  offset) and compares the members at every version with Active Record's own
62
62
  answer. `tree_history_spec.rb` edits a tree of one model, so a root can sit
63
63
  inside another root's tree, with children whose attributes are encrypted,
64
- serialized, enums stored as strings, custom types, decimals, and JSON. It reads
65
- the expected states with plain Active Record, not through the gem.
64
+ serialized, enums stored as strings, custom types, decimals, and JSON.
65
+ `through_history_spec.rb` edits two teams' join records and the records they
66
+ reach, through every kind of `has_many :through`: to a `belongs_to`, through a
67
+ scoped part, ranked with a limit, to a `has_many`, through another through, a
68
+ `has_one` through, and with `source_type:`. `habtm_history_spec.rb` attaches,
69
+ detaches, creates, renames, and destroys tags between checkpoints. HABTM
70
+ membership is known only at root versions, so it expects what the
71
+ [reference](reference.md#habtm-limitation) describes: at each point, the
72
+ members the next root version recorded, as each was then, and only once it
73
+ exists. These three read the expected states with plain Active Record, not
74
+ through the gem.
75
+
76
+ `replay_differential_spec.rb` checks activity against the gem's own full
77
+ snapshots instead. Activity carries each snapshot forward from the previous
78
+ event, reading again only what the event changed; this replays generated
79
+ histories that way and with a full snapshot at every event, and fails on any
80
+ difference. Needing no expected states, it covers what the others avoid:
81
+ `has_paper_trail only:` and `ignore:` that leave keys out of `object_changes`,
82
+ and keys written by `update_columns` or with versioning off.
83
+ Mutant cannot check that carrying forward: a mutation that turns it off
84
+ falls back to a full snapshot, which gives the same answers, more slowly. This
85
+ check is what catches one that gives a different answer.
66
86
 
67
87
  ```console
68
88
  mise exec -- bundle exec rake spec_oracle
@@ -16,7 +16,8 @@ module PaperTrailDiff
16
16
  def safe?(routes, version, delta)
17
17
  !scoped_route?(routes) &&
18
18
  !unsafe_through_membership_event?(routes, version) &&
19
- !unsafe_nested_membership_delta?(routes, delta)
19
+ !unsafe_nested_membership_delta?(routes, delta) &&
20
+ !unsafe_owned_relationship_delta?(routes, delta)
20
21
  end
21
22
 
22
23
  #: (untyped, untyped, RecordSnapshot, SnapshotNormalizer, Array[Array[untyped]], untyped, ActivitySnapshotDelta?) -> [bool, RecordSnapshot]
@@ -92,6 +93,37 @@ module PaperTrailDiff
92
93
  end
93
94
  end
94
95
 
96
+ # A delta replaces a record's attributes and keeps its associations, so an
97
+ # edit to a key one of them follows, such as a comment's `reviewer_id`
98
+ # under `comments.reviewer`, would leave the old target in place. The
99
+ # branch is read again instead.
100
+ #: (Array[Array[untyped]], ActivitySnapshotDelta?) -> bool
101
+ def unsafe_owned_relationship_delta?(routes, delta)
102
+ return false unless delta
103
+
104
+ routes.any? do |route|
105
+ _name, reflection, subtree, = route.last
106
+ subtree.children.each_key.any? do |name|
107
+ owned_keys(reflection.klass.reflect_on_association(name)).any? do |key|
108
+ delta.before_value(key).to_s != delta.after_value(key).to_s
109
+ end
110
+ end
111
+ end
112
+ end
113
+
114
+ # The record's own columns that decide what an association of it holds: a
115
+ # belongs_to's key and type, or those of the belongs_to a through starts
116
+ # from. A has_one or has_many follows the record's primary key.
117
+ #: (untyped) -> Array[untyped]
118
+ def owned_keys(reflection)
119
+ return [] unless reflection
120
+ return owned_keys(reflection.through_reflection) if reflection.through_reflection?
121
+ return [] unless reflection.belongs_to?
122
+
123
+ keys = Array(reflection.foreign_key)
124
+ reflection.polymorphic? ? [*keys, reflection.foreign_type] : keys
125
+ end
126
+
95
127
  #: (RecordSnapshot, Array[untyped], untyped, ActivitySnapshotDelta?, Array[untyped], SnapshotNormalizer, Array[untyped], ?direct: bool) -> [untyped, RecordSnapshot?]
96
128
  def route_event_state( # rubocop:disable Metrics/ParameterLists
97
129
  snapshot, route, version, delta, fallback_record, normalizer, endpoints, direct: false
@@ -9,6 +9,7 @@ module PaperTrailDiff
9
9
  @traversal = traversal
10
10
  @collection_routes = {} #: Hash[Array[untyped], Array[Array[untyped]]]
11
11
  @belongs_to_routes = {} #: Hash[Array[untyped], Array[Array[untyped]]]
12
+ @through_parts = {} #: Hash[Array[untyped], bool]
12
13
  end
13
14
 
14
15
  #: (untyped, AssociationTree, String, ?path: String) -> Array[Array[untyped]]
@@ -21,11 +22,41 @@ module PaperTrailDiff
21
22
  cached(@belongs_to_routes, model_class, tree, target_type, path, :belongs_to)
22
23
  end
23
24
 
25
+ # Whether a has_many through in the tree joins through, or reaches,
26
+ # records of the type. Its membership follows their keys, which a route
27
+ # to the record elsewhere in the tree does not update.
28
+ #: (untyped, AssociationTree, String) -> bool
29
+ def through_part?(model_class, tree, target_type)
30
+ key = [model_class, tree, target_type]
31
+ return @through_parts[key] if @through_parts.key?(key)
32
+
33
+ @through_parts[key] = through_part_below?(model_class, tree, target_type, '')
34
+ end
35
+
24
36
  private
25
37
 
26
38
  # @rbs @traversal: AssociationTraversal
27
39
  # @rbs @collection_routes: Hash[Array[untyped], Array[Array[untyped]]]
28
40
  # @rbs @belongs_to_routes: Hash[Array[untyped], Array[Array[untyped]]]
41
+ # @rbs @through_parts: Hash[Array[untyped], bool]
42
+
43
+ #: (untyped, AssociationTree, String, String) -> bool
44
+ def through_part_below?(model_class, tree, target_type, path)
45
+ @traversal.reflections_for(model_class, tree, path: path).any? do |reflection|
46
+ next true if through_reaches?(reflection, target_type)
47
+
48
+ subtree = tree.child(reflection.name.to_s) #: AssociationTree
49
+ child_path = Support.association_path(path, reflection.name)
50
+ !reflection.polymorphic? && !subtree.empty? &&
51
+ through_part_below?(reflection.klass, subtree, target_type, child_path)
52
+ end
53
+ end
54
+
55
+ #: (untyped, String) -> bool
56
+ def through_reaches?(reflection, target_type)
57
+ reflection.through_reflection? &&
58
+ reflection.chain.any? { |part| part.klass.base_class.name.to_s == target_type }
59
+ end
29
60
 
30
61
  # Timelines interleave event types, so every requested combination is
31
62
  # retained. Model, tree, and path are fixed per adapter, leaving one entry