paper_trail_diff 0.14.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 (150) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +501 -0
  3. data/QUICKSTART.md +21 -4
  4. data/README.md +59 -56
  5. data/docs/architecture.md +32 -11
  6. data/docs/performance.md +125 -391
  7. data/docs/reference.md +470 -117
  8. data/docs/testing.md +83 -7
  9. data/lib/paper_trail_diff/activity_boundary.rb +83 -26
  10. data/lib/paper_trail_diff/activity_child_candidate_loader.rb +2 -1
  11. data/lib/paper_trail_diff/activity_collection_event_applier.rb +33 -1
  12. data/lib/paper_trail_diff/activity_event.rb +41 -10
  13. data/lib/paper_trail_diff/activity_event_route_finder.rb +31 -0
  14. data/lib/paper_trail_diff/activity_event_snapshot_refresher.rb +12 -1
  15. data/lib/paper_trail_diff/activity_history.rb +34 -9
  16. data/lib/paper_trail_diff/activity_range.rb +18 -3
  17. data/lib/paper_trail_diff/activity_root_snapshot_refresher.rb +43 -25
  18. data/lib/paper_trail_diff/activity_snapshot_sequence.rb +76 -37
  19. data/lib/paper_trail_diff/activity_target_candidate_loader.rb +5 -5
  20. data/lib/paper_trail_diff/activity_timeline_builder.rb +272 -111
  21. data/lib/paper_trail_diff/activity_transaction_grouper.rb +2 -1
  22. data/lib/paper_trail_diff/activity_tree_filter.rb +114 -0
  23. data/lib/paper_trail_diff/activity_version_collector.rb +7 -5
  24. data/lib/paper_trail_diff/activity_view.rb +69 -0
  25. data/lib/paper_trail_diff/analysis.rb +37 -6
  26. data/lib/paper_trail_diff/analysis_batch.rb +25 -31
  27. data/lib/paper_trail_diff/approximate_paths.rb +48 -0
  28. data/lib/paper_trail_diff/association_activity_edge.rb +6 -6
  29. data/lib/paper_trail_diff/association_discovery.rb +9 -1
  30. data/lib/paper_trail_diff/association_key.rb +56 -0
  31. data/lib/paper_trail_diff/association_traversal.rb +13 -4
  32. data/lib/paper_trail_diff/batch_boundary_resolver.rb +3 -4
  33. data/lib/paper_trail_diff/batch_preload.rb +53 -0
  34. data/lib/paper_trail_diff/batched_root_analyzer.rb +18 -14
  35. data/lib/paper_trail_diff/batched_root_versions.rb +38 -14
  36. data/lib/paper_trail_diff/branch_snapshot_refresher.rb +19 -16
  37. data/lib/paper_trail_diff/change_row.rb +133 -0
  38. data/lib/paper_trail_diff/collection_comparator.rb +5 -32
  39. data/lib/paper_trail_diff/configuration.rb +35 -12
  40. data/lib/paper_trail_diff/deleted_analysis_batch.rb +23 -19
  41. data/lib/paper_trail_diff/deleted_root_filter.rb +101 -0
  42. data/lib/paper_trail_diff/deprecation.rb +61 -0
  43. data/lib/paper_trail_diff/diagnostics.rb +86 -99
  44. data/lib/paper_trail_diff/endpoint.rb +26 -3
  45. data/lib/paper_trail_diff/errors.rb +3 -1
  46. data/lib/paper_trail_diff/fallback_paths.rb +38 -0
  47. data/lib/paper_trail_diff/historical_association_reifier.rb +2 -4
  48. data/lib/paper_trail_diff/historical_filter.rb +19 -10
  49. data/lib/paper_trail_diff/historical_snapshot_store.rb +57 -67
  50. data/lib/paper_trail_diff/live_endpoint_batch_loader.rb +1 -35
  51. data/lib/paper_trail_diff/nested_comparator.rb +19 -18
  52. data/lib/paper_trail_diff/paper_trail_adapter.rb +198 -166
  53. data/lib/paper_trail_diff/preloaded_endpoint_batch_loader.rb +13 -1
  54. data/lib/paper_trail_diff/prepared_activity_index.rb +17 -13
  55. data/lib/paper_trail_diff/prepared_edge_loader.rb +2 -1
  56. data/lib/paper_trail_diff/prepared_history.rb +15 -1
  57. data/lib/paper_trail_diff/prepared_history_loader.rb +2 -3
  58. data/lib/paper_trail_diff/prepared_record_index.rb +42 -7
  59. data/lib/paper_trail_diff/read_snapshot.rb +77 -0
  60. data/lib/paper_trail_diff/root_version_selection.rb +4 -2
  61. data/lib/paper_trail_diff/scope_condition.rb +157 -32
  62. data/lib/paper_trail_diff/scope_ranking.rb +23 -14
  63. data/lib/paper_trail_diff/scoped_analysis.rb +11 -0
  64. data/lib/paper_trail_diff/scoped_analysis_builder.rb +29 -11
  65. data/lib/paper_trail_diff/scoped_root_selection.rb +29 -16
  66. data/lib/paper_trail_diff/snapshot.rb +16 -1
  67. data/lib/paper_trail_diff/support.rb +29 -2
  68. data/lib/paper_trail_diff/time_range.rb +39 -16
  69. data/lib/paper_trail_diff/timeline_builder.rb +13 -7
  70. data/lib/paper_trail_diff/timeline_range.rb +9 -1
  71. data/lib/paper_trail_diff/timeline_snapshot_provider.rb +24 -17
  72. data/lib/paper_trail_diff/transaction_cut.rb +240 -0
  73. data/lib/paper_trail_diff/traversal_preparer.rb +134 -29
  74. data/lib/paper_trail_diff/version.rb +1 -1
  75. data/lib/paper_trail_diff/version_boundary.rb +41 -10
  76. data/lib/paper_trail_diff/version_query.rb +34 -10
  77. data/lib/paper_trail_diff/version_scope_filter.rb +9 -10
  78. data/lib/paper_trail_diff/version_sequence_diagnostics.rb +35 -17
  79. data/lib/paper_trail_diff/version_table.rb +60 -0
  80. data/lib/paper_trail_diff.rb +101 -57
  81. data/sig/generated/paper_trail_diff/activity_boundary.rbs +54 -19
  82. data/sig/generated/paper_trail_diff/activity_collection_event_applier.rbs +13 -0
  83. data/sig/generated/paper_trail_diff/activity_event.rbs +25 -4
  84. data/sig/generated/paper_trail_diff/activity_event_route_finder.rbs +14 -0
  85. data/sig/generated/paper_trail_diff/activity_event_snapshot_refresher.rbs +6 -0
  86. data/sig/generated/paper_trail_diff/activity_history.rbs +21 -6
  87. data/sig/generated/paper_trail_diff/activity_range.rbs +9 -2
  88. data/sig/generated/paper_trail_diff/activity_root_snapshot_refresher.rbs +21 -10
  89. data/sig/generated/paper_trail_diff/activity_snapshot_sequence.rbs +48 -9
  90. data/sig/generated/paper_trail_diff/activity_timeline_builder.rbs +138 -30
  91. data/sig/generated/paper_trail_diff/activity_tree_filter.rbs +73 -0
  92. data/sig/generated/paper_trail_diff/activity_version_collector.rbs +2 -0
  93. data/sig/generated/paper_trail_diff/activity_view.rbs +42 -0
  94. data/sig/generated/paper_trail_diff/analysis.rbs +24 -5
  95. data/sig/generated/paper_trail_diff/analysis_batch.rbs +8 -15
  96. data/sig/generated/paper_trail_diff/approximate_paths.rbs +23 -0
  97. data/sig/generated/paper_trail_diff/association_discovery.rbs +5 -0
  98. data/sig/generated/paper_trail_diff/association_key.rbs +29 -0
  99. data/sig/generated/paper_trail_diff/association_traversal.rbs +4 -0
  100. data/sig/generated/paper_trail_diff/batch_preload.rbs +29 -0
  101. data/sig/generated/paper_trail_diff/batched_root_analyzer.rbs +13 -10
  102. data/sig/generated/paper_trail_diff/batched_root_versions.rbs +14 -4
  103. data/sig/generated/paper_trail_diff/branch_snapshot_refresher.rbs +6 -0
  104. data/sig/generated/paper_trail_diff/change_row.rbs +86 -0
  105. data/sig/generated/paper_trail_diff/collection_comparator.rbs +2 -16
  106. data/sig/generated/paper_trail_diff/configuration.rbs +19 -3
  107. data/sig/generated/paper_trail_diff/deleted_analysis_batch.rbs +11 -8
  108. data/sig/generated/paper_trail_diff/deleted_root_filter.rbs +56 -0
  109. data/sig/generated/paper_trail_diff/deprecation.rbs +35 -0
  110. data/sig/generated/paper_trail_diff/diagnostics.rbs +37 -30
  111. data/sig/generated/paper_trail_diff/endpoint.rbs +11 -2
  112. data/sig/generated/paper_trail_diff/errors.rbs +3 -1
  113. data/sig/generated/paper_trail_diff/fallback_paths.rbs +22 -0
  114. data/sig/generated/paper_trail_diff/historical_filter.rbs +12 -2
  115. data/sig/generated/paper_trail_diff/historical_snapshot_store.rbs +33 -28
  116. data/sig/generated/paper_trail_diff/live_endpoint_batch_loader.rbs +0 -15
  117. data/sig/generated/paper_trail_diff/nested_comparator.rbs +10 -7
  118. data/sig/generated/paper_trail_diff/paper_trail_adapter.rbs +64 -52
  119. data/sig/generated/paper_trail_diff/preloaded_endpoint_batch_loader.rbs +9 -1
  120. data/sig/generated/paper_trail_diff/prepared_activity_index.rbs +11 -4
  121. data/sig/generated/paper_trail_diff/prepared_history.rbs +10 -0
  122. data/sig/generated/paper_trail_diff/prepared_record_index.rbs +20 -2
  123. data/sig/generated/paper_trail_diff/read_snapshot.rbs +43 -0
  124. data/sig/generated/paper_trail_diff/root_version_selection.rbs +2 -0
  125. data/sig/generated/paper_trail_diff/scope_condition.rbs +81 -15
  126. data/sig/generated/paper_trail_diff/scope_ranking.rbs +14 -6
  127. data/sig/generated/paper_trail_diff/scoped_analysis.rbs +6 -0
  128. data/sig/generated/paper_trail_diff/scoped_analysis_builder.rbs +14 -2
  129. data/sig/generated/paper_trail_diff/scoped_root_selection.rbs +16 -7
  130. data/sig/generated/paper_trail_diff/snapshot.rbs +8 -0
  131. data/sig/generated/paper_trail_diff/support.rbs +15 -0
  132. data/sig/generated/paper_trail_diff/time_range.rbs +24 -9
  133. data/sig/generated/paper_trail_diff/timeline_builder.rbs +6 -2
  134. data/sig/generated/paper_trail_diff/timeline_range.rbs +2 -0
  135. data/sig/generated/paper_trail_diff/timeline_snapshot_provider.rbs +17 -7
  136. data/sig/generated/paper_trail_diff/transaction_cut.rbs +126 -0
  137. data/sig/generated/paper_trail_diff/traversal_preparer.rbs +66 -8
  138. data/sig/generated/paper_trail_diff/version_boundary.rbs +22 -3
  139. data/sig/generated/paper_trail_diff/version_query.rbs +18 -2
  140. data/sig/generated/paper_trail_diff/version_scope_filter.rbs +4 -5
  141. data/sig/generated/paper_trail_diff/version_sequence_diagnostics.rbs +19 -9
  142. data/sig/generated/paper_trail_diff/version_table.rbs +30 -0
  143. data/sig/generated/paper_trail_diff.rbs +29 -26
  144. metadata +49 -11
  145. data/lib/paper_trail_diff/activity_grouping.rb +0 -38
  146. data/lib/paper_trail_diff/batch_safety.rb +0 -63
  147. data/lib/paper_trail_diff/time_activity_timeline_builder.rb +0 -223
  148. data/sig/generated/paper_trail_diff/activity_grouping.rbs +0 -22
  149. data/sig/generated/paper_trail_diff/batch_safety.rbs +0 -30
  150. data/sig/generated/paper_trail_diff/time_activity_timeline_builder.rbs +0 -92
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 8b8f753f8bf15574c43fe572252b467b6066f097d0ad9990b6f1d8a74f41d938
4
- data.tar.gz: 536266a31306236cc26e71b3024af058f96a0544d363f0fb971b5b49f9b1b578
3
+ metadata.gz: 31ad8d55dab710a7295d5c6fef92918fee436492e35ec6fa785f49de025c2994
4
+ data.tar.gz: 04c4f17548bcda07300bb857dc6194b698f907bb1b71db06e61dbb3037e533dd
5
5
  SHA512:
6
- metadata.gz: 5070f94bc6bb46a58d6a80352aebd2f7c2392e0486c0197fe8977cb257af3b1a7644643fc1587df33bf6b0138df25ac67a3629ccf004fc627de3be883b321db1
7
- data.tar.gz: 8771c47edd7d8ec39347b7d76883af7c2ff7137ac7670064672dbc5fccea0c196d5e461624c183c8d51890b8a84472625fba8cc283c72d1375a0331fd3cb1efd
6
+ metadata.gz: 6a2cbc59fa7e53d31b78b1f0d5863519e1c72063718791323b938f73668ee53ddb19f6ac5cdf4d72b656dc6ec5c154e26485994da2ac90a6141d67928668c4ed
7
+ data.tar.gz: 7700f7863dcd954cea284ea1564def6a1d4b2a8679dd49a01bf618cf36333b6aba8c7e83b32cc7f2c481c81701ef5127c899c8cb9ce551c6379cc608273dfc68
data/CHANGELOG.md CHANGED
@@ -3,6 +3,507 @@
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
+
156
+ ## [0.15.0] - 2026-10-31
157
+
158
+ ### Breaking changes
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
+
168
+ - An association whose model keeps its versions, or its PT-AT version
169
+ associations, in different tables than its owner's raises
170
+ `UnsupportedAssociationError` in every method, and `association_paths`
171
+ leaves it out. History read through it was wrong: PT-AT records a child's
172
+ membership with the child's versions but reads it from the owner's tables,
173
+ so a child that moved to another owner was never reported as removed, and a
174
+ root with its own version table raised `ActiveRecord::StatementInvalid`.
175
+
176
+ - An association keyed on a column other than a primary key
177
+ (`primary_key: :legacy_id`), or a `has_many :through` with such a part,
178
+ raises `UnsupportedAssociationError` up front in every method, and
179
+ `association_paths` leaves it out. PT-AT records which record a child
180
+ pointed at by that record's ID, and history matched children by ID, so an
181
+ article's history showed another article's comments, and a comment's past
182
+ article was the wrong one. Comparisons against the current record were
183
+ right, so the same range disagreed with itself.
184
+ - An association path history cannot read, such as one with a scope written
185
+ as SQL text, a scope that takes the owner, or a condition on a string
186
+ column on MySQL or SQL Server, raises `UnsupportedAssociationError` in every
187
+ method that reads history, unless you pass the new `allow_approximate: true`.
188
+ The gem reads such a path with PT-AT, which rebuilds an association from its
189
+ current members and never checks the scope against them: a record that
190
+ entered the scope since was reported as a member it was not, so a comment
191
+ moved into `-> { where("position > 2") }` showed as changed rather than
192
+ added. Single-record methods did this without warning, and batch methods
193
+ described it only as costly.
194
+ - `include_deleted: true` keeps only the deleted records that met the
195
+ relation's conditions when they were destroyed, in both `deleted` and
196
+ `unreachable`. It returned every deleted record of the model that changed in
197
+ the window, so a report on one account's articles included other accounts'
198
+ deleted articles with their contents. The relation's conditions must be
199
+ plain conditions on the model's own columns; a join or SQL text raises
200
+ `ConfigurationError`.
201
+
202
+ ### Added
203
+
204
+ - `diagnose` reports every reason `compare` would refuse the same request as
205
+ an error, with `compare`'s message, so `ok?` is false whenever `compare`
206
+ would refuse. It said `ok?` for a path `compare` reads only approximately,
207
+ such as a scope written as SQL text, raised on an unknown or unsupported
208
+ association instead of reporting it, and checked only the join model a
209
+ `has_many :through` goes through first, not every model it reads. It
210
+ takes `allow_approximate:`, and with `true` reports such a path as an
211
+ `:approximate_association` warning. The new error codes are
212
+ `:unknown_association`, `:unsupported_association`, and
213
+ `:approximate_association`; an unversioned target's message now matches
214
+ `compare`'s.
215
+
216
+ - `diagnose` takes the current record as either endpoint, as `compare` does,
217
+ so `compare(version, record)` can be checked before it runs. Its version
218
+ checks then run from the version to the latest one. An endpoint that is
219
+ neither a version nor a saved record raises `InvalidEndpointError` naming
220
+ that, rather than `VersionMismatchError`.
221
+
222
+ - Activity steps list the events whose changes they show as `step.sources`,
223
+ oldest first. A step from `group: :transaction` lists every event in the
224
+ transaction, each with its own author, record, and version ID, where
225
+ `source_boundary` names only the first. `to_h(metadata: true)` adds a
226
+ `sources` list.
227
+ - `recorded_changes: true` on `activity_timeline`, on `analyze`, `analyze_many`,
228
+ and `analyze_scope` with `activity: true`, and on `report` gives each
229
+ boundary the changes its version recorded, as `recorded_changes(version)`
230
+ returns them. The versions are already loaded, so it adds no queries, and it
231
+ replaces the reference recipe that loaded every step's version again.
232
+ Without the option, `boundary.recorded_changes` raises `ConfigurationError`
233
+ rather than returning `nil`. Names in `ignore:` or `ignore: { all: }` are
234
+ left out, and so are names on the root path, `"$"`, for the root's own
235
+ versions. Names on an association path are not, because a child's version
236
+ does not say which path reached it.
237
+ - `change_rows` on an activity step, on an `Analysis` built with
238
+ `activity: true`, and on a `report` or `analyze_scope` result flattens
239
+ activity into `ChangeRow` objects: one per edited field, and one per record
240
+ that appeared or disappeared followed by its fields. Each names its record,
241
+ association path, and source version, and `to_h` gives a flat hash. It
242
+ replaces the README recipe for turning a report into rows, which had no rows
243
+ for whole records, so a record added or removed with only blank fields left
244
+ no trace.
245
+
246
+ - `associations:` takes what `includes` takes: a single name
247
+ (`associations: :comments`) or hashes of names to what to include below them
248
+ (`associations: [:author, { comments: :replies }]`), as well as the arrays of
249
+ names and dotted paths it took before.
250
+
251
+ - `nested_changes` compares two top-level arrays, as a `json` column can hold,
252
+ and reports one `ArrayChange` at the empty path, `[]`. It returned `{}`,
253
+ although arrays nested in an object were compared.
254
+
255
+ ### Changed
256
+
257
+ - The reference describes how PT-AT records HABTM membership and how the gem
258
+ credits it. A change made between two root versions is credited to the
259
+ step after the earlier one, so a checkpoint's capture is credited to whoever
260
+ saved the version before it; a checkpoint just before the change as well
261
+ credits it to its author. Only the first version an instance saves after
262
+ changing a HABTM is right; PT-AT never forgets the instance's changes, not
263
+ even on `reload`. A later save from it records the old membership, and the
264
+ gem reports members removed and added again that never left.
265
+
266
+ - The performance guide describes current behavior instead of logging each
267
+ past change: what the batch methods cost, what still grows with a report,
268
+ the version indexes, what costs a query per record, historical filters,
269
+ large reports, and how to measure. Its measurements were taken again. The
270
+ earlier ones remain in `benchmark/results/` and in the changelog.
271
+
272
+ - `historical_filter:` reads the history of the relation's records only, and
273
+ of deleted records, which a relation cannot test. It read every record of
274
+ the model that changed in the window, so a report on one account's articles
275
+ raised `BatchLimitExceededError` when another account had more matching
276
+ articles than `limit:`, and spent `max_filter_versions:` on their versions.
277
+ Matching deleted records no longer count toward `limit:` unless
278
+ `include_deleted: true` is given, as without a filter.
279
+
280
+ - The reference says how a record created without a version, such as one
281
+ imported with `insert_all`, and history pruned with `has_paper_trail
282
+ limit:` read.
283
+
284
+ - `IncompleteTimeRangeError` no longer advises the deprecated
285
+ `close_on: :current`. The quickstart and performance guide no longer say
286
+ that `has_many :through` or limited associations need the opt-ins, and the
287
+ reference says that `association_paths` lists paths that need
288
+ `allow_approximate: true`.
289
+
290
+ - The quickstart sets PaperTrail's `yaml_column_permitted_classes`. In a new
291
+ Rails 8.1 app, versions hold timestamps as `ActiveSupport::TimeWithZone`,
292
+ and the quickstart's first `reify` raised `Psych::DisallowedClass` without
293
+ it. Its documentation spec now reads a version in that form.
294
+
295
+ - The README and architecture guide recommend a second version index,
296
+ `(item_type, created_at, item_id)`. Batch methods with `since:` or
297
+ `within:` find changed records by type and time, which the one index they
298
+ recommended cannot narrow, so each report read every version of the model:
299
+ about 230 ms instead of 2 ms on PostgreSQL with 5 million versions.
300
+ - The gemspec requires Active Record 7.1 to 8.1. CI tests 7.2 through 8.1,
301
+ and the suite passes on 7.1. It named only PaperTrail, so Bundler could
302
+ install the gem with Active Record 6.1 or 7.0, whose relations and Arel
303
+ nodes the gem reads differently.
304
+ - `close_on:` is deprecated and warns through the new
305
+ `PaperTrailDiff.deprecator`. It has had no effect since a window began
306
+ closing on the current record by default; remove it. In a Rails app,
307
+ register the deprecator with
308
+ `Rails.application.deprecators[:paper_trail_diff] = PaperTrailDiff.deprecator`.
309
+ - `allow_expensive:` is deprecated and has no effect. It refused exactly the
310
+ paths `allow_approximate:` refuses, so batch methods needed both or
311
+ neither; `allow_approximate: true` alone now accepts such a path in every
312
+ method, and `UnsupportedBatchPathError` is no longer raised. Batch methods
313
+ refuse such a path before their first query, as before, now with
314
+ `UnsupportedAssociationError`.
315
+ - `reload_live_endpoints:` is deprecated and warns. It still works until it
316
+ is removed. Skipping the reload saves a query for the records and one per
317
+ association level in each call, 2 for 500 articles with their comments,
318
+ and reads values from objects that may be stale; it also needs every
319
+ requested association loaded, and reads limited ones again anyway. It was
320
+ on `compare`, `compare_many`, and `activity_timeline` only. Remove it.
321
+
322
+ ### Fixed
323
+
324
+ - A HABTM member created in the same transaction as the checkpoint that
325
+ records it is a member at that checkpoint, as a member attached there
326
+ already was. It was left out, because it had no state before the
327
+ transaction, so the checkpoint missed it and a comparison from the
328
+ checkpoint to now reported it added.
329
+
330
+ - `association_paths` leaves out an association whose target, or a model its
331
+ `has_many :through` goes through, has no `has_paper_trail`, such as the
332
+ `file_attachment` and `file_blob` that `has_one_attached` defines. Every
333
+ request that reads history refused them with `UnversionedAssociationError`,
334
+ so a settings screen built from the list offered paths that always failed.
335
+
336
+ - `diagnose` reports `:tied_version_timestamps`, and `compare` emits
337
+ `ambiguous_association_boundary.paper_trail_diff`, only when the request can
338
+ read a path with PT-AT: one history reads only approximately, a composite
339
+ foreign key, or a polymorphic `belongs_to`. PT-AT places association changes
340
+ by timestamp alone. For every other path, since 0.14.0, versions that share a
341
+ timestamp are ordered by ID, so a change between them is reported, yet both
342
+ warned that it could not be detected. A request refused for a path PT-AT
343
+ would read now raises before the notification.
344
+
345
+ - `timeline`, `activity_timeline`, and `analyze` read every version of a
346
+ model whose versions association has a scope
347
+ (`has_paper_trail versions: { scope: }`), as the other methods already did.
348
+ They read only the versions the scope kept, so a change saved in a version
349
+ it left out was credited to the next one kept: with a bot's edits hidden,
350
+ an editor's step showed the bot's later edit too, and the same record and
351
+ window gave different steps in `analyze` and `analyze_many`. A version the
352
+ scope leaves out is also accepted as an endpoint. To report only some
353
+ changes, pass `version_scope:`.
354
+
355
+ - Activity steps leave out the versions a record saved while it was outside
356
+ the root's tree. A comment edited on another article, then moved to this
357
+ one, brought that edit into the article's timeline as a step, and a
358
+ transaction group's `sources` listed it. Saved together with a comment added
359
+ to the article, the edit took the credit for the addition. The same went for
360
+ a comment edited after it moved away or left a scope, and for an author
361
+ renamed after the article changed authors. A version now counts when its
362
+ record is in the tree before or after its transaction. The versions of a
363
+ `has_many :through`'s join rows are all still kept.
364
+
365
+ - `timeline`, `activity_timeline`, `analyze`, and `analyze_many` raise
366
+ `InvalidEndpointError` naming what they were given when it is not a record
367
+ of a versioned model, such as `nil`, a model class, a relation, or a
368
+ version. They raised a bare `NoMethodError`, or said to provide `from` and
369
+ `to`. `report` names `since` when it is `nil` or a range.
370
+
371
+ - A scope ordered by a datetime, such as
372
+ `-> { order(created_at: :desc, id: :desc).limit(3) }`, is read from history
373
+ under Rails' default time-zone-aware attributes. Rails wraps those
374
+ attributes' types, which hid the datetime, so every method raised
375
+ `UnsupportedAssociationError` for the documented recipe.
376
+
377
+ - A `Date` bound of `within:` or `since:` is a whole day in `Time.zone`, and
378
+ a string a time in `Time.zone`, or in UTC without one. They were read in
379
+ the server's own zone, so the same window covered different hours on
380
+ different servers, and a same-day `Date..Date` window covered one instant
381
+ and found nothing.
382
+
383
+ - A `has_many :through` whose join model is not versioned raises
384
+ `UnversionedAssociationError` naming the join model when its history is
385
+ read, and `diagnose` reports it as an error, so `ok?` is false. A
386
+ comparison raised a bare `KeyError` while `diagnose` reported only a
387
+ warning.
388
+
389
+ - `reload_live_endpoints: false` reads an association with a `limit` or
390
+ `offset`, directly or in a part it goes through, or a scope that takes the
391
+ owner, again for each record. Active Record's `preload` applies the limit across all the records
392
+ it loads, so with three articles preloaded, two kept one comment each and
393
+ the third none, and their unchanged comments were reported as removed.
394
+
395
+ - A root and its associations that share one version table other than
396
+ PaperTrail's `versions` can be compared. Association lookups joined PT-AT's
397
+ version associations to the `versions` table whatever table the versions
398
+ were in, so every method raised `ActiveRecord::StatementInvalid`.
399
+
400
+ - A `within:` or `since:` window whose edge falls inside a transaction that
401
+ saved a version of the root record reports the whole transaction in the
402
+ later window. A window starting between a comment edit and the `touch: true`
403
+ article version saved with it showed the edit at the article's next change,
404
+ credited to that change's author, and the window ending there left it out;
405
+ when the article saved first, its version was in one window and the comment
406
+ edit in the other. Each root's edges move back to the transaction's start,
407
+ read in a fixed number of queries per 200 records.
408
+
409
+ - `activity_timeline`, and `analyze` with `activity: true`, no longer report a
410
+ child version saved in the same transaction as the root version that ends
411
+ the range. A `touch: true` parent version is saved this way after every
412
+ child save. PT-AT rebuilds the parent's associations at that version as they
413
+ were before the transaction, so the child's step was always empty and its
414
+ change was reported nowhere. The range now ends before that transaction, as
415
+ `compare` and `timeline` already did. End at a later version or at the
416
+ current record to include the change, with `group: :transaction` to credit it
417
+ to the child's version.
418
+ - A range that starts at a version now starts before that version's
419
+ transaction, as one that ends there already ended. A child version saved
420
+ earlier in the same transaction, such as the update behind a `touch: true`
421
+ parent version, was read after its change, so `compare`, `analyze`,
422
+ `timeline`, and `activity_timeline` from that version left the change out.
423
+ It was also missing from the range ending there, so a history split at that
424
+ version reported it nowhere. It is now inside the range that starts there.
425
+ - A past `within:` window in `activity_timeline`, and in `analyze`,
426
+ `analyze_many`, `analyze_scope`, and `report` with `activity: true`, no
427
+ longer includes association changes made after it. When the root had no
428
+ version after the window, the window closed on current state, so a comment
429
+ edited in August appeared in a July window, in its last step, `to_snapshot`,
430
+ and `diff`; with a later root version the same window was right. It now
431
+ closes on current state only when nothing on a requested path was recorded
432
+ after it. The reasoning in 0.8.0, that nothing had been recorded since,
433
+ checked only the root's own versions. `timeline`, and `analyze` without
434
+ `activity:`, still run their last step to the root's next version or the
435
+ current record; the reference now says so.
436
+ - Association scopes read from history now cover `IS NULL` and `IS NOT NULL`
437
+ on a column of any type, such as a soft-delete scope's
438
+ `where(deleted_at: nil)`, and `NOT` with SQL's rules for NULL, such as
439
+ `where.not(position: [1, nil])`. These were read with PT-AT before, so a
440
+ record restored from a soft delete showed as changed rather than added, and
441
+ batch methods refused them without `allow_expensive: true`. A condition on a
442
+ PostgreSQL `citext` column, which compares without regard to case, is no
443
+ longer read as exact text.
444
+ - A `historical_filter:` hash casts its values, and the recorded ones, to each
445
+ attribute's type before comparing them, as `where` does. An enum given as a
446
+ symbol (`{ status: :published }`), and a date or time read from a `json` or
447
+ `jsonb` version column, which PaperTrail returns as a string, never matched,
448
+ so the report silently selected nothing.
449
+ - Versions from two version tables saved in the same instant raise
450
+ `AmbiguousVersionOrderError`, as the reference promises, instead of being
451
+ ordered by their ids. Each table counts its ids separately, so their order
452
+ said nothing about which change came first, and an activity timeline built
453
+ from them could credit a change to the wrong step.
454
+ - `compare_many`, `analyze_many`, `analyze_scope`, and `report` load a
455
+ `has_one` of every current record in one query again, as before 0.14.0.
456
+ 0.14.0 meant to load only a `has_one` with a declared limit or offset per
457
+ record, but checked the association's scope, to which Active Record adds
458
+ `limit(1)` for every `has_one`, so every `has_one` cost one query per
459
+ record.
460
+ - `report`, `analyze_scope`, and `analyze_many` with `activity: true` no
461
+ longer read a root's current row once more for activity through a
462
+ `has_many :through` after its last version. The batch has already loaded
463
+ it, so the query count no longer grows with the number of roots.
464
+ - A snapshot's collections list their records by type, then ID, as the
465
+ reference says, wherever the snapshot was read from. Snapshots rebuilt from
466
+ history or carried through an activity timeline listed them in the order
467
+ they were found, and a ranked association in its query's order, so `to_h` of
468
+ the same state differed between methods. Diffs were already ordered.
469
+ - With a `json` or `jsonb` `object` column, an activity step no longer
470
+ reports an unchanged timestamp as changed. PaperTrail returns such a
471
+ column's times as strings, and a step after a child's update carried them
472
+ into the snapshot as they were, so the next step that read the child again
473
+ reported `created_at` changing from a string to the same time. Activity now
474
+ casts them as it does every other recorded state. The specs had covered the
475
+ JSON serializer on a text column only, which PaperTrail casts.
476
+
477
+ ### Development
478
+
479
+ - A new oracle suite, `rake spec_oracle`, checks rebuilt history against the
480
+ truth rather than against other gem methods. It makes seeded random edits to
481
+ an article graph one transaction at a time, records the live state after
482
+ each, and compares every endpoint, timeline step, activity step, window, and
483
+ batch result with those states. It also checks that two windows meeting
484
+ between transactions or inside one report each step once, scoped membership
485
+ against Active Record, and a tree of one model whose children have
486
+ encrypted, serialized, enum, custom-type, decimal, and JSON attributes.
487
+ `rake spec` runs it, so CI runs it on every database. `ORACLE_SEEDS` and
488
+ `ORACLE_STEPS` widen a run. See `docs/testing.md`.
489
+ - `PTD_PROBE_ALLOW_APPROXIMATE=1` makes the reconstruction probe pass
490
+ `allow_approximate: true`, so its PT-AT-read scenario runs rather than
491
+ raising, and neither benchmark passes the deprecated `close_on:` any more.
492
+ - On SQL Server the association specs keep their versions 5 ms apart. Specs
493
+ that compare the gem with PT-AT failed at random there: PT-AT compares
494
+ version times through SQL text, which the SQL Server adapter writes as
495
+ `datetime` values up to 1/300 s off, and after the host clock stepped back
496
+ the test clock packed versions microseconds apart until it caught up.
497
+ - The reporting benchmark loads the monotonic test clock, so its results no
498
+ longer depend on the host clock. A clock that stepped backwards, as WSL2's
499
+ does, could date a root's destroy before its last update, and
500
+ `deleted_roots` then raised `IncompleteTimeRangeError`. The seeded history
501
+ and query counts are unchanged. Allocations rise by under 1% in
502
+ `many_roots` and `retained_activity`, where the gem reads the clock once
503
+ per root. The investigation scripts that seed through the same workload
504
+ load the clock too; `scalar_cost.rb` freezes time in front of it, so its
505
+ parity check still sees one instant.
506
+
6
507
  ## [0.14.0] - 2026-10-29
