paper_trail_diff 0.17.1 → 0.18.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 (215) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +648 -0
  3. data/QUICKSTART.md +12 -14
  4. data/README.md +32 -30
  5. data/docs/architecture.md +65 -29
  6. data/docs/performance.md +161 -46
  7. data/docs/reference.md +495 -394
  8. data/docs/testing.md +9 -15
  9. data/lib/paper_trail_diff/activity_belongs_to_event_applier.rb +42 -9
  10. data/lib/paper_trail_diff/activity_boundary.rb +15 -6
  11. data/lib/paper_trail_diff/activity_child_candidate_loader.rb +91 -18
  12. data/lib/paper_trail_diff/activity_collection_event_applier.rb +14 -15
  13. data/lib/paper_trail_diff/activity_collection_record_updater.rb +18 -8
  14. data/lib/paper_trail_diff/activity_collection_route_updater.rb +12 -25
  15. data/lib/paper_trail_diff/activity_event.rb +53 -34
  16. data/lib/paper_trail_diff/activity_event_record_normalizer.rb +12 -26
  17. data/lib/paper_trail_diff/activity_event_record_resolver.rb +45 -32
  18. data/lib/paper_trail_diff/activity_event_snapshot_refresher.rb +26 -33
  19. data/lib/paper_trail_diff/activity_history.rb +28 -34
  20. data/lib/paper_trail_diff/activity_relationship.rb +3 -26
  21. data/lib/paper_trail_diff/activity_root_snapshot_refresher.rb +14 -8
  22. data/lib/paper_trail_diff/activity_snapshot_delta.rb +2 -3
  23. data/lib/paper_trail_diff/activity_snapshot_sequence.rb +92 -25
  24. data/lib/paper_trail_diff/activity_timeline_builder.rb +128 -77
  25. data/lib/paper_trail_diff/activity_transaction_applier.rb +49 -0
  26. data/lib/paper_trail_diff/activity_tree_filter.rb +70 -57
  27. data/lib/paper_trail_diff/activity_tree_places.rb +76 -0
  28. data/lib/paper_trail_diff/activity_version_collector.rb +45 -32
  29. data/lib/paper_trail_diff/activity_view.rb +2 -0
  30. data/lib/paper_trail_diff/analysis.rb +6 -5
  31. data/lib/paper_trail_diff/analysis_batch.rb +21 -17
  32. data/lib/paper_trail_diff/association_activity_edge.rb +99 -85
  33. data/lib/paper_trail_diff/association_activity_selection.rb +46 -14
  34. data/lib/paper_trail_diff/association_discovery.rb +4 -4
  35. data/lib/paper_trail_diff/association_key.rb +10 -18
  36. data/lib/paper_trail_diff/association_traversal.rb +72 -92
  37. data/lib/paper_trail_diff/batch_boundary_resolver.rb +1 -7
  38. data/lib/paper_trail_diff/batch_preload.rb +2 -3
  39. data/lib/paper_trail_diff/batched_root_analyses.rb +60 -25
  40. data/lib/paper_trail_diff/batched_root_analyzer.rb +5 -5
  41. data/lib/paper_trail_diff/batched_root_versions.rb +7 -30
  42. data/lib/paper_trail_diff/branch_snapshot_refresher.rb +19 -14
  43. data/lib/paper_trail_diff/candidate_table.rb +160 -0
  44. data/lib/paper_trail_diff/change_attribution.rb +15 -23
  45. data/lib/paper_trail_diff/collection_identity_index.rb +68 -24
  46. data/lib/paper_trail_diff/collection_transition.rb +3 -3
  47. data/lib/paper_trail_diff/comparison_batch.rb +13 -6
  48. data/lib/paper_trail_diff/database_time.rb +85 -0
  49. data/lib/paper_trail_diff/deleted_analysis_batch.rb +22 -23
  50. data/lib/paper_trail_diff/deleted_root_filter.rb +10 -6
  51. data/lib/paper_trail_diff/diagnostics.rb +26 -86
  52. data/lib/paper_trail_diff/endpoint.rb +37 -5
  53. data/lib/paper_trail_diff/engine.rb +1 -1
  54. data/lib/paper_trail_diff/errors.rb +0 -6
  55. data/lib/paper_trail_diff/exact_column_type.rb +96 -0
  56. data/lib/paper_trail_diff/historical_snapshot_store.rb +88 -83
  57. data/lib/paper_trail_diff/instrumentation.rb +0 -8
  58. data/lib/paper_trail_diff/live_endpoint_batch_loader.rb +1 -4
  59. data/lib/paper_trail_diff/live_graph_collector.rb +1 -3
  60. data/lib/paper_trail_diff/nested_comparator.rb +42 -10
  61. data/lib/paper_trail_diff/paper_trail_adapter.rb +55 -98
  62. data/lib/paper_trail_diff/prepared_activity_index.rb +214 -182
  63. data/lib/paper_trail_diff/prepared_child_candidates.rb +13 -3
  64. data/lib/paper_trail_diff/prepared_edge_loader.rb +11 -49
  65. data/lib/paper_trail_diff/prepared_history.rb +27 -177
  66. data/lib/paper_trail_diff/prepared_history_loader.rb +39 -57
  67. data/lib/paper_trail_diff/prepared_record_index.rb +221 -147
  68. data/lib/paper_trail_diff/prepared_snapshot_builder.rb +47 -42
  69. data/lib/paper_trail_diff/prepared_state_association_reader.rb +85 -62
  70. data/lib/paper_trail_diff/recorded_changes.rb +34 -10
  71. data/lib/paper_trail_diff/recorded_owner.rb +67 -0
  72. data/lib/paper_trail_diff/root_version_selection.rb +6 -2
  73. data/lib/paper_trail_diff/scope_condition.rb +120 -80
  74. data/lib/paper_trail_diff/scope_ranking.rb +14 -32
  75. data/lib/paper_trail_diff/scoped_analysis.rb +11 -6
  76. data/lib/paper_trail_diff/scoped_analysis_builder.rb +17 -11
  77. data/lib/paper_trail_diff/scoped_root_selection.rb +91 -85
  78. data/lib/paper_trail_diff/selection_window.rb +31 -0
  79. data/lib/paper_trail_diff/snapshot.rb +60 -58
  80. data/lib/paper_trail_diff/snapshot_members.rb +115 -0
  81. data/lib/paper_trail_diff/snapshot_normalizer.rb +0 -11
  82. data/lib/paper_trail_diff/step.rb +1 -5
  83. data/lib/paper_trail_diff/stored_form.rb +146 -0
  84. data/lib/paper_trail_diff/stored_json_values.rb +8 -5
  85. data/lib/paper_trail_diff/stored_time_precision.rb +67 -33
  86. data/lib/paper_trail_diff/stored_values.rb +35 -3
  87. data/lib/paper_trail_diff/support.rb +185 -35
  88. data/lib/paper_trail_diff/time_of_day.rb +13 -2
  89. data/lib/paper_trail_diff/time_range.rb +85 -11
  90. data/lib/paper_trail_diff/time_version_range.rb +5 -1
  91. data/lib/paper_trail_diff/timeline_builder.rb +5 -11
  92. data/lib/paper_trail_diff/timeline_range.rb +56 -19
  93. data/lib/paper_trail_diff/timeline_snapshot_provider.rb +31 -7
  94. data/lib/paper_trail_diff/total_order.rb +19 -5
  95. data/lib/paper_trail_diff/transaction_anchors.rb +138 -0
  96. data/lib/paper_trail_diff/transaction_cut.rb +67 -327
  97. data/lib/paper_trail_diff/transaction_ends.rb +194 -0
  98. data/lib/paper_trail_diff/traversal_preparer.rb +12 -24
  99. data/lib/paper_trail_diff/{approximate_paths.rb → unreadable_paths.rb} +8 -9
  100. data/lib/paper_trail_diff/value_objects.rb +8 -6
  101. data/lib/paper_trail_diff/version.rb +1 -1
  102. data/lib/paper_trail_diff/version_association_candidate_scope.rb +12 -10
  103. data/lib/paper_trail_diff/version_boundary.rb +0 -29
  104. data/lib/paper_trail_diff/version_query.rb +49 -1
  105. data/lib/paper_trail_diff/version_scope_filter.rb +74 -5
  106. data/lib/paper_trail_diff/version_sequence_diagnostics.rb +4 -31
  107. data/lib/paper_trail_diff/version_table.rb +8 -1
  108. data/lib/paper_trail_diff.rb +56 -110
  109. data/sig/generated/paper_trail_diff/activity_belongs_to_event_applier.rbs +24 -2
  110. data/sig/generated/paper_trail_diff/activity_boundary.rbs +6 -0
  111. data/sig/generated/paper_trail_diff/activity_child_candidate_loader.rbs +46 -5
  112. data/sig/generated/paper_trail_diff/activity_collection_event_applier.rbs +7 -4
  113. data/sig/generated/paper_trail_diff/activity_collection_record_updater.rbs +11 -2
  114. data/sig/generated/paper_trail_diff/activity_collection_route_updater.rbs +8 -6
  115. data/sig/generated/paper_trail_diff/activity_event.rbs +27 -18
  116. data/sig/generated/paper_trail_diff/activity_event_record_normalizer.rbs +7 -11
  117. data/sig/generated/paper_trail_diff/activity_event_record_resolver.rbs +26 -8
  118. data/sig/generated/paper_trail_diff/activity_event_snapshot_refresher.rbs +10 -2
  119. data/sig/generated/paper_trail_diff/activity_history.rbs +23 -26
  120. data/sig/generated/paper_trail_diff/activity_relationship.rbs +0 -6
  121. data/sig/generated/paper_trail_diff/activity_root_snapshot_refresher.rbs +5 -0
  122. data/sig/generated/paper_trail_diff/activity_snapshot_sequence.rbs +53 -10
  123. data/sig/generated/paper_trail_diff/activity_timeline_builder.rbs +64 -38
  124. data/sig/generated/paper_trail_diff/activity_transaction_applier.rbs +28 -0
  125. data/sig/generated/paper_trail_diff/activity_tree_filter.rbs +46 -38
  126. data/sig/generated/paper_trail_diff/activity_tree_places.rbs +45 -0
  127. data/sig/generated/paper_trail_diff/activity_version_collector.rbs +21 -11
  128. data/sig/generated/paper_trail_diff/analysis.rbs +6 -5
  129. data/sig/generated/paper_trail_diff/analysis_batch.rbs +8 -6
  130. data/sig/generated/paper_trail_diff/association_activity_edge.rbs +58 -45
  131. data/sig/generated/paper_trail_diff/association_activity_selection.rbs +20 -3
  132. data/sig/generated/paper_trail_diff/association_discovery.rbs +2 -2
  133. data/sig/generated/paper_trail_diff/association_key.rbs +2 -11
  134. data/sig/generated/paper_trail_diff/association_traversal.rbs +43 -44
  135. data/sig/generated/paper_trail_diff/batch_boundary_resolver.rbs +0 -2
  136. data/sig/generated/paper_trail_diff/batched_root_analyses.rbs +40 -17
  137. data/sig/generated/paper_trail_diff/batched_root_analyzer.rbs +2 -2
  138. data/sig/generated/paper_trail_diff/batched_root_versions.rbs +2 -11
  139. data/sig/generated/paper_trail_diff/branch_snapshot_refresher.rbs +12 -8
  140. data/sig/generated/paper_trail_diff/candidate_table.rbs +97 -0
  141. data/sig/generated/paper_trail_diff/change_attribution.rbs +9 -16
  142. data/sig/generated/paper_trail_diff/collection_identity_index.rbs +33 -13
  143. data/sig/generated/paper_trail_diff/collection_transition.rbs +2 -2
  144. data/sig/generated/paper_trail_diff/comparison_batch.rbs +5 -0
  145. data/sig/generated/paper_trail_diff/database_time.rbs +48 -0
  146. data/sig/generated/paper_trail_diff/deleted_analysis_batch.rbs +13 -15
  147. data/sig/generated/paper_trail_diff/deleted_root_filter.rbs +4 -0
  148. data/sig/generated/paper_trail_diff/diagnostics.rbs +13 -31
  149. data/sig/generated/paper_trail_diff/endpoint.rbs +14 -1
  150. data/sig/generated/paper_trail_diff/errors.rbs +0 -8
  151. data/sig/generated/paper_trail_diff/exact_column_type.rbs +51 -0
  152. data/sig/generated/paper_trail_diff/historical_snapshot_store.rbs +51 -31
  153. data/sig/generated/paper_trail_diff/instrumentation.rbs +0 -5
  154. data/sig/generated/paper_trail_diff/nested_comparator.rbs +21 -0
  155. data/sig/generated/paper_trail_diff/paper_trail_adapter.rbs +18 -29
  156. data/sig/generated/paper_trail_diff/prepared_activity_index.rbs +138 -94
  157. data/sig/generated/paper_trail_diff/prepared_child_candidates.rbs +10 -2
  158. data/sig/generated/paper_trail_diff/prepared_edge_loader.rbs +4 -21
  159. data/sig/generated/paper_trail_diff/prepared_history.rbs +22 -79
  160. data/sig/generated/paper_trail_diff/prepared_history_loader.rbs +24 -32
  161. data/sig/generated/paper_trail_diff/prepared_record_index.rbs +137 -63
  162. data/sig/generated/paper_trail_diff/prepared_snapshot_builder.rbs +22 -13
  163. data/sig/generated/paper_trail_diff/prepared_state_association_reader.rbs +41 -28
  164. data/sig/generated/paper_trail_diff/recorded_changes.rbs +19 -3
  165. data/sig/generated/paper_trail_diff/recorded_owner.rbs +39 -0
  166. data/sig/generated/paper_trail_diff/root_version_selection.rbs +4 -1
  167. data/sig/generated/paper_trail_diff/scope_condition.rbs +65 -52
  168. data/sig/generated/paper_trail_diff/scope_ranking.rbs +10 -23
  169. data/sig/generated/paper_trail_diff/scoped_analysis.rbs +11 -6
  170. data/sig/generated/paper_trail_diff/scoped_analysis_builder.rbs +7 -2
  171. data/sig/generated/paper_trail_diff/scoped_root_selection.rbs +49 -43
  172. data/sig/generated/paper_trail_diff/selection_window.rbs +19 -0
  173. data/sig/generated/paper_trail_diff/snapshot.rbs +37 -38
  174. data/sig/generated/paper_trail_diff/snapshot_members.rbs +58 -0
  175. data/sig/generated/paper_trail_diff/snapshot_normalizer.rbs +0 -4
  176. data/sig/generated/paper_trail_diff/stored_form.rbs +63 -0
  177. data/sig/generated/paper_trail_diff/stored_json_values.rbs +0 -2
  178. data/sig/generated/paper_trail_diff/stored_time_precision.rbs +33 -20
  179. data/sig/generated/paper_trail_diff/stored_values.rbs +18 -2
  180. data/sig/generated/paper_trail_diff/support.rbs +96 -16
  181. data/sig/generated/paper_trail_diff/time_of_day.rbs +4 -0
  182. data/sig/generated/paper_trail_diff/time_range.rbs +49 -4
  183. data/sig/generated/paper_trail_diff/time_version_range.rbs +3 -0
  184. data/sig/generated/paper_trail_diff/timeline_builder.rbs +3 -6
  185. data/sig/generated/paper_trail_diff/timeline_range.rbs +29 -8
  186. data/sig/generated/paper_trail_diff/timeline_snapshot_provider.rbs +17 -4
  187. data/sig/generated/paper_trail_diff/total_order.rbs +9 -3
  188. data/sig/generated/paper_trail_diff/transaction_anchors.rbs +80 -0
  189. data/sig/generated/paper_trail_diff/transaction_cut.rbs +43 -176
  190. data/sig/generated/paper_trail_diff/transaction_ends.rbs +124 -0
  191. data/sig/generated/paper_trail_diff/traversal_preparer.rbs +6 -11
  192. data/sig/generated/paper_trail_diff/{approximate_paths.rbs → unreadable_paths.rbs} +6 -7
  193. data/sig/generated/paper_trail_diff/value_objects.rbs +4 -2
  194. data/sig/generated/paper_trail_diff/version_association_candidate_scope.rbs +11 -5
  195. data/sig/generated/paper_trail_diff/version_boundary.rbs +0 -14
  196. data/sig/generated/paper_trail_diff/version_query.rbs +26 -0
  197. data/sig/generated/paper_trail_diff/version_scope_filter.rbs +28 -2
  198. data/sig/generated/paper_trail_diff/version_sequence_diagnostics.rbs +4 -15
  199. data/sig/generated/paper_trail_diff/version_table.rbs +4 -0
  200. data/sig/generated/paper_trail_diff.rbs +22 -23
  201. metadata +28 -20
  202. data/lib/paper_trail_diff/activity_target_candidate_loader.rb +0 -123
  203. data/lib/paper_trail_diff/fallback_paths.rb +0 -35
  204. data/lib/paper_trail_diff/habtm_transaction_owners.rb +0 -70
  205. data/lib/paper_trail_diff/historical_association_reifier.rb +0 -161
  206. data/lib/paper_trail_diff/historical_filter.rb +0 -210
  207. data/lib/paper_trail_diff/own_window.rb +0 -35
  208. data/lib/paper_trail_diff/prepared_association_reifier.rb +0 -51
  209. data/sig/generated/paper_trail_diff/activity_target_candidate_loader.rbs +0 -74
  210. data/sig/generated/paper_trail_diff/fallback_paths.rbs +0 -22
  211. data/sig/generated/paper_trail_diff/habtm_transaction_owners.rbs +0 -41
  212. data/sig/generated/paper_trail_diff/historical_association_reifier.rbs +0 -58
  213. data/sig/generated/paper_trail_diff/historical_filter.rbs +0 -96
  214. data/sig/generated/paper_trail_diff/own_window.rbs +0 -22
  215. data/sig/generated/paper_trail_diff/prepared_association_reifier.rbs +0 -27
