paper_trail_diff 0.16.0 → 0.17.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (206) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +581 -1
  3. data/README.md +42 -7
  4. data/docs/architecture.md +7 -5
  5. data/docs/performance.md +86 -38
  6. data/docs/reference.md +309 -92
  7. data/docs/testing.md +240 -32
  8. data/lib/paper_trail_diff/activity_belongs_to_event_applier.rb +2 -16
  9. data/lib/paper_trail_diff/activity_boundary.rb +55 -34
  10. data/lib/paper_trail_diff/activity_child_candidate_loader.rb +46 -57
  11. data/lib/paper_trail_diff/activity_collection_event_applier.rb +3 -13
  12. data/lib/paper_trail_diff/activity_collection_route_updater.rb +1 -1
  13. data/lib/paper_trail_diff/activity_event.rb +33 -21
  14. data/lib/paper_trail_diff/activity_event_record_resolver.rb +16 -116
  15. data/lib/paper_trail_diff/activity_event_route_finder.rb +29 -29
  16. data/lib/paper_trail_diff/activity_event_snapshot_refresher.rb +2 -7
  17. data/lib/paper_trail_diff/activity_history.rb +90 -49
  18. data/lib/paper_trail_diff/activity_range.rb +9 -35
  19. data/lib/paper_trail_diff/activity_root_snapshot_refresher.rb +74 -40
  20. data/lib/paper_trail_diff/activity_root_steps.rb +10 -13
  21. data/lib/paper_trail_diff/activity_scope_filter.rb +77 -0
  22. data/lib/paper_trail_diff/activity_snapshot_delta.rb +12 -15
  23. data/lib/paper_trail_diff/activity_snapshot_sequence.rb +37 -15
  24. data/lib/paper_trail_diff/activity_target_candidate_loader.rb +35 -43
  25. data/lib/paper_trail_diff/activity_timeline_builder.rb +194 -249
  26. data/lib/paper_trail_diff/activity_transaction_grouper.rb +3 -1
  27. data/lib/paper_trail_diff/activity_tree_filter.rb +54 -13
  28. data/lib/paper_trail_diff/activity_version_collector.rb +72 -138
  29. data/lib/paper_trail_diff/activity_view.rb +22 -11
  30. data/lib/paper_trail_diff/analysis.rb +19 -5
  31. data/lib/paper_trail_diff/analysis_batch.rb +16 -58
  32. data/lib/paper_trail_diff/approximate_paths.rb +4 -8
  33. data/lib/paper_trail_diff/association_activity_edge.rb +5 -24
  34. data/lib/paper_trail_diff/association_activity_selection.rb +10 -18
  35. data/lib/paper_trail_diff/association_discovery.rb +1 -6
  36. data/lib/paper_trail_diff/association_key.rb +9 -6
  37. data/lib/paper_trail_diff/association_traversal.rb +49 -6
  38. data/lib/paper_trail_diff/batch_boundary_resolver.rb +33 -42
  39. data/lib/paper_trail_diff/batch_preload.rb +2 -12
  40. data/lib/paper_trail_diff/batched_root_analyses.rb +72 -0
  41. data/lib/paper_trail_diff/batched_root_analyzer.rb +16 -14
  42. data/lib/paper_trail_diff/batched_root_versions.rb +25 -20
  43. data/lib/paper_trail_diff/branch_snapshot_refresher.rb +27 -31
  44. data/lib/paper_trail_diff/change_attribution.rb +329 -0
  45. data/lib/paper_trail_diff/change_row.rb +30 -10
  46. data/lib/paper_trail_diff/comparison_batch.rb +3 -4
  47. data/lib/paper_trail_diff/configuration.rb +1 -1
  48. data/lib/paper_trail_diff/deleted_analysis_batch.rb +22 -37
  49. data/lib/paper_trail_diff/deleted_root_filter.rb +3 -6
  50. data/lib/paper_trail_diff/deprecation.rb +4 -43
  51. data/lib/paper_trail_diff/diagnostics.rb +1 -2
  52. data/lib/paper_trail_diff/direct_record_state_loader.rb +8 -1
  53. data/lib/paper_trail_diff/endpoint.rb +78 -44
  54. data/lib/paper_trail_diff/errors.rb +2 -9
  55. data/lib/paper_trail_diff/fallback_paths.rb +2 -5
  56. data/lib/paper_trail_diff/habtm_transaction_owners.rb +5 -3
  57. data/lib/paper_trail_diff/historical_association_reifier.rb +3 -1
  58. data/lib/paper_trail_diff/historical_filter.rb +40 -15
  59. data/lib/paper_trail_diff/historical_snapshot_store.rb +80 -38
  60. data/lib/paper_trail_diff/instrumentation.rb +0 -8
  61. data/lib/paper_trail_diff/live_endpoint_batch_loader.rb +11 -7
  62. data/lib/paper_trail_diff/live_endpoint_provider.rb +7 -23
  63. data/lib/paper_trail_diff/live_graph_collector.rb +3 -3
  64. data/lib/paper_trail_diff/nested_comparator.rb +46 -19
  65. data/lib/paper_trail_diff/net_change.rb +276 -0
  66. data/lib/paper_trail_diff/own_window.rb +35 -0
  67. data/lib/paper_trail_diff/paper_trail_adapter.rb +40 -45
  68. data/lib/paper_trail_diff/prepared_activity_index.rb +197 -45
  69. data/lib/paper_trail_diff/prepared_child_candidates.rb +58 -0
  70. data/lib/paper_trail_diff/prepared_edge_loader.rb +43 -107
  71. data/lib/paper_trail_diff/prepared_history.rb +20 -31
  72. data/lib/paper_trail_diff/prepared_history_loader.rb +46 -9
  73. data/lib/paper_trail_diff/prepared_record_index.rb +137 -47
  74. data/lib/paper_trail_diff/prepared_snapshot_builder.rb +16 -0
  75. data/lib/paper_trail_diff/prepared_state_association_reader.rb +17 -19
  76. data/lib/paper_trail_diff/read_snapshot.rb +41 -19
  77. data/lib/paper_trail_diff/recorded_changes.rb +10 -11
  78. data/lib/paper_trail_diff/recorded_changes_reader.rb +60 -0
  79. data/lib/paper_trail_diff/recorded_class.rb +14 -19
  80. data/lib/paper_trail_diff/recorded_columns.rb +33 -0
  81. data/lib/paper_trail_diff/root_version_plan.rb +20 -22
  82. data/lib/paper_trail_diff/root_version_selection.rb +39 -29
  83. data/lib/paper_trail_diff/scope_condition.rb +7 -17
  84. data/lib/paper_trail_diff/scope_ranking.rb +16 -22
  85. data/lib/paper_trail_diff/scoped_analysis.rb +27 -4
  86. data/lib/paper_trail_diff/scoped_analysis_builder.rb +4 -3
  87. data/lib/paper_trail_diff/scoped_root_selection.rb +60 -41
  88. data/lib/paper_trail_diff/snapshot_normalizer.rb +18 -3
  89. data/lib/paper_trail_diff/stored_json_values.rb +52 -0
  90. data/lib/paper_trail_diff/stored_time_precision.rb +30 -18
  91. data/lib/paper_trail_diff/stored_values.rb +20 -0
  92. data/lib/paper_trail_diff/support.rb +185 -35
  93. data/lib/paper_trail_diff/time_of_day.rb +39 -0
  94. data/lib/paper_trail_diff/time_range.rb +37 -20
  95. data/lib/paper_trail_diff/time_version_range.rb +5 -10
  96. data/lib/paper_trail_diff/timeline_builder.rb +3 -3
  97. data/lib/paper_trail_diff/timeline_range.rb +18 -12
  98. data/lib/paper_trail_diff/timeline_snapshot_provider.rb +1 -1
  99. data/lib/paper_trail_diff/total_order.rb +55 -0
  100. data/lib/paper_trail_diff/transaction_cut.rb +192 -91
  101. data/lib/paper_trail_diff/traversal_preparer.rb +5 -8
  102. data/lib/paper_trail_diff/value_objects.rb +8 -4
  103. data/lib/paper_trail_diff/version.rb +1 -1
  104. data/lib/paper_trail_diff/version_association_candidate_scope.rb +27 -16
  105. data/lib/paper_trail_diff/version_boundary.rb +37 -21
  106. data/lib/paper_trail_diff/version_query.rb +25 -25
  107. data/lib/paper_trail_diff/version_range.rb +12 -16
  108. data/lib/paper_trail_diff/version_sequence_diagnostics.rb +32 -0
  109. data/lib/paper_trail_diff/version_table.rb +12 -8
  110. data/lib/paper_trail_diff.rb +28 -42
  111. data/sig/generated/paper_trail_diff/activity_belongs_to_event_applier.rbs +0 -8
  112. data/sig/generated/paper_trail_diff/activity_boundary.rbs +39 -17
  113. data/sig/generated/paper_trail_diff/activity_child_candidate_loader.rbs +19 -22
  114. data/sig/generated/paper_trail_diff/activity_collection_event_applier.rbs +0 -5
  115. data/sig/generated/paper_trail_diff/activity_event.rbs +25 -9
  116. data/sig/generated/paper_trail_diff/activity_event_record_resolver.rbs +6 -34
  117. data/sig/generated/paper_trail_diff/activity_event_route_finder.rbs +11 -4
  118. data/sig/generated/paper_trail_diff/activity_event_snapshot_refresher.rbs +0 -3
  119. data/sig/generated/paper_trail_diff/activity_history.rbs +54 -19
  120. data/sig/generated/paper_trail_diff/activity_range.rbs +6 -20
  121. data/sig/generated/paper_trail_diff/activity_root_snapshot_refresher.rbs +36 -2
  122. data/sig/generated/paper_trail_diff/activity_root_steps.rbs +6 -6
  123. data/sig/generated/paper_trail_diff/activity_scope_filter.rbs +51 -0
  124. data/sig/generated/paper_trail_diff/activity_snapshot_delta.rbs +5 -3
  125. data/sig/generated/paper_trail_diff/activity_snapshot_sequence.rbs +21 -3
  126. data/sig/generated/paper_trail_diff/activity_target_candidate_loader.rbs +19 -24
  127. data/sig/generated/paper_trail_diff/activity_timeline_builder.rbs +121 -127
  128. data/sig/generated/paper_trail_diff/activity_tree_filter.rbs +41 -8
  129. data/sig/generated/paper_trail_diff/activity_version_collector.rbs +42 -35
  130. data/sig/generated/paper_trail_diff/activity_view.rbs +16 -8
  131. data/sig/generated/paper_trail_diff/analysis.rbs +15 -6
  132. data/sig/generated/paper_trail_diff/analysis_batch.rbs +6 -24
  133. data/sig/generated/paper_trail_diff/association_activity_edge.rbs +0 -13
  134. data/sig/generated/paper_trail_diff/association_activity_selection.rbs +6 -9
  135. data/sig/generated/paper_trail_diff/association_discovery.rbs +0 -3
  136. data/sig/generated/paper_trail_diff/association_key.rbs +5 -0
  137. data/sig/generated/paper_trail_diff/association_traversal.rbs +26 -2
  138. data/sig/generated/paper_trail_diff/batch_boundary_resolver.rbs +17 -17
  139. data/sig/generated/paper_trail_diff/batch_preload.rbs +0 -4
  140. data/sig/generated/paper_trail_diff/batched_root_analyses.rbs +47 -0
  141. data/sig/generated/paper_trail_diff/batched_root_analyzer.rbs +9 -8
  142. data/sig/generated/paper_trail_diff/batched_root_versions.rbs +10 -6
  143. data/sig/generated/paper_trail_diff/branch_snapshot_refresher.rbs +11 -5
  144. data/sig/generated/paper_trail_diff/change_attribution.rbs +194 -0
  145. data/sig/generated/paper_trail_diff/change_row.rbs +22 -7
  146. data/sig/generated/paper_trail_diff/deleted_analysis_batch.rbs +11 -12
  147. data/sig/generated/paper_trail_diff/deleted_root_filter.rbs +0 -2
  148. data/sig/generated/paper_trail_diff/deprecation.rbs +4 -24
  149. data/sig/generated/paper_trail_diff/direct_record_state_loader.rbs +4 -0
  150. data/sig/generated/paper_trail_diff/endpoint.rbs +40 -16
  151. data/sig/generated/paper_trail_diff/errors.rbs +2 -11
  152. data/sig/generated/paper_trail_diff/habtm_transaction_owners.rbs +2 -1
  153. data/sig/generated/paper_trail_diff/historical_filter.rbs +20 -9
  154. data/sig/generated/paper_trail_diff/historical_snapshot_store.rbs +40 -10
  155. data/sig/generated/paper_trail_diff/instrumentation.rbs +0 -3
  156. data/sig/generated/paper_trail_diff/live_endpoint_batch_loader.rbs +3 -0
  157. data/sig/generated/paper_trail_diff/live_endpoint_provider.rbs +5 -8
  158. data/sig/generated/paper_trail_diff/live_graph_collector.rbs +2 -2
  159. data/sig/generated/paper_trail_diff/nested_comparator.rbs +20 -4
  160. data/sig/generated/paper_trail_diff/net_change.rbs +168 -0
  161. data/sig/generated/paper_trail_diff/own_window.rbs +22 -0
  162. data/sig/generated/paper_trail_diff/paper_trail_adapter.rbs +9 -6
  163. data/sig/generated/paper_trail_diff/prepared_activity_index.rbs +114 -14
  164. data/sig/generated/paper_trail_diff/prepared_child_candidates.rbs +39 -0
  165. data/sig/generated/paper_trail_diff/prepared_edge_loader.rbs +18 -35
  166. data/sig/generated/paper_trail_diff/prepared_history.rbs +9 -12
  167. data/sig/generated/paper_trail_diff/prepared_history_loader.rbs +28 -3
  168. data/sig/generated/paper_trail_diff/prepared_record_index.rbs +68 -14
  169. data/sig/generated/paper_trail_diff/prepared_snapshot_builder.rbs +12 -0
  170. data/sig/generated/paper_trail_diff/prepared_state_association_reader.rbs +6 -7
  171. data/sig/generated/paper_trail_diff/read_snapshot.rbs +27 -8
  172. data/sig/generated/paper_trail_diff/recorded_changes.rbs +4 -2
  173. data/sig/generated/paper_trail_diff/recorded_changes_reader.rbs +41 -0
  174. data/sig/generated/paper_trail_diff/recorded_class.rbs +7 -6
  175. data/sig/generated/paper_trail_diff/recorded_columns.rbs +21 -0
  176. data/sig/generated/paper_trail_diff/root_version_plan.rbs +8 -4
  177. data/sig/generated/paper_trail_diff/root_version_selection.rbs +27 -13
  178. data/sig/generated/paper_trail_diff/scope_condition.rbs +0 -2
  179. data/sig/generated/paper_trail_diff/scope_ranking.rbs +10 -10
  180. data/sig/generated/paper_trail_diff/scoped_analysis.rbs +19 -0
  181. data/sig/generated/paper_trail_diff/scoped_analysis_builder.rbs +2 -2
  182. data/sig/generated/paper_trail_diff/scoped_root_selection.rbs +37 -14
  183. data/sig/generated/paper_trail_diff/snapshot_normalizer.rbs +7 -0
  184. data/sig/generated/paper_trail_diff/stored_json_values.rbs +35 -0
  185. data/sig/generated/paper_trail_diff/stored_time_precision.rbs +19 -5
  186. data/sig/generated/paper_trail_diff/stored_values.rbs +13 -0
  187. data/sig/generated/paper_trail_diff/support.rbs +120 -23
  188. data/sig/generated/paper_trail_diff/time_of_day.rbs +21 -0
  189. data/sig/generated/paper_trail_diff/time_range.rbs +15 -8
  190. data/sig/generated/paper_trail_diff/time_version_range.rbs +2 -5
  191. data/sig/generated/paper_trail_diff/timeline_builder.rbs +2 -2
  192. data/sig/generated/paper_trail_diff/timeline_range.rbs +12 -7
  193. data/sig/generated/paper_trail_diff/total_order.rbs +32 -0
  194. data/sig/generated/paper_trail_diff/transaction_cut.rbs +111 -52
  195. data/sig/generated/paper_trail_diff/traversal_preparer.rbs +2 -2
  196. data/sig/generated/paper_trail_diff/value_objects.rbs +5 -1
  197. data/sig/generated/paper_trail_diff/version_association_candidate_scope.rbs +10 -9
  198. data/sig/generated/paper_trail_diff/version_boundary.rbs +15 -8
  199. data/sig/generated/paper_trail_diff/version_query.rbs +17 -10
  200. data/sig/generated/paper_trail_diff/version_range.rbs +6 -9
  201. data/sig/generated/paper_trail_diff/version_sequence_diagnostics.rbs +13 -0
  202. data/sig/generated/paper_trail_diff/version_table.rbs +3 -0
  203. data/sig/generated/paper_trail_diff.rbs +16 -16
  204. metadata +28 -6
  205. data/lib/paper_trail_diff/preloaded_endpoint_batch_loader.rb +0 -60
  206. data/sig/generated/paper_trail_diff/preloaded_endpoint_batch_loader.rbs +0 -32
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 31ad8d55dab710a7295d5c6fef92918fee436492e35ec6fa785f49de025c2994
4
- data.tar.gz: 04c4f17548bcda07300bb857dc6194b698f907bb1b71db06e61dbb3037e533dd
3
+ metadata.gz: dde7a0e50f1010dc5381cb7bcca48e359d3ce85bacee4f2c2fd0c82f5edc9fca
4
+ data.tar.gz: f2c8da78755ef3f2a336fbe9f6fe66b72f87af31b99aad5bfdc6931b0dbeee9a
5
5
  SHA512:
6
- metadata.gz: 6a2cbc59fa7e53d31b78b1f0d5863519e1c72063718791323b938f73668ee53ddb19f6ac5cdf4d72b656dc6ec5c154e26485994da2ac90a6141d67928668c4ed
7
- data.tar.gz: 7700f7863dcd954cea284ea1564def6a1d4b2a8679dd49a01bf618cf36333b6aba8c7e83b32cc7f2c481c81701ef5127c899c8cb9ce551c6379cc608273dfc68
6
+ metadata.gz: c687e380deaec613c0bb7b911d20f1041bd6f3ace09111d28cc060111a4865867d9bcbe57ae6dcc848dece9b64e1fd9bb5507f21a36611727ad651bfad8137d4
7
+ data.tar.gz: 5448861cc4a58b21b8560533f4237143f9cfb166ebaa1892e49be50ce354cc40c79cae206749250ed3912f5dd804b3c32a61129bac48937d446ab6ab6803c845
data/CHANGELOG.md CHANGED
@@ -3,6 +3,586 @@
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.17.1] - 2026-11-07
7
+
8
+ ### Fixed
9
+
10
+ - A change to a root's own field that was saved without a version, after an
11
+ earlier version of the same transaction changed that field, is no longer
12
+ split with that earlier version's change. The earlier change is already in
13
+ the state a step starts from, so the step's row for the field is the
14
+ unversioned change alone.
15
+ - A window that starts inside a transaction now reports an associated
16
+ record that the transaction moved out of the root's tree before the
17
+ window's start, such as a comment moved to another parent and then saved
18
+ again or destroyed. The window before it leaves such a change to this
19
+ one, so a window split there no longer loses it from both halves.
20
+
21
+ ## [0.17.0] - 2026-11-04
22
+
23
+ ### Breaking changes
24
+
25
+ - The options deprecated in 0.15.0 are removed, and passing one raises
26
+ `ArgumentError` (unknown keyword):
27
+ - `close_on:` on `timeline`, `activity_timeline`, `analyze`, `analyze_many`,
28
+ and `analyze_scope`. It had no effect: a window already closes on the
29
+ current record when nothing on its requested paths was recorded after it.
30
+ - `allow_expensive:` on `compare_many`, `analyze_many`, `analyze_scope`, and
31
+ `report`. It had no effect: `allow_approximate: true` alone accepts a path
32
+ read with PT-AT.
33
+ - `reload_live_endpoints:` on `compare`, `compare_many`, and
34
+ `activity_timeline`. Every method now reloads the current records it
35
+ compares with, as it did by default.
36
+ - `UnloadedAssociationError`, which only `reload_live_endpoints: false` raised,
37
+ and `UnsupportedBatchPathError`, which nothing raised since 0.15.0, are
38
+ removed. Code that rescues either must stop naming it.
39
+ - The `compare.paper_trail_diff`, `compare_many.paper_trail_diff`, and
40
+ `load_live_endpoints.paper_trail_diff` payloads no longer have a
41
+ `reload_live_endpoints` key.
42
+ - `version_scope:` applies to the versions of the requested associations as
43
+ it does to the root's own:
44
+ - In `analyze_scope` and `report`, a change on a requested association
45
+ selects a record only when the filter keeps its version. A record that
46
+ only versions the filter leaves out changed is no longer selected, and no
47
+ longer counts toward `limit:`.
48
+ - In activity (`activity_timeline`, `activity: true`, and `report`), the
49
+ filter decides which steps are reported: every step of a transaction in
50
+ which it keeps a version, of any record, and each version saved outside a
51
+ transaction that it keeps. Activity listed every step between the first
52
+ and the last root version the filter kept, whoever made it, and every
53
+ change on an association. Every version is still replayed, so each step
54
+ shows what its own change did. An analysis starts at the first change the
55
+ filter keeps, on the record or its associations, and ends after the last.
56
+ - Without associations, activity reports the root's versions the filter
57
+ keeps, as `timeline` does.
58
+
59
+ The record and its associations keep their versions in one table, which
60
+ the filter reads for all of them, so a condition on `item_type` or
61
+ `item_id` now leaves out the associations' changes. A filter that keeps
62
+ every version now reads as no filter: a range of one version, which no
63
+ later version reveals, has that version's state rather than none.
64
+
65
+ ### Added
66
+
67
+ - With `recorded_changes: true`, change rows tell a write saved without a
68
+ version, such as `update_columns`, apart from the change it follows.
69
+ PaperTrail reads such a write into the record's next version, or its
70
+ current row, so it shows up in the step of the record's previous change,
71
+ and its row was credited to that change's author. The part of a change no
72
+ version recorded now has a row of its own, whose `source` has kind
73
+ `:unversioned`, names the record, and has no version, event, author, or
74
+ time; `ChangeRow#unversioned?` and `ActivityBoundary#unversioned?` tell
75
+ them apart. A field a version recorded changing from 10 to 20, which an
76
+ `update_columns` then set to 99, gives two rows: 10 to 20, credited to the
77
+ version, and 20 to 99, unversioned. A write between two of a record's
78
+ versions in one transaction, which no step shows on its own, is split off
79
+ the same way. A row stays whole, credited to a version, where history
80
+ cannot show the write was unrecorded: a version that recorded no changes,
81
+ such as a `touch`; a column `has_paper_trail` leaves out of
82
+ `object_changes`; a field a create left at its default; and the start of a
83
+ transaction that began before a window and saved no version of the root.
84
+ The [change rows](docs/reference.md#change-rows) reference lists them.
85
+
86
+ - `Analysis#net_changes` and `ScopedAnalysis#net_changes` fold an activity's
87
+ change rows into one `NetChange` for each record: its fields before the
88
+ rows a block keeps, its fields with only those changes made, and the
89
+ difference. Keeping the rows that name an author reports what people
90
+ changed, and with `recorded_changes: true` leaves out writes saved without
91
+ a version: `report.net_changes { |row| row.source.whodunnit }`. The root
92
+ comes first whenever anything changed. The states come from the steps'
93
+ snapshots, so it needs `snapshots: true`. See
94
+ [net changes](docs/reference.md#net-changes).
95
+
96
+ - `ScopedAnalysis#analysis_for(record)` returns the analysis of one of
97
+ `roots`, the records `analyze_scope` and `report` load, without building
98
+ its key: the base class's name and the ID as a string, which a subclass or
99
+ an integer ID gets wrong when built by hand.
100
+
101
+ - `within:` accepts an endless range, such as `1.day.ago..`, which runs
102
+ through the current saved state, as `report` does.
103
+
104
+ - `diagnose` warns with `inverted_version_order` when a record's versions are
105
+ dated in another order than their IDs show they were saved in. PaperTrail
106
+ dates an update with the record's `updated_at` unless `has_paper_trail
107
+ synchronize_version_creation_timestamp: false`, so a save that set
108
+ `updated_at` itself, such as an import keeping another system's times, a
109
+ `touch(time:)`, or one made with timestamps off, can date its version in
110
+ the past. History is read in time order, so such an update is read before
111
+ the change it followed, and one dated before the record's `create` reads as
112
+ the record deleted and created again. The
113
+ [version order](docs/reference.md#version-order) section explains the fix.
114
+
115
+ - On SQL Server, each call reads its history and live rows in one `SNAPSHOT`
116
+ transaction when the database allows snapshot isolation
117
+ (`ALTER DATABASE ... SET ALLOW_SNAPSHOT_ISOLATION ON`), as it does at
118
+ `REPEATABLE READ` on PostgreSQL and MySQL. A commit that lands during the
119
+ call is then seen by none of its statements. Each call checks the setting
120
+ first, in one statement; without it, nothing changes.
121
+
122
+ ### Changed
123
+
124
+ - A change row names the version of its own record that made the change.
125
+ It named its step's source boundary: for a transaction group, the
126
+ transaction's first event, whichever record that was; and without
127
+ grouping, a child's change that showed up at a later event of its
128
+ transaction, in a step another record's version opens, named that version.
129
+ A record created or destroyed names its create or destroy, and its fields
130
+ the version that recorded each value. A record that joined or left through
131
+ another record's change, such as a new `belongs_to` target, still names the
132
+ step's source boundary.
133
+ Without `recorded_changes: true` the gem cannot tell which of a record's
134
+ versions in a transaction made a change, and names the last of them.
135
+
136
+ - `recorded_changes`, and each activity boundary's `recorded_changes`, read
137
+ values as a step's diff reads them, so a recorded value equals the state it
138
+ produced: a time of day on 2000-01-01, and with JSON history, times to the
139
+ digits history stores and binary and `serialize`d values as JSON stored
140
+ them.
141
+
142
+ - `report` reads every version saved since `since:`, with no end. Its window
143
+ ended at the time of the call, so a version a server whose clock ran ahead
144
+ of the reporting server's had dated a moment later was left out, and the
145
+ report ended before a change the current record already held. It no longer
146
+ looks for transactions that cross that end, or for each record's first
147
+ version after it, which saves up to three statements per 500 records.
148
+ `analysis.window` is endless (`since..`) for a report, and a `since:` in the
149
+ future gives an empty report rather than raising `InvalidTimeRangeError`,
150
+ whose message named `within:`.
151
+
152
+ - The README said change rows leave out the blank fields of a record that
153
+ appeared or disappeared. Only `nil` fields are left out: an empty string or
154
+ `false` gets a row.
155
+
156
+ - The performance guide's query counts were measured again, and it compares
157
+ PaperTrail's JSON serializer with its default YAML one: a report read JSON
158
+ in about 40% less time. It also says what `historical_filter:` costs on SQL
159
+ Server, where each page of matching records lists every matching id. The
160
+ architecture guide no longer says a window's transaction lookups take four
161
+ per root, sent 200 roots per query.
162
+
163
+ - The reference says what happens when two transactions save in the same
164
+ tree at the same time, so that their versions interleave: each forms more
165
+ than one group with `group: :transaction`, and a record one of them changed
166
+ and changed back can appear in the other's steps, and in a window's
167
+ starting state and diff.
168
+
169
+ - `analyze_many`, `analyze_scope`, `report`, and `compare_many` list at most
170
+ 500 ids in a statement, as the rest of the gem does. Reading the batch's
171
+ versions, the transactions its first versions belong to, its associations'
172
+ candidates and rows, its deleted records' destroys, and its current rows
173
+ and their associations each listed every record of the batch at once. On
174
+ SQL Server, which writes such a list into the statement and compiles it
175
+ afresh, a `report` of 10,000 articles and their comments took 17.1 s and
176
+ now takes 11.4 s, and one of 20,000 took 38.9 s and now takes 23.0 s; a
177
+ statement listing 20,000 transactions alone failed with error 8623. With
178
+ `historical_filter:`, or a version table whose `item_id` does not share the
179
+ key's type, the records are read among a list of ids, which each page of
180
+ 250 repeated: they are now read in pages of one past `limit:`, up to 2,000.
181
+ On SQL Server, such a report of 10,000 articles took 47.4 s and now takes
182
+ 14.4 s, and one of 20,000 took 280.5 s and now takes 51.1 s.
183
+
184
+ - `analyze_scope` and `report` read the records a relation selects in pages
185
+ of one past `limit:`, at least 250 and at most 2,000 records, rather than
186
+ 250. Each page runs again the subqueries that find which records changed
187
+ and skips the rows before it, so a selection of 10,000 articles changed in
188
+ the window, with their comments, took 1.5 s on SQLite and now takes 0.3 s.
189
+
190
+ - `historical_filter:` reads its candidates' versions, and selecting a record
191
+ by a change on its associations reads ids, 500 to a statement rather than
192
+ 250, as the rest of the gem does.
193
+
194
+ - Activity on associations decodes each of the record's versions once for
195
+ the call. It decoded a version again at every event the version bounded,
196
+ up to five times: a `report` of 10,000 articles with their comments took
197
+ about 20 s on SQLite and now takes about 18 s, and peaks at about 100 MB
198
+ less memory.
199
+
200
+ - History on a `has_and_belongs_to_many` groups the members PT-AT recorded
201
+ by transaction once. Each of the root's transactions looked through every
202
+ member recorded for all of them, so the cost grew with the square of the
203
+ root's versions: a `timeline` of an article with 2,000 versions and its
204
+ tags took 9.2 s and now takes 1.9 s, and an `analyze_many` of 200 tagged
205
+ articles with 20 versions each took 34.6 s and now takes 4.0 s. The
206
+ members and the transactions' owners are read 500 transactions per
207
+ statement, as other lists of ids are: on SQL Server, a statement listing
208
+ 40,000 ids timed out.
209
+
210
+ - With `version_scope:`, `timeline`, `analyze`, and the batch methods find
211
+ the version after each one the filter keeps with a search. They passed
212
+ every version in range before it, so the cost grew with the square of the
213
+ record's versions: a `timeline` of an article with 4,000 versions, half of
214
+ them kept, took 9.5 s and now takes 1.4 s, about as long as without the
215
+ filter.
216
+
217
+ - Preparing history no longer checks each record against every one before
218
+ it in two lists: the targets of a polymorphic `belongs_to`, and the owners
219
+ of an association requested both alone and as the first part of a
220
+ `has_many :through`. Each check cost little, about 0.1 s in an
221
+ `analyze_many` of 3,000 authors with their articles and the comments
222
+ through them, but the total grew with the square of the batch.
223
+
224
+ - Snapshots of a record with its associations do less work at each version
225
+ of the record, with the same results. Each member's version times and its
226
+ scope's condition are read once rather than at every version, a member
227
+ that did not change is normalized once, and a snapshot that starts from
228
+ the current record reads its associations from prepared history, as one
229
+ that starts from a version does, rather than building each member as an
230
+ Active Record record. A `timeline` of an article with 2,001 versions and
231
+ 300 comments took 14.9 s and now takes 7.5 s, and an `analyze_scope` with
232
+ activity over a day's changes to 373 articles, with their comments,
233
+ replies, reviewers, and authors, took 4.3 s and now takes 3.9 s.
234
+
235
+ - With `recorded_changes: true`, a boundary decodes its version's changes the
236
+ first time its `recorded_changes` is read, and each version is decoded once
237
+ for the whole call. Every boundary decoded its version when it was built,
238
+ so a version that many records share in a batch, such as an author's, was
239
+ decoded once for each of them, and a step nobody read cost as much as one
240
+ that was. A decoding error now raises when the changes are read.
241
+
242
+ - Activity asks Active Record whether a value is a version or a record once
243
+ for each model class, rather than on every read: Active Record answers
244
+ `respond_to?` by also looking through the record's attributes. An
245
+ `analyze_many` of 2,000 articles with their comments took about 9% less
246
+ time.
247
+
248
+ - `analyze_many`, `analyze_scope`, and `report` with `activity: true` read
249
+ the association history of a record that has no version in the window,
250
+ but whose associated records changed there, together with the rest of the
251
+ batch. Such a record, as in a `report(since:)` of articles that only gained
252
+ comments, read its own history, at about nine statements each. A batch of
253
+ 20 such articles took 188 statements and now takes 14, as many as one.
254
+
255
+ - Activity on a `has_many` or `has_one` reads the children each owner had
256
+ once. Preparing the history read them for its snapshots, and finding the
257
+ activity read them again: an `analyze_many` of three articles with their
258
+ comments took 16 statements and now takes 14.
259
+
260
+ - `analyze` and `activity_timeline` with activity on associations read the
261
+ current record's row once for the snapshots that start from it, as
262
+ `analyze_many` already did. Each such snapshot read the row again: after
263
+ four transactions that changed two comments each, an article's activity
264
+ read its row ten times rather than four.
265
+
266
+ - On SQL Server, a window's transaction-edge lookup sends its record ids as
267
+ bound parameters, as the other id lists do, instead of writing them into
268
+ each statement. SQL Server compiled each such statement afresh, at about
269
+ 0.05 ms per id. On 10,000 roots, the lookup's SQL time fell from 1.4 s to
270
+ 0.7 s and a report from 5.1 s to 4.4 s, with the same windows. The lookup
271
+ now names 250 ids a statement rather than 500, since each id appears twice
272
+ in it: 1,000 ids a statement was slower, and would exceed the 999 bound
273
+ parameters SQLite allowed before 3.32.
274
+
275
+ - Activity reads the state of a transaction that saved its root together
276
+ with descendants once for that transaction's descendant events, not again
277
+ at each one. PT-AT reads what a transaction saved as it stood before the
278
+ transaction began, so from one descendant's event to the next in the same
279
+ transaction the snapshot is the same; it was rebuilt whole each time. A
280
+ `report` on 100 articles, each created with 100 comments in one transaction
281
+ and edited with all of them in another, took 20.1 s and now takes 4.6 s,
282
+ and allocated a quarter as many objects. On 10,000 articles at about 1.5
283
+ versions each with their comments, it took 14.6 s and now takes 13.9 s.
284
+ The results are the same.
285
+
286
+ - Activity carries the snapshot at a root's version to the next event by
287
+ comparing the root's state at the two, which the snapshots decode anyway.
288
+ It decoded the version's recorded changes and the state after it a second
289
+ time instead, which took longer than rebuilding the snapshot whole. The
290
+ next descendant's event in the same transaction as a root's update is now
291
+ carried forward the same way, where it was rebuilt whole. A `report` on
292
+ 2,000 articles with about 1.5 comments each, each article edited ten
293
+ times and about a fifth of those edits saved with a comment, took 19.9 s
294
+ and now takes 14.8 s, with a fifth fewer allocations. The results are the
295
+ same.
296
+
297
+ - A batch reads its requested associations' reflections once for the whole
298
+ call, where each root's activity resolved and checked them again, and it
299
+ reads a current record's attributes for its history only when a read
300
+ reaches past that record's last version. Most do not: in a `report` on
301
+ 10,000 articles with their comments, about a quarter of the 25,000 current
302
+ records were read that way. The snapshots that start from a root's current
303
+ row also share one reading of it, from the record the call loaded. That
304
+ report takes about 7% less time and allocates 8% fewer objects; one on
305
+ 2,000 articles edited ten times each, and one on 100 articles with 100
306
+ comments each, about 3% less time. The results are the same.
307
+
308
+ ### Fixed
309
+
310
+ - `nested_changes` treats `:a` and `"a"` as one key inside arrays too, as it
311
+ already did in objects. An array whose objects differed only in key type,
312
+ such as a hash built in Ruby against one read back from JSON, was reported
313
+ as having lost one element and gained another. Elements are still reported
314
+ as they were given, and `{ a: 1, "a" => 2 }` inside an array now raises
315
+ `AmbiguousNestedKeyError`, as it does in an object.
316
+
317
+ - With `historical_filter:`, `analyze_scope` and `report` test each record over
318
+ the window its analysis covers. A transaction that crosses the window's
319
+ start or end moves that window to where the transaction began, but the
320
+ filter read the window as asked: it missed a value the record held at the
321
+ moved start, such as its title before the transaction changed it, and
322
+ matched one held only past a moved end.
323
+
324
+ - `analyze_scope` and `report` no longer lose a record's change when a
325
+ window's edge falls inside a transaction that saved the record before the
326
+ edge and another article, or a record off the requested paths, after it.
327
+ The record's window moved to the later window, which did not select it,
328
+ while the earlier window left the change out: an update, or a deletion with
329
+ `include_deleted: true`, was in neither report. Such a transaction now moves
330
+ no edge, so the change is in the earlier window, with the record's version.
331
+ When the transaction saved a record on the requested paths after the edge,
332
+ the edge still moves, and `analyze_scope` and `report` now select the record
333
+ in the later window with or without `activity: true`.
334
+
335
+ - Activity over a window (`activity: true`, `activity_timeline`, and
336
+ `report`) no longer raises `KeyError` when a record on one requested path,
337
+ such as an author, is also a `belongs_to` target on another path with
338
+ associations requested below it
339
+ (`["author", "comments.reviewer.reviewed_comments"]`). A target named only
340
+ by a version saved after the window was followed as if its own associations
341
+ had been read, and they had not been.
342
+
343
+ - With `historical_filter:`, `analyze_scope` and `report` accept a relation
344
+ grouped by anything but the ID, such as each author's latest article
345
+ (`select("MAX(id) AS id").group(:author_id)`), and select the records it
346
+ groups among those that match. Before filtering, they asked the relation
347
+ for the IDs among each 250 candidates, which reads a group's column
348
+ instead of its aggregate: PostgreSQL, MySQL, and SQL Server rejected the
349
+ query, and SQLite returned any record of each group.
350
+
351
+ - History stored as JSON no longer reports two kinds of value as changed in
352
+ every comparison with the current record, though nothing changed them. A
353
+ `json` or `jsonb` `object` column stores a `serialize`d attribute as JSON
354
+ writes it, so a `Date` or `Symbol` inside it came back as a String: that
355
+ attribute is now read as JSON writes it on every side, the current
356
+ record's included. PaperTrail's JSON serializer stores a `binary` column
357
+ as `{ "value" => bytes }`, which is now read as the bytes.
358
+
359
+ - Without associations, activity (`activity_timeline`, `activity: true`, and
360
+ `report`) reports a change saved without a version, such as one by
361
+ `update_columns` or with versioning off, in the step for the record's
362
+ previous recorded change, as `timeline` and activity on associations do.
363
+ It was reported in the step for the record's next version, and so credited
364
+ to that version's author: a title written by `update_columns` after
365
+ Alice's edit was reported as part of Mallory's next edit.
366
+
367
+ - `analyze_scope` and `report` read every record a relation selects when its
368
+ order has ties, such as `Article.order(:status)`, and more than 250 records
369
+ match. Records were read 250 at a time in that order, and PostgreSQL and
370
+ MySQL may return rows that tie in a different order for each query, so some
371
+ records were read twice and others never, without an error: of 2,000
372
+ changed articles ordered by status, PostgreSQL selected 1,606. The ID now
373
+ ends any order that does not already sort by it. SQL text counts as sorting
374
+ by the ID when it names the column, alone or after the table's name. The
375
+ order of a relation grouped by anything but the ID is kept as given, since
376
+ a database sorts groups only by what they group or aggregate.
377
+
378
+ - With PaperTrail's default YAML serializer, a `time` column reads as the
379
+ time each version recorded. PaperTrail 16 and 17 decode such a value as
380
+ `nil`, unless the column is time-zone aware and the time zone is UTC, and
381
+ so did the gem, so the step that set a time showed no change, every
382
+ comparison of a later version with the current record showed the time
383
+ changing from `nil`, and `recorded_changes` reported
384
+ `{ from: nil, to: nil }`. That includes records the gem rebuilds with
385
+ PaperTrail's `reify`: models with initialization callbacks, custom types or
386
+ defaults, default scopes that assign attributes, or encrypted attributes;
387
+ a version that holds a column the model no longer has; the records a
388
+ callable `historical_filter:` receives; and association members PT-AT
389
+ rebuilds. Each such record's time is assigned from its own version, which
390
+ is decoded a second time only when it holds a time of day. A time is read
391
+ on 2000-01-01, as the row keeps it: a column that is not time-zone aware
392
+ keeps in memory the date of the time assigned to it, such as
393
+ `Time.current`'s, and the versions saved from that record store it. Before
394
+ Active Record 8.1, a zone-aware time read from the database falls on
395
+ 2000-01-01 in UTC, and one assigned on 2000-01-01 in the time zone, so
396
+ every time of day is compared on 2000-01-01 in its own zone, as Active
397
+ Record 8.1 reads both.
398
+
399
+ - `analyze_scope` and `report` accept a relation whose `limit` or `offset` is
400
+ a String, as request parameters are, such as
401
+ `Article.offset(params[:offset])`. A String offset raised `TypeError`, and
402
+ before Active Record 8.1, which casts a limit as it is set, a String limit
403
+ raised `NoMethodError`. A String `limit` or `offset` in an association's
404
+ scope is read from history as an Integer one is: before 8.1 a String limit
405
+ raised `TypeError` there, and a String offset made the association one that
406
+ only `allow_approximate: true` reads.
407
+
408
+ - Activity from a version reports a record that left one of the requested
409
+ associations earlier in that version's transaction, such as a comment
410
+ moved to another article or destroyed just before the article's version
411
+ was saved. The range starts from the state before the transaction, which
412
+ holds the record, but the record's own versions were not read, so its
413
+ removal was left out, or reported in the next step that read the
414
+ association again, under that step's transaction and author.
415
+
416
+ - Activity on a `has_many :through` leaves out the versions a join record
417
+ saved while it joined another record, judged by transaction as any record
418
+ is: by whether it joined the owner before the transaction or after it. A
419
+ card created on one board and moved to another later brought every version
420
+ it saved on the first board into the second board's activity, and so did a
421
+ card created and destroyed inside one transaction: each was a step of its
422
+ own, and a transaction group listed it in `sources`. Inside a transaction,
423
+ where a change surfaces one event late, such a step also took the credit
424
+ for the change made just before it, under its own author.
425
+
426
+ - A window in which every event was of a record outside the requested
427
+ associations throughout, such as a comment past a scope's `limit` or one
428
+ its default scope leaves out, reports nothing. With nothing recorded after
429
+ it, such a window had a step whose `sources` held `nil` and that showed the
430
+ record as created. With something recorded after it, the analysis was empty
431
+ but still held both snapshots; both are `nil` now, as for any analysis that
432
+ reports nothing.
433
+
434
+ - Back-to-back windows, or a `report` with `since:` after an earlier report,
435
+ that meet inside a transaction that saved associated records on both sides
436
+ of the edge, and no version of the root, report the changes it saved before
437
+ the edge. Neither window reported them: the earlier one ended at the state
438
+ before the transaction, as any window ending inside one does, and the later
439
+ one started after them, and did not know a record the transaction
440
+ destroyed before the edge. Now all of the transaction's changes are
441
+ reported once: in the later window, which starts from the state before the
442
+ transaction, when a version it saved after the edge is of a record on the
443
+ requested paths, and otherwise in the earlier window. A transaction group
444
+ lists in `sources` only the versions inside its window. Finding such
445
+ transactions takes one statement per 500 of the transactions a window's
446
+ history reads; when it finds one, the window's history is read again from
447
+ where that transaction began.
448
+
449
+ - A window whose last change a `version_scope:` keeps is followed by the
450
+ version that shows what that change did, and that version now comes after
451
+ the window as well. Activity reported no step for the change, and
452
+ `analyze_many` with associations read the associations' state at that
453
+ version from history that ended with the window: a comment edited again
454
+ after it showed its latest body instead of the one it had then.
455
+
456
+ - `analyze_many` with `activity: true`, associations, and a `version_scope:`
457
+ that keeps none of a record's versions reports nothing for that record over
458
+ its whole history, as `analyze` does. It raised `IncompleteTimeRangeError`.
459
+
460
+ - Activity reports a change to a `belongs_to` target that the root took
461
+ without a version, such as an author set while `has_paper_trail only:`
462
+ left `author_id` out, when the root's next version moved to another target.
463
+ Only that version's stored state named the target, so the target's own
464
+ versions were not events: its rename went unreported by activity read
465
+ step by step, while the same history read in full showed it in an
466
+ unrelated step.
467
+
468
+ - Activity on a `has_and_belongs_to_many` reports the addition of a record
469
+ that the transaction saving the root created and attached, when the record
470
+ was detached again before the root's next version. Only that transaction's
471
+ root version records the record as a member. Its creation was judged by the
472
+ states before and after the transaction, and the record was a member in
473
+ neither, so the creation was left out: activity reported the record's
474
+ removal but never its addition.
475
+
476
+ - `analyze` with `activity: true` from a version to the same version is
477
+ empty, as is any analysis in which nothing is reported. It reported the
478
+ record as destroyed: its `diff` held a presence change to `nil`, and its
479
+ `to_snapshot` was `nil`.
480
+
481
+ - `analyze_many` and `analyze_scope` without associations raise
482
+ `AmbiguousVersionOrderError` for versions they cannot order, as `timeline`
483
+ and `analyze` already did: versions that share a timestamp and whose ids
484
+ do not count up, such as UUIDs. They read such versions in the order of
485
+ their ids, so a record's steps could follow a random sequence, including
486
+ a destroy and re-creation that never happened.
487
+
488
+ ### Development
489
+
490
+ - `ORACLE_SHRINK=1` reduces a failing oracle example to the few steps that
491
+ matter. The generators draw through a random source that keeps each draw
492
+ by step, and the reducer runs the example again with steps left out and
493
+ choices set to the first one, while it still fails the same way. The example
494
+ then reports the reduced history's versions and mismatches, and a file that
495
+ replays it with `ORACLE_REPLAY`. An oracle failure prints the command. The
496
+ replay differential oracle reports each read that differs, with both
497
+ results, rather than only the transactions it made. The consistency checks'
498
+ histories reduce the same way.
499
+
500
+ - `.github/workflows/oracle.yml` runs 200 more oracle seeds each night with
501
+ `ORACLE_STEPS=40`, in eight jobs, from a window that moves 200 seeds a day,
502
+ so each night tries histories no run has. A job reduces its first two
503
+ failing examples and keeps its log and their replay files as an artifact.
504
+
505
+ - `spec/unit/engine_properties_spec.rb` and
506
+ `spec/unit/nested_comparator_properties_spec.rb` check the comparison
507
+ engine over generated snapshots and JSON values, without a database: an
508
+ equal copy compares as no change, a diff applied to the first snapshot gives
509
+ the second, comparing the other way gives the opposite diff, every change
510
+ is real and in order, a carried-forward collection reports what one built
511
+ whole does, and the result is frozen. The oracles compute the diffs they
512
+ expect with the engine, so they cannot catch a bug in it. Of six engine bugs
513
+ injected to try them, the properties caught all six in about a second; the
514
+ engine's own specs missed two, which only integration and association
515
+ examples caught.
516
+
517
+ - `spec/unit/net_changes_properties_spec.rb` checks the fold behind
518
+ `net_changes` over generated histories in which each record has one state:
519
+ the rows of any run of steps fold into each record's change between the
520
+ run's first and last states, the root comes first and then each record by
521
+ its first kept change, the rows that move records in and out leave each, kept
522
+ alone, as its last move left it, and a record that stayed changes only in
523
+ fields a kept row set. Of six fold bugs injected to try them, they caught
524
+ all six, as the fold's own specs do.
525
+
526
+ - `spec/oracle/unversioned_writes_spec.rb` builds seeded histories of saves
527
+ and `update_columns` writes to an article, its comments and its author,
528
+ several to a transaction, and checks every change row against the writes:
529
+ a field's rows chain into the step's change, a row credited to a version
530
+ ends at a value that version recorded, an unversioned row ends at a value
531
+ an `update_columns` wrote, and a write a later version or the current row
532
+ reads has a row of its own. It runs over the whole history, grouped and
533
+ not, and over windows that start and end inside transactions.
534
+
535
+ - Every oracle that reads an activity timeline from end to end also checks
536
+ its net changes (`spec/support/net_changes_check.rb`): with every row
537
+ kept, each record's `before` and `after` must be its state where the step
538
+ of its first row starts and where the timeline ends, and the record must
539
+ be listed exactly when the two differ. The unversioned-writes oracle also
540
+ keeps only the rows of versions and checks that each article and comment
541
+ ends at its last recorded save.
542
+
543
+ - `spec/association/report_sql_work_spec.rb` bounds how a report's SQL grows
544
+ with other records' history in its window, counted in the steps SQLite's
545
+ virtual machine takes, which are the same on every run. A statement that
546
+ reads the window again for each of the roots' versions fails it; one such
547
+ statement, never released, took reports on SQLite from 6 to 44 ms an
548
+ article (see [SQL work](docs/testing.md#sql-work)). The reporting benchmark
549
+ has an `association_window` case: a `report` over articles with their
550
+ comments read through PT-AT, with the README's indexes.
551
+
552
+ - `spec/oracle/shapes_history_spec.rb` compares rebuilt history with plain
553
+ Active Record for shapes the other oracles leave out: polymorphic
554
+ `belongs_to`, `has_many` and `has_one` with `as:`, children that use
555
+ single-table inheritance and change type, an association to one subclass,
556
+ a child's own `belongs_to`, scoped and ranked `has_many` and `has_one`, and
557
+ a default scope. It checks every endpoint, timeline step, activity step,
558
+ window and window split, through `spec/support/graph_oracle.rb`, which
559
+ reads the expected states for any model. It found the first three bugs
560
+ above; a longer run of the replay differential found the fourth.
561
+ `ORACLE_SHOW` prints more than the first five mismatches.
562
+
563
+ - The SQL Server 2022 CI job's database allows snapshot isolation and the
564
+ 2019 job's does not, so both ways of reading a call run on CI.
565
+
566
+ - The oracles' transactions take turns between authors, and every window
567
+ split is also read with a `version_scope:` that keeps one author's versions.
568
+ It must report exactly the unfiltered steps of the transactions that author
569
+ saved a version in.
570
+
571
+ - Mutation testing in CI runs in four parallel jobs, each mutating every
572
+ fourth method in scope (`script/mutant_shard.rb`). A pull request that
573
+ changed 84 methods took 33 minutes on one runner, close to the job's
574
+ 45-minute limit.
575
+
576
+ - `PAPER_TRAIL_DIFF_SERIALIZER=json` runs the suites with PaperTrail's JSON
577
+ serializer, and a new CI job runs them that way. Before, about 40 of some
578
+ 1,800 examples wrote JSON history, and none on the PaperTrail 16 or SQL
579
+ Server jobs. Run with JSON, the suites found no fault in the gem: the specs
580
+ that failed wrote YAML fixtures by hand, were about YAML itself, or read
581
+ times more finely than JSON keeps them (milliseconds), which the gem
582
+ refuses or rounds as documented. Those specs now write fixtures with the
583
+ configured serializer, keep YAML where YAML is the subject, and compare
584
+ times as JSON history holds them.
585
+
6
586
  ## [0.16.0] - 2026-11-01
7
587
 
8
588
  ### Changed
@@ -62,7 +642,7 @@ project follows [Semantic Versioning](https://semver.org/).
62
642
  ### Fixed
63
643
 
64
644
  - Batch methods with `within:` or `since:` look for transactions that cross
65
- the window's edges in one statement per 500 records. 0.15.0 wrote a
645
+ the window's edges in one statement per 250 records. 0.15.0 wrote a
66
646
  separate lookup for each record into the statement, which SQL Server took
67
647
  about a second to compile per 200 records, so a report on 10,800 records
68
648
  spent nearly two minutes there. On 1.4 million versions, 0.15.0 failed for