7
508
 
8
509
  ### Breaking changes
data/QUICKSTART.md CHANGED
@@ -37,6 +37,19 @@ table. `--with-changes` adds `object_changes`, which PaperTrail uses for
37
37
  for each event. This gem can also compare the full earlier records saved in
38
38
  PaperTrail's `object` column.
39
39
 
40
+ PaperTrail stores earlier records as YAML, and Rails reads back only the YAML
41
+ classes you allow. Without this, reading the first version raises
42
+ `Psych::DisallowedClass`. Add PaperTrail's list to `config/application.rb`,
43
+ inside `class Application`:
44
+
45
+ <!-- executable:quickstart-config -->
46
+ ```ruby
47
+ config.active_record.yaml_column_permitted_classes = [
48
+ ActiveRecord::Type::Time::Value, ActiveSupport::TimeWithZone, ActiveSupport::TimeZone,
49
+ BigDecimal, Date, Symbol, Time
50
+ ]
51
+ ```
52
+
40
53
  ## 2. Version a model
41
54
 
42
55
  Create an article model and tell PaperTrail to track its changes:
@@ -233,10 +246,11 @@ The same `within:` option works on `activity_timeline`, `analyze`,
233
246
  | Recent activity through now, for the records a relation selects | `report(scope, since:, limit:)` |
