paper_trail_diff 0.16.0 → 0.17.1

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 (206) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +581 -1
  3. data/README.md +42 -7
  4. data/docs/architecture.md +7 -5
  5. data/docs/performance.md +86 -38
  6. data/docs/reference.md +309 -92
  7. data/docs/testing.md +240 -32
  8. data/lib/paper_trail_diff/activity_belongs_to_event_applier.rb +2 -16
  9. data/lib/paper_trail_diff/activity_boundary.rb +55 -34
  10. data/lib/paper_trail_diff/activity_child_candidate_loader.rb +46 -57
  11. data/lib/paper_trail_diff/activity_collection_event_applier.rb +3 -13
  12. data/lib/paper_trail_diff/activity_collection_route_updater.rb +1 -1
  13. data/lib/paper_trail_diff/activity_event.rb +33 -21
  14. data/lib/paper_trail_diff/activity_event_record_resolver.rb +16 -116
  15. data/lib/paper_trail_diff/activity_event_route_finder.rb +29 -29
  16. data/lib/paper_trail_diff/activity_event_snapshot_refresher.rb +2 -7
  17. data/lib/paper_trail_diff/activity_history.rb +90 -49
  18. data/lib/paper_trail_diff/activity_range.rb +9 -35
  19. data/lib/paper_trail_diff/activity_root_snapshot_refresher.rb +74 -40
  20. data/lib/paper_trail_diff/activity_root_steps.rb +10 -13
  21. data/lib/paper_trail_diff/activity_scope_filter.rb +77 -0
  22. data/lib/paper_trail_diff/activity_snapshot_delta.rb +12 -15
  23. data/lib/paper_trail_diff/activity_snapshot_sequence.rb +37 -15
  24. data/lib/paper_trail_diff/activity_target_candidate_loader.rb +35 -43
  25. data/lib/paper_trail_diff/activity_timeline_builder.rb +194 -249
  26. data/lib/paper_trail_diff/activity_transaction_grouper.rb +3 -1
  27. data/lib/paper_trail_diff/activity_tree_filter.rb +54 -13
  28. data/lib/paper_trail_diff/activity_version_collector.rb +72 -138
  29. data/lib/paper_trail_diff/activity_view.rb +22 -11
  30. data/lib/paper_trail_diff/analysis.rb +19 -5
  31. data/lib/paper_trail_diff/analysis_batch.rb +16 -58
  32. data/lib/paper_trail_diff/approximate_paths.rb +4 -8
  33. data/lib/paper_trail_diff/association_activity_edge.rb +5 -24
  34. data/lib/paper_trail_diff/association_activity_selection.rb +10 -18
  35. data/lib/paper_trail_diff/association_discovery.rb +1 -6
  36. data/lib/paper_trail_diff/association_key.rb +9 -6
  37. data/lib/paper_trail_diff/association_traversal.rb +49 -6
  38. data/lib/paper_trail_diff/batch_boundary_resolver.rb +33 -42
  39. data/lib/paper_trail_diff/batch_preload.rb +2 -12
  40. data/lib/paper_trail_diff/batched_root_analyses.rb +72 -0
  41. data/lib/paper_trail_diff/batched_root_analyzer.rb +16 -14
  42. data/lib/paper_trail_diff/batched_root_versions.rb +25 -20
  43. data/lib/paper_trail_diff/branch_snapshot_refresher.rb +27 -31
  44. data/lib/paper_trail_diff/change_attribution.rb +329 -0
  45. data/lib/paper_trail_diff/change_row.rb +30 -10
  46. data/lib/paper_trail_diff/comparison_batch.rb +3 -4
  47. data/lib/paper_trail_diff/configuration.rb +1 -1
  48. data/lib/paper_trail_diff/deleted_analysis_batch.rb +22 -37
  49. data/lib/paper_trail_diff/deleted_root_filter.rb +3 -6
  50. data/lib/paper_trail_diff/deprecation.rb +4 -43
  51. data/lib/paper_trail_diff/diagnostics.rb +1 -2
  52. data/lib/paper_trail_diff/direct_record_state_loader.rb +8 -1
  53. data/lib/paper_trail_diff/endpoint.rb +78 -44
  54. data/lib/paper_trail_diff/errors.rb +2 -9
  55. data/lib/paper_trail_diff/fallback_paths.rb +2 -5
  56. data/lib/paper_trail_diff/habtm_transaction_owners.rb +5 -3
  57. data/lib/paper_trail_diff/historical_association_reifier.rb +3 -1
  58. data/lib/paper_trail_diff/historical_filter.rb +40 -15
  59. data/lib/paper_trail_diff/historical_snapshot_store.rb +80 -38
  60. data/lib/paper_trail_diff/instrumentation.rb +0 -8
  61. data/lib/paper_trail_diff/live_endpoint_batch_loader.rb +11 -7
  62. data/lib/paper_trail_diff/live_endpoint_provider.rb +7 -23
  63. data/lib/paper_trail_diff/live_graph_collector.rb +3 -3
  64. data/lib/paper_trail_diff/nested_comparator.rb +46 -19
  65. data/lib/paper_trail_diff/net_change.rb +276 -0
  66. data/lib/paper_trail_diff/own_window.rb +35 -0
  67. data/lib/paper_trail_diff/paper_trail_adapter.rb +40 -45
  68. data/lib/paper_trail_diff/prepared_activity_index.rb +197 -45
  69. data/lib/paper_trail_diff/prepared_child_candidates.rb +58 -0
  70. data/lib/paper_trail_diff/prepared_edge_loader.rb +43 -107
  71. data/lib/paper_trail_diff/prepared_history.rb +20 -31
  72. data/lib/paper_trail_diff/prepared_history_loader.rb +46 -9
  73. data/lib/paper_trail_diff/prepared_record_index.rb +137 -47
  74. data/lib/paper_trail_diff/prepared_snapshot_builder.rb +16 -0
  75. data/lib/paper_trail_diff/prepared_state_association_reader.rb +17 -19
  76. data/lib/paper_trail_diff/read_snapshot.rb +41 -19
  77. data/lib/paper_trail_diff/recorded_changes.rb +10 -11
  78. data/lib/paper_trail_diff/recorded_changes_reader.rb +60 -0
  79. data/lib/paper_trail_diff/recorded_class.rb +14 -19
  80. data/lib/paper_trail_diff/recorded_columns.rb +33 -0
  81. data/lib/paper_trail_diff/root_version_plan.rb +20 -22
  82. data/lib/paper_trail_diff/root_version_selection.rb +39 -29
  83. data/lib/paper_trail_diff/scope_condition.rb +7 -17
  84. data/lib/paper_trail_diff/scope_ranking.rb +16 -22
  85. data/lib/paper_trail_diff/scoped_analysis.rb +27 -4
  86. data/lib/paper_trail_diff/scoped_analysis_builder.rb +4 -3
  87. data/lib/paper_trail_diff/scoped_root_selection.rb +60 -41
  88. data/lib/paper_trail_diff/snapshot_normalizer.rb +18 -3
  89. data/lib/paper_trail_diff/stored_json_values.rb +52 -0
  90. data/lib/paper_trail_diff/stored_time_precision.rb +30 -18
  91. data/lib/paper_trail_diff/stored_values.rb +20 -0
  92. data/lib/paper_trail_diff/support.rb +185 -35
  93. data/lib/paper_trail_diff/time_of_day.rb +39 -0
  94. data/lib/paper_trail_diff/time_range.rb +37 -20
  95. data/lib/paper_trail_diff/time_version_range.rb +5 -10
  96. data/lib/paper_trail_diff/timeline_builder.rb +3 -3
  97. data/lib/paper_trail_diff/timeline_range.rb +18 -12
  98. data/lib/paper_trail_diff/timeline_snapshot_provider.rb +1 -1
  99. data/lib/paper_trail_diff/total_order.rb +55 -0
  100. data/lib/paper_trail_diff/transaction_cut.rb +192 -91
  101. data/lib/paper_trail_diff/traversal_preparer.rb +5 -8
  102. data/lib/paper_trail_diff/value_objects.rb +8 -4
  103. data/lib/paper_trail_diff/version.rb +1 -1
  104. data/lib/paper_trail_diff/version_association_candidate_scope.rb +27 -16
  105. data/lib/paper_trail_diff/version_boundary.rb +37 -21
  106. data/lib/paper_trail_diff/version_query.rb +25 -25
  107. data/lib/paper_trail_diff/version_range.rb +12 -16
  108. data/lib/paper_trail_diff/version_sequence_diagnostics.rb +32 -0
  109. data/lib/paper_trail_diff/version_table.rb +12 -8
  110. data/lib/paper_trail_diff.rb +28 -42
  111. data/sig/generated/paper_trail_diff/activity_belongs_to_event_applier.rbs +0 -8
  112. data/sig/generated/paper_trail_diff/activity_boundary.rbs +39 -17
  113. data/sig/generated/paper_trail_diff/activity_child_candidate_loader.rbs +19 -22
  114. data/sig/generated/paper_trail_diff/activity_collection_event_applier.rbs +0 -5
  115. data/sig/generated/paper_trail_diff/activity_event.rbs +25 -9
  116. data/sig/generated/paper_trail_diff/activity_event_record_resolver.rbs +6 -34
  117. data/sig/generated/paper_trail_diff/activity_event_route_finder.rbs +11 -4
  118. data/sig/generated/paper_trail_diff/activity_event_snapshot_refresher.rbs +0 -3
  119. data/sig/generated/paper_trail_diff/activity_history.rbs +54 -19
  120. data/sig/generated/paper_trail_diff/activity_range.rbs +6 -20
  121. data/sig/generated/paper_trail_diff/activity_root_snapshot_refresher.rbs +36 -2
  122. data/sig/generated/paper_trail_diff/activity_root_steps.rbs +6 -6
  123. data/sig/generated/paper_trail_diff/activity_scope_filter.rbs +51 -0
  124. data/sig/generated/paper_trail_diff/activity_snapshot_delta.rbs +5 -3
  125. data/sig/generated/paper_trail_diff/activity_snapshot_sequence.rbs +21 -3
  126. data/sig/generated/paper_trail_diff/activity_target_candidate_loader.rbs +19 -24
  127. data/sig/generated/paper_trail_diff/activity_timeline_builder.rbs +121 -127
  128. data/sig/generated/paper_trail_diff/activity_tree_filter.rbs +41 -8
  129. data/sig/generated/paper_trail_diff/activity_version_collector.rbs +42 -35
  130. data/sig/generated/paper_trail_diff/activity_view.rbs +16 -8
  131. data/sig/generated/paper_trail_diff/analysis.rbs +15 -6
  132. data/sig/generated/paper_trail_diff/analysis_batch.rbs +6 -24
  133. data/sig/generated/paper_trail_diff/association_activity_edge.rbs +0 -13
  134. data/sig/generated/paper_trail_diff/association_activity_selection.rbs +6 -9
  135. data/sig/generated/paper_trail_diff/association_discovery.rbs +0 -3
  136. data/sig/generated/paper_trail_diff/association_key.rbs +5 -0
  137. data/sig/generated/paper_trail_diff/association_traversal.rbs +26 -2
  138. data/sig/generated/paper_trail_diff/batch_boundary_resolver.rbs +17 -17
  139. data/sig/generated/paper_trail_diff/batch_preload.rbs +0 -4
  140. data/sig/generated/paper_trail_diff/batched_root_analyses.rbs +47 -0
  141. data/sig/generated/paper_trail_diff/batched_root_analyzer.rbs +9 -8
  142. data/sig/generated/paper_trail_diff/batched_root_versions.rbs +10 -6
  143. data/sig/generated/paper_trail_diff/branch_snapshot_refresher.rbs +11 -5
  144. data/sig/generated/paper_trail_diff/change_attribution.rbs +194 -0
  145. data/sig/generated/paper_trail_diff/change_row.rbs +22 -7
  146. data/sig/generated/paper_trail_diff/deleted_analysis_batch.rbs +11 -12
  147. data/sig/generated/paper_trail_diff/deleted_root_filter.rbs +0 -2
  148. data/sig/generated/paper_trail_diff/deprecation.rbs +4 -24
  149. data/sig/generated/paper_trail_diff/direct_record_state_loader.rbs +4 -0
  150. data/sig/generated/paper_trail_diff/endpoint.rbs +40 -16
  151. data/sig/generated/paper_trail_diff/errors.rbs +2 -11
  152. data/sig/generated/paper_trail_diff/habtm_transaction_owners.rbs +2 -1
  153. data/sig/generated/paper_trail_diff/historical_filter.rbs +20 -9
  154. data/sig/generated/paper_trail_diff/historical_snapshot_store.rbs +40 -10
  155. data/sig/generated/paper_trail_diff/instrumentation.rbs +0 -3
  156. data/sig/generated/paper_trail_diff/live_endpoint_batch_loader.rbs +3 -0
  157. data/sig/generated/paper_trail_diff/live_endpoint_provider.rbs +5 -8
  158. data/sig/generated/paper_trail_diff/live_graph_collector.rbs +2 -2
  159. data/sig/generated/paper_trail_diff/nested_comparator.rbs +20 -4
  160. data/sig/generated/paper_trail_diff/net_change.rbs +168 -0
  161. data/sig/generated/paper_trail_diff/own_window.rbs +22 -0
  162. data/sig/generated/paper_trail_diff/paper_trail_adapter.rbs +9 -6
  163. data/sig/generated/paper_trail_diff/prepared_activity_index.rbs +114 -14
  164. data/sig/generated/paper_trail_diff/prepared_child_candidates.rbs +39 -0
  165. data/sig/generated/paper_trail_diff/prepared_edge_loader.rbs +18 -35
  166. data/sig/generated/paper_trail_diff/prepared_history.rbs +9 -12
  167. data/sig/generated/paper_trail_diff/prepared_history_loader.rbs +28 -3
  168. data/sig/generated/paper_trail_diff/prepared_record_index.rbs +68 -14
  169. data/sig/generated/paper_trail_diff/prepared_snapshot_builder.rbs +12 -0
  170. data/sig/generated/paper_trail_diff/prepared_state_association_reader.rbs +6 -7
  171. data/sig/generated/paper_trail_diff/read_snapshot.rbs +27 -8
  172. data/sig/generated/paper_trail_diff/recorded_changes.rbs +4 -2
  173. data/sig/generated/paper_trail_diff/recorded_changes_reader.rbs +41 -0
  174. data/sig/generated/paper_trail_diff/recorded_class.rbs +7 -6
  175. data/sig/generated/paper_trail_diff/recorded_columns.rbs +21 -0
  176. data/sig/generated/paper_trail_diff/root_version_plan.rbs +8 -4
  177. data/sig/generated/paper_trail_diff/root_version_selection.rbs +27 -13
  178. data/sig/generated/paper_trail_diff/scope_condition.rbs +0 -2
  179. data/sig/generated/paper_trail_diff/scope_ranking.rbs +10 -10
  180. data/sig/generated/paper_trail_diff/scoped_analysis.rbs +19 -0
  181. data/sig/generated/paper_trail_diff/scoped_analysis_builder.rbs +2 -2
  182. data/sig/generated/paper_trail_diff/scoped_root_selection.rbs +37 -14
  183. data/sig/generated/paper_trail_diff/snapshot_normalizer.rbs +7 -0
  184. data/sig/generated/paper_trail_diff/stored_json_values.rbs +35 -0
  185. data/sig/generated/paper_trail_diff/stored_time_precision.rbs +19 -5
  186. data/sig/generated/paper_trail_diff/stored_values.rbs +13 -0
  187. data/sig/generated/paper_trail_diff/support.rbs +120 -23
  188. data/sig/generated/paper_trail_diff/time_of_day.rbs +21 -0
  189. data/sig/generated/paper_trail_diff/time_range.rbs +15 -8
  190. data/sig/generated/paper_trail_diff/time_version_range.rbs +2 -5
  191. data/sig/generated/paper_trail_diff/timeline_builder.rbs +2 -2
  192. data/sig/generated/paper_trail_diff/timeline_range.rbs +12 -7
  193. data/sig/generated/paper_trail_diff/total_order.rbs +32 -0
  194. data/sig/generated/paper_trail_diff/transaction_cut.rbs +111 -52
  195. data/sig/generated/paper_trail_diff/traversal_preparer.rbs +2 -2
  196. data/sig/generated/paper_trail_diff/value_objects.rbs +5 -1
  197. data/sig/generated/paper_trail_diff/version_association_candidate_scope.rbs +10 -9
  198. data/sig/generated/paper_trail_diff/version_boundary.rbs +15 -8
  199. data/sig/generated/paper_trail_diff/version_query.rbs +17 -10
  200. data/sig/generated/paper_trail_diff/version_range.rbs +6 -9
  201. data/sig/generated/paper_trail_diff/version_sequence_diagnostics.rbs +13 -0
  202. data/sig/generated/paper_trail_diff/version_table.rbs +3 -0
  203. data/sig/generated/paper_trail_diff.rbs +16 -16
  204. metadata +28 -6
  205. data/lib/paper_trail_diff/preloaded_endpoint_batch_loader.rb +0 -60
  206. data/sig/generated/paper_trail_diff/preloaded_endpoint_batch_loader.rbs +0 -32
