paper_trail_diff 0.16.0 → 0.17.0

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