234
247
 
235
248
  Use the batch methods for many records so they can share database queries.
236
- Some scoped associations and `has_many :through` histories still need queries
237
- for each record. Batch calls reject those with `UnsupportedBatchPathError`.
238
- The error names the association. `allow_expensive: true` permits that extra work;
239
- see the [performance guide](docs/performance.md) before using it in a large report.
249
+ A few scoped associations, such as one whose scope is SQL text, can be read
250
+ only with PT-AT, approximately and one record at a time. Every method rejects
251
+ them with `UnsupportedAssociationError`, naming the association; passing
252
+ `allow_approximate: true` accepts both costs. See
253
+ [costly associations](docs/reference.md#costly-associations).
240
254
 
241
255
  When associations are included, `timeline` compares their values at the article's
242
256
  versions. `activity_timeline` also reports the comments' own version events, even
@@ -388,6 +402,9 @@ window to select that article.
388
402
  comments does not automatically include every association on each comment.
389
403
  - Historical output cannot contain data that PaperTrail or PT-AT did not record
390
404
  or can no longer reconstruct.
405
+ - A report with `since:` or `within:` gets slow as the version table grows
406
+ unless you add the
407
+ [two version indexes](docs/architecture.md#database-indexes).
391
408
 
392
409
  For association support, performance, error handling, ignore rules, and all
393
410
  available result methods, see the