paper_trail_diff 0.17.1 → 0.18.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (215) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +648 -0
  3. data/QUICKSTART.md +12 -14
  4. data/README.md +32 -30
  5. data/docs/architecture.md +65 -29
  6. data/docs/performance.md +161 -46
  7. data/docs/reference.md +495 -394
  8. data/docs/testing.md +9 -15
  9. data/lib/paper_trail_diff/activity_belongs_to_event_applier.rb +42 -9
  10. data/lib/paper_trail_diff/activity_boundary.rb +15 -6
  11. data/lib/paper_trail_diff/activity_child_candidate_loader.rb +91 -18
  12. data/lib/paper_trail_diff/activity_collection_event_applier.rb +14 -15
  13. data/lib/paper_trail_diff/activity_collection_record_updater.rb +18 -8
  14. data/lib/paper_trail_diff/activity_collection_route_updater.rb +12 -25
  15. data/lib/paper_trail_diff/activity_event.rb +53 -34
  16. data/lib/paper_trail_diff/activity_event_record_normalizer.rb +12 -26
  17. data/lib/paper_trail_diff/activity_event_record_resolver.rb +45 -32
  18. data/lib/paper_trail_diff/activity_event_snapshot_refresher.rb +26 -33
  19. data/lib/paper_trail_diff/activity_history.rb +28 -34
  20. data/lib/paper_trail_diff/activity_relationship.rb +3 -26
  21. data/lib/paper_trail_diff/activity_root_snapshot_refresher.rb +14 -8
  22. data/lib/paper_trail_diff/activity_snapshot_delta.rb +2 -3
  23. data/lib/paper_trail_diff/activity_snapshot_sequence.rb +92 -25
  24. data/lib/paper_trail_diff/activity_timeline_builder.rb +128 -77
  25. data/lib/paper_trail_diff/activity_transaction_applier.rb +49 -0
  26. data/lib/paper_trail_diff/activity_tree_filter.rb +70 -57
  27. data/lib/paper_trail_diff/activity_tree_places.rb +76 -0
  28. data/lib/paper_trail_diff/activity_version_collector.rb +45 -32
  29. data/lib/paper_trail_diff/activity_view.rb +2 -0
  30. data/lib/paper_trail_diff/analysis.rb +6 -5
  31. data/lib/paper_trail_diff/analysis_batch.rb +21 -17
  32. data/lib/paper_trail_diff/association_activity_edge.rb +99 -85
  33. data/lib/paper_trail_diff/association_activity_selection.rb +46 -14
  34. data/lib/paper_trail_diff/association_discovery.rb +4 -4
  35. data/lib/paper_trail_diff/association_key.rb +10 -18
  36. data/lib/paper_trail_diff/association_traversal.rb +72 -92
  37. data/lib/paper_trail_diff/batch_boundary_resolver.rb +1 -7
  38. data/lib/paper_trail_diff/batch_preload.rb +2 -3
  39. data/lib/paper_trail_diff/batched_root_analyses.rb +60 -25
  40. data/lib/paper_trail_diff/batched_root_analyzer.rb +5 -5
  41. data/lib/paper_trail_diff/batched_root_versions.rb +7 -30
  42. data/lib/paper_trail_diff/branch_snapshot_refresher.rb +19 -14
  43. data/lib/paper_trail_diff/candidate_table.rb +160 -0
  44. data/lib/paper_trail_diff/change_attribution.rb +15 -23
  45. data/lib/paper_trail_diff/collection_identity_index.rb +68 -24
  46. data/lib/paper_trail_diff/collection_transition.rb +3 -3
  47. data/lib/paper_trail_diff/comparison_batch.rb +13 -6
  48. data/lib/paper_trail_diff/database_time.rb +85 -0
  49. data/lib/paper_trail_diff/deleted_analysis_batch.rb +22 -23
  50. data/lib/paper_trail_diff/deleted_root_filter.rb +10 -6
  51. data/lib/paper_trail_diff/diagnostics.rb +26 -86
  52. data/lib/paper_trail_diff/endpoint.rb +37 -5
  53. data/lib/paper_trail_diff/engine.rb +1 -1
  54. data/lib/paper_trail_diff/errors.rb +0 -6
  55. data/lib/paper_trail_diff/exact_column_type.rb +96 -0
  56. data/lib/paper_trail_diff/historical_snapshot_store.rb +88 -83
  57. data/lib/paper_trail_diff/instrumentation.rb +0 -8
  58. data/lib/paper_trail_diff/live_endpoint_batch_loader.rb +1 -4
  59. data/lib/paper_trail_diff/live_graph_collector.rb +1 -3
  60. data/lib/paper_trail_diff/nested_comparator.rb +42 -10
  61. data/lib/paper_trail_diff/paper_trail_adapter.rb +55 -98
  62. data/lib/paper_trail_diff/prepared_activity_index.rb +214 -182
  63. data/lib/paper_trail_diff/prepared_child_candidates.rb +13 -3
  64. data/lib/paper_trail_diff/prepared_edge_loader.rb +11 -49
  65. data/lib/paper_trail_diff/prepared_history.rb +27 -177
  66. data/lib/paper_trail_diff/prepared_history_loader.rb +39 -57
  67. data/lib/paper_trail_diff/prepared_record_index.rb +221 -147
  68. data/lib/paper_trail_diff/prepared_snapshot_builder.rb +47 -42
  69. data/lib/paper_trail_diff/prepared_state_association_reader.rb +85 -62
  70. data/lib/paper_trail_diff/recorded_changes.rb +34 -10
  71. data/lib/paper_trail_diff/recorded_owner.rb +67 -0
  72. data/lib/paper_trail_diff/root_version_selection.rb +6 -2
  73. data/lib/paper_trail_diff/scope_condition.rb +120 -80
  74. data/lib/paper_trail_diff/scope_ranking.rb +14 -32
  75. data/lib/paper_trail_diff/scoped_analysis.rb +11 -6
  76. data/lib/paper_trail_diff/scoped_analysis_builder.rb +17 -11
  77. data/lib/paper_trail_diff/scoped_root_selection.rb +91 -85
  78. data/lib/paper_trail_diff/selection_window.rb +31 -0
  79. data/lib/paper_trail_diff/snapshot.rb +60 -58
  80. data/lib/paper_trail_diff/snapshot_members.rb +115 -0
  81. data/lib/paper_trail_diff/snapshot_normalizer.rb +0 -11
  82. data/lib/paper_trail_diff/step.rb +1 -5
  83. data/lib/paper_trail_diff/stored_form.rb +146 -0
  84. data/lib/paper_trail_diff/stored_json_values.rb +8 -5
  85. data/lib/paper_trail_diff/stored_time_precision.rb +67 -33
  86. data/lib/paper_trail_diff/stored_values.rb +35 -3
  87. data/lib/paper_trail_diff/support.rb +185 -35
  88. data/lib/paper_trail_diff/time_of_day.rb +13 -2
  89. data/lib/paper_trail_diff/time_range.rb +85 -11
  90. data/lib/paper_trail_diff/time_version_range.rb +5 -1
  91. data/lib/paper_trail_diff/timeline_builder.rb +5 -11
  92. data/lib/paper_trail_diff/timeline_range.rb +56 -19
  93. data/lib/paper_trail_diff/timeline_snapshot_provider.rb +31 -7
  94. data/lib/paper_trail_diff/total_order.rb +19 -5
  95. data/lib/paper_trail_diff/transaction_anchors.rb +138 -0
  96. data/lib/paper_trail_diff/transaction_cut.rb +67 -327
  97. data/lib/paper_trail_diff/transaction_ends.rb +194 -0
  98. data/lib/paper_trail_diff/traversal_preparer.rb +12 -24
  99. data/lib/paper_trail_diff/{approximate_paths.rb → unreadable_paths.rb} +8 -9
  100. data/lib/paper_trail_diff/value_objects.rb +8 -6
  101. data/lib/paper_trail_diff/version.rb +1 -1
  102. data/lib/paper_trail_diff/version_association_candidate_scope.rb +12 -10
  103. data/lib/paper_trail_diff/version_boundary.rb +0 -29
  104. data/lib/paper_trail_diff/version_query.rb +49 -1
  105. data/lib/paper_trail_diff/version_scope_filter.rb +74 -5
  106. data/lib/paper_trail_diff/version_sequence_diagnostics.rb +4 -31
  107. data/lib/paper_trail_diff/version_table.rb +8 -1
  108. data/lib/paper_trail_diff.rb +56 -110
  109. data/sig/generated/paper_trail_diff/activity_belongs_to_event_applier.rbs +24 -2
  110. data/sig/generated/paper_trail_diff/activity_boundary.rbs +6 -0
  111. data/sig/generated/paper_trail_diff/activity_child_candidate_loader.rbs +46 -5
  112. data/sig/generated/paper_trail_diff/activity_collection_event_applier.rbs +7 -4
  113. data/sig/generated/paper_trail_diff/activity_collection_record_updater.rbs +11 -2
  114. data/sig/generated/paper_trail_diff/activity_collection_route_updater.rbs +8 -6
  115. data/sig/generated/paper_trail_diff/activity_event.rbs +27 -18
  116. data/sig/generated/paper_trail_diff/activity_event_record_normalizer.rbs +7 -11
  117. data/sig/generated/paper_trail_diff/activity_event_record_resolver.rbs +26 -8
  118. data/sig/generated/paper_trail_diff/activity_event_snapshot_refresher.rbs +10 -2
  119. data/sig/generated/paper_trail_diff/activity_history.rbs +23 -26
  120. data/sig/generated/paper_trail_diff/activity_relationship.rbs +0 -6
  121. data/sig/generated/paper_trail_diff/activity_root_snapshot_refresher.rbs +5 -0
  122. data/sig/generated/paper_trail_diff/activity_snapshot_sequence.rbs +53 -10
  123. data/sig/generated/paper_trail_diff/activity_timeline_builder.rbs +64 -38
  124. data/sig/generated/paper_trail_diff/activity_transaction_applier.rbs +28 -0
  125. data/sig/generated/paper_trail_diff/activity_tree_filter.rbs +46 -38
  126. data/sig/generated/paper_trail_diff/activity_tree_places.rbs +45 -0
  127. data/sig/generated/paper_trail_diff/activity_version_collector.rbs +21 -11
  128. data/sig/generated/paper_trail_diff/analysis.rbs +6 -5
  129. data/sig/generated/paper_trail_diff/analysis_batch.rbs +8 -6
  130. data/sig/generated/paper_trail_diff/association_activity_edge.rbs +58 -45
  131. data/sig/generated/paper_trail_diff/association_activity_selection.rbs +20 -3
  132. data/sig/generated/paper_trail_diff/association_discovery.rbs +2 -2
  133. data/sig/generated/paper_trail_diff/association_key.rbs +2 -11
  134. data/sig/generated/paper_trail_diff/association_traversal.rbs +43 -44
  135. data/sig/generated/paper_trail_diff/batch_boundary_resolver.rbs +0 -2
  136. data/sig/generated/paper_trail_diff/batched_root_analyses.rbs +40 -17
  137. data/sig/generated/paper_trail_diff/batched_root_analyzer.rbs +2 -2
  138. data/sig/generated/paper_trail_diff/batched_root_versions.rbs +2 -11
  139. data/sig/generated/paper_trail_diff/branch_snapshot_refresher.rbs +12 -8
  140. data/sig/generated/paper_trail_diff/candidate_table.rbs +97 -0
  141. data/sig/generated/paper_trail_diff/change_attribution.rbs +9 -16
  142. data/sig/generated/paper_trail_diff/collection_identity_index.rbs +33 -13
  143. data/sig/generated/paper_trail_diff/collection_transition.rbs +2 -2
  144. data/sig/generated/paper_trail_diff/comparison_batch.rbs +5 -0
  145. data/sig/generated/paper_trail_diff/database_time.rbs +48 -0
  146. data/sig/generated/paper_trail_diff/deleted_analysis_batch.rbs +13 -15
  147. data/sig/generated/paper_trail_diff/deleted_root_filter.rbs +4 -0
  148. data/sig/generated/paper_trail_diff/diagnostics.rbs +13 -31
  149. data/sig/generated/paper_trail_diff/endpoint.rbs +14 -1
  150. data/sig/generated/paper_trail_diff/errors.rbs +0 -8
  151. data/sig/generated/paper_trail_diff/exact_column_type.rbs +51 -0
  152. data/sig/generated/paper_trail_diff/historical_snapshot_store.rbs +51 -31
  153. data/sig/generated/paper_trail_diff/instrumentation.rbs +0 -5
  154. data/sig/generated/paper_trail_diff/nested_comparator.rbs +21 -0
  155. data/sig/generated/paper_trail_diff/paper_trail_adapter.rbs +18 -29
  156. data/sig/generated/paper_trail_diff/prepared_activity_index.rbs +138 -94
  157. data/sig/generated/paper_trail_diff/prepared_child_candidates.rbs +10 -2
  158. data/sig/generated/paper_trail_diff/prepared_edge_loader.rbs +4 -21
  159. data/sig/generated/paper_trail_diff/prepared_history.rbs +22 -79
  160. data/sig/generated/paper_trail_diff/prepared_history_loader.rbs +24 -32
  161. data/sig/generated/paper_trail_diff/prepared_record_index.rbs +137 -63
  162. data/sig/generated/paper_trail_diff/prepared_snapshot_builder.rbs +22 -13
  163. data/sig/generated/paper_trail_diff/prepared_state_association_reader.rbs +41 -28
  164. data/sig/generated/paper_trail_diff/recorded_changes.rbs +19 -3
  165. data/sig/generated/paper_trail_diff/recorded_owner.rbs +39 -0
  166. data/sig/generated/paper_trail_diff/root_version_selection.rbs +4 -1
  167. data/sig/generated/paper_trail_diff/scope_condition.rbs +65 -52
  168. data/sig/generated/paper_trail_diff/scope_ranking.rbs +10 -23
  169. data/sig/generated/paper_trail_diff/scoped_analysis.rbs +11 -6
  170. data/sig/generated/paper_trail_diff/scoped_analysis_builder.rbs +7 -2
  171. data/sig/generated/paper_trail_diff/scoped_root_selection.rbs +49 -43
  172. data/sig/generated/paper_trail_diff/selection_window.rbs +19 -0
  173. data/sig/generated/paper_trail_diff/snapshot.rbs +37 -38
  174. data/sig/generated/paper_trail_diff/snapshot_members.rbs +58 -0
  175. data/sig/generated/paper_trail_diff/snapshot_normalizer.rbs +0 -4
  176. data/sig/generated/paper_trail_diff/stored_form.rbs +63 -0
  177. data/sig/generated/paper_trail_diff/stored_json_values.rbs +0 -2
  178. data/sig/generated/paper_trail_diff/stored_time_precision.rbs +33 -20
  179. data/sig/generated/paper_trail_diff/stored_values.rbs +18 -2
  180. data/sig/generated/paper_trail_diff/support.rbs +96 -16
  181. data/sig/generated/paper_trail_diff/time_of_day.rbs +4 -0
  182. data/sig/generated/paper_trail_diff/time_range.rbs +49 -4
  183. data/sig/generated/paper_trail_diff/time_version_range.rbs +3 -0
  184. data/sig/generated/paper_trail_diff/timeline_builder.rbs +3 -6
  185. data/sig/generated/paper_trail_diff/timeline_range.rbs +29 -8
  186. data/sig/generated/paper_trail_diff/timeline_snapshot_provider.rbs +17 -4
  187. data/sig/generated/paper_trail_diff/total_order.rbs +9 -3
  188. data/sig/generated/paper_trail_diff/transaction_anchors.rbs +80 -0
  189. data/sig/generated/paper_trail_diff/transaction_cut.rbs +43 -176
  190. data/sig/generated/paper_trail_diff/transaction_ends.rbs +124 -0
  191. data/sig/generated/paper_trail_diff/traversal_preparer.rbs +6 -11
  192. data/sig/generated/paper_trail_diff/{approximate_paths.rbs → unreadable_paths.rbs} +6 -7
  193. data/sig/generated/paper_trail_diff/value_objects.rbs +4 -2
  194. data/sig/generated/paper_trail_diff/version_association_candidate_scope.rbs +11 -5
  195. data/sig/generated/paper_trail_diff/version_boundary.rbs +0 -14
  196. data/sig/generated/paper_trail_diff/version_query.rbs +26 -0
  197. data/sig/generated/paper_trail_diff/version_scope_filter.rbs +28 -2
  198. data/sig/generated/paper_trail_diff/version_sequence_diagnostics.rbs +4 -15
  199. data/sig/generated/paper_trail_diff/version_table.rbs +4 -0
  200. data/sig/generated/paper_trail_diff.rbs +22 -23
  201. metadata +28 -20
  202. data/lib/paper_trail_diff/activity_target_candidate_loader.rb +0 -123
  203. data/lib/paper_trail_diff/fallback_paths.rb +0 -35
  204. data/lib/paper_trail_diff/habtm_transaction_owners.rb +0 -70
  205. data/lib/paper_trail_diff/historical_association_reifier.rb +0 -161
  206. data/lib/paper_trail_diff/historical_filter.rb +0 -210
  207. data/lib/paper_trail_diff/own_window.rb +0 -35
  208. data/lib/paper_trail_diff/prepared_association_reifier.rb +0 -51
  209. data/sig/generated/paper_trail_diff/activity_target_candidate_loader.rbs +0 -74
  210. data/sig/generated/paper_trail_diff/fallback_paths.rbs +0 -22
  211. data/sig/generated/paper_trail_diff/habtm_transaction_owners.rbs +0 -41
  212. data/sig/generated/paper_trail_diff/historical_association_reifier.rbs +0 -58
  213. data/sig/generated/paper_trail_diff/historical_filter.rbs +0 -96
  214. data/sig/generated/paper_trail_diff/own_window.rbs +0 -22
  215. data/sig/generated/paper_trail_diff/prepared_association_reifier.rbs +0 -27