data/CHANGELOG.md CHANGED
@@ -3,6 +3,614 @@
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.18.0] - 2026-11-15
7
+
8
+ ### Breaking changes
9
+
10
+ - `report` with `associations:` now defaults to `group: :transaction`, so each
11
+ save of a record and its associated records is one activity step, with every
12
+ version of that save in `step.sources`. Pass `group: nil` for the previous
13
+ step per version. A `report` without `associations:`, and `analyze`,
14
+ `analyze_many`, and `analyze_scope`, are unchanged.
15
+
16
+ - `PaperTrailDiff.timeline` and `PaperTrailDiff.activity_timeline` are
17
+ removed. Each returned what `analyze` already returns alongside its diff,
18
+ from the same read:
19
+
20
+ ```ruby
21
+ PaperTrailDiff.timeline(article, **options)
22
+ # becomes
23
+ PaperTrailDiff.analyze(article, **options).timeline
24
+
25
+ PaperTrailDiff.activity_timeline(article, **options)
26
+ # becomes
27
+ PaperTrailDiff.analyze(article, activity: true, **options).activity_timeline
28
+ ```
29
+
30
+ The options are the same. The `activity_timeline.paper_trail_diff`
31
+ notification is replaced by `analyze.paper_trail_diff`, which every
32
+ `analyze` emits, with the same payload; its `step_count` counts the
33
+ activity timeline with `activity: true` and the root timeline without.
34
+ - `has_and_belongs_to_many` associations are no longer read. Naming one in
35
+ `associations:`, at the root or below it, raises
36
+ `UnsupportedAssociationError`, `association_paths` leaves it out, and
37
+ `supported_association_macros` no longer lists it. A join table has no
38
+ versions, so its history could only be read at the root's own
39
+ transaction-backed versions, never up to the current record, and not at
40
+ all with a scope or below the root. Replace it with a `has_many :through`
41
+ a join model that has `has_paper_trail`, as
42
+ [the reference shows](docs/reference.md#replacing-a-has_and_belongs_to_many):
43
+ add an `id` to the join table, and put `dependent: :destroy` on the
44
+ through association so that a member leaving saves a version. With it go
45
+ `UnsupportedLiveActivityError`, which only a `has_and_belongs_to_many`
46
+ raised, and the `habtm_transaction_shared`, `transaction_id_missing`, and
47
+ `transaction_id_column_missing` codes of `diagnose`.
48
+ - `allow_approximate:` is removed from every method, and no association is
49
+ read with PT-AT's reifier any more. An association whose scope history
50
+ cannot read, such as one that takes the owner or is written as SQL text,
51
+ raises `UnsupportedAssociationError` in every method that reads history:
52
+ PT-AT rebuilt it from its current members without checking the scope, so
53
+ a record that entered the scope since was reported as a member it was
54
+ not. Remove the path, or rewrite its scope as plain conditions on the
55
+ target's own columns. `diagnose` reports it as `unreadable_association`,
56
+ formerly `approximate_association`.
57
+ - `historical_filter:` and `max_filter_versions:` are removed from
58
+ `analyze_scope` and `report`, and `FilterLimitExceededError` with them.
59
+ Select records with the relation, which tests current values, and narrow
60
+ the changes reported with `version_scope:`.
61
+ - An association with a composite foreign key, or a `has_many :through`
62
+ that goes through one, raises `UnsupportedAssociationError`. It was read
63
+ with PT-AT's reifier, one record at a time and by timestamp alone.
64
+ - A polymorphic `belongs_to` whose record points at a class with a default
65
+ scope history cannot read raises `UnsupportedAssociationError` when that
66
+ record is read, instead of being read with PT-AT's reifier.
67
+ - The `ambiguous_association_boundary.paper_trail_diff` notification and
68
+ the `tied_version_timestamps` warning of `diagnose` are removed. Both
69
+ reported versions sharing a timestamp on a path PT-AT's reifier read;
70
+ every path is now read from loaded history, which orders such versions
71
+ by id.
72
+
73
+ ### Added
74
+
75
+ - `ScopedAnalysis#total`, returned by `analyze_scope` and `report`, counts
76
+ the existing records the relation selects before its own `limit` and
77
+ `offset`, so a page of changed records can show how many pages there
78
+ are. A paged relation takes one more statement for it.
79
+
80
+ ### Changed
81
+
82
+ - Activity reads what each version recorded unless `recorded_changes: false`
83
+ is passed; `recorded_changes: true` was needed before. Change rows
84
+ therefore credit each field's change to the version that recorded it, and
85
+ a write saved without a version, such as `update_columns`, gets a row of
86
+ its own with `unversioned?` true, instead of being credited to the
87
+ record's last version. `to_h(metadata: true)` on an activity step
88
+ includes each boundary's recorded changes.
89
+ - A transaction now takes effect where it saved its last version, in every
90
+ activity timeline. A window from `within:` or `since:` reports the
91
+ transactions that end inside it, each whole and under its own versions,
92
+ instead of moving its edges to where a transaction began. `analysis.window`
93
+ is therefore always the window you asked for, a step of a transaction that
94
+ began before the window can hold a version saved before it, and a
95
+ transaction group lists every version its transaction saved. The
96
+ `moved_window.paper_trail_diff` notification is gone, since no window
97
+ moves. Four things follow that you may notice:
98
+ - `timeline`, and a window without associations, report each version of the
99
+ record where it was saved, as before, but no longer move a window for a
100
+ transaction that also saved an associated record.
101
+ - `analyze_scope` and `report` select a record for a window by the versions
102
+ saved in it. A record whose transaction saves in the window and ends after
103
+ it is selected with nothing to report, and reported in the later window.
104
+ With associations, a window also selects by the versions that
105
+ transactions open at its start saved before it, since it reports those
106
+ transactions.
107
+ - `historical_filter:` reads each version where it was saved, so a record
108
+ whose transaction began before the window is checked from the state its
109
+ versions before the window left.
110
+ - With associations and `activity: true`, a window after a destroyed
111
+ record's last version reports nothing, or the deletion when the
112
+ transaction that destroyed the record ends inside the window, as
113
+ `analyze_scope` with `include_deleted: true` does. `analyze` and
114
+ `activity_timeline` raised `IncompleteTimeRangeError` there.
115
+ - A window with associations, with `activity: true` or without, runs one
116
+ more statement per version table, to find the transactions open at its
117
+ start, and no longer one per 250 records
118
+ for each edge, and `analyze_scope` and `report` run it once more to select
119
+ their records. A read with associations runs one more statement per 500
120
+ transactions its history holds, to read where each ends. See
121
+ [performance](docs/performance.md#what-still-grows).
122
+
123
+ - On SQL Server, a selection that reads its candidates in Ruby, as one with
124
+ `historical_filter:` or a version table whose `item_id` does not share the
125
+ key's type does, writes more than 500 of them to a temporary table once and
126
+ reads each page from it, instead of listing every id on every page. A
127
+ selection of 10,000 records took 0.6 s instead of 5 s, and one of 20,000
128
+ took 1.1 s instead of 30 s. A read that prevents writes, such as a replica
129
+ read through Rails' automatic role switching, still lists the ids, since
130
+ Active Record counts the table's statements as writes.
131
+
132
+ - An activity timeline no longer reads a whole association again for each
133
+ event of a transaction that saved more than one record in the tree, such
134
+ as two comments, or a comment and the article it touches. Each of the
135
+ transaction's versions is applied to the record it saved, as a version
136
+ alone in its transaction already was. One article with 1,000 comments and
137
+ 1,000 transactions that each edited two of them took 1.9 s instead of
138
+ 20.6 s, and 1.0 s instead of 18.8 s when each edited one comment and the
139
+ article. Results are unchanged.
140
+
141
+ - Replaying a `has_many` whose membership a version did not change no
142
+ longer sorts the collection again. A history of 3,200 comments edited
143
+ 3,200 times took 1.8 s instead of 11 s.
144
+
145
+ - Reads with associations do less work, with the same results:
146
+ - A belongs_to target created inside an activity range no longer reads
147
+ its owners' branch again from history unless an owner holds no target.
148
+ An article with 1,000 comments, each given a newly created reviewer,
149
+ took 0.97 s instead of 28.5 s for `comments.reviewer`.
150
+ - Activity finds each owner's belongs_to targets in the states its history
151
+ already loaded, and no longer runs two more statements per belongs_to
152
+ path to read PT-AT's rows and the live rows.
153
+ - A window finds where the transactions open at its start began once,
154
+ before reading, instead of reading the window and then reading it again
155
+ from there; `analyze_scope` and `report` share that one statement
156
+ across record selection and every record of the model. A report with
157
+ an unrelated open transaction ran 19 statements instead of 27.
158
+ - `include_deleted:` with a relation that has no conditions, on a model
159
+ that is not a subclass, asks the version table which destroys stored a
160
+ state instead of decoding each one. 2,000 deleted articles took 37 ms
161
+ instead of 753 ms.
162
+ - A state read from JSON history converts only the attributes whose type
163
+ needs it, listed once per model, and a value already frozen throughout
164
+ is no longer walked again to keep it immutable. A report over records
165
+ with 100-key JSON values took 2.0 s instead of 2.4 s.
166
+
167
+ - Association scopes, and ranges and orders in them, are read in Ruby only on
168
+ the SQL column types the gem lists for each of SQLite, PostgreSQL, MySQL, and
169
+ SQL Server, instead of on any column Active Record casts as an integer,
170
+ boolean, string, date, or time. A column of another type, or on another
171
+ adapter, is now refused unless you pass `allow_approximate: true`, like any
172
+ scope the gem cannot read. On SQL Server this leaves out a legacy `datetime` or `smalldatetime` key, which
173
+ rounds the times it stores.
174
+
175
+ - A `has_many` or `has_one` whose target declares no `belongs_to` on its
176
+ foreign key, and a `has_many :through` with such a part, now raises
177
+ `UnsupportedAssociationError` up front in every method. `diagnose` reports
178
+ it as `:unsupported_association` and `association_paths` leaves it out.
179
+ PT-AT records a record's owner on the record's own versions, once for each
180
+ `belongs_to` it declares, so with none nothing said a record that was
181
+ destroyed or moved away had been in the association: `compare`, timelines,
182
+ analyses and `report` showed the records the association holds now and
183
+ silently left out the ones that left. Declare the `belongs_to` on the
184
+ target to request the path. Versions saved before then recorded no owner,
185
+ so a record that left before then is still not reported.
186
+
187
+ - A version now reads alike wherever it is used: as an endpoint of
188
+ `compare`, and as the start or the end of a range. Each reads the records
189
+ around it as they stood before every transaction that had not ended where
190
+ the version's own took effect, as windows already did. A range starts
191
+ before its first version's transaction took effect and ends where its last
192
+ version's took effect: what another transaction saved before the start is
193
+ in the starting state if that transaction ended first, and reported in its
194
+ own step if it ended later. `compare` used to read a version by when the
195
+ records around it were saved, and `from:` used to count everything saved
196
+ before it as settled. So two ranges that meet at a version now report each
197
+ change once, as the range over both does, and a range from a version
198
+ inside a transaction no longer reports another transaction's finished
199
+ change as its own. A read with associations of a range of versions runs one
200
+ more statement per version table, to find a transaction open at its start,
201
+ and one more to find where its last version's transaction ended.
202
+ - A destroyed record's history ends where its destruction took effect. A
203
+ window holding the destruction reports it even when another transaction
204
+ that saved in the tree before it ends later, and a change another
205
+ transaction committed in the tree before the destroying one ended is
206
+ reported in the window it ended in.
207
+ - Activity on the record alone, without associations, reports each version
208
+ where it was saved, as `timeline` does and as the reference said. A window
209
+ edge between two saves of one transaction no longer loses the first.
210
+ - With associations, `version_scope:` selects a record in `analyze_scope`
211
+ and `report` whenever its activity reports something: a version selects it
212
+ when the filter keeps any version of its transaction, as activity keeps
213
+ whole transactions.
214
+ - Values are compared in the form the database stores them, as the history
215
+ stores them: times to the column's precision (to 1/300 s on a SQL Server
216
+ `datetime`), MySQL `float` to single precision, SQLite decimals as the
217
+ numbers SQLite returns, and fixed-width `char` columns padded or stripped as
218
+ the database does. A record saved with a value the database rounds no
219
+ longer shows a change against its own version. `historical_filter:`
220
+ compares its expected values in the same form.
221
+ - A time of day reads in `ActiveRecord.default_timezone`, as Active Record
222
+ stores it, including one stored as JSON text with a date and an offset.
223
+ - Errors are raised up front with the gem's own classes: `analyze_scope` and
224
+ `report` on a model without PaperTrail raise `InvalidEndpointError`, and a
225
+ version class without an `object` column `ConfigurationError`;
226
+ `compare_many` with an unknown boundary symbol raises
227
+ `InvalidTimelineRangeError`; `version_scope:` is checked where it is given,
228
+ and must take the relation as its one argument and return it narrowed, or
229
+ an array of its versions; `report(since:)` must be a time, date or string;
230
+ boolean options must be `true` or `false`; a root with unsaved changes is
231
+ refused; a version loaded without `object` is refused; and a relation that
232
+ selects columns without the primary key raises `ConfigurationError`.
233
+ - `historical_filter:` refuses an attribute named twice, as a string and a
234
+ symbol.
235
+ - `diagnose` raises `ReversedEndpointsError` for two versions given newest
236
+ first, as `compare` does, instead of reporting `ok?`.
237
+ - `within:` and `since:` refuse a string that names no real day, such as
238
+ `"12"` or `"2026-02-30"`, which `Time.zone.parse` read as noon today and
239
+ as 2 March.
240
+ - `max_filter_versions:` is checked whether or not `historical_filter:` is
241
+ given, and `recorded_changes` refuses a version loaded without its
242
+ `object_changes` column instead of answering that it recorded nothing.
243
+ - `unreachable` and `deleted` list integer ids by value, so 2 comes before 10.
244
+ - A has_many or has_one read with associations runs one more statement per
245
+ read, for the first versions of children made without a version (see
246
+ Fixed).
247
+ - History reads every association member from its recorded state, including
248
+ members of a model whose records need their own initialization (an
249
+ `after_initialize` callback, the attribute API, encryption, or a default
250
+ scope that assigns), which it instantiates once per state to read as a
251
+ record would hold it. Such a member's foreign keys and type columns are
252
+ read from its stored attributes, as Active Record loads its associations,
253
+ rather than through a reader method the model overrides.
254
+
255
+ ### Fixed
256
+
257
+ - On SQL Server, two `report` or `analyze_scope` calls with `associations:`
258
+ at the same time could deadlock in tempdb, and one raised
259
+ `ActiveRecord::DeadlockVictim`. The adapter read the candidate table's
260
+ columns from tempdb's catalog before each fill, which another call's
261
+ `DROP TABLE` held locks on. The table is now filled by statements the
262
+ adapter does not inspect, which also saves a catalog query per call.
263
+ - `report` and `analyze_scope` now select the record a child left when the
264
+ child's first version is the update that moved or detached it, such as a
265
+ row from before PaperTrail was installed. They read the old owner from
266
+ that version's stored state, as an activity analysis does, at every level
267
+ of a path and for the join rows of a `has_many :through`. Each `has_many`
268
+ or `has_one` edge on a path runs one more statement for each source of
269
+ changes below it.
270
+ - `report(associations: nil)` raises `ConfigurationError` naming the option,
271
+ as `analyze_scope` does, instead of `NoMethodError`.
272
+
273
+ - On SQL Server, `analyze_scope` and `report` with `associations:` select
274
+ their records from a temporary table that each candidate subquery fills
275
+ in turn, rather than from one statement joining the subqueries with `OR`,
276
+ which SQL Server planned to run the associations' subqueries once per
277
+ record. Selecting the orders changed in a week, among 1,600 with line
278
+ items, took 35 s, past the adapter's default 5 s timeout, and now takes
279
+ 0.4 s. A read that prevents writes still uses the single statement.
280
+ - A `belongs_to` whose class is an STI subclass no longer keeps a target
281
+ that an update retyped out of the subclass, or misses one retyped into
282
+ it. The change was reported at the next event, under that event's author.
283
+ - A polymorphic `belongs_to` with an id and no type reads as no target, as
284
+ Active Record reads it. History holding such a state raised
285
+ `UnsupportedAssociationError`.
286
+ - A date assigned to a datetime column, which Active Record leaves on the
287
+ instance when time zone aware attributes are off or `update_columns`
288
+ writes it, and PaperTrail stores from there, is read as midnight in
289
+ Active Record's default time zone, as the database keeps it. It was read
290
+ in `Time.zone`, or kept as a Date, so a version and the unchanged row
291
+ differed.
292
+ - The digits JSON history keeps for a time are read from what its writer
293
+ writes, a custom serializer that wraps PaperTrail's JSON one included.
294
+ They were assumed from Active Support's setting, so such a serializer, or
295
+ the legacy JSON format that writes whole seconds, read every unchanged
296
+ time as changed.
297
+ - An attribute a model declares without a column, such as a form field, is
298
+ left out of every diff, change row and snapshot, as no row holds it.
299
+ PaperTrail stores whatever the instance held for it. `historical_filter:`
300
+ refuses it as an unknown attribute, as `where` cannot name it.
301
+ - `historical_filter:` reads text or a date given for a datetime attribute
302
+ as `where` does, in the database's time zone. In any zone but UTC the two
303
+ selected different records. A value its attribute cannot take, such as a
304
+ Hash for a time, raises `ConfigurationError` instead of Active Record's
305
+ own error.
306
+ - `nested_changes` tells 1 from 1.0 inside arrays, as under a hash key and
307
+ as the attribute diff does.
308
+ - In `analyze_many` and `report`, a root that sits in another root's tree
309
+ is read there from the versions loaded for it. Its window's versions were
310
+ used instead, so the other root could report a record that joined it
311
+ only after the window, with the values it got then.
312
+ - `analyze_many` with associations and `activity: true` gives a root with
313
+ no versions an empty analysis over its whole history, as `analyze` does.
314
+ It raised `IncompleteTimeRangeError`.
315
+ - A `has_one :through` with no order reads, in history, the target Active
316
+ Record reads: that of its first join row by key on SQLite, PostgreSQL and
317
+ MySQL, and the target with the lowest id on SQL Server. It read the
318
+ lowest id everywhere. With two join rows, a diff from a past version to
319
+ the unchanged record reported it replaced.
320
+ - Activity on a path below an association to an STI subclass no longer
321
+ raises `UnknownAssociationError` when a child is retyped to its base class
322
+ and back.
323
+ - `report` and `analyze_scope` select a root whose change sits below a row
324
+ saved without versions, such as one from before PaperTrail, as `analyze`
325
+ reports it. Such a row holds its live key throughout.
326
+ - With `version_scope:`, an analysis ends after the last change the filter
327
+ keeps. A kept version of a record that had left the tree moved its end to
328
+ the next event, so its `diff` and `to_snapshot` held a change the filter
329
+ drops.
330
+ - A record moved by its own update is credited, in `change_rows`, to that
331
+ version. Two records moved in one transaction were both credited to the
332
+ last version the step read.
333
+ - `compare` from a version saved outside a transaction, as
334
+ `save_with_version` saves one, reads a transaction still open there as
335
+ open, as the range from that version does. Such a comparison runs one more
336
+ statement, to find where the history's transactions end.
337
+ - `report` and `analyze_scope` with associations no longer select a record
338
+ that changed only before the window while an unrelated transaction was
339
+ open across its start. Before the start, only the versions of the
340
+ transactions open there select a record. Such records came back with
341
+ nothing to report, counted toward `limit:`, and a destroyed one was listed
342
+ in `unreachable`.
343
+ - A transaction takes effect at its latest dated version, ids breaking a
344
+ tie, and is open across a window's start when it has versions dated on
345
+ both sides. A callback or nested save declared before `has_paper_trail`
346
+ saves other records' versions first and its own last, dated as its save
347
+ began. The transaction was placed at its last version by id, so another
348
+ transaction's edit of the same record was reported by no step, and two
349
+ windows cut between its dates reported its change in neither.
350
+ - Two ranges that meet at the destroy version of a record restored later
351
+ under its id report its removal once, in the range from the destroy. A
352
+ window over the record's earlier life credits the transaction that
353
+ restored it as a window that begins after the destruction does.
354
+
355
+ - Comparing a JSON array that holds a BigDecimal NaN or infinity no longer
356
+ raises `FloatDomainError`; it compares as a Float NaN or infinity did.
357
+ - An activity timeline no longer leaves a record as it was at one of two
358
+ places a path reaches it. An article read with
359
+ `associations: ["author.articles"]` is the root and one of its author's
360
+ articles; a comment read with `["article.comments"]` is one of its
361
+ article's comments; under `["articles.comments.article"]` an article is a
362
+ member of a collection and the target of a `belongs_to` below it; and a
363
+ polymorphic `belongs_to` can point back at any record in the tree. An
364
+ event on such a record changed it at one place only. The step and any
365
+ window around it then missed the change at the other, and the next event
366
+ in that branch reported it, credited to its own author in `change_rows`.
367
+ Such an event now has the branches that hold the record read again, or
368
+ the whole snapshot for the root, which costs the size of what is read. See
369
+ [performance](docs/performance.md#what-still-grows). `compare` and
370
+ `timeline` were not affected.
371
+
372
+ - `activity_timeline`, `analyze` with `activity: true`, `analyze_many`, and
373
+ `report` no longer raise `ConfigurationError` ("prepared activity graph is
374
+ missing ...") for a path that continues past a `belongs_to` when no record
375
+ read had one, such as `associations: ["article.author"]` on a comment
376
+ created without an article. They read the record with nothing on that path.
377
+
378
+ - An activity timeline no longer reads a whole collection again for each event
379
+ that put a record into it or took one out. A snapshot kept a table of its
380
+ records' positions, and built it again and checked their order again
381
+ whenever its members changed, so a replay's time grew with its events times
382
+ the size of the collection: 3,000 comments created one at a time on one
383
+ article took 19.2 s to replay and now take 3.6 s, and 1,000 took 2.1 s and
384
+ now take 0.7 s. Edits were not affected. A record is now found by searching
385
+ the order a snapshot holds its records in. See
386
+ [performance](docs/performance.md#what-still-grows).
387
+
388
+ - A `has_many` or `has_one` whose owners use single-table inheritance no
389
+ longer loses the records that left it when the target's `belongs_to` names
390
+ another class of the owners' table than the owner's own or its base class.
391
+ With `Doc`, `Report < Doc` and `AnnualReport < Report`, and notes that
392
+ `belongs_to :report`, a note destroyed or moved away from an annual report
393
+ was missing from `compare`, timelines and analyses, and when `Doc` declared
394
+ the association, `analyze_scope` and `report` did not select a record whose
395
+ only change was such a note. PT-AT records the class the `belongs_to` names,
396
+ and the gem looked for the owner's class and its base class only.
397
+
398
+ - `analyze_scope` and `report` over a window no longer slow down with the size
399
+ of the model's table on PostgreSQL. The statement that finds the records
400
+ changed in the window and deleted since asked with `NOT IN (SELECT id ...)`,
401
+ which PostgreSQL does not plan as an anti-join: it reads every id of the
402
+ table, and reads them again for each version in the window once they
403
+ outgrow `work_mem`. With 2 million articles and 2,000 of them edited in the
404
+ window, a `report` took 16 s and now takes 1.4 s, and with 500,000 it took
405
+ 11 s and now takes 1.5 s. That statement, and the one like it for records
406
+ selected by their associations, now asks with `NOT EXISTS`. Results are
407
+ unchanged. See [performance](docs/performance.md#database-indexes).
408
+
409
+ - An activity timeline over a tree no longer slows down with the tree's size
410
+ times its events. Each event of an associated record is checked against the
411
+ snapshots around its transaction, to leave out a record that was outside
412
+ the tree, and each check looked through every collection of the snapshot.
413
+ The records each snapshot holds are now kept up from one snapshot to the
414
+ next, by what its event changed. 2,000 replies created one at a time under
415
+ 2,000 comments of one article took 10.4 s to replay and now take 1.4 s, and
416
+ 3,000 comments created one at a time took 3.6 s and now take 1.8 s. A window
417
+ with `activity: true` on a record not saved since the window, with 2,000
418
+ comments created after it, took 1.8 s and now takes 0.8 s. Results are
419
+ unchanged.
420
+
421
+ - A range that ended in the past no longer slows down with the children its
422
+ records have gained since. A `has_many` or `has_one` read every child that
423
+ was ever its owner's from the range's start onward, with each child's row
424
+ and versions, and only then left out those created after the range. With
425
+ 2,000 comments added to an article after the range, a `compare` of two of
426
+ its versions took 132 ms and now takes 10 ms, as with none, and `timeline`
427
+ between them, or `analyze` over a window that a later version of the article
428
+ ends, went from about 160 ms to about 12 ms. A child is left out when its
429
+ first version is a `create` saved after the range's end, so one whose
430
+ creation was never recorded is still read. Where `item_id` is not stored as
431
+ the child's key is, as with a string `item_id` and integer keys, the child's
432
+ current row is still read, though not its versions. Results are unchanged.
433
+
434
+ - An association scope that negates an empty list along with another
435
+ condition, such as `where.not(status: [], score: 1)`, now reads a record
436
+ whose `status` is NULL as the database does. Active Record writes the empty
437
+ list as a condition that is always false, so the negation is true for every
438
+ record, but history read it against a NULL as unknown and left the record
439
+ out, reporting a current member as added.
440
+
441
+ - `recorded_changes`, and change rows with `recorded_changes: true`, now cast
442
+ the values a `json` or `jsonb` `object_changes` column stores. PaperTrail
443
+ leaves such a column's dates, times, and decimals as the strings JSON gives
444
+ back, and the gem returned them that way: a recorded change no longer
445
+ equalled the state it produced, so one change became three change rows, two
446
+ of them credited to writes without a version, and a model with a `time`
447
+ column raised `NoMethodError`.
448
+
449
+ - A report with `historical_filter:` can be paged with the relation, as the
450
+ reference says. A relation with a `limit` now reads its candidates in its
451
+ own order and stops matching when the page is full, and only the page
452
+ counts toward `limit:`. Before, every match counted, so
453
+ `Article.order(:id).limit(20)` with `limit: 20` raised
454
+ `BatchLimitExceededError` whenever more than 20 records matched, and the
455
+ history of every match was read to return one page.
456
+
457
+ - A hash `historical_filter:` now works on a model with an encrypted
458
+ attribute, and on a version that names a column since dropped. It raised
459
+ "cannot read recorded attributes directly"; such a version is now rebuilt
460
+ as PaperTrail rebuilds it and compared by its decrypted, cast values.
461
+
462
+ - A hash `historical_filter:` with a list or a range as a value, such as
463
+ `{ status: %i[published archived] }`, raises `ConfigurationError` instead
464
+ of matching nothing. `where` would match any of the values; a filter
465
+ compares one, so use a callable for several. A list is still the value of
466
+ an attribute that holds one, such as a serialized or an array column.
467
+
468
+ - `include_deleted: true`, and a readable association scope, accept an
469
+ equality or a list on a date or a time column, such as `where(due: date)`,
470
+ wherever they already accepted a range on it. Before, the relation was
471
+ refused, or the scope read by its slower path.
472
+
473
+ - `version_scope:` raises `ConfigurationError` when the callable returns
474
+ anything but a relation on the version class it was given. A callable that
475
+ returned another model's relation, such as `Document.all`, silently
476
+ selected the versions whose ids equalled that model's ids.
477
+
478
+ - A relation ordered by another table's key written in quotes, such as
479
+ `order('accounts."id"')`, is no longer read as ordered by the model's own
480
+ key, so its pages get the tie-breaker they need.
481
+
482
+ - `recorded_changes(version)` leaves out a name the model no longer has,
483
+ such as a column dropped since, as diffs, timelines, and change rows do.
484
+
485
+ - `nested_changes` compares two arrays in time proportional to their length.
486
+ Arrays of objects took time proportional to its square: 16,000 objects
487
+ took 53 s and now take 0.2 s. Results are unchanged.
488
+
489
+ - Without `activity:`, `analyze`, `analyze_many`, `analyze_scope` and
490
+ `timeline` with associations could report an associated record's change
491
+ backwards, and then again forwards, when two transactions interleaved: one
492
+ edited a comment, another saved the article, and the first then saved the
493
+ article too. The comment read as edited at the other transaction's version
494
+ and as not yet edited at its own. Whether it did depended on how far back
495
+ the history read went, so `analyze_many` could disagree with `analyze` for
496
+ the same record. These reads now place each associated record's change
497
+ where its transaction ends, as activity does, and report it once. They
498
+ run the statements activity runs for that: one per version table for a
499
+ window, to find the transactions open at its start, and one per 500
500
+ transactions the history holds.
501
+ - `analyze_many`, `analyze_scope` and `report` without a window could read
502
+ a record's history differently from `analyze`, when a transaction changed
503
+ an associated record before the record's first version and ended after it,
504
+ such as one that renamed an author and later saved an article created in
505
+ between. The batch reported the rename as a change in the article's
506
+ history, once backwards and once forwards, because its history also held
507
+ an older record's versions. A history without a window now
508
+ begins at the record's first version, however it is read.
509
+ - Two transactions that saved in one record's tree at the same time
510
+ interleave their versions, and activity timelines read them wrongly in four
511
+ ways, all fixed by reading each transaction where it ends:
512
+ - A change could be credited to the other transaction's author, such as a
513
+ comment one transaction removed reported under the one that saved
514
+ meanwhile.
515
+ - Back-to-back windows that met inside such a transaction could report one
516
+ of its changes in neither window.
517
+ - Back-to-back windows could report a change in both, when a transaction
518
+ saved an associated record before the record itself, around another
519
+ transaction.
520
+ - A window that started inside a transaction credited an edit the
521
+ transaction saved before the window to the version of another record.
522
+ - A transaction that went on to save a record outside the requested paths,
523
+ such as a comment moved to another article, was placed at its last version
524
+ on them, which depends on where a window starts. Back-to-back windows could
525
+ then report one of its changes in neither. Where a transaction ends is now
526
+ read from its version table, whatever records it saved.
527
+ - A range that ended while a transaction saving in the tree was still open
528
+ read the records it had saved as changed. They now read as they stood
529
+ before it, since it had not ended.
530
+ - A window that started while a transaction was open read a record that
531
+ transaction had already saved as changed, when the transaction saved
532
+ nothing else of the tree inside the window. Its snapshot then disagreed
533
+ with the one the window before it ended on.
534
+ - Without `paper_trail-association_tracking` loaded, asking for an
535
+ association between two versioned models raised `NoMethodError`. Reading
536
+ its history now raises `AssociationTrackingUnavailableError`, as
537
+ documented, and `association_paths` and a comparison of two current
538
+ records work again.
539
+ - On PostgreSQL, an association scope with a condition on a `character(n)`
540
+ column is no longer read as plain conditions. PostgreSQL pads such values
541
+ and compares them without the padding, which Ruby does not, so a member
542
+ could read as leaving and rejoining the association. It is now refused
543
+ unless you pass `allow_approximate: true`, as a `citext` condition is.
544
+ - A `within:` window whose first later version tied with another version
545
+ of the same record, with ids that cannot order them (such as UUIDs),
546
+ ended in whichever of the two had the lower id. Such a tie now raises
547
+ `AmbiguousVersionOrderError`, as one inside the window already did.
548
+ - `analyze_scope` and `report` raise `ConfigurationError` for a relation
549
+ grouped by anything but its primary key that has no order of its own,
550
+ instead of sending a query the database rejects.
551
+ - A `has_one` that two records point at, with no order of its own, now reads
552
+ the one with the lowest primary key at every point in history, as Active
553
+ Record reads it on SQLite, MySQL and SQL Server. History read another one,
554
+ so comparing the last version with the current record reported the
555
+ relationship changing when nothing had.
556
+ - A `within:` edge finer than a microsecond is cut to the microsecond, as
557
+ adapters write it into SQL. A version saved in the edge's microsecond was
558
+ in `timeline`'s window but not in `activity_timeline`'s or
559
+ `analyze_many`'s.
560
+ - A `within:` edge is cut to the digits the version table's `created_at`
561
+ keeps, as the database compares it. On a column that keeps whole seconds,
562
+ as a MySQL `datetime` without a precision does, an edge with a fraction
563
+ put a version saved in that second inside the window for one method and
564
+ outside it for another.
565
+ - With more than one version table, a `within:` window no longer reads an
566
+ unrelated transaction as one that crosses its edge. PaperTrail numbers a
567
+ transaction by the id of its first version in whichever table that was, so
568
+ two transactions can share a number in one table, and a window that started
569
+ or ended before the later one moved to where the earlier one began,
570
+ which could be years before: a window could take in changes from long
571
+ before it, or come back empty. `analyze_scope` selected records by the
572
+ earlier transaction too. Transactions of one number are now told apart
573
+ by the versions they began with.
574
+ - A transaction of associated records that moved a record away from the
575
+ root before a window's start, and after it saved only records under the
576
+ one it moved, was reported in neither window: `activity_timeline` and an
577
+ `activity: true` analysis left its changes out.
578
+ - A window that started inside a transaction which began at the instant
579
+ another saved its last versions, as it can where `created_at` keeps whole
580
+ seconds or two versions share a time, cut the earlier transaction in two,
581
+ and part of its change surfaced in the later transaction's step.
582
+ - A comment one transaction created and deleted again while another saved in
583
+ the same tree is no longer reported as added or removed in the other's
584
+ steps, nor held in a window's starting state or diff.
585
+ - Two activity windows that meet inside a transaction no longer both report
586
+ it when the transaction moved a `has_many :through` join row onto the
587
+ root and destroyed it after the edge, such as a card moved to a board and
588
+ destroyed while its assignee was renamed. The window after the edge judged
589
+ the join row by its destroy alone, where it was on the root, so the change
590
+ appeared in both halves. A join row's versions in one transaction are now
591
+ judged by the whole transaction, wherever a window's edge falls in it.
592
+ - A destroyed record read without `within:` ends at its last version,
593
+ instead of raising.
594
+ - A NaN stored on both sides no longer reads as a change, in attributes,
595
+ nested JSON, arrays and recorded changes.
596
+ - `recorded_changes: true` keeps a serialized hash's symbol keys, reads
597
+ versions of a custom class without `object_changes`, and leaves out a
598
+ change whose two sides are the same.
599
+ - `analyze_many` and `analyze_scope` read a root that stands in another
600
+ root's tree as `analyze` does when the roots are of two STI classes of one
601
+ table, and a windowed batch reads such a root at its state in the window,
602
+ not from its current row.
603
+ - A `belongs_to` naming an STI subclass reads no row of a sibling class, and
604
+ an `as:` child is a member only while its type is its owner's polymorphic
605
+ name, as Active Record reads them.
606
+ - A `has_many :through` with `source_type:` and a path below it descends only
607
+ into targets of that type, instead of raising for another type's.
608
+ - A `has_many :through` join row created and destroyed in one transaction is
609
+ no longer read as present, in another transaction's step or at the end of
610
+ a window.
611
+ - The end boundary of a window's last step no longer depends on which other
612
+ roots are in a batch.
613
+
6
614
  ## [0.17.1] - 2026-11-07
7
615
 
8
616
  ### Fixed
@@ -17,6 +625,46 @@ project follows [Semantic Versioning](https://semver.org/).
17
625
  window's start, such as a comment moved to another parent and then saved
18
626
  again or destroyed. The window before it leaves such a change to this
19
627
  one, so a window split there no longer loses it from both halves.
628
+ - A serialized attribute that changed between values Ruby's `==` calls
629
+ equal, such as a Time to the matching string or `1` to `1.0`, alone or
630
+ nested, is reported as a change. Values must now be equal both ways, and a
631
+ Float differs from the Integer it equals.
632
+ - `recorded_changes` types an STI subclass's version with the subclass's
633
+ attribute types, as a step's states do, so an enum or a retyped column of
634
+ the subclass reads as its value.
635
+ - A relation passed to `analyze_scope`, `report` or `include_deleted:` is
636
+ read beside parts that choose no rows, such as `distinct`, `select`,
637
+ `order`, `unscope`, `rewhere`, `lock`, `annotate`, `preload` or
638
+ `create_with`, instead of being refused. Joins, `from`, `group`,
639
+ `having` and `with` are still refused.
640
+ - `include_deleted:` refuses a condition on a column `has_paper_trail skip:`
641
+ leaves out of history, as `historical_filter:` does, instead of comparing
642
+ it with the column's default; and, on SQLite, a `Date` bound on a datetime
643
+ column, which SQLite compares as text, instead of reading it as midnight.
644
+ - `historical_filter:` matches nothing for a value the attribute's type
645
+ cannot write, such as `''` or `'abc'` for an integer or one out of its
646
+ range, as `where` does.
647
+ - `historical_filter:`, with a hash or a callable, reads the live row as
648
+ history keeps it, so an unchanged value matches alike whether a version or
649
+ the live row closes the window, under JSON history too. A relation with
650
+ `limit(0)` selects nothing with a filter, as without one.
651
+ - A child made without a version, whose first version moved it to another
652
+ owner, is under the owner it left until then: PT-AT names only the owner a
653
+ version saved, so the one before is read from the first version's state.
654
+ - A `has_one :through` over a `has_one` reads every row of its parts, as its
655
+ one query joins them, rather than only the has_one's first row: a project
656
+ whose first pin has no user now has the user of the next, as Active Record
657
+ returns.
658
+ - A through's join row whose transaction changed nothing the tree shows,
659
+ such as a pin that names no user, or a member's own versions under a
660
+ through of a through before the member joined, is no longer a step of the
661
+ root. A member's versions under such a through are steps only where a
662
+ membership of the root named the member, and a record that is a join row
663
+ under one association is judged as any member under the others.
664
+ - `compare` between two versions of a record whose STI class changed
665
+ between them reads both from one history, so a change below the record in
666
+ between, such as a note moved to a member, is reported. It was read from
667
+ two histories, each beginning at its own version, and was missed.
20
668
 
21
669
  ## [0.17.0] - 2026-11-04
22
670