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