data/docs/reference.md CHANGED
@@ -84,6 +84,8 @@ Six things follow from this:
84
84
  leave it out.
85
85
  [`recorded_changes`](#what-a-version-recorded) reads what a version itself
86
86
  recorded, and activity steps can [include it](#what-each-event-recorded-recorded_changes-true).
87
+ With it, [change rows](#change-rows) give such a write a row of its own,
88
+ credited to no one.
87
89
  - **A record created without a version looks as if it always existed.** A
88
90
  row written with versioning off, or imported with `insert_all`, has no
89
91
  `create` version, so history never reports it as added: its earliest
@@ -172,20 +174,38 @@ all of today and `august...september` stops before September 1. A string is a
172
174
  time in `Time.zone` unless it names an offset. Without `Time.zone`, both are
173
175
  read in UTC, never in the server's own zone.
174
176
 
177
+ An endless range, such as `1.day.ago..`, runs through the current saved state:
178
+ it holds every version saved since it began, whatever time its server's clock
179
+ gave it, and it ends at the current record. `report` uses one.
180
+
175
181
  A window edge that falls inside a transaction moves back to where that
176
182
  transaction began, so the whole transaction is in the later window, as it is
177
- when a range [starts or ends at a version](#choosing-a-range). This applies to
178
- transactions that saved a version of the root record, such as a comment edit
179
- and the `touch: true` article version saved with it. So back-to-back windows,
180
- or a `report` with `since:` after an earlier report, show each change exactly
181
- once, credited to the transaction that made it. Each root moves its own edges,
182
- so in a batch two roots can start a few moments apart.
183
+ when a range [starts or ends at a version](#choosing-a-range). It moves when
184
+ the transaction saved the root record after the edge, such as a comment edit
185
+ and the `touch: true` article version saved with it, or saved the root before
186
+ the edge and a record of a class on the requested paths after it. A
187
+ transaction that saved the root only before the edge, and nothing on its paths
188
+ after it, moves no edge: the root's change is in the earlier window, with its
189
+ version, even when the transaction went on to save another article. A
190
+ transaction that saved only associated records moves no edge either. When it
191
+ saved some of them before the edge and some after, its changes are still all
192
+ in one window: in the later one when a version it saved after the edge is of a
193
+ record on the requested paths before or after the transaction, and otherwise
194
+ in the earlier one. A polymorphic `belongs_to` names its target's class only in
195
+ each record, so a target saved after the edge moves nothing: the root's change
196
+ is then in the earlier window and the target's in the later one. A
197
+ [transaction group](#one-step-per-transaction-group-transaction) lists in
198
+ `sources` only the versions inside its window. So back-to-back windows, or a
199
+ `report` with `since:` after an earlier report, show each change exactly
200
+ once, credited to the transaction that made it. Each root moves its own
201
+ edges, so in a batch two roots can start a few moments apart.
183
202
 
184
203
  `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.
204
+ Ruby range, endless for `report` and any other endless window. It is `nil` when
205
+ `within:` or `since:` was not given. Every step of the analysis is inside it,
206
+ so to check a step against the window, use `analysis.window` rather than the
207
+ range you passed: a step at the start of a moved window begins before the time
208
+ you asked for.
189
209
 
190
210
  ```ruby
191
211
  analysis = PaperTrailDiff.analyze_many(articles, within: window, activity: true).values.first
@@ -231,19 +251,14 @@ in the step for that record's last recorded change.
231
251
  If the window's last change destroyed the record, the window closes on that
232
252
  deletion instead. See [a destroyed record](#a-destroyed-record).
233
253
 
234
- `close_on: :current` is deprecated and has no effect; passing it warns through
235
- `PaperTrailDiff.deprecator`. Remove it. In a Rails app, register the deprecator
236
- with `Rails.application.deprecators[:paper_trail_diff] = PaperTrailDiff.deprecator`
237
- to handle its warnings as the app's own.
238
-
239
254
  `timeline` returns no steps for a window with no versions of the root record.
240
255
  `activity_timeline` still reports chosen associations that changed in such a
241
256
  window.
242
257
 
243
258
  ### Reporting only some changes: `version_scope:`
244
259
 
245
- `version_scope:` narrows which of the root record's versions are reported. It
246
- receives the version relation and returns a narrower one:
260
+ `version_scope:` narrows which changes are reported. It receives the version
261
+ relation and returns a narrower one:
247
262
 
248
263
  ```ruby
249
264
  user_edits = ->(scope) { scope.where.not(whodunnit: nil) }
@@ -263,17 +278,29 @@ It is accepted by `timeline`, `activity_timeline`, `analyze`, `analyze_many`,
263
278
  reported alice: what alice changed bob: what bob changed
264
279
  ```
265
280
 
266
- - It looks at the root record's versions only. Someone who only edited comments
267
- has no root versions to select. To find one person's changes, including to
268
- associations, see [one person's changes](#one-persons-changes).
281
+ - `timeline` looks at the root record's versions only, so someone who only
282
+ edited comments has none for it to report. Activity reports their changes:
283
+ see [one person's changes](#one-persons-changes).
284
+ - In activity (`activity_timeline`, `activity: true`, and `report`), it
285
+ chooses the changes on the requested associations as well. A transaction is
286
+ reported whole, every step of it, when the filter keeps any version saved
287
+ in it, of whichever record: PT-AT shows a transaction's changes together, at
288
+ its last step, so no step inside one belongs to a single version. A version
289
+ saved outside a transaction is reported when the filter keeps it. Every
290
+ version is still read, so each step shows what its own change did, and an
291
+ analysis starts at the first change the filter keeps and ends after the
292
+ last. Without associations, the steps are the root's versions the filter
293
+ keeps, as `timeline` reports them.
269
294
  - 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.
274
- - `activity_timeline` uses the filter to decide where the range starts and
275
- ends, but still lists every step inside it. Dropping one would move its
276
- change into a neighboring step and credit the wrong person.
295
+ a record is selected only when the filter keeps one of its own versions in
296
+ the window, or a version of a record on a requested association. A record
297
+ changed only by versions it drops would have nothing to report, so it is
298
+ left out, and it does not count toward `limit:`.
299
+ - The record and its requested associations keep their versions in one table
300
+ (see [custom version classes](#models-schemas-and-edge-cases)), and the
301
+ filter reads it for all of them. A condition on `item_type` or `item_id`
302
+ therefore leaves out the associations' changes; filter on the version's own
303
+ columns, such as `whodunnit` or `event`.
277
304
 
278
305
  ## compare
279
306
 
@@ -314,8 +341,7 @@ diff.to_h
314
341
  - A current record must be saved, not destroyed, and have no unsaved changes.
315
342
  The gem reloads it, so in-memory edits and cached associations are ignored.
316
343
  - Options: `associations:`, `ignore:`, and `allow_approximate:` (see
317
- [costly associations](#costly-associations)). `reload_live_endpoints:` is
318
- deprecated (see [reusing loaded records](#reusing-loaded-records)).
344
+ [costly associations](#costly-associations)).
319
345
 
320
346
  ## compare_many
321
347
 
@@ -345,21 +371,6 @@ diffs.fetch(["Order", orders.first.id.to_s]) # => PaperTrailDiff::Diff
345
371
  If you look up versions yourself, do it in bulk. Looking up one record at a
346
372
  time brings back the per-record queries this method avoids.
347
373
 
348
- ### Reusing loaded records
349
-
350
- Every method reloads the current records it compares with, together with the
351
- requested associations, in a query for the records and one per association
352
- level. `reload_live_endpoints: false` on `compare`, `compare_many`, and
353
- `activity_timeline` skips that reload and reads your loaded objects instead.
354
- It is deprecated and will be removed: it saves those few queries per call (2
355
- for 500 articles with their comments), and the values then come from objects
356
- that may be stale. Until it is removed it still works,
357
- with a warning. A requested association that is not loaded raises
358
- `UnloadedAssociationError`, and one with a `limit` or `offset`, directly or in
359
- a part it goes through, or a scope that takes the owner, is read again for
360
- each record, because Active Record's `preload` applies a limit to all the
361
- records it loads together.
362
-
363
374
  ## timeline
364
375
 
365
376
  `timeline(record)` returns one step for each pair of neighboring versions of the
@@ -429,12 +440,26 @@ end
429
440
  current record. You do not need to save the article after each comment change.
430
441
  - Options: `from:`, `to:`, `within:`, `associations:`, `ignore:`,
431
442
  `version_scope:`, `snapshots:`, `group:`, `recorded_changes:`,
432
- `allow_approximate:`. `reload_live_endpoints:` is deprecated (see
433
- [reusing loaded records](#reusing-loaded-records)).
443
+ `allow_approximate:`.
434
444
 
435
445
  ### One person's changes
436
446
 
437
- Filter the steps in Ruby by `source_boundary.whodunnit`:
447
+ Pass a [`version_scope:`](#reporting-only-some-changes-version_scope) that
448
+ keeps their versions. Activity then reports only the transactions they saved
449
+ a version in, on the record or on its associations:
450
+
451
+ <!-- executable:readme-person-scope -->
452
+ ```ruby
453
+ priya = ->(versions) { versions.where(whodunnit: "Priya Shah") }
454
+ steps = PaperTrailDiff.activity_timeline(
455
+ article, within: window, associations: %i[comments tags], version_scope: priya
456
+ )
457
+
458
+ steps.map { |step| step.source_boundary.whodunnit }.uniq # ["Priya Shah"]
459
+ ```
460
+
461
+ To count everyone's changes from one read, group the steps in Ruby by
462
+ `source_boundary.whodunnit` instead:
438
463
 
439
464
  <!-- executable:readme-person-changes -->
440
465
  ```ruby
@@ -452,13 +477,9 @@ authors = attributed.group_by { |step| step.source_boundary.whodunnit }
452
477
  .transform_values(&:length)
453
478
  ```
454
479
 
455
- This includes changes to associations, which `version_scope:` cannot see.
456
- Filter after the call rather than asking the gem for fewer versions: every step
457
- has to be rebuilt anyway for each one to be correct, so filtering earlier saves
458
- nothing.
459
-
460
480
  For many records, use `report` or `analyze_many(..., activity: true)` instead of
461
- calling `activity_timeline` in a loop, so the database work is shared.
481
+ calling `activity_timeline` in a loop, so the database work is shared. With
482
+ `version_scope:`, `report` selects only the records that person changed.
462
483
 
463
484
  ### One step per transaction: `group: :transaction`
464
485
 
@@ -474,13 +495,22 @@ PaperTrailDiff.activity_timeline(article, associations: [:comments], group: :tra
474
495
  it. A field set and then restored inside the transaction is not reported.
475
496
  - Its `source_boundary` is the first event in the transaction. That event's
476
497
  author is not necessarily the author of every grouped change. `step.sources`
477
- lists every event in the transaction, each with its own author, except
478
- those of records that were outside the tree before and after it.
498
+ lists every event in the transaction, each with its own author, except two
499
+ kinds: those of records outside the tree before the transaction, after it,
500
+ and at every version of the root it saved; and those saved before a window
501
+ that starts inside a transaction of associated records only (see
502
+ [time windows](#time-windows)). Its [change rows](#change-rows) each name
503
+ the event of their own record.
479
504
  - Versions without a `transaction_id` are never grouped.
480
505
  - A savepoint that rolls back can split one transaction into more than one
481
506
  group. PT-AT clears the transaction id when the savepoint rolls back, so the
482
507
  versions the transaction saves afterwards form a separate group. Releasing
483
508
  the savepoint keeps one group.
509
+ - A step joins only the group of the step just before it. Two transactions
510
+ that save in the same tree at the same time, so that their versions
511
+ interleave, each form a group for every run of their own versions: the
512
+ state between two runs holds the other transaction's change, so no single
513
+ step could show either one alone.
484
514
  - Also accepted by `analyze`, `analyze_many`, and `analyze_scope` with
485
515
  `activity: true`, and by `report`.
486
516
 
@@ -509,6 +539,7 @@ step.from_snapshot.associations["comments"].records.first.attributes["author"]
509
539
  record did not exist yet.
510
540
  - Also accepted by `analyze`, `analyze_many`, and `analyze_scope` with
511
541
  `activity: true`, and by `report`.
542
+ - [`net_changes`](#net-changes) reads them, so it needs this option.
512
543
 
513
544
  ### What each event recorded: `recorded_changes: true`
514
545
 
@@ -538,10 +569,11 @@ end
538
569
  - Each boundary's `recorded_changes` is what
539
570
  `PaperTrailDiff.recorded_changes(version)` returns for its version: `nil`
540
571
  when nothing was recorded, and always `nil` for the current record. The
541
- versions are already loaded, so this adds no queries, but decoding each
542
- version's changes takes time: about a third more for a `report` of 200
543
- articles with comments, with history stored as YAML. Pass it only when you
544
- use them.
572
+ versions are already loaded, so this adds no queries. A version's changes
573
+ are decoded the first time a boundary's `recorded_changes` is read, and once
574
+ for the whole call, however many steps or records share the version. Read
575
+ them from the boundary rather than calling `PaperTrailDiff.recorded_changes`
576
+ for its version, which decodes it again each time.
545
577
  - Without the option, `recorded_changes` raises `ConfigurationError` instead of
546
578
  returning `nil`, so a missing option cannot look like a version that recorded
547
579
  nothing.
@@ -628,9 +660,10 @@ analysis.to_h(snapshots: true, metadata: true)
628
660
  - `from_snapshot` is the record as it was when the range began: before the
629
661
  first change in a window, or before the change of the version you passed as
630
662
  `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.
663
+ filter keeps, on the record or, with `activity: true`, on its associations.
664
+ It is `nil` when the record was created inside the range; the state right
665
+ after it was created is then the first activity step's `to_snapshot`, which
666
+ `snapshots: true` keeps.
634
667
  - To read the record at one version, with its values typed and its
635
668
  associations, take `from_snapshot` from a range that starts there:
636
669
  `PaperTrailDiff.analyze(article, from: version, to: article).from_snapshot`.
@@ -695,7 +728,11 @@ report.roots # the selected records, in relation order
695
728
  report.unreachable # identities of selected records that no longer exist
696
729
  report.deleted # { identity => Analysis or nil }, with include_deleted: true
697
730
 
698
- analyses, unreachable = report # destructures into the first two
731
+ report.roots.each do |order|
732
+ report.analysis_for(order) # its Analysis, without building the identity
733
+ end
734
+
735
+ analyses, unreachable = report # destructures into analyses and unreachable
699
736
  ```
700
737
 
701
738
  It takes the same options as `analyze_many`, plus `limit:`, `historical_filter:`,
@@ -704,9 +741,8 @@ all history.
704
741
 
705
742
  ### report
706
743
 
707
- `report(scope, since:, limit:)` is `analyze_scope` with
708
- `within: since..Time.now.utc` and `activity: true`. Use it for "what happened
709
- recently":
744
+ `report(scope, since:, limit:)` is `analyze_scope` with `within: since..`, an
745
+ endless window, and `activity: true`. Use it for "what happened recently":
710
746
 
711
747
  ```ruby
712
748
  report = PaperTrailDiff.report(Article.all, since: 1.day.ago, limit: 100)
@@ -727,7 +763,7 @@ and `allow_approximate:`.
727
763
  versions and cannot show a change to its associations alone, so only a
728
764
  record's own version selects it. With
729
765
  [`version_scope:`](#reporting-only-some-changes-version_scope), only the
730
- record's own versions that the filter keeps select it.
766
+ versions the filter keeps select it, the record's own and its associations'.
731
767
  - **An analysis can still be empty.** A record is selected by any version on its
732
768
  paths, but its analysis compares only the state you requested. A join row
733
769
  whose role changed, or a version that touched only ignored columns, selects a
@@ -739,9 +775,17 @@ and `allow_approximate:`.
739
775
  selected, the call raises `BatchLimitExceededError` instead of returning part
740
776
  of the answer. Narrow the relation or the window, or raise the limit.
741
777
  - **To paginate, use the relation.** Its `order`, `limit`, and `offset` choose
742
- the page. Without an `order`, records are taken in ascending ID order. Add an
743
- ID tie-breaker to any other order. If a join repeats a record, it is analyzed
744
- once, in order of first appearance.
778
+ the page. Without an `order`, records are taken in ascending ID order. Any
779
+ other order gets the ID as a last tie-breaker unless it already sorts by it,
780
+ so that records that tie are neither skipped nor read twice. SQL text counts
781
+ as sorting by the ID when it names the column, alone or after the table's
782
+ name, as `order("title, id")` does. Give the queries that show the page the
783
+ same tie-breaker, such as `order(:status, :id)`, so that they list the
784
+ records the report analyzed. If a join repeats a record, it is analyzed
785
+ once, in order of first appearance. A relation grouped by anything but the
786
+ ID, such as `select("MAX(id) AS id").group(:author_id)`, keeps its own
787
+ order, since a database sorts groups only by what they group or aggregate.
788
+ It needs one that tells its groups apart, such as `order(:author_id)`.
745
789
  - Selection still scans the versions in the window, so keep windows reasonable
746
790
  for large tables. Each requested association adds one query per level, however
747
791
  many records it selects. Changes to associations are found from PT-AT's
@@ -797,8 +841,11 @@ report = PaperTrailDiff.report(
797
841
  )
798
842
  ```
799
843
 
800
- The filter checks the record as it was when the window started and after each
801
- change made inside it. A record matches if any of those states match. With a
844
+ The filter checks the record as it was when its window started and after each
845
+ change made inside it. That window is the one its analysis covers
846
+ (`analysis.window`): a transaction that crosses an edge moves the edge to where
847
+ the transaction began (see [time windows](#time-windows)). A record matches if
848
+ any of those states match. With a
802
849
  hash, every key must be equal (`==`) once both sides are cast to the
803
850
  attribute's type, as `where` casts its values: `{ status: :published }` matches
804
851
  an enum, and a date or time matches whether the history stored it as YAML or
@@ -909,7 +956,7 @@ such a path and names it. Remove it from `associations:`, rewrite its scope as
909
956
  plain conditions on the target's own columns, or pass `allow_approximate:
910
957
  true` to accept PT-AT's answer, which also accepts its cost of queries per
911
958
  record in batch methods. A comparison of two current records reads no history
912
- and needs no opt-in. `allow_expensive:` is deprecated and has no effect.
959
+ and needs no opt-in.
913
960
 
914
961
  A polymorphic `belongs_to` is loaded together too, with one query per target
915
962
  class. Its classes are known only from the records, though, so batch methods
@@ -1153,6 +1200,7 @@ for numeric IDs).
1153
1200
  | `ActivityStep` | one `activity_timeline` step |
1154
1201
  | `ActivityBoundary` | one end of a step |
1155
1202
  | `ChangeRow` | one row from `change_rows` |
1203
+ | `NetChange` | one record's entry from `net_changes` |
1156
1204
  | `Analysis` | result of `analyze` |
1157
1205
  | `ScopedAnalysis` | result of `analyze_scope` and `report` |
1158
1206
  | `TraversalEntry`, `RecordReference` | entries from `each_change` and `each_entry` |
@@ -1205,7 +1253,7 @@ record reachable through two requested paths appears at both.
1205
1253
  ### Change rows
1206
1254
 
1207
1255
  For a table or an export, `change_rows` flattens activity into one row per
1208
- change, each attributed to its step's source version:
1256
+ change, each credited to the version that made it:
1209
1257
 
1210
1258
  ```ruby
1211
1259
  steps.last.change_rows # one activity step
@@ -1219,14 +1267,15 @@ row.from # nil for :added
1219
1267
  row.to # nil for :removed
1220
1268
  row.record # a RecordReference, or nil for the root
1221
1269
  row.association_path # ["comments"], or [] for the root
1222
- row.source # the step's source_boundary
1270
+ row.source # the ActivityBoundary of the version that made the change
1271
+ row.unversioned? # true for a change saved without a version
1223
1272
  row.to_h # the above, plus version_id, event, whodunnit, recorded_at,
1224
1273
  # and transaction_id
1225
1274
  ```
1226
1275
 
1227
1276
  - An edited field is one `:changed` row. A record that appeared or disappeared
1228
1277
  gets an `:added` or `:removed` row with `attribute` `nil`, then a row for each
1229
- field that has a value and for each record it holds.
1278
+ field that is not `nil` and for each record it holds.
1230
1279
  - A replaced `belongs_to` or `has_one` target gives the old record `:removed`
1231
1280
  rows, then the new one `:added` rows.
1232
1281
  - Rows follow the diff's walking order, and an analysis's rows follow its steps
@@ -1234,6 +1283,112 @@ row.to_h # the above, plus version_id, event, whodunnit, recorded_at
1234
1283
  - `Analysis#change_rows` raises `ConfigurationError` without `activity: true`.
1235
1284
  `report.change_rows` leaves out a deleted record without destroy history.
1236
1285
 
1286
+ Which version a row names:
1287
+
1288
+ - A field's change names the version of the row's own record that made it,
1289
+ among those its step's transaction saved. Inside a transaction, a record's
1290
+ change can show up at a later event than its own, in a step another record's
1291
+ version opens; the row still names its own record's version. With
1292
+ `recorded_changes: true`, that is the version that recorded the field's new
1293
+ value. Without it, the gem cannot tell which of a record's versions made
1294
+ the change, so the row names the last of them.
1295
+ - A record created or destroyed names its `create` or `destroy`. Its fields
1296
+ name the version that recorded each value: the `create`, or a later save in
1297
+ the same step. A record that joined or left through another record's
1298
+ change, such as a new `belongs_to` target or a `has_and_belongs_to_many`
1299
+ member, names the step's `source_boundary`.
1300
+
1301
+ With `recorded_changes: true`, a change PaperTrail did not record gets a row of
1302
+ its own: a write [saved without a version](#how-papertrail-stores-history),
1303
+ such as `update_columns`. Its source has kind `:unversioned` and names the
1304
+ record, with no version, event, author, or time, so `to_h` has `nil` for
1305
+ `version_id`, `event`, `whodunnit`, `recorded_at`, and `transaction_id`. A
1306
+ field a version recorded changing from `10` to `20`, and that a later
1307
+ `update_columns` set to `99`, gives two rows: `10` to `20`, credited to the
1308
+ version, then `20` to `99`, unversioned. To report only what versions
1309
+ recorded, leave such rows out:
1310
+
1311
+ <!-- executable:reference-unversioned-rows -->
1312
+ ```ruby
1313
+ analysis = PaperTrailDiff.analyze(
1314
+ article, associations: [:comments], activity: true, recorded_changes: true
1315
+ )
1316
+
1317
+ analysis.change_rows.reject(&:unversioned?)
1318
+ ```
1319
+
1320
+ The gem splits off only what the versions show was not recorded. A row stays
1321
+ whole, credited to a version, where they cannot:
1322
+
1323
+ - the version recorded no changes, as a `touch` does, or the version table
1324
+ has no `object_changes` column;
1325
+ - the column is one `has_paper_trail ignore:` or `skip:` names, or `only:`
1326
+ leaves out;
1327
+ - the field is one a `create` left at its default, which no version records:
1328
+ a later write to it reads as the value the record was created with;
1329
+ - the version is in a transaction that began before a window and saved no
1330
+ version of the root (see [time windows](#time-windows)), whose earlier
1331
+ versions the window does not read.
1332
+
1333
+ Rows follow each step's diff, so a change a version recorded and a later write
1334
+ without a version undid, leaving the field as it was, has no row.
1335
+
1336
+ ### Net changes
1337
+
1338
+ `net_changes` folds change rows into one entry per record: its fields before
1339
+ the rows a block keeps, and its fields with only their changes made. This
1340
+ example keeps the rows with an author. A write saved without a version has
1341
+ none, so with `recorded_changes: true` it is left out:
1342
+
1343
+ <!-- executable:reference-net-changes -->
1344
+ ```ruby
1345
+ analysis = PaperTrailDiff.analyze(
1346
+ article, associations: [:comments], activity: true, snapshots: true,
1347
+ recorded_changes: true
1348
+ )
1349
+
1350
+ changes = analysis.net_changes { |row| row.source.whodunnit }
1351
+ ```
1352
+
1353
+ ```ruby
1354
+ change = changes.first
1355
+ change.root? # true for the article, which comes first
1356
+ change.record # a RecordReference, or nil for the root
1357
+ change.association_path # ["comments"], or [] for the root
1358
+ change.before # a RecordSnapshot of its fields, or nil if it was added
1359
+ change.after # its fields after the kept changes, or nil if removed
1360
+ change.diff # a Diff of before and after
1361
+ change.added? # before is nil
1362
+ change.removed? # after is nil
1363
+ change.sources # the ActivityBoundary of each kept change, each once
1364
+ report.net_changes { |row| ... } # { identity => changes }, keyed as change_rows
1365
+ ```
1366
+
1367
+ Without a block, every row is kept, and `before` and `after` are the record's
1368
+ states around all of its changes.
1369
+
1370
+ - `before` is the record's state when the step holding its first kept change
1371
+ began, so it includes the changes dropped before then.
1372
+ - `after` is `before` with only the kept changes made: each field takes the
1373
+ value of its last kept row. A record that appears takes the fields it
1374
+ appeared with. A record appears or disappears only through its own row,
1375
+ whose `attribute` is `nil`, so a block that keeps only some fields also
1376
+ leaves out the records added and removed.
1377
+ - A record whose kept changes leave it as it was is left out, as is one added
1378
+ and removed again.
1379
+ - The root comes first whenever anything is listed. When only the records it
1380
+ holds changed, its `before` and `after` are the same and its `diff` is
1381
+ empty.
1382
+ - `before` and `after` hold only the record's own fields; each record it holds
1383
+ has an entry of its own. A record has one entry for each association path,
1384
+ whichever records along the path hold it, so a reply moved from one comment
1385
+ to another is one entry.
1386
+ - The states come from the steps' snapshots, so `net_changes` raises
1387
+ `ConfigurationError` without `snapshots: true`, as it does without
1388
+ `activity: true`.
1389
+ - To leave out only the writes saved without a version, keep the other rows:
1390
+ `{ |row| !row.unversioned? }`.
1391
+
1237
1392
  ## JSON columns
1238
1393
 
1239
1394
  A `json` or `jsonb` column is compared as one value. `nested_changes` reports
@@ -1248,6 +1403,8 @@ PaperTrailDiff.nested_changes(from_value, to_value) # also accepts two values
1248
1403
  ```
1249
1404
 
1250
1405
  - Paths are arrays because a key may contain a dot.
1406
+ - `:a` and `"a"` are one key at any depth, inside arrays too, so a path's keys
1407
+ are strings. Values are reported as they were given.
1251
1408
  - Arrays are compared by their elements, not positions. An `ArrayChange` has
1252
1409
  `added`, `removed`, and `reordered?`, plus the whole `from` and `to`. Objects
1253
1410
  inside arrays are compared whole.
@@ -1295,6 +1452,10 @@ Other details:
1295
1452
  - Unlike PaperTrail's `version.changeset`, it never loads the record. That
1296
1453
  saves a query per version, and a deleted record's values keep their types,
1297
1454
  such as an enum's label rather than the integer PaperTrail stored.
1455
+ - Values read as a step's `diff` reads them, so a recorded value equals the
1456
+ state it produced: a time of day falls on 2000-01-01, and with
1457
+ [JSON history](#history-stored-as-json), times keep the digits history
1458
+ stores and binary and `serialize`d values read as JSON stored them.
1298
1459
 
1299
1460
  For activity steps, pass `recorded_changes: true` instead of loading the
1300
1461
  versions again. Each step's sources then carry what their versions recorded,
@@ -1360,7 +1521,8 @@ warning instead. `ok?` does not prove the history is complete.
1360
1521
 
1361
1522
  - **Single-table inheritance.** Results are keyed by the base class, as
1362
1523
  PaperTrail stores it: a `Book < Publication` is `["Publication", "12"]`. Use
1363
- `PaperTrailDiff::Endpoint.identity(record)` to build keys.
1524
+ `PaperTrailDiff::Endpoint.identity(record)` to build keys, or
1525
+ `analysis_for(record)` on the result of `analyze_scope` or `report`.
1364
1526
  - **Non-integer primary keys**, such as UUIDs, are supported, and so is a string
1365
1527
  `versions.item_id` column.
1366
1528
  - **Custom version classes** (`has_paper_trail versions: { class_name: }`) are
@@ -1388,6 +1550,19 @@ the gem raises `AmbiguousVersionOrderError` naming both instead of guessing.
1388
1550
  Timestamps stored to the second, as on a MySQL `datetime` column, make ties
1389
1551
  common. `diagnose` reports this as an error.
1390
1552
 
1553
+ A record's versions should also be dated in the order they were saved.
1554
+ PaperTrail dates an update with the record's `updated_at` unless the model
1555
+ sets `has_paper_trail synchronize_version_creation_timestamp: false`, so a save
1556
+ that sets `updated_at` itself, such as an import that keeps another system's
1557
+ times, a `touch(time:)`, or one made with timestamps off, can date its version
1558
+ before the one saved before it. Versions are read in time order, so such an update is read
1559
+ before the change it followed, and one dated before the record's `create`
1560
+ reads as the record deleted and created again. When IDs that count up show a
1561
+ record's versions dated out of the order they were saved in, `diagnose` warns
1562
+ with `inverted_version_order`. Set the option on models whose `updated_at`
1563
+ your application sets, and correct the stored `created_at` of versions
1564
+ already saved.
1565
+
1391
1566
  `created_at` comes from your application server's clock. A clock that jumps
1392
1567
  backwards, or servers whose clocks disagree, can record a later change with an
1393
1568
  earlier time. Keep server clocks synchronized.
@@ -1424,6 +1599,19 @@ precision was never recorded and cannot be reported. A `json` or `jsonb`
1424
1599
  column also returns times and dates as strings, which PaperTrail leaves as
1425
1600
  they are; the gem casts them back to the attribute's type.
1426
1601
 
1602
+ Two kinds of value come back as something their type cannot cast back:
1603
+
1604
+ - A `json` or `jsonb` `object` column stores a `serialize`d attribute as
1605
+ JSON writes it, so keys come back as strings, and dates, times, and symbols
1606
+ inside it as strings. The gem reads that attribute in this form on every
1607
+ side, the current record's too, so a value nothing changed is not reported
1608
+ as changed: `{ due: Date.new(2026, 11, 3) }` appears as
1609
+ `{ "due" => "2026-11-03" }`.
1610
+ - PaperTrail's JSON serializer stores a `binary` column as
1611
+ `{ "value" => bytes }`, and cannot store bytes that are not UTF-8. The gem
1612
+ reads the bytes. On PostgreSQL, PaperTrail cannot read such a `bytea` value
1613
+ back at all: its `reify` raises `TypeError`, and so does the gem.
1614
+
1427
1615
  ### Writing history in tests
1428
1616
 
1429
1617
  To give versions fixed times in a test, save them at those times with
@@ -1474,6 +1662,11 @@ Payloads contain counts, model names, ids, times, association paths, and
1474
1662
  options, never record data. To see the SQL for one call, subscribe to `sql.active_record`
1475
1663
  around it with `ActiveSupport::Notifications.subscribed`.
1476
1664
 
1665
+ `PaperTrailDiff.deprecator` warns when an option is deprecated; none is now. In
1666
+ a Rails app, register it with
1667
+ `Rails.application.deprecators[:paper_trail_diff] = PaperTrailDiff.deprecator`
1668
+ to handle its warnings as the app's own.
1669
+
1477
1670
  ## Errors
1478
1671
 
1479
1672
  All errors inherit from `PaperTrailDiff::Error`.
@@ -1481,13 +1674,11 @@ All errors inherit from `PaperTrailDiff::Error`.
1481
1674
  | Error | Raised when |
1482
1675
  | --- | --- |
1483
1676
  | `ConfigurationError` | An option is invalid |
1484
- | `UnsupportedBatchPathError` | No longer raised; kept until `allow_expensive:` is removed |
1485
1677
  | `InvalidEndpointError` | A record is unsaved, destroyed, or has unsaved changes, or `recorded_changes` is given something other than a version |
1486
- | `UnloadedAssociationError` | The deprecated `reload_live_endpoints: false`, and an association is not loaded |
1487
1678
  | `VersionMismatchError` | Two endpoints belong to different records |
1488
1679
  | `ReversedEndpointsError` | Two versions are given newest first |
1489
1680
  | `InvalidTimelineRangeError` | A range is invalid, for example `within:` with `from:`, or `:last` |
1490
- | `InvalidTimeRangeError` | `within:` is not a finite, time-ordered range |
1681
+ | `InvalidTimeRangeError` | `within:` is not a range with a beginning, in time order |
1491
1682
  | `IncompleteTimeRangeError` | A window's last change has no later version and the record has no saved row to read instead |
1492
1683
  | `AmbiguousVersionOrderError` | Versions cannot be ordered (see [version order](#version-order)) |
1493
1684
  | `BatchLimitExceededError` | More records are selected than `limit:` allows |
@@ -1510,21 +1701,47 @@ Results can only be as complete as the history PaperTrail and PT-AT recorded.
1510
1701
  [how PaperTrail stores history](#how-papertrail-stores-history).
1511
1702
  - Deleted versions, schema changes, and serializer changes can affect how old
1512
1703
  versions read.
1704
+ - With PaperTrail's default YAML serializer, PaperTrail 16 and 17 decode a
1705
+ `time` (time of day) column as `nil`, in `reify` and `changeset` alike,
1706
+ unless the column is time-zone aware, as a Rails app's are, and the time
1707
+ zone is UTC. The gem reads the time each version recorded, including in
1708
+ the records it passes to a callable `historical_filter:`, but your own
1709
+ calls to those PaperTrail methods still return `nil`. PaperTrail's JSON
1710
+ serializer, and SQL Server, whose adapter stores a time its own way, are
1711
+ not affected. Snapshots and diffs show every time of day on 2000-01-01 in
1712
+ its own zone, as Active Record 8.1 reads one. Active Record before 8.1
1713
+ reads a zone-aware time from the database on 2000-01-01 in UTC, so
1714
+ `record.opens_at` can show another date than the snapshot of that time.
1513
1715
  - Each call reads its history and live rows in one snapshot on PostgreSQL and
1514
1716
  MySQL (through mysql2 or trilogy), and on adapters built on them such as
1515
1717
  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).
1718
+ statements. On SQL Server it does so only when the database allows snapshot
1719
+ isolation, which you turn on with
1720
+ `ALTER DATABASE your_database SET ALLOW_SNAPSHOT_ISOLATION ON`; each call
1721
+ checks the setting first. The snapshot covers the database of the record's
1722
+ model and its versions; an associated model on another database is read
1723
+ outside it. A call made inside a transaction of your own keeps that
1724
+ transaction's isolation level. To make the whole call see one snapshot,
1725
+ start that transaction at `REPEATABLE READ` or stricter, or at `SNAPSHOT` on
1726
+ SQL Server. SQLite, and SQL Server without snapshot isolation, take no
1727
+ snapshot, so a commit during a call can appear in some of its statements
1728
+ and not others. A long call holds its snapshot until it ends: on PostgreSQL
1729
+ that can keep VACUUM from reclaiming old row versions, on MySQL it keeps
1730
+ undo history, and on SQL Server it keeps row versions in `tempdb`.
1731
+ - A savepoint that rolls back, or another transaction saving in the same tree
1732
+ at the same time, can split one transaction into several transaction groups;
1733
+ see [one step per transaction group](#one-step-per-transaction-group-transaction).
1734
+ - Two transactions that save in one record's tree at the same time, so that
1735
+ their versions interleave, are read in the order of their versions. A
1736
+ version reads the records its own transaction saved as they stood before
1737
+ the transaction, but a version of the other transaction reads them as they
1738
+ stood after the change saved before it. So a record that one transaction
1739
+ changed and changed back, such as a comment it created and deleted again,
1740
+ can appear in the other's steps, crediting that transaction with adding
1741
+ or removing it, and a window's starting state and diff can hold it too.
1742
+ Row locks keep the two from saving the same record, so this needs both to
1743
+ save different records of one tree within moments of each other. See
1744
+ [version order](#version-order).
1528
1745
  - HABTM membership history exists only where PT-AT recorded it in a
1529
1746
  transaction, and only for the root record without a scope: a scoped HABTM,
1530
1747
  or one below the root, raises `UnsupportedAssociationError`, and a transaction that another record with