data/docs/reference.md CHANGED
@@ -10,9 +10,8 @@ including ones most applications never need.
10
10
  - [Choosing a method](#choosing-a-method)
11
11
  - [Choosing a range](#choosing-a-range)
12
12
  - [compare](#compare) and [compare_many](#compare_many)
13
- - [timeline](#timeline)
14
- - [activity_timeline](#activity_timeline)
15
- - [analyze](#analyze)
13
+ - [analyze](#analyze), with its [timeline](#timeline) and
14
+ [activity_timeline](#activity_timeline)
16
15
  - [Reports for many records](#reports-for-many-records):
17
16
  `analyze_many`, `analyze_scope`, `report`
18
17
  - [Associations](#associations)
@@ -24,13 +23,14 @@ including ones most applications never need.
24
23
  - [Models, schemas, and edge cases](#models-schemas-and-edge-cases)
25
24
  - [Instrumentation](#instrumentation)
26
25
  - [Errors](#errors)
26
+ - [What results rest on](#what-results-rest-on)
27
27
  - [Limitations](#limitations)
28
28
 
29
29
  ## Words used on this page
30
30
 
31
31
  | Word | Meaning |
32
32
  | --- | --- |
33
- | Root record | The record you ask about, such as the article in `timeline(article)` |
33
+ | Root record | The record you ask about, such as the article in `analyze(article)` |
34
34
  | Child | An associated record you include with `associations:`, such as a comment |
35
35
  | Current state | The record's saved values in the database right now |
36
36
  | Snapshot | A read-only copy of a record's data at one point, returned by this gem |
@@ -75,7 +75,9 @@ Six things follow from this:
75
75
  with `update_columns` or with versioning off creates no version, but it
76
76
  changes the values the record's next version stores, or its current row. The
77
77
  gem reads the result of a change from there, so the write appears in the step
78
- for that record's previous recorded change and is attributed to its author.
78
+ for that record's previous recorded change, whose source is that change's
79
+ version. In [change rows](#change-rows) the write has a row of its own,
80
+ credited to no one.
79
81
  Ending a range at a version leaves out only the writes after it. A column
80
82
  that `has_paper_trail only:` or `ignore:` leaves out of `object_changes` is
81
83
  read the same way, so a key saved with a version is that version's change.
@@ -83,15 +85,20 @@ Six things follow from this:
83
85
  in the step of the parent's previous change; pass the column in `ignore:` to
84
86
  leave it out.
85
87
  [`recorded_changes`](#what-a-version-recorded) reads what a version itself
86
- recorded, and activity steps can [include it](#what-each-event-recorded-recorded_changes-true).
87
- With it, [change rows](#change-rows) give such a write a row of its own,
88
- credited to no one.
88
+ recorded, and activity steps [include it](#what-each-event-recorded).
89
89
  - **A record created without a version looks as if it always existed.** A
90
90
  row written with versioning off, or imported with `insert_all`, has no
91
91
  `create` version, so history never reports it as added: its earliest
92
92
  version's stored values are its state from before history began, and an
93
93
  association includes it there. Rows from before PaperTrail was installed
94
- are the same, which is usually what you want.
94
+ are the same, which is usually what you want. One such row needs care: a
95
+ child whose first version moves it to another owner. That version stores
96
+ the old owner's key, but PaperTrail-AssociationTracking records the new
97
+ one. Activity steps, `report`, and `analyze_scope` read the old owner from
98
+ the version's stored state, so they report the child leaving it; `compare`
99
+ and `analyze` without `activity: true` find a past owner's children by
100
+ PaperTrail-AssociationTracking's records only, so there the owner it left
101
+ never held it. Every later move is found everywhere.
95
102
  - **Pruned history is gone.** With `has_paper_trail limit:`, PaperTrail
96
103
  deletes a record's oldest versions, and the earliest one left becomes its
97
104
  start: states before it cannot be read, and an older version passed in is
@@ -103,15 +110,14 @@ Six things follow from this:
103
110
  | --- | --- |
104
111
  | Net difference between two versions, or a version and the current record | `compare(from, to)` |
105
112
  | The same for a list of `{ from:, to: }` pairs, one per record | `compare_many(pairs)` |
106
- | Each change to one record, version by version | `timeline(record)` |
107
- | Each change to one record and its chosen associations, with who made it | `activity_timeline(record, associations: ...)` |
108
- | Net difference and timeline together | `analyze(record)` |
109
- | The same, plus the activity timeline | `analyze(record, activity: true)` |
113
+ | Net difference and each change to one record, version by version | `analyze(record)`, then `diff` and `timeline` |
114
+ | The same, plus each change to its chosen associations, with who made it | `analyze(record, associations: ..., activity: true)`, then `activity_timeline` |
110
115
  | Analyses for an array of records | `analyze_many(records)` |
111
116
  | Analyses for the records a relation selects, over a time window | `analyze_scope(scope, within:, limit:)` |
112
117
  | Recent activity through now, for the records a relation selects | `report(scope, since:, limit:)` |
113
118
 
114
- `timeline` and `activity_timeline` differ in which versions become steps. Given
119
+ An analysis's `timeline` and `activity_timeline` differ in which versions
120
+ become steps. Given
115
121
  an article with two comment edits between two article versions:
116
122
 
117
123
  ```text
@@ -131,14 +137,14 @@ belongs to one recorded event, which is what you need to show who did what.
131
137
 
132
138
  ## Choosing a range
133
139
 
134
- `timeline`, `activity_timeline`, and `analyze` cover the record's whole history
135
- through its current state unless you say otherwise:
140
+ `analyze` covers the record's whole history through its current state unless
141
+ you say otherwise:
136
142
 
137
143
  ```ruby
138
- PaperTrailDiff.timeline(article) # all of it
139
- PaperTrailDiff.timeline(article, from: some_version) # from a version to now
140
- PaperTrailDiff.timeline(article, from: :first, to: later_version)
141
- PaperTrailDiff.timeline(article, within: 1.week.ago..Time.current)
144
+ PaperTrailDiff.analyze(article) # all of it
145
+ PaperTrailDiff.analyze(article, from: some_version) # from a version to now
146
+ PaperTrailDiff.analyze(article, from: :first, to: later_version)
147
+ PaperTrailDiff.analyze(article, within: 1.week.ago..Time.current)
142
148
  ```
143
149
 
144
150
  - `from:` defaults to `:first`, the record's earliest version.
@@ -166,60 +172,76 @@ and `...` excludes it, which is useful for back-to-back windows:
166
172
 
167
173
  ```ruby
168
174
  window = Time.zone.parse("2026-08-01")...Time.zone.parse("2026-09-01")
169
- steps = PaperTrailDiff.timeline(article, within: window)
175
+ steps = PaperTrailDiff.analyze(article, within: window).timeline
170
176
  ```
171
177
 
178
+ A bound is read to the microsecond, as adapters write it into SQL, so a
179
+ version saved in the microsecond of a `Time.now` start is inside the window.
180
+ Where the versions table's `created_at` keeps fewer digits, as a MySQL
181
+ `datetime` column without a precision keeps whole seconds, a bound is read to
182
+ those: a window from 12:00:00.7 starts at 12:00:00, with the versions saved in
183
+ that second.
184
+
172
185
  A `Date` bound is a whole day in `Time.zone`, so `Date.today..Date.today` is
173
186
  all of today and `august...september` stops before September 1. A string is a
174
- time in `Time.zone` unless it names an offset. Without `Time.zone`, both are
187
+ time in `Time.zone` unless it names an offset, and must name a real day:
188
+ `"12"` or `"2026-02-30"` raises `InvalidTimeRangeError`. Without `Time.zone`, both are
175
189
  read in UTC, never in the server's own zone.
176
190
 
177
191
  An endless range, such as `1.day.ago..`, runs through the current saved state:
178
192
  it holds every version saved since it began, whatever time its server's clock
179
193
  gave it, and it ends at the current record. `report` uses one.
180
194
 
181
- A window edge that falls inside a transaction moves back to where that
182
- transaction began, so the whole transaction is in the later window, as it is
183
- when a range [starts or ends at a version](#choosing-a-range). It moves when
184
- the transaction saved the root record after the edge, such as a comment edit
185
- and the `touch: true` article version saved with it, or saved the root before
186
- the edge and a record of a class on the requested paths after it. A
187
- transaction that saved the root only before the edge, and nothing on its paths
188
- after it, moves no edge: the root's change is in the earlier window, with its
189
- version, even when the transaction went on to save another article. A
190
- transaction that saved only associated records moves no edge either. When it
191
- saved some of them before the edge and some after, its changes are still all
192
- in one window: in the later one when a version it saved after the edge is of a
193
- record on the requested paths before or after the transaction, and otherwise
194
- in the earlier one. A polymorphic `belongs_to` names its target's class only in
195
- each record, so a target saved after the edge moves nothing: the root's change
196
- is then in the earlier window and the target's in the later one. A
197
- [transaction group](#one-step-per-transaction-group-transaction) lists in
198
- `sources` only the versions inside its window. So back-to-back windows, or a
199
- `report` with `since:` after an earlier report, show each change exactly
200
- once, credited to the transaction that made it. Each root moves its own
201
- edges, so in a batch two roots can start a few moments apart.
202
-
203
- `analysis.window` is the window an `Analysis` covers after any such move, as a
204
- Ruby range, endless for `report` and any other endless window. It is `nil` when
205
- `within:` or `since:` was not given. Every step of the analysis is inside it,
206
- so to check a step against the window, use `analysis.window` rather than the
207
- range you passed: a step at the start of a moved window begins before the time
208
- you asked for.
195
+ A transaction takes effect where it saved its last version, so a window
196
+ reports the transactions that end inside it, each of them whole. One that
197
+ began before the window and ends inside it is reported there, with what it
198
+ saved before the window: a comment edit, say, and the `touch: true` article
199
+ version saved with it after the window's start. One that begins inside the
200
+ window and ends after it is left to the window its last version is in. So
201
+ back-to-back windows, or a `report` with `since:` after an earlier report,
202
+ show each change exactly once, credited to the transaction that made it and to
203
+ its own version, and a
204
+ [transaction group](#one-step-per-transaction-group-transaction) lists every
205
+ version its transaction saved, wherever they fall.
206
+
207
+ Where a transaction ends is read from its version table: the last version it
208
+ saved there, of any record, on the requested paths or not. So every window
209
+ places a transaction alike, whichever of its records the window reads. A
210
+ version table whose ids do not count up, such as one keyed by UUID, names the
211
+ last version by when it was saved. Without associations, each version of the
212
+ record is reported where it was saved, since nothing else of its transaction
213
+ is read. `analyze` without `activity:` compares the record's
214
+ own versions, and report each where it was saved too. With associations, the
215
+ records around each of those versions still read as they stood before every
216
+ transaction that had not ended yet, so an associated record's change is
217
+ reported once, in the step where its transaction ends.
218
+
219
+ A history read without a window begins at the record's first version, or at
220
+ `from:`, before that version's transaction took effect, and ends where the
221
+ transaction of its last version, or of `to:`, took effect. What another
222
+ transaction saved before the start, such as an author it renamed before the
223
+ article was created, is part of the state the history begins in if that
224
+ transaction ended first, and is reported in its own step if it ended later.
225
+ So two ranges that meet at a version report each change once, as the range
226
+ over both does, and `compare` reads a version as both ranges do. A destroyed
227
+ record's history ends where its destruction took effect; a change another
228
+ transaction committed later is not the record's.
229
+
230
+ Two transactions that save in one record's tree at the same time interleave
231
+ their versions. Each is reported as if it ran alone, in the order they end: a
232
+ record reads as it stood before every transaction that had not ended yet.
233
+
234
+ The window itself does not move. `analysis.window` is the window you asked
235
+ for, as a Ruby range, endless for `report` and any other endless window, and
236
+ `nil` when `within:` or `since:` was not given. A step of a transaction that
237
+ began before the window can hold a version saved before `analysis.window`
238
+ begins.
209
239
 
210
240
  ```ruby
211
241
  analysis = PaperTrailDiff.analyze_many(articles, within: window, activity: true).values.first
212
- analysis.window # => window, or one that starts earlier
242
+ analysis.window # => window
213
243
  ```
214
244
 
215
- Each move emits a `moved_window.paper_trail_diff` notification whose payload
216
- has `item_type`, `item_id`, the `requested` range, and the moved `window`. In
217
- history saved by your application, an edge moves back by the time one
218
- transaction took, usually well under a second. A move of minutes or days
219
- means a transaction ran that long, or that the versions' times were changed
220
- after they were saved, as a test might do; see
221
- [writing history in tests](#writing-history-in-tests).
222
-
223
245
  A closed window can still change. PaperTrail stamps a version's `created_at`
224
246
  when it builds the version, inside its transaction, and the transaction commits
225
247
  later. A transaction that stamped a change inside the window and committed
@@ -232,12 +254,12 @@ open transactions, so it cannot tell when a window has settled.
232
254
  To show what the window's last change produced, the gem reads the state just
233
255
  before the next change after the window:
234
256
 
235
- - With `activity_timeline`, or `analyze` with `activity: true`, that is the next
257
+ - With `activity: true`, that is the next
236
258
  version of the record or of any record on a requested association path. If
237
259
  none was recorded after the window, it reads the current record instead,
238
260
  and the last step's `to_boundary.kind` is `:current`. So a window that ended
239
261
  long ago ends at its own end, even when only a comment changed since.
240
- - `timeline`, and `analyze` without `activity:`, compare the record's own
262
+ - Without `activity:`, `analyze` compares the record's own
241
263
  versions. The last step runs to the record's next version, or to the
242
264
  current record when it has none, and an association change made in between
243
265
  is part of that step, credited to its author. Use `activity: true` to keep
@@ -251,7 +273,7 @@ in the step for that record's last recorded change.
251
273
  If the window's last change destroyed the record, the window closes on that
252
274
  deletion instead. See [a destroyed record](#a-destroyed-record).
253
275
 
254
- `timeline` returns no steps for a window with no versions of the root record.
276
+ `timeline` holds no steps for a window with no versions of the root record.
255
277
  `activity_timeline` still reports chosen associations that changed in such a
256
278
  window.
257
279
 
@@ -263,11 +285,12 @@ relation and returns a narrower one:
263
285
  ```ruby
264
286
  user_edits = ->(scope) { scope.where.not(whodunnit: nil) }
265
287
 
266
- PaperTrailDiff.timeline(article, within: window, version_scope: user_edits)
288
+ PaperTrailDiff.analyze(article, within: window, version_scope: user_edits)
267
289
  ```
268
290
 
269
- It is accepted by `timeline`, `activity_timeline`, `analyze`, `analyze_many`,
270
- `analyze_scope`, and `report`.
291
+ It is accepted by `analyze`, `analyze_many`, `analyze_scope`, and `report`. It may return the relation narrowed, or an
292
+ array of versions taken from it. Anything else, such as a relation on another
293
+ class or an array of IDs, raises `ConfigurationError`.
271
294
 
272
295
  - Each reported change is compared with the version right after it, even if
273
296
  that version is filtered out. So each step shows exactly what that one change
@@ -281,7 +304,7 @@ It is accepted by `timeline`, `activity_timeline`, `analyze`, `analyze_many`,
281
304
  - `timeline` looks at the root record's versions only, so someone who only
282
305
  edited comments has none for it to report. Activity reports their changes:
283
306
  see [one person's changes](#one-persons-changes).
284
- - In activity (`activity_timeline`, `activity: true`, and `report`), it
307
+ - In activity (`activity: true`, and `report`), it
285
308
  chooses the changes on the requested associations as well. A transaction is
286
309
  reported whole, every step of it, when the filter keeps any version saved
287
310
  in it, of whichever record: PT-AT shows a transaction's changes together, at
@@ -289,13 +312,17 @@ It is accepted by `timeline`, `activity_timeline`, `analyze`, `analyze_many`,
289
312
  saved outside a transaction is reported when the filter keeps it. Every
290
313
  version is still read, so each step shows what its own change did, and an
291
314
  analysis starts at the first change the filter keeps and ends after the
292
- last. Without associations, the steps are the root's versions the filter
315
+ last, a kept version of a record outside the root's tree being no change
316
+ of the root's. Without associations, the steps are the root's versions the filter
293
317
  keeps, as `timeline` reports them.
294
318
  - In `analyze_scope` and `report`, it also chooses which records are selected:
295
319
  a record is selected only when the filter keeps one of its own versions in
296
- the window, or a version of a record on a requested association. A record
297
- changed only by versions it drops would have nothing to report, so it is
298
- left out, and it does not count toward `limit:`.
320
+ the window, or a version of a record on a requested association. With
321
+ associations, as activity reports them, it keeps a version when it keeps
322
+ any version of that version's transaction, so a record is selected
323
+ whenever its activity reports something. A record changed only by versions
324
+ it drops would have nothing to report, so it is left out, and it does not
325
+ count toward `limit:`.
299
326
  - The record and its requested associations keep their versions in one table
300
327
  (see [custom version classes](#models-schemas-and-edge-cases)), and the
301
328
  filter reads it for all of them. A condition on `item_type` or `item_id`
@@ -340,8 +367,7 @@ diff.to_h
340
367
  deleted.
341
368
  - A current record must be saved, not destroyed, and have no unsaved changes.
342
369
  The gem reloads it, so in-memory edits and cached associations are ignored.
343
- - Options: `associations:`, `ignore:`, and `allow_approximate:` (see
344
- [costly associations](#costly-associations)).
370
+ - Options: `associations:` and `ignore:`.
345
371
 
346
372
  ## compare_many
347
373
 
@@ -365,20 +391,61 @@ diffs.fetch(["Order", orders.first.id.to_s]) # => PaperTrailDiff::Diff
365
391
  record, so `{ from: :first, to: :first }` raises.
366
392
  - A record with no versions gets an empty `Diff`.
367
393
  - Each record can appear in only one pair, because results are keyed by record.
368
- - Options: `associations:`, `ignore:`, and `allow_approximate:` (see
369
- [costly associations](#costly-associations)).
394
+ - Options: `associations:` and `ignore:`.
370
395
 
371
396
  If you look up versions yourself, do it in bulk. Looking up one record at a
372
397
  time brings back the per-record queries this method avoids.
373
398
 
399
+ ## analyze
400
+
401
+ `analyze(record)` returns an `Analysis` with the net `diff` and the `timeline`
402
+ for one range, reading each version once:
403
+
404
+ ```ruby
405
+ analysis = PaperTrailDiff.analyze(article, associations: ["comments.replies"], activity: true)
406
+
407
+ analysis.diff # net change over the range
408
+ analysis.timeline # one step per version of the record
409
+ analysis.activity_timeline # nil unless activity: true
410
+ analysis.from_snapshot # the full state at the start (nil before creation)
411
+ analysis.to_snapshot # the full state at the end
412
+ analysis.window # the time window it covers, or nil without within:
413
+ analysis.to_h(snapshots: true, metadata: true)
414
+ ```
415
+
416
+ - See [choosing a range](#choosing-a-range) for `from:`, `to:`, and `within:`.
417
+ - `from_snapshot` is the record as it was when the range began: before the
418
+ first change in a window, or before the change of the version you passed as
419
+ `from:`. With `version_scope:`, a window begins at the first change the
420
+ filter keeps, on the record or, with `activity: true`, on its associations.
421
+ It is `nil` when the record was created inside the range; the state right
422
+ after it was created is then the first activity step's `to_snapshot`, which
423
+ `snapshots: true` keeps.
424
+ - To read the record at one version, with its values typed and its
425
+ associations, take `from_snapshot` from a range that starts there:
426
+ `PaperTrailDiff.analyze(article, from: version, to: article).from_snapshot`.
427
+ Don't decode `version.object` yourself; the gem casts what PaperTrail
428
+ stores, which a `json` column or an enum leaves in another form.
429
+ - When nothing in the range is reported, the analysis is empty: an empty
430
+ `diff` and timelines, and `nil` for `from_snapshot` and `to_snapshot`. Here
431
+ `nil` means no state was read, not that the record did not exist; reading
432
+ one would rebuild the record's whole graph, a cost per record in a batch.
433
+ Use `compare` with a version and the record to see a state that did not
434
+ change.
435
+ - `activity: true` also builds the activity timeline. `snapshots:`, `group:`,
436
+ and `recorded_changes:` apply to the activity timeline and require
437
+ `activity: true`.
438
+ - Options: `from:`, `to:`, `within:`, `associations:`, `ignore:`, `activity:`,
439
+ `version_scope:`, `snapshots:`, `group:`, `recorded_changes:`.
440
+
374
441
  ## timeline
375
442
 
376
- `timeline(record)` returns one step for each pair of neighboring versions of the
377
- root record, ending at its current state by default. See
443
+ An analysis's `timeline` holds one step for each pair of neighboring versions
444
+ of the root record, ending at its current state by default. See
378
445
  [choosing a range](#choosing-a-range) for `from:`, `to:`, and `within:`.
379
446
 
380
447
  ```ruby
381
- steps = PaperTrailDiff.timeline(article)
448
+ steps = PaperTrailDiff.analyze(article).timeline
382
449
 
383
450
  steps.first.diff # a PaperTrailDiff::Diff
384
451
  steps.first.empty? # true if nothing reported changed
@@ -400,17 +467,17 @@ steps.reject(&:empty?) # hide steps with no reported changes
400
467
  step. `from` and `to` are boundary hashes with `kind`, `version_id`,
401
468
  `item_type`, `item_id`, and `recorded_at`. `to_h(metadata: true)` adds author,
402
469
  event, transaction ID, and record to each boundary.
403
- - Options: `from:`, `to:`, `within:`, `associations:`, `ignore:`,
404
- `version_scope:`, `allow_approximate:`.
405
470
 
406
471
  ## activity_timeline
407
472
 
408
- `activity_timeline(record, associations: ...)` returns one step for each
409
- recorded event of the root record **or** a chosen association. It ends at the
410
- current record by default.
473
+ With `activity: true`, an analysis's `activity_timeline` holds one step for
474
+ each recorded event of the root record **or** a chosen association. It ends at
475
+ the current record by default.
411
476
 
412
477
  ```ruby
413
- steps = PaperTrailDiff.activity_timeline(article, associations: ["comments.replies", :author])
478
+ steps = PaperTrailDiff.analyze(
479
+ article, associations: ["comments.replies", :author], activity: true
480
+ ).activity_timeline
414
481
 
415
482
  steps.reject(&:empty?).each do |step|
416
483
  step.source_boundary.whodunnit # who made this change
@@ -438,9 +505,6 @@ end
438
505
  `to_h(snapshots: true)` adds the retained snapshots.
439
506
  - A child's change becomes visible at the next recorded event, or at the
440
507
  current record. You do not need to save the article after each comment change.
441
- - Options: `from:`, `to:`, `within:`, `associations:`, `ignore:`,
442
- `version_scope:`, `snapshots:`, `group:`, `recorded_changes:`,
443
- `allow_approximate:`.
444
508
 
445
509
  ### One person's changes
446
510
 
@@ -451,9 +515,10 @@ a version in, on the record or on its associations:
451
515
  <!-- executable:readme-person-scope -->
452
516
  ```ruby
453
517
  priya = ->(versions) { versions.where(whodunnit: "Priya Shah") }
454
- steps = PaperTrailDiff.activity_timeline(
455
- article, within: window, associations: %i[comments tags], version_scope: priya
456
- )
518
+ steps = PaperTrailDiff.analyze(
519
+ article, within: window, associations: %i[comments], activity: true,
520
+ version_scope: priya
521
+ ).activity_timeline
457
522
 
458
523
  steps.map { |step| step.source_boundary.whodunnit }.uniq # ["Priya Shah"]
459
524
  ```
@@ -463,9 +528,9 @@ To count everyone's changes from one read, group the steps in Ruby by
463
528
 
464
529
  <!-- executable:readme-person-changes -->
465
530
  ```ruby
466
- steps = PaperTrailDiff.activity_timeline(
467
- article, within: window, associations: %i[comments tags]
468
- )
531
+ steps = PaperTrailDiff.analyze(
532
+ article, within: window, associations: %i[comments], activity: true
533
+ ).activity_timeline
469
534
 
470
535
  attributed = steps.reject(&:empty?)
471
536
  by_priya = attributed.select { |step| step.source_boundary.whodunnit == "Priya Shah" }
@@ -478,7 +543,7 @@ authors = attributed.group_by { |step| step.source_boundary.whodunnit }
478
543
  ```
479
544
 
480
545
  For many records, use `report` or `analyze_many(..., activity: true)` instead of
481
- calling `activity_timeline` in a loop, so the database work is shared. With
546
+ calling `analyze` in a loop, so the database work is shared. With
482
547
  `version_scope:`, `report` selects only the records that person changed.
483
548
 
484
549
  ### One step per transaction: `group: :transaction`
@@ -488,7 +553,7 @@ action shows up as several steps. `group: :transaction` combines steps from the
488
553
  same database transaction:
489
554
 
490
555
  ```ruby
491
- PaperTrailDiff.activity_timeline(article, associations: [:comments], group: :transaction)
556
+ PaperTrailDiff.analyze(article, associations: [:comments], activity: true, group: :transaction)
492
557
  ```
493
558
 
494
559
  - A combined step compares the state before the transaction with the state after
@@ -508,11 +573,13 @@ PaperTrailDiff.activity_timeline(article, associations: [:comments], group: :tra
508
573
  the savepoint keeps one group.
509
574
  - A step joins only the group of the step just before it. Two transactions
510
575
  that save in the same tree at the same time, so that their versions
511
- interleave, each form a group for every run of their own versions: the
512
- state between two runs holds the other transaction's change, so no single
513
- step could show either one alone.
514
- - Also accepted by `analyze`, `analyze_many`, and `analyze_scope` with
515
- `activity: true`, and by `report`.
576
+ interleave, each form a group for every run of their own versions. A
577
+ transaction's changes to associated records are read once it has ended
578
+ (see [version order](#version-order)), so they appear in the group of its
579
+ last run; the changes its root versions record appear in their own runs.
580
+ - Also accepted by `analyze_many` and `analyze_scope` with `activity: true`,
581
+ and by `report`, which groups by default when given `associations:` (pass
582
+ `group: nil` to turn it off).
516
583
 
517
584
  Without grouping, a step inside a transaction can look empty. A child's new
518
585
  value is only visible at the next recorded event, and inside a transaction that
@@ -527,7 +594,9 @@ A step's `diff` holds only what changed. To show unchanged fields too, such as
527
594
  a comment's author next to an edited comment body, keep the snapshots:
528
595
 
529
596
  ```ruby
530
- steps = PaperTrailDiff.activity_timeline(article, associations: [:comments], snapshots: true)
597
+ steps = PaperTrailDiff.analyze(
598
+ article, associations: [:comments], activity: true, snapshots: true
599
+ ).activity_timeline
531
600
 
532
601
  step = steps.reject(&:empty?).last
533
602
  step.from_snapshot.associations["comments"].records.first.attributes["author"]
@@ -537,21 +606,22 @@ step.from_snapshot.associations["comments"].records.first.attributes["author"]
537
606
  do use memory, because each one contains every chosen association.
538
607
  - `from_snapshot` is `nil` for a step starting at a `create` version, because the
539
608
  record did not exist yet.
540
- - Also accepted by `analyze`, `analyze_many`, and `analyze_scope` with
541
- `activity: true`, and by `report`.
609
+ - Also accepted by `analyze_many` and `analyze_scope` with `activity: true`,
610
+ and by `report`.
542
611
  - [`net_changes`](#net-changes) reads them, so it needs this option.
543
612
 
544
- ### What each event recorded: `recorded_changes: true`
613
+ ### What each event recorded
545
614
 
546
- A step's `diff` compares the state before and after an event. To also see what
547
- PaperTrail [stored with each version](#what-a-version-recorded), such as for an
548
- audit log, pass `recorded_changes: true`:
615
+ A step's `diff` compares the state before and after an event. Its boundaries
616
+ also carry what PaperTrail
617
+ [stored with each version](#what-a-version-recorded), such as for an audit
618
+ log:
549
619
 
550
620
  <!-- executable:reference-step-sources -->
551
621
  ```ruby
552
- steps = PaperTrailDiff.activity_timeline(
553
- article, associations: [:comments], group: :transaction, recorded_changes: true
554
- )
622
+ steps = PaperTrailDiff.analyze(
623
+ article, associations: [:comments], activity: true, group: :transaction
624
+ ).activity_timeline
555
625
 
556
626
  steps.reject(&:empty?).flat_map(&:sources).map do |source|
557
627
  {
@@ -574,10 +644,14 @@ end
574
644
  for the whole call, however many steps or records share the version. Read
575
645
  them from the boundary rather than calling `PaperTrailDiff.recorded_changes`
576
646
  for its version, which decodes it again each time.
577
- - Without the option, `recorded_changes` raises `ConfigurationError` instead of
578
- returning `nil`, so a missing option cannot look like a version that recorded
579
- nothing.
580
- - `to_h(metadata: true)` includes them on each boundary and source.
647
+ - `to_h(metadata: true)` includes them on each boundary and source, which
648
+ decodes every version's changes.
649
+ - `recorded_changes: false` leaves them unread: a boundary's
650
+ `recorded_changes` then raises `ConfigurationError` instead of returning
651
+ `nil`, `to_h(metadata: true)` leaves them out, and
652
+ [change rows](#change-rows) credit a field's whole change to the last of
653
+ its record's versions. The boundaries of a root `timeline`, built without
654
+ `activity: true`, never read them.
581
655
  - Names in `ignore:`, or in `ignore: { all: }`, are left out. So are names
582
656
  ignored on the root path, `"$"`, for the root's own versions. Names ignored
583
657
  on an association path are not left out, because a child's version does not
@@ -602,85 +676,18 @@ A `within:` window whose last change is the deletion ends the same way, and the
602
676
  `diff` of an `analyze` over that window ends at "no record". Removing a chosen
603
677
  child is reported as `removed` in its parent's association.
604
678
 
605
- ### HABTM limitation
606
-
607
- `has_and_belongs_to_many` join rows have no versions, so the gem cannot split
608
- their changes into separate events once a range runs past the last root version
609
- into the current record. That case raises `UnsupportedLiveActivityError`. End
610
- the range at a version instead (see the
611
- [checkpoint recipe](#saving-a-checkpoint)), or use a join model with
612
- `has_many :through`.
613
-
614
- PT-AT records HABTM members under the transaction a version was saved in, and
615
- does not say which record they belong to. If another record with a HABTM of the
616
- same name, such as a second article, also saved a version in that transaction
617
- and members were recorded there, reading the root's membership at that version
618
- raises `IncompleteAssociationHistoryError` instead of mixing both records'
619
- members. Save each HABTM owner's versions in a transaction of its own.
620
-
621
- PT-AT records membership only when the owner saves a version, so the gem knows
622
- it only at root versions. A change made between two root versions is reported
623
- in the first step after the earlier one, and credited to that step's source:
624
- usually the earlier root version, which someone else may have saved. A member
625
- created between them is reported in the step that starts with its creation
626
- instead. A change attached before a checkpoint is therefore credited to
627
- whoever saved the version before the checkpoint, not to the checkpoint's
628
- author. To credit a change to the person who made it, save a checkpoint just
629
- before the change as well as after it: the step between the two checkpoints is
630
- theirs.
631
-
632
- PT-AT works out the membership a version records from the instance that saves
633
- it: the instance's current members, with the changes that instance made undone,
634
- so that the version holds the membership from before its own event. It never
635
- forgets those changes, not even on `reload`. Only the first version an instance
636
- saves after changing a HABTM is right; each later save from it records the
637
- membership from before that change again. The gem then reports the change late,
638
- or reports a member that never left as removed and added again. Load the record
639
- again, with `find`, before saving it a second time, and save checkpoints from a
640
- freshly loaded record, as the [checkpoint recipe](#saving-a-checkpoint) does.
641
-
642
- ## analyze
679
+ With `activity: true` and associations, the deletion is reported in the
680
+ window its transaction ends in, like any other change. So a window after the
681
+ `destroy` version can still report it, when the transaction went on saving
682
+ other records, and a window after that transaction's end reports nothing: an
683
+ empty timeline and an empty diff.
643
684
 
644
- `analyze(record)` returns an `Analysis` with the net `diff` and the `timeline`
645
- for one range, reading each version once:
646
-
647
- ```ruby
648
- analysis = PaperTrailDiff.analyze(article, associations: ["comments.replies"], activity: true)
649
-
650
- analysis.diff # net change over the range
651
- analysis.timeline # the same steps timeline returns
652
- analysis.activity_timeline # nil unless activity: true
653
- analysis.from_snapshot # the full state at the start (nil before creation)
654
- analysis.to_snapshot # the full state at the end
655
- analysis.window # the time window it covers, or nil without within:
656
- analysis.to_h(snapshots: true, metadata: true)
657
- ```
658
-
659
- - It accepts the same ranges as `timeline`.
660
- - `from_snapshot` is the record as it was when the range began: before the
661
- first change in a window, or before the change of the version you passed as
662
- `from:`. With `version_scope:`, a window begins at the first change the
663
- filter keeps, on the record or, with `activity: true`, on its associations.
664
- It is `nil` when the record was created inside the range; the state right
665
- after it was created is then the first activity step's `to_snapshot`, which
666
- `snapshots: true` keeps.
667
- - To read the record at one version, with its values typed and its
668
- associations, take `from_snapshot` from a range that starts there:
669
- `PaperTrailDiff.analyze(article, from: version, to: article).from_snapshot`.
670
- Don't decode `version.object` yourself; the gem casts what PaperTrail
671
- stores, which a `json` column or an enum leaves in another form.
672
- - When nothing in the range is reported, the analysis is empty: an empty
673
- `diff` and timelines, and `nil` for `from_snapshot` and `to_snapshot`. Here
674
- `nil` means no state was read, not that the record did not exist; reading
675
- one would rebuild the record's whole graph, a cost per record in a batch.
676
- Use `compare` with a version and the record to see a state that did not
677
- change.
678
- - `activity: true` also builds the activity timeline. `snapshots:`, `group:`,
679
- and `recorded_changes:` apply to the activity timeline and require
680
- `activity: true`.
681
- - Options: `from:`, `to:`, `within:`, `associations:`, `ignore:`, `activity:`,
682
- `version_scope:`, `snapshots:`, `group:`, `recorded_changes:`,
683
- `allow_approximate:`.
685
+ A record restored afterwards under its id, as saving `version.reify` does,
686
+ is the same root before and after. A range that ends at its `destroy` then
687
+ ends before the deletion, as at any other version, and the range from the
688
+ `destroy` reports the removal, in its step to the version that restored it,
689
+ so the two report it once. The transaction that restored it is the root's
690
+ from its first event, as for a record created afresh.
684
691
 
685
692
  ## Reports for many records
686
693
 
@@ -708,7 +715,7 @@ results.fetch(["Order", order.id.to_s]).diff
708
715
  are `nil` (see [analyze](#analyze)).
709
716
  - Records must be saved and unique.
710
717
  - Options: `within:`, `associations:`, `ignore:`, `activity:`, `version_scope:`,
711
- `snapshots:`, `group:`, `recorded_changes:`, `allow_approximate:`.
718
+ `snapshots:`, `group:`, `recorded_changes:`.
712
719
 
713
720
  ### analyze_scope
714
721
 
@@ -727,6 +734,7 @@ report.analyses # { identity => Analysis } for records that still exist
727
734
  report.roots # the selected records, in relation order
728
735
  report.unreachable # identities of selected records that no longer exist
729
736
  report.deleted # { identity => Analysis or nil }, with include_deleted: true
737
+ report.total # how many existing records the relation selects, before its limit and offset
730
738
 
731
739
  report.roots.each do |order|
732
740
  report.analysis_for(order) # its Analysis, without building the identity
@@ -735,8 +743,8 @@ end
735
743
  analyses, unreachable = report # destructures into analyses and unreachable
736
744
  ```
737
745
 
738
- It takes the same options as `analyze_many`, plus `limit:`, `historical_filter:`,
739
- `max_filter_versions:`, and `include_deleted:`. `within:` can be omitted to use
746
+ It takes the same options as `analyze_many`, plus `limit:` and
747
+ `include_deleted:`. `within:` can be omitted to use
740
748
  all history.
741
749
 
742
750
  ### report
@@ -749,8 +757,13 @@ report = PaperTrailDiff.report(Article.all, since: 1.day.ago, limit: 100)
749
757
  ```
750
758
 
751
759
  It accepts `associations:`, `ignore:`, `version_scope:`, `snapshots:`, `group:`,
752
- `recorded_changes:`, `include_deleted:`, `historical_filter:`, `max_filter_versions:`,
753
- and `allow_approximate:`.
760
+ `recorded_changes:`, and `include_deleted:`.
761
+
762
+ With `associations:`, `report` groups by transaction unless told otherwise:
763
+ each save of a record and its associated records is one step, as with
764
+ [`group: :transaction`](#one-step-per-transaction-group-transaction). Pass
765
+ `group: nil` for a step per version. A report without `associations:` is not
766
+ grouped.
754
767
 
755
768
  ### Which records are selected
756
769
 
@@ -763,14 +776,14 @@ and `allow_approximate:`.
763
776
  versions and cannot show a change to its associations alone, so only a
764
777
  record's own version selects it. With
765
778
  [`version_scope:`](#reporting-only-some-changes-version_scope), only the
766
- versions the filter keeps select it, the record's own and its associations'.
779
+ versions the filter keeps select it, the record's own and its associations',
780
+ each with its whole transaction when associations are requested.
767
781
  - **An analysis can still be empty.** A record is selected by any version on its
768
782
  paths, but its analysis compares only the state you requested. A join row
769
783
  whose role changed, or a version that touched only ignored columns, selects a
770
784
  record with nothing to report.
771
785
  - **A relation checks current values.** `Order.where(status: "open")` means open
772
- now, not open during the window. Use `historical_filter:` to select by past
773
- values.
786
+ now, not open during the window.
774
787
  - **`limit:` is a safety ceiling, not a page size.** If more records are
775
788
  selected, the call raises `BatchLimitExceededError` instead of returning part
776
789
  of the answer. Narrow the relation or the window, or raise the limit.
@@ -781,16 +794,33 @@ and `allow_approximate:`.
781
794
  as sorting by the ID when it names the column, alone or after the table's
782
795
  name, as `order("title, id")` does. Give the queries that show the page the
783
796
  same tie-breaker, such as `order(:status, :id)`, so that they list the
784
- records the report analyzed. If a join repeats a record, it is analyzed
797
+ records the report analyzed. `total` counts the records the relation selects before
798
+ its `limit` and `offset`, for a pager's "page 2 of 6"; a paged relation
799
+ takes one more statement for it. A relation grouped by another column
800
+ counts its groups. Deleted records are not counted. If a join repeats a record, it is analyzed
785
801
  once, in order of first appearance. A relation grouped by anything but the
786
802
  ID, such as `select("MAX(id) AS id").group(:author_id)`, keeps its own
787
803
  order, since a database sorts groups only by what they group or aggregate.
788
- It needs one that tells its groups apart, such as `order(:author_id)`.
804
+ It needs one that tells its groups apart, such as `order(:author_id)`;
805
+ without any order it raises `ConfigurationError`.
789
806
  - Selection still scans the versions in the window, so keep windows reasonable
790
807
  for large tables. Each requested association adds one query per level, however
791
808
  many records it selects. Changes to associations are found from PT-AT's
792
809
  `version_associations`, so history recorded before PT-AT was installed selects
793
- nothing.
810
+ nothing, and neither does a `belongs_to` target's change for a record that
811
+ has no version of its own, such as one created with PaperTrail turned off:
812
+ `analyze` on that record reports the change, but no selection finds it.
813
+ The same holds below the root: a product renamed does not select an order
814
+ whose line item has no version, over `line_items.product`, nor a tag
815
+ renamed an order whose join row has none, over a `has_many :through`. After
816
+ adding PaperTrail to existing data, every row is in this state until it is
817
+ next saved. A
818
+ change below a `has_many` or `has_one` child that has no version selects
819
+ the owner its row names now, since such a child has held that key
820
+ throughout, as an analysis reads it.
821
+ - **A window with associations reads from where the transactions open at
822
+ its start began**, and selects by the versions those transactions saved
823
+ before it, but by no other version saved before the start.
794
824
 
795
825
  ### Deleted records
796
826
 
@@ -807,8 +837,9 @@ is not paginated.
807
837
  as it stood when it was destroyed, and keeps only those that match. So a report
808
838
  on `Article.where(account_id: account.id)` returns that account's deletions,
809
839
  not every account's. The relation's conditions must be plain conditions on the
810
- model's own columns, as a [readable association scope's](#costly-associations)
811
- must, ranges included; anything else, such as a join or SQL text, raises
840
+ model's own columns, as a [readable association scope's](#association-scopes)
841
+ must, ranges and equality on a date or a time included; anything else, such
842
+ as a join or SQL text, raises
812
843
  `ConfigurationError`. `Article.none` keeps none. Its order, limit, and offset
813
844
  are ignored here, since they choose a page of existing rows. A record whose
814
845
  destroy PaperTrail did not record has no state to test and stays listed.
@@ -828,53 +859,7 @@ step's `diff.record_presence_change.from` is the record just before it was
828
859
  deleted, even when it was also created inside the window, where
829
860
  `from_snapshot` is `nil`.
830
861
 
831
- ### Selecting by past values: `historical_filter:`
832
-
833
- `historical_filter:` selects records by values they had at any point in the
834
- window. For example, to find articles that were titled `"Published"` at some
835
- point in the last day, including ones published during it:
836
-
837
- ```ruby
838
- report = PaperTrailDiff.report(
839
- Article.all, since: 1.day.ago, limit: 100,
840
- historical_filter: { title: "Published" }
841
- )
842
- ```
843
-
844
- The filter checks the record as it was when its window started and after each
845
- change made inside it. That window is the one its analysis covers
846
- (`analysis.window`): a transaction that crosses an edge moves the edge to where
847
- the transaction began (see [time windows](#time-windows)). A record matches if
848
- any of those states match. With a
849
- hash, every key must be equal (`==`) once both sides are cast to the
850
- attribute's type, as `where` casts its values: `{ status: :published }` matches
851
- an enum, and a date or time matches whether the history stored it as YAML or
852
- as a string in a `json` column. Values are read from the stored history
853
- without calling `reify`, and unknown or unrecorded attributes raise an error
854
- instead of matching `nil`. For other checks, pass a callable such as
855
- `->(article) { article.title.start_with?("Pub") }`; it receives each state as a
856
- model instance and may run queries of its own.
857
-
858
- - It looks only at the record itself, not its associations, and does not check
859
- whether a value was held for the whole window.
860
- - Only the history of records the relation selects is read, and the relation's
861
- order, `limit`, and `offset` then page the ones that match. Deleted records,
862
- which a relation cannot test, are read too, and those that match are listed
863
- in `unreachable`.
864
- - Matching records the relation selects count toward `limit:`, and matching
865
- stops as soon as the limit is exceeded. Matching deleted records count only
866
- with `include_deleted: true`, as without a filter.
867
- - `max_filter_versions:` limits how many versions the filter loads, including
868
- the one version after the window it reads for each record, and the versions
869
- of deleted records. The default is 10,000. Going over raises
870
- `FilterLimitExceededError` before the extra batch is checked. It does not
871
- limit queries inside a callable.
872
- - `version_scope:` narrows which changes are reported, not which states are
873
- tested here.
874
- - It is accepted by `analyze_scope` and `report`, which select records from a
875
- relation.
876
-
877
- ### Costly associations
862
+ ### Association scopes
878
863
 
879
864
  Most associations are loaded for all records together. That includes an
880
865
  association whose scope, or whose target's default scope, is plain conditions
@@ -895,13 +880,21 @@ boolean, and enum columns, with SQL's rules for NULL. A `nil` test
895
880
  scope such as `where(deleted_at: nil)` is read too. String and text columns
896
881
  are read only on SQLite and PostgreSQL, and only without a column collation:
897
882
  MySQL and SQL Server compare strings without regard to case or trailing spaces
898
- by default, which the gem cannot repeat, and neither is PostgreSQL's
899
- `citext`.
883
+ by default, which the gem cannot repeat. Neither is PostgreSQL's `citext`,
884
+ which ignores case, nor its `character(n)`, which pads with spaces.
885
+
886
+ The gem lists the SQL column types it reads this way for each of SQLite,
887
+ PostgreSQL, MySQL (`mysql2` and `trilogy`), and SQL Server. A condition or
888
+ order on a column of any other type, or on another adapter, is not read,
889
+ like the scopes described below. On SQL Server a `datetime2` is read but not
890
+ a legacy `datetime` or `smalldatetime`, which round the times they store.
900
891
 
901
892
  Ranges, such as `where(position: 2..)` or `where(created_at: 1.day.ago...)`,
902
893
  and Arel's `gt`, `gteq`, `lt`, and `lteq`, are read on the columns an order
903
894
  can sort by, below: integer, integer enum, date, and datetime columns, with
904
- the same conditions on a datetime's precision.
895
+ the same conditions on a datetime's precision. Equality and `IN` on a date or a
896
+ datetime column, such as `where(due_on: Date.current)`, are read under those
897
+ conditions too.
905
898
 
906
899
  A `limit` or `offset`, and the order of a `has_one`, are read the same way
907
900
  when the order is total and the gem can repeat it:
@@ -937,35 +930,31 @@ comment that meets the part's conditions, not only the latest. Its own `limit`
937
930
  or `offset` ranks the rows the join yields, so a record reached through two
938
931
  join records fills two places, as in the query. A `has_one :through` whose
939
932
  own scope or whose parts have a limit, an offset, or a `has_one` order is not
940
- read.
933
+ read. One without an order reads, as Active Record does, the target of its
934
+ first join row by key.
941
935
 
942
936
  The gem cannot read the rest: a `limit` or `offset` whose order is not total or
943
937
  sorts by another column type (strings follow a collation) or by a datetime
944
938
  history cannot rank exactly, scopes that take the owner
945
939
  (`->(article) { ... }`), scopes written as SQL strings, ranges on other column
946
940
  types, scopes that join or select, and conditions on other column types or
947
- other tables, such as a string column on MySQL. For these it asks PT-AT, which costs queries per
948
- record and is approximate: PT-AT rebuilds an association from its current
949
- members, swapping in their older versions, and never checks the scope against
950
- them. A record that entered the scope since is reported as a member it was
951
- not, so a comment moved into `-> { where("position > 2") }`, or restored from
952
- a soft delete, shows as changed rather than added.
941
+ other tables, such as a string column on MySQL. Who met such a scope at a
942
+ past point cannot be told from stored versions.
953
943
 
954
944
  So every method that reads history raises `UnsupportedAssociationError` for
955
- such a path and names it. Remove it from `associations:`, rewrite its scope as
956
- plain conditions on the target's own columns, or pass `allow_approximate:
957
- true` to accept PT-AT's answer, which also accepts its cost of queries per
958
- record in batch methods. A comparison of two current records reads no history
959
- and needs no opt-in.
945
+ such a path and names it. Remove it from `associations:`, or rewrite its scope
946
+ as plain conditions on the target's own columns. A comparison of two current
947
+ records reads no history and accepts any scope. A composite foreign key is
948
+ refused the same way: association history is recorded by a single id.
960
949
 
961
950
  A polymorphic `belongs_to` is loaded together too, with one query per target
962
951
  class. Its classes are known only from the records, though, so batch methods
963
- cannot reject one with a scope they cannot read in advance: a record that
964
- points at such a class is read on its own, without an error. A scope on the
965
- polymorphic `belongs_to` itself is rejected.
952
+ cannot reject one with a default scope they cannot read in advance: reading a
953
+ record that points at such a class raises `UnsupportedAssociationError`. A
954
+ scope on the polymorphic `belongs_to` itself is rejected.
966
955
 
967
956
  This check covers known association cases only. Your model callbacks, custom
968
- attribute types, and callable filters can still run queries. See the
957
+ attribute types can still run queries. See the
969
958
  [performance guide](performance.md) for measurements.
970
959
 
971
960
  ## Associations
@@ -981,18 +970,27 @@ diff = PaperTrailDiff.compare(from, to, associations: [:author, "comments.replie
981
970
  (`associations: :comments`) or hashes of names to what to include below them
982
971
  (`associations: [:author, { comments: :replies }]`).
983
972
 
984
- Supported: `belongs_to`, `has_one`, `has_many` (including `:through`), and
985
- `has_and_belongs_to_many`. Associated models must use `has_paper_trail`, and
973
+ Supported: `belongs_to`, `has_one`, and `has_many` (including `:through`).
974
+ A `has_and_belongs_to_many` is not: see
975
+ [replacing a has_and_belongs_to_many](#replacing-a-has_and_belongs_to_many).
976
+ Associated models must use `has_paper_trail`, the
977
+ target of a `has_one` or `has_many` must declare the `belongs_to` back, and
986
978
  historical states need PT-AT installed and enabled
987
979
  (`PaperTrail.config.track_associations = true`). The gem never follows
988
980
  associations you did not ask for, so cyclic models are safe.
989
981
 
982
+ When more than one record points at the owner of a `has_one` without an
983
+ order, history reads the one with the lowest primary key, as Active Record's
984
+ `LIMIT 1` does on SQLite, MySQL, and SQL Server. PostgreSQL promises no order
985
+ there, so its current record can read another one: give such a `has_one` an
986
+ order, or a unique index, to make the choice the same everywhere.
987
+
990
988
  How each kind is reported:
991
989
 
992
990
  | Association | Record replaced, added, or removed | Same record, fields changed |
993
991
  | --- | --- | --- |
994
992
  | `belongs_to`, `has_one` | `relationship` (a `ValueChange` of snapshots) | `changed` |
995
- | `has_many`, HABTM | `added`, `removed` (snapshots) | `changed` (`RecordChange`) |
993
+ | `has_many` | `added`, `removed` (snapshots) | `changed` (`RecordChange`) |
996
994
 
997
995
  ```ruby
998
996
  diff.associations["author"].relationship # from one author to another
@@ -1019,8 +1017,7 @@ comments.changed.first.associations["replies"].added
1019
1017
  names no class, such as one a renamed model left in its versions, raises
1020
1018
  `IncompleteAssociationHistoryError` naming the record.
1021
1019
  - `has_many :through` uses the versioned join model's history, so join-model
1022
- attributes are available. HABTM reports membership and the target's
1023
- attributes; it has no join model, so it has no join attributes.
1020
+ attributes are available.
1024
1021
  - A `has_many :through` holds, at each point, the records the owner reached
1025
1022
  through the join records it had then. A record that moves to another join
1026
1023
  record leaves one owner and joins the other, and so does every record under
@@ -1036,24 +1033,11 @@ comments.changed.first.associations["replies"].added
1036
1033
  model with no versions, so the through cannot be rebuilt from history.
1037
1034
  Replace the HABTM with a `has_many :through` a versioned join model to
1038
1035
  compare it. `association_paths` leaves such a through out.
1039
- - A HABTM can only be rebuilt on the root record. PT-AT records membership
1040
- when the record that owns it saves a version, in rows that name the
1041
- transaction and the association but not the owner, so a root checkpoint
1042
- holds the root's membership and no one else's. A HABTM later in a path, such
1043
- as `"tags.articles"` or `"author.articles.tags"`, raises
1044
- `UnsupportedAssociationError` up front in every method, even when the path
1045
- leads back to the root, as `"comments.article.tags"` does.
1046
- `association_paths` leaves such a path out. To follow another record's
1047
- memberships, compare that record's own checkpoints, or replace the HABTM
1048
- with a `has_many :through` a versioned join model.
1049
- - A HABTM with a scope, such as `-> { where(active: true) }`, or whose target
1050
- has a default scope, raises `UnsupportedAssociationError` up front in every
1051
- method. PT-AT records a HABTM's members by loading the association through
1052
- its scope when the owner saves, so a target outside the scope then is never
1053
- recorded, and one that enters the scope before the owner's next save is a
1054
- member history cannot show. Replace it with a `has_many :through` a
1055
- versioned join model, which can be scoped. `association_paths` leaves it
1056
- out.
1036
+ - A `has_and_belongs_to_many` raises `UnsupportedAssociationError` up front
1037
+ in every method, wherever it is in a path, and `association_paths` leaves
1038
+ it out. Its join rows have no versions, so nothing records when a member
1039
+ joined or left. See
1040
+ [replacing a has_and_belongs_to_many](#replacing-a-has_and_belongs_to_many).
1057
1041
  - An association keyed on a column other than a primary key, such as
1058
1042
  `has_many :comments, primary_key: :legacy_id`, raises
1059
1043
  `UnsupportedAssociationError` up front in every method, and so does a
@@ -1061,22 +1045,75 @@ comments.changed.first.associations["replies"].added
1061
1045
  pointed at by that record's ID, so history read that way would show other
1062
1046
  records' children. `association_paths` leaves it out. Naming the primary key
1063
1047
  itself, `primary_key: :id`, is accepted.
1048
+ - A `has_many` or `has_one` whose target declares no `belongs_to` on its
1049
+ foreign key, such as `has_many :comments` when `Comment` has no
1050
+ `belongs_to :article`, raises `UnsupportedAssociationError` up front in
1051
+ every method, and so does a `has_many :through` with such a part. PT-AT
1052
+ records a record's owner on the record's own versions, once for each
1053
+ `belongs_to` it declares, so with none nothing says a comment that was
1054
+ destroyed or moved away was ever the article's. `association_paths` leaves
1055
+ it out. Declare the `belongs_to` to request the path; versions saved before
1056
+ then recorded no owner, so a record that left before then is not reported.
1064
1057
  - A root that uses single-table inheritance gets the associations of the
1065
1058
  class it had at each version, so you can request one that only a subclass
1066
1059
  declares. Without an `item_subtype` column, PaperTrail stores only the base
1067
1060
  class; the gem reads the subclass from the type column the version stored.
1068
1061
  A version where the record was a class without that association raises
1069
1062
  `UnknownAssociationError`, as a current record of that class would. A
1070
- stored type that names no class raises `InvalidEndpointError`.
1063
+ stored type that names no class raises `InvalidEndpointError`. A child's
1064
+ `belongs_to` may name any class of the owner's table: PT-AT records the
1065
+ class it names, and the gem looks for each one the target declares.
1071
1066
  - Requesting associations for a historical state without PT-AT raises
1072
1067
  `AssociationTrackingUnavailableError`. Unknown names raise
1073
1068
  `UnknownAssociationError`; unsupported macros raise
1074
1069
  `UnsupportedAssociationError`.
1075
1070
 
1071
+ ### Replacing a has_and_belongs_to_many
1072
+
1073
+ A `has_and_belongs_to_many` keeps its members in a join table with no model,
1074
+ so PaperTrail saves no version when one joins or leaves. Give the join table
1075
+ a model with `has_paper_trail`, and read the association with
1076
+ `has_many :through`:
1077
+
1078
+ ```ruby
1079
+ class AddIdToArticlesTags < ActiveRecord::Migration[7.1]
1080
+ def change
1081
+ add_column :articles_tags, :id, :primary_key # a version names its row by id
1082
+ end
1083
+ end
1084
+
1085
+ class Tagging < ApplicationRecord
1086
+ self.table_name = "articles_tags"
1087
+ belongs_to :article
1088
+ belongs_to :tag
1089
+ has_paper_trail
1090
+ end
1091
+
1092
+ class Article < ApplicationRecord
1093
+ has_many :taggings, dependent: :destroy
1094
+ has_many :tags, through: :taggings, dependent: :destroy
1095
+ has_paper_trail
1096
+ end
1097
+ ```
1098
+
1099
+ `article.tags`, `article.tags << tag`, and `article.tag_ids = ids` work as
1100
+ before. Two things differ:
1101
+
1102
+ - `dependent: :destroy` on the `has_many :through` is what records a member
1103
+ leaving. Without it, `article.tags.delete(tag)` and `tag_ids=` delete the
1104
+ join row without callbacks, so no version is saved and history cannot
1105
+ show when the member left.
1106
+ - Members that joined before the change have no `create` version, so they
1107
+ read as members from before history began, like any
1108
+ [record created without a version](#how-papertrail-stores-history).
1109
+
1110
+ Request `associations: [:tags]` for the members, or `["taggings.tag"]` to
1111
+ read the join rows' own attributes too.
1112
+
1076
1113
  ### Saving a checkpoint
1077
1114
 
1078
1115
  Sometimes you want a version of the root record without changing it, for
1079
- example to fix the end of a report or to capture HABTM membership. Save one
1116
+ example to fix the end of a report. Save one
1080
1117
  inside a transaction on a freshly loaded record, and turn off PaperTrail's
1081
1118
  timestamp synchronization for that model so the version records the time it
1082
1119
  was saved:
@@ -1094,17 +1131,7 @@ end
1094
1131
  ```
1095
1132
 
1096
1133
  Without `synchronize_version_creation_timestamp: false`, the checkpoint takes the
1097
- record's old `updated_at` as its time and lands in the past. Save one record per
1098
- transaction: HABTM membership cannot be read from a transaction in which
1099
- another record with the same HABTM also saved a version (see the
1100
- [HABTM limitation](#habtm-limitation)). A checkpoint records membership as it
1101
- is when saved, including a member attached or created earlier in the same
1102
- transaction. A change it captures is credited to the step before it, so its
1103
- author is whoever saved the version before the checkpoint, unless that is a
1104
- checkpoint the same person saved just before the change. A member created in
1105
- the checkpoint's transaction is reported in the step of its creation instead,
1106
- or, when the range ends at the checkpoint, in the step before it. Don't save
1107
- the instance that made the HABTM change again; it records the old membership.
1134
+ record's old `updated_at` as its time and lands in the past.
1108
1135
 
1109
1136
  ### Files from ActiveStorage
1110
1137
 
@@ -1288,18 +1315,20 @@ Which version a row names:
1288
1315
  - A field's change names the version of the row's own record that made it,
1289
1316
  among those its step's transaction saved. Inside a transaction, a record's
1290
1317
  change can show up at a later event than its own, in a step another record's
1291
- version opens; the row still names its own record's version. With
1292
- `recorded_changes: true`, that is the version that recorded the field's new
1293
- value. Without it, the gem cannot tell which of a record's versions made
1294
- the change, so the row names the last of them.
1318
+ version opens; the row still names its own record's version: the one that
1319
+ recorded the field's new value. With `recorded_changes: false`, the gem
1320
+ cannot tell which of a record's versions made the change, so the row names
1321
+ the last of them.
1295
1322
  - A record created or destroyed names its `create` or `destroy`. Its fields
1296
1323
  name the version that recorded each value: the `create`, or a later save in
1297
- the same step. A record that joined or left through another record's
1298
- change, such as a new `belongs_to` target or a `has_and_belongs_to_many`
1299
- member, names the step's `source_boundary`.
1300
-
1301
- With `recorded_changes: true`, a change PaperTrail did not record gets a row of
1302
- its own: a write [saved without a version](#how-papertrail-stores-history),
1324
+ the same step. A record that joined or left by its own update, such as a
1325
+ comment moved to another article, names the last of its versions in the
1326
+ step's transaction. A record that joined or left through another record's
1327
+ change, such as a new `belongs_to` target, names the step's
1328
+ `source_boundary`.
1329
+
1330
+ A change PaperTrail did not record gets a row of its own, unless
1331
+ `recorded_changes: false` is passed: a write [saved without a version](#how-papertrail-stores-history),
1303
1332
  such as `update_columns`. Its source has kind `:unversioned` and names the
1304
1333
  record, with no version, event, author, or time, so `to_h` has `nil` for
1305
1334
  `version_id`, `event`, `whodunnit`, `recorded_at`, and `transaction_id`. A
@@ -1311,7 +1340,7 @@ recorded, leave such rows out:
1311
1340
  <!-- executable:reference-unversioned-rows -->
1312
1341
  ```ruby
1313
1342
  analysis = PaperTrailDiff.analyze(
1314
- article, associations: [:comments], activity: true, recorded_changes: true
1343
+ article, associations: [:comments], activity: true
1315
1344
  )
1316
1345
 
1317
1346
  analysis.change_rows.reject(&:unversioned?)
@@ -1338,13 +1367,12 @@ without a version undid, leaving the field as it was, has no row.
1338
1367
  `net_changes` folds change rows into one entry per record: its fields before
1339
1368
  the rows a block keeps, and its fields with only their changes made. This
1340
1369
  example keeps the rows with an author. A write saved without a version has
1341
- none, so with `recorded_changes: true` it is left out:
1370
+ none, so it is left out:
1342
1371
 
1343
1372
  <!-- executable:reference-net-changes -->
1344
1373
  ```ruby
1345
1374
  analysis = PaperTrailDiff.analyze(
1346
- article, associations: [:comments], activity: true, snapshots: true,
1347
- recorded_changes: true
1375
+ article, associations: [:comments], activity: true, snapshots: true
1348
1376
  )
1349
1377
 
1350
1378
  changes = analysis.net_changes { |row| row.source.whodunnit }
@@ -1407,7 +1435,8 @@ PaperTrailDiff.nested_changes(from_value, to_value) # also accepts two values
1407
1435
  are strings. Values are reported as they were given.
1408
1436
  - Arrays are compared by their elements, not positions. An `ArrayChange` has
1409
1437
  `added`, `removed`, and `reordered?`, plus the whole `from` and `to`. Objects
1410
- inside arrays are compared whole.
1438
+ inside arrays are compared whole. Elements match as values under a key do,
1439
+ so `1` and `1.0` are different elements.
1411
1440
  - A missing key is `PaperTrailDiff::NestedComparator::ABSENT`, not `nil`, because
1412
1441
  `{"a": null}` and `{}` are different.
1413
1442
  - Two arrays at the top, as a `json` column can hold, return one `ArrayChange`
@@ -1448,7 +1477,8 @@ Other details:
1448
1477
  `{}`.
1449
1478
  - `ignore:` takes an array of attribute names and defaults to `updated_at`, as
1450
1479
  elsewhere. It does not take `paths:`, because a version does not say which
1451
- association path it was reached through. Primary keys are left out.
1480
+ association path it was reached through. Primary keys are left out, and so
1481
+ is a name the model no longer has, such as a column dropped since.
1452
1482
  - Unlike PaperTrail's `version.changeset`, it never loads the record. That
1453
1483
  saves a query per version, and a deleted record's values keep their types,
1454
1484
  such as an enum's label rather than the integer PaperTrail stored.
@@ -1457,16 +1487,15 @@ Other details:
1457
1487
  [JSON history](#history-stored-as-json), times keep the digits history
1458
1488
  stores and binary and `serialize`d values read as JSON stored them.
1459
1489
 
1460
- For activity steps, pass `recorded_changes: true` instead of loading the
1461
- versions again. Each step's sources then carry what their versions recorded,
1462
- with no extra queries; see
1463
- [what each event recorded](#what-each-event-recorded-recorded_changes-true):
1490
+ Activity steps need no such call. Each step's sources carry what their
1491
+ versions recorded, with no extra queries; see
1492
+ [what each event recorded](#what-each-event-recorded):
1464
1493
 
1465
1494
  <!-- executable:reference-recorded-changes -->
1466
1495
  ```ruby
1467
- steps = PaperTrailDiff.activity_timeline(
1468
- article, associations: [:comments], recorded_changes: true
1469
- )
1496
+ steps = PaperTrailDiff.analyze(
1497
+ article, associations: [:comments], activity: true
1498
+ ).activity_timeline
1470
1499
 
1471
1500
  steps.last.source_boundary.recorded_changes
1472
1501
  ```
@@ -1485,14 +1514,14 @@ Each descriptor has `path`, `kind`, `target_type`, `through`, `polymorphic`,
1485
1514
  and `cycle`. Cycles are marked and not followed.
1486
1515
 
1487
1516
  Only associations a request accepts are listed, so each path can be passed to
1488
- `associations:`. The PaperTrail versions association, a `has_many :through`
1489
- that goes through a HABTM, a scoped HABTM, a HABTM below the root, an
1517
+ `associations:`. The PaperTrail versions association, a
1518
+ `has_and_belongs_to_many`, a `has_many :through` that goes through one, an
1490
1519
  association keyed on a column other than a primary key, one whose ends keep
1491
1520
  their versions in different tables, and one whose target, or a model its
1492
1521
  `has_many :through` goes through, has no `has_paper_trail` are left out. A path
1493
- history can read only approximately, such as one with a scope written as SQL
1494
- text, is listed, but requesting it also takes `allow_approximate: true` (see
1495
- [costly associations](#costly-associations)). A `has_many :through` Active
1522
+ with a scope history cannot read, such as one written as SQL text, is listed,
1523
+ since a comparison of two current records accepts it; a request that reads
1524
+ history refuses it (see [association scopes](#association-scopes)). A `has_many :through` Active
1496
1525
  Record cannot follow, such as one through a polymorphic `belongs_to`, raises
1497
1526
  Active Record's own error from any model discovery reaches, as requesting it
1498
1527
  does.
@@ -1502,7 +1531,7 @@ association history. They are what `compare` takes: two versions, or a version
1502
1531
  and the current record.
1503
1532
 
1504
1533
  ```ruby
1505
- report = PaperTrailDiff.diagnose(from_version, article, associations: [:tags, "comments.replies"])
1534
+ report = PaperTrailDiff.diagnose(from_version, article, associations: [:author, "comments.replies"])
1506
1535
 
1507
1536
  report.ok? # no errors among the checks that ran
1508
1537
  report.errors.map(&:code)
@@ -1513,9 +1542,9 @@ Association checks run only for requested associations. The version-order check
1513
1542
  always runs. Every reason `compare` would refuse the same request is an error,
1514
1543
  with the message `compare` would raise, so `ok?` is false whenever `compare`
1515
1544
  would refuse: an unknown or unsupported association, missing association
1516
- tracking, an unversioned target, or a path read only approximately. Pass
1517
- `allow_approximate: true`, as you would to `compare`, and such a path is a
1518
- warning instead. `ok?` does not prove the history is complete.
1545
+ tracking, an unversioned target, or a path history cannot read. Endpoints `compare` rejects whatever their history holds,
1546
+ such as versions given newest first, two records, or an unsaved record, raise
1547
+ the error `compare` raises. `ok?` does not prove the history is complete.
1519
1548
 
1520
1549
  ## Models, schemas, and edge cases
1521
1550
 
@@ -1528,17 +1557,52 @@ warning instead. `ok?` does not prove the history is complete.
1528
1557
  - **Custom version classes** (`has_paper_trail versions: { class_name: }`) are
1529
1558
  supported. For association history, a model and each association you ask
1530
1559
  for must keep their versions, and their PT-AT version associations, in the
1531
- same tables. PT-AT reads an association's history from its owner's tables
1532
- and numbers transactions within one table, so it cannot follow an
1533
- association into a different version table. Such an association raises
1534
- `UnsupportedAssociationError` naming both tables, and `association_paths`
1535
- leaves it out. One custom table shared by the models works like
1536
- PaperTrail's own.
1560
+ same tables. PT-AT reads an association's history from its owner's
1561
+ tables, so it cannot follow an association into a different version
1562
+ table. Such an association raises `UnsupportedAssociationError` naming
1563
+ both tables, and `association_paths` leaves it out. One custom table
1564
+ shared by the models works like PaperTrail's own.
1565
+
1566
+ PaperTrail numbers a transaction by the id of the first version it
1567
+ saved, in whichever table that was, so with more than one version table
1568
+ two transactions can share a number. Where a [time window](#time-windows)
1569
+ looks for the start of a transaction, the gem tells them apart by the
1570
+ version each began with, which carries its own id as its number. It
1571
+ consults the version classes loaded at the time, in the model's
1572
+ database: load them eagerly, as production does, or name them before
1573
+ reading. It cannot tell two apart when the earlier one's first version
1574
+ has been deleted, or when both ran at the same time. Within the history
1575
+ of one record and its associations, versions are still grouped by number
1576
+ alone, so where two transactions of one number both saved them, their
1577
+ versions are read as one transaction's: one step, or one group, runs from
1578
+ the first of them to the last, and the changes of every step between are
1579
+ reported inside it. In a young database both tables count from 1, so
1580
+ such numbers are common there. The version a transaction began with also
1581
+ marks where it began only when it is dated first: with a second version
1582
+ table, a callback that saves other records before its own version (see
1583
+ [version order](#version-order)) can make a window read that transaction
1584
+ as two.
1537
1585
  - **A scoped versions association** (`has_paper_trail versions: { scope: }`)
1538
1586
  does not change what is read: every method reads all of a record's
1539
1587
  versions, because a history replayed without some of them would credit
1540
1588
  their changes to the next version kept. To report only some changes, pass
1541
1589
  [`version_scope:`](#reporting-only-some-changes-version_scope).
1590
+ - **Values the database rounds.** PaperTrail stores the value a record held
1591
+ in memory, and the database may have stored less of it. The gem compares
1592
+ every side in the form the database keeps: times to the column's precision
1593
+ (a SQL Server `datetime` to 1/300 s, read back to the millisecond), a MySQL
1594
+ `float` to single precision, a SQLite decimal as the number SQLite returns,
1595
+ and a fixed-width `char` column padded (PostgreSQL, SQL Server) or with its
1596
+ trailing spaces stripped (MySQL). So saving `12:00:00.1234567` to a column
1597
+ that keeps microseconds is not reported as a change. A date assigned to a
1598
+ datetime column, which Active Record leaves on the instance when time zone
1599
+ aware attributes are off or `update_columns` writes it, is read as
1600
+ midnight in Active Record's default time zone, as the database stores it.
1601
+ A `serialize`d hash in a `json` or `jsonb` history keeps string keys only
1602
+ (see [history stored as JSON](#history-stored-as-json)).
1603
+ - **Attributes without a column**, such as one declared with `attribute` for
1604
+ a form, are left out of every diff, snapshot and change row. PaperTrail
1605
+ stores whatever the instance held for one, but no row holds it.
1542
1606
 
1543
1607
  ### Version order
1544
1608
 
@@ -1547,6 +1611,8 @@ works when IDs increase with each insert, as autoincrement IDs do, in one
1547
1611
  table. UUID version IDs do not, and models with their own version tables count
1548
1612
  IDs separately, so two such versions with the same timestamp cannot be ordered;
1549
1613
  the gem raises `AmbiguousVersionOrderError` naming both instead of guessing.
1614
+ That includes a tie for the first version after a `within:` window, which
1615
+ holds the state the window ends in.
1550
1616
  Timestamps stored to the second, as on a MySQL `datetime` column, make ties
1551
1617
  common. `diagnose` reports this as an error.
1552
1618
 
@@ -1563,6 +1629,14 @@ with `inverted_version_order`. Set the option on models whose `updated_at`
1563
1629
  your application sets, and correct the stored `created_at` of versions
1564
1630
  already saved.
1565
1631
 
1632
+ The versions of different records in one transaction can be dated out of
1633
+ the order they were saved in too: a callback or nested save that a model
1634
+ declares before `has_paper_trail` saves other records' versions first and
1635
+ the model's own last, dated as its save began. A transaction takes effect at
1636
+ its latest dated version, ids breaking a tie, and a window reads it as open
1637
+ across its start when it has versions dated on both sides, so its changes
1638
+ are reported once whichever version it saved last.
1639
+
1566
1640
  `created_at` comes from your application server's clock. A clock that jumps
1567
1641
  backwards, or servers whose clocks disagree, can record a later change with an
1568
1642
  earlier time. Keep server clocks synchronized.
@@ -1574,26 +1648,31 @@ can therefore show a state the database never held, and a result for an earlier
1574
1648
  version or a closed window can change once that transaction commits.
1575
1649
  [Time windows](#time-windows) explains how to settle a report.
1576
1650
 
1651
+ Two transactions that save in one record's tree at the same time interleave
1652
+ their versions. Each version was saved while the other transaction's changes
1653
+ were not yet committed, so at a version of one, a record the other saved
1654
+ reads as it stood before the other began, as a record the version's own
1655
+ transaction saved does. A version reads so wherever it is used: in
1656
+ `compare`, and as the start or the end of a range. The other's changes appear from the event after its
1657
+ last version, in a step it opens, so a record it changed and changed back,
1658
+ such as a comment it created and deleted again, appears in no step and in no
1659
+ window's starting state or diff. A transaction is open from its first
1660
+ version on the requested paths in the range, or from the range's start when
1661
+ it began before it, to the latest dated version it saved of any record in
1662
+ the same version table. Row locks keep the two from saving the same
1663
+ record.
1664
+
1577
1665
  Association changes between versions with the same timestamp are placed using
1578
- the same order. A few association shapes fall back to PT-AT's own reifier, which
1579
- uses timestamps only: a path history reads only approximately, which takes
1580
- `allow_approximate: true`, a composite foreign key, and a polymorphic
1581
- `belongs_to` whose target's default scope history cannot read. The
1582
- [architecture notes](architecture.md) list them. When a request includes such a
1583
- path, or any polymorphic `belongs_to`, whose targets are known only per record,
1584
- `diagnose` warns about tied timestamps and a comparison between two tied
1585
- versions emits the `ambiguous_association_boundary.paper_trail_diff`
1586
- notification. Recording timestamps below one second avoids the problem. On SQL Server, PT-AT compares
1587
- those timestamps only to about 3 milliseconds (a `datetime` tick, 1/300 s),
1588
- because the adapter writes the times in its queries that way, so for these
1589
- shapes two versions saved closer together than that may be read in the wrong
1590
- order.
1666
+ the same order.
1591
1667
 
1592
1668
  ### History stored as JSON
1593
1669
 
1594
1670
  PaperTrail's JSON serializer, and a `json` or `jsonb` `object` column, store
1595
1671
  times to milliseconds by default (`ActiveSupport::JSON::Encoding.time_precision`).
1596
- For those histories the gem compares all times at that precision, so an
1672
+ The gem reads the digits from what the history's writer writes, a serializer
1673
+ of your own that wraps the JSON one included, so the legacy JSON format,
1674
+ which writes whole seconds, keeps whole seconds. For those histories the gem
1675
+ compares all times at that precision, so an
1597
1676
  unchanged timestamp is not reported as changed. A change smaller than that
1598
1677
  precision was never recorded and cannot be reported. A `json` or `jsonb`
1599
1678
  column also returns times and dates as strings, which PaperTrail leaves as
@@ -1627,9 +1706,9 @@ If you change `created_at` after saving instead, change every version saved
1627
1706
  in the same transaction, not only the ones you check. PT-AT gives all of
1628
1707
  them the same `transaction_id`, including versions of other models saved by
1629
1708
  callbacks. A version left at the time the test ran makes that transaction
1630
- seem to last from your chosen time until today. A window edge in between
1631
- then moves back to the transaction's start (see [Time windows](#time-windows)),
1632
- and the window can lose the changes the test expects.
1709
+ seem to last from your chosen time until today. The transaction is then
1710
+ reported where it ends, today (see [Time windows](#time-windows)), and a window
1711
+ around your chosen time loses the changes the test expects.
1633
1712
 
1634
1713
  ```ruby
1635
1714
  def set_version_time(version, time)
@@ -1645,12 +1724,11 @@ subscribe to:
1645
1724
 
1646
1725
  - `compare.paper_trail_diff`
1647
1726
  - `compare_many.paper_trail_diff`
1648
- - `activity_timeline.paper_trail_diff` (includes `step_count`)
1727
+ - `analyze.paper_trail_diff` (includes `step_count`, the length of
1728
+ `activity_timeline` with `activity: true` and of `timeline` without)
1649
1729
  - `analyze_many.paper_trail_diff`
1650
1730
  - `load_live_endpoints.paper_trail_diff`
1651
1731
  - `prepare_history.paper_trail_diff`
1652
- - `ambiguous_association_boundary.paper_trail_diff`
1653
- - `moved_window.paper_trail_diff`, when a [window edge moves](#time-windows)
1654
1732
 
1655
1733
  ```ruby
1656
1734
  ActiveSupport::Notifications.subscribe(/\.paper_trail_diff\z/) do |name, start, finish, _id, payload|
@@ -1673,39 +1751,74 @@ All errors inherit from `PaperTrailDiff::Error`.
1673
1751
 
1674
1752
  | Error | Raised when |
1675
1753
  | --- | --- |
1676
- | `ConfigurationError` | An option is invalid |
1677
- | `InvalidEndpointError` | A record is unsaved, destroyed, or has unsaved changes, or `recorded_changes` is given something other than a version |
1754
+ | `ConfigurationError` | An option is invalid, or the version class has no `object` column to read states from |
1755
+ | `InvalidEndpointError` | A record is unsaved, destroyed, or has unsaved changes, a version was loaded without its `object`, a model has no `has_paper_trail`, or `recorded_changes` is given something other than a version |
1678
1756
  | `VersionMismatchError` | Two endpoints belong to different records |
1679
1757
  | `ReversedEndpointsError` | Two versions are given newest first |
1680
- | `InvalidTimelineRangeError` | A range is invalid, for example `within:` with `from:`, or `:last` |
1758
+ | `InvalidTimelineRangeError` | A range is invalid, for example `within:` with `from:`, or `:last`, or a boundary symbol is unknown |
1681
1759
  | `InvalidTimeRangeError` | `within:` is not a range with a beginning, in time order |
1682
1760
  | `IncompleteTimeRangeError` | A window's last change has no later version and the record has no saved row to read instead |
1683
1761
  | `AmbiguousVersionOrderError` | Versions cannot be ordered (see [version order](#version-order)) |
1684
1762
  | `BatchLimitExceededError` | More records are selected than `limit:` allows |
1685
- | `FilterLimitExceededError` | `historical_filter:` needs more than `max_filter_versions:` |
1686
1763
  | `AssociationTrackingUnavailableError` | Association history is requested without PT-AT |
1687
1764
  | `UnknownAssociationError` | An association name does not exist |
1688
- | `UnsupportedAssociationError` | An association's macro is not supported, a path continues past a polymorphic `belongs_to`, a `has_many :through` goes through a HABTM, a HABTM is scoped or below the root, an association is keyed on a column other than a primary key, or history cannot read a [costly association](#costly-associations) and `allow_approximate: true` was not passed |
1765
+ | `UnsupportedAssociationError` | An association's macro is not supported, a path continues past a polymorphic `belongs_to`, an association is a `has_and_belongs_to_many` or a `has_many :through` that goes through one, an association is keyed on a column other than a primary key, the target of a `has_one` or `has_many` declares no `belongs_to` on its foreign key, an association has a composite foreign key, or history cannot read an [association's scope](#association-scopes) |
1689
1766
  | `UnversionedAssociationError` | An association's target model, or a model a `has_many :through` goes through, has no `has_paper_trail`, including the class a polymorphic `belongs_to` names |
1690
- | `IncompleteAssociationHistoryError` | PT-AT did not record enough to rebuild an association, such as HABTM without a transaction or in a transaction another record with that HABTM also saved a version in, or a polymorphic type names no class |
1691
- | `UnsupportedLiveActivityError` | A HABTM activity range ends at the current record |
1767
+ | `IncompleteAssociationHistoryError` | PT-AT did not record enough to rebuild an association, such as a polymorphic type that names no class |
1692
1768
  | `AmbiguousNestedKeyError` | `nested_changes` finds keys like `:a` and `"a"` together |
1693
1769
 
1770
+ ## What results rest on
1771
+
1772
+ Every result is one of three kinds. Knowing which tells you how far to trust
1773
+ it for an audit.
1774
+
1775
+ **Recorded.** PaperTrail stored it, and the gem reads it back: a record's
1776
+ attributes at each version, each version's event, author, and time, and the
1777
+ changes a version [recorded](#what-a-version-recorded). A
1778
+ [change row](#change-rows) credited to a version is one that version
1779
+ recorded.
1780
+
1781
+ **Rebuilt by a stated rule.** PaperTrail did not store it, so the gem derives
1782
+ it the same way every time:
1783
+
1784
+ - *Where a transaction takes effect.* PaperTrail records which versions one
1785
+ transaction saved, not when it committed. The gem places a transaction at
1786
+ the last version it saved, and reports it whole there; see
1787
+ [time windows](#time-windows). Two transactions that overlapped are
1788
+ reported in the order of their last versions, which is usually, but not
1789
+ provably, the order they committed in.
1790
+ - *The order of versions saved in the same instant.* By id; see
1791
+ [version order](#version-order).
1792
+ - *Who was in an association.* PaperTrail stores no membership. The gem
1793
+ reads each candidate's foreign key, and the columns of a
1794
+ [scope](#association-scopes), from its own versions at that point.
1795
+ - *Which record an unordered `has_one` holds* when several match: the one
1796
+ with the lowest primary key.
1797
+ - *A write saved without a version*, such as `update_columns`. It is seen
1798
+ only in the state the next version stores, so it appears in the step of
1799
+ the record's previous recorded change. Its change row is marked
1800
+ `unversioned?`, with no author or time, since none was recorded.
1801
+
1802
+ **Refused.** Where neither holds, a call raises instead of estimating: an
1803
+ association [scope](#association-scopes) history cannot read, a composite
1804
+ foreign key, a `has_and_belongs_to_many`, an unversioned target, or versions
1805
+ that cannot be ordered. No result is an approximation.
1806
+
1694
1807
  ## Limitations
1695
1808
 
1696
1809
  Results can only be as complete as the history PaperTrail and PT-AT recorded.
1697
1810
 
1698
1811
  - Changes made with versioning off, with `update_columns`, or to `skip:` columns
1699
1812
  were never recorded. The first two still appear, in the step for the record's
1700
- previous recorded change and attributed to its author; see
1813
+ previous recorded change, and their [change rows](#change-rows) are marked
1814
+ `unversioned?`; see
1701
1815
  [how PaperTrail stores history](#how-papertrail-stores-history).
1702
1816
  - Deleted versions, schema changes, and serializer changes can affect how old
1703
1817
  versions read.
1704
1818
  - With PaperTrail's default YAML serializer, PaperTrail 16 and 17 decode a
1705
1819
  `time` (time of day) column as `nil`, in `reify` and `changeset` alike,
1706
1820
  unless the column is time-zone aware, as a Rails app's are, and the time
1707
- zone is UTC. The gem reads the time each version recorded, including in
1708
- the records it passes to a callable `historical_filter:`, but your own
1821
+ zone is UTC. The gem reads the time each version recorded, but your own
1709
1822
  calls to those PaperTrail methods still return `nil`. PaperTrail's JSON
1710
1823
  serializer, and SQL Server, whose adapter stores a time its own way, are
1711
1824
  not affected. Snapshots and diffs show every time of day on 2000-01-01 in
@@ -1731,26 +1844,14 @@ Results can only be as complete as the history PaperTrail and PT-AT recorded.
1731
1844
  - A savepoint that rolls back, or another transaction saving in the same tree
1732
1845
  at the same time, can split one transaction into several transaction groups;
1733
1846
  see [one step per transaction group](#one-step-per-transaction-group-transaction).
1734
- - Two transactions that save in one record's tree at the same time, so that
1735
- their versions interleave, are read in the order of their versions. A
1736
- version reads the records its own transaction saved as they stood before
1737
- the transaction, but a version of the other transaction reads them as they
1738
- stood after the change saved before it. So a record that one transaction
1739
- changed and changed back, such as a comment it created and deleted again,
1740
- can appear in the other's steps, crediting that transaction with adding
1741
- or removing it, and a window's starting state and diff can hold it too.
1742
- Row locks keep the two from saving the same record, so this needs both to
1743
- save different records of one tree within moments of each other. See
1744
- [version order](#version-order).
1745
- - HABTM membership history exists only where PT-AT recorded it in a
1746
- transaction, and only for the root record without a scope: a scoped HABTM,
1747
- or one below the root, raises `UnsupportedAssociationError`, and a transaction that another record with
1748
- that HABTM also saved a version in raises `IncompleteAssociationHistoryError`. HABTM changes cannot become their own
1749
- activity steps.
1750
- - PT-AT has its own
1751
- [limitations](https://github.com/westonganger/paper_trail-association_tracking#limitations),
1752
- especially for some `has_one` histories. The gem follows PT-AT's configured
1753
- error behavior.
1847
+ - A transaction that saves in two version tables is read in each as far as
1848
+ its versions there: where it ends is read from one version table at a time.
1849
+ - A `has_and_belongs_to_many` has no history to read; see
1850
+ [replacing a has_and_belongs_to_many](#replacing-a-has_and_belongs_to_many).
1851
+ - The gem reads the rows PT-AT records with each version to find the records
1852
+ an association held, and rebuilds every state itself. PT-AT's own
1853
+ [limitations](https://github.com/westonganger/paper_trail-association_tracking#limitations)
1854
+ apply to what it records, not to its reifier, which the gem does not use.
1754
1855
  - Deep association paths cost more to rebuild. Request only what you need.
1755
1856
 
1756
1857
  Read PaperTrail's