paper_trail_diff 0.13.1 → 0.15.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 (181) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +630 -0
  3. data/QUICKSTART.md +30 -10
  4. data/README.md +91 -13
  5. data/docs/architecture.md +62 -18
  6. data/docs/performance.md +116 -298
  7. data/docs/reference.md +554 -102
  8. data/docs/testing.md +93 -14
  9. data/lib/paper_trail_diff/activity_belongs_to_event_applier.rb +19 -9
  10. data/lib/paper_trail_diff/activity_boundary.rb +83 -26
  11. data/lib/paper_trail_diff/activity_child_candidate_loader.rb +2 -1
  12. data/lib/paper_trail_diff/activity_collection_event_applier.rb +11 -1
  13. data/lib/paper_trail_diff/activity_collection_record_updater.rb +16 -2
  14. data/lib/paper_trail_diff/activity_event.rb +41 -10
  15. data/lib/paper_trail_diff/activity_event_record_resolver.rb +20 -1
  16. data/lib/paper_trail_diff/activity_event_route_finder.rb +2 -1
  17. data/lib/paper_trail_diff/activity_event_snapshot_refresher.rb +1 -1
  18. data/lib/paper_trail_diff/activity_history.rb +34 -9
  19. data/lib/paper_trail_diff/activity_range.rb +32 -5
  20. data/lib/paper_trail_diff/activity_relationship.rb +12 -0
  21. data/lib/paper_trail_diff/activity_root_snapshot_refresher.rb +5 -2
  22. data/lib/paper_trail_diff/activity_snapshot_sequence.rb +76 -37
  23. data/lib/paper_trail_diff/activity_target_candidate_loader.rb +131 -0
  24. data/lib/paper_trail_diff/activity_timeline_builder.rb +281 -120
  25. data/lib/paper_trail_diff/activity_transaction_grouper.rb +2 -1
  26. data/lib/paper_trail_diff/activity_tree_filter.rb +114 -0
  27. data/lib/paper_trail_diff/activity_version_collector.rb +37 -24
  28. data/lib/paper_trail_diff/activity_view.rb +69 -0
  29. data/lib/paper_trail_diff/analysis.rb +13 -1
  30. data/lib/paper_trail_diff/analysis_batch.rb +24 -30
  31. data/lib/paper_trail_diff/approximate_paths.rb +48 -0
  32. data/lib/paper_trail_diff/association_activity_edge.rb +236 -0
  33. data/lib/paper_trail_diff/association_activity_selection.rb +197 -0
  34. data/lib/paper_trail_diff/association_discovery.rb +14 -11
  35. data/lib/paper_trail_diff/association_key.rb +56 -0
  36. data/lib/paper_trail_diff/association_traversal.rb +180 -47
  37. data/lib/paper_trail_diff/batch_boundary_resolver.rb +3 -4
  38. data/lib/paper_trail_diff/batch_preload.rb +53 -0
  39. data/lib/paper_trail_diff/batched_root_analyzer.rb +12 -14
  40. data/lib/paper_trail_diff/batched_root_versions.rb +53 -47
  41. data/lib/paper_trail_diff/change_row.rb +133 -0
  42. data/lib/paper_trail_diff/collection_comparator.rb +5 -32
  43. data/lib/paper_trail_diff/comparison_batch.rb +37 -10
  44. data/lib/paper_trail_diff/configuration.rb +35 -12
  45. data/lib/paper_trail_diff/deleted_analysis_batch.rb +45 -27
  46. data/lib/paper_trail_diff/deleted_root_filter.rb +79 -0
  47. data/lib/paper_trail_diff/deprecation.rb +61 -0
  48. data/lib/paper_trail_diff/diagnostics.rb +105 -102
  49. data/lib/paper_trail_diff/direct_record_state_loader.rb +10 -1
  50. data/lib/paper_trail_diff/endpoint.rb +26 -3
  51. data/lib/paper_trail_diff/errors.rb +5 -2
  52. data/lib/paper_trail_diff/fallback_paths.rb +38 -0
  53. data/lib/paper_trail_diff/habtm_transaction_owners.rb +68 -0
  54. data/lib/paper_trail_diff/historical_association_reifier.rb +34 -6
  55. data/lib/paper_trail_diff/historical_filter.rb +19 -10
  56. data/lib/paper_trail_diff/historical_snapshot_store.rb +63 -76
  57. data/lib/paper_trail_diff/live_endpoint_batch_loader.rb +12 -13
  58. data/lib/paper_trail_diff/live_graph_collector.rb +1 -1
  59. data/lib/paper_trail_diff/nested_comparator.rb +19 -18
  60. data/lib/paper_trail_diff/paper_trail_adapter.rb +136 -125
  61. data/lib/paper_trail_diff/preloaded_endpoint_batch_loader.rb +14 -2
  62. data/lib/paper_trail_diff/prepared_activity_index.rb +110 -36
  63. data/lib/paper_trail_diff/prepared_edge_loader.rb +31 -46
  64. data/lib/paper_trail_diff/prepared_history.rb +70 -53
  65. data/lib/paper_trail_diff/prepared_history_loader.rb +34 -43
  66. data/lib/paper_trail_diff/prepared_record_index.rb +64 -7
  67. data/lib/paper_trail_diff/prepared_snapshot_builder.rb +1 -1
  68. data/lib/paper_trail_diff/prepared_state_association_reader.rb +119 -29
  69. data/lib/paper_trail_diff/recorded_changes.rb +83 -0
  70. data/lib/paper_trail_diff/recorded_class.rb +53 -0
  71. data/lib/paper_trail_diff/root_version_selection.rb +4 -2
  72. data/lib/paper_trail_diff/scope_condition.rb +386 -0
  73. data/lib/paper_trail_diff/scope_ranking.rb +206 -0
  74. data/lib/paper_trail_diff/scoped_analysis.rb +11 -0
  75. data/lib/paper_trail_diff/scoped_analysis_builder.rb +20 -11
  76. data/lib/paper_trail_diff/scoped_root_selection.rb +105 -49
  77. data/lib/paper_trail_diff/snapshot.rb +16 -1
  78. data/lib/paper_trail_diff/snapshot_normalizer.rb +10 -3
  79. data/lib/paper_trail_diff/support.rb +38 -6
  80. data/lib/paper_trail_diff/time_range.rb +37 -18
  81. data/lib/paper_trail_diff/time_version_range.rb +5 -5
  82. data/lib/paper_trail_diff/timeline_builder.rb +7 -7
  83. data/lib/paper_trail_diff/timeline_range.rb +9 -1
  84. data/lib/paper_trail_diff/timeline_snapshot_provider.rb +24 -17
  85. data/lib/paper_trail_diff/transaction_cut.rb +181 -0
  86. data/lib/paper_trail_diff/traversal_preparer.rb +134 -29
  87. data/lib/paper_trail_diff/version.rb +1 -1
  88. data/lib/paper_trail_diff/version_association_candidate_scope.rb +13 -3
  89. data/lib/paper_trail_diff/version_boundary.rb +37 -8
  90. data/lib/paper_trail_diff/version_query.rb +34 -10
  91. data/lib/paper_trail_diff/version_range.rb +8 -15
  92. data/lib/paper_trail_diff/version_scope_filter.rb +20 -13
  93. data/lib/paper_trail_diff/version_sequence_diagnostics.rb +31 -16
  94. data/lib/paper_trail_diff/version_table.rb +60 -0
  95. data/lib/paper_trail_diff.rb +126 -55
  96. data/sig/generated/paper_trail_diff/activity_belongs_to_event_applier.rbs +10 -2
  97. data/sig/generated/paper_trail_diff/activity_boundary.rbs +54 -19
  98. data/sig/generated/paper_trail_diff/activity_collection_event_applier.rbs +5 -0
  99. data/sig/generated/paper_trail_diff/activity_collection_record_updater.rbs +5 -0
  100. data/sig/generated/paper_trail_diff/activity_event.rbs +25 -4
  101. data/sig/generated/paper_trail_diff/activity_event_record_resolver.rbs +7 -0
  102. data/sig/generated/paper_trail_diff/activity_history.rbs +21 -6
  103. data/sig/generated/paper_trail_diff/activity_range.rbs +14 -3
  104. data/sig/generated/paper_trail_diff/activity_relationship.rbs +3 -0
  105. data/sig/generated/paper_trail_diff/activity_root_snapshot_refresher.rbs +2 -0
  106. data/sig/generated/paper_trail_diff/activity_snapshot_sequence.rbs +48 -9
  107. data/sig/generated/paper_trail_diff/activity_target_candidate_loader.rbs +79 -0
  108. data/sig/generated/paper_trail_diff/activity_timeline_builder.rbs +138 -28
  109. data/sig/generated/paper_trail_diff/activity_tree_filter.rbs +73 -0
  110. data/sig/generated/paper_trail_diff/activity_version_collector.rbs +12 -4
  111. data/sig/generated/paper_trail_diff/activity_view.rbs +42 -0
  112. data/sig/generated/paper_trail_diff/analysis.rbs +8 -1
  113. data/sig/generated/paper_trail_diff/analysis_batch.rbs +8 -15
  114. data/sig/generated/paper_trail_diff/approximate_paths.rbs +23 -0
  115. data/sig/generated/paper_trail_diff/association_activity_edge.rbs +148 -0
  116. data/sig/generated/paper_trail_diff/association_activity_selection.rbs +112 -0
  117. data/sig/generated/paper_trail_diff/association_discovery.rbs +8 -5
  118. data/sig/generated/paper_trail_diff/association_key.rbs +29 -0
  119. data/sig/generated/paper_trail_diff/association_traversal.rbs +88 -9
  120. data/sig/generated/paper_trail_diff/batch_preload.rbs +29 -0
  121. data/sig/generated/paper_trail_diff/batched_root_analyzer.rbs +9 -10
  122. data/sig/generated/paper_trail_diff/batched_root_versions.rbs +14 -10
  123. data/sig/generated/paper_trail_diff/change_row.rbs +86 -0
  124. data/sig/generated/paper_trail_diff/collection_comparator.rbs +2 -16
  125. data/sig/generated/paper_trail_diff/comparison_batch.rbs +22 -4
  126. data/sig/generated/paper_trail_diff/configuration.rbs +19 -3
  127. data/sig/generated/paper_trail_diff/deleted_analysis_batch.rbs +20 -8
  128. data/sig/generated/paper_trail_diff/deleted_root_filter.rbs +48 -0
  129. data/sig/generated/paper_trail_diff/deprecation.rbs +35 -0
  130. data/sig/generated/paper_trail_diff/diagnostics.rbs +44 -32
  131. data/sig/generated/paper_trail_diff/direct_record_state_loader.rbs +6 -0
  132. data/sig/generated/paper_trail_diff/endpoint.rbs +11 -2
  133. data/sig/generated/paper_trail_diff/errors.rbs +5 -2
  134. data/sig/generated/paper_trail_diff/fallback_paths.rbs +22 -0
  135. data/sig/generated/paper_trail_diff/habtm_transaction_owners.rbs +40 -0
  136. data/sig/generated/paper_trail_diff/historical_association_reifier.rbs +13 -0
  137. data/sig/generated/paper_trail_diff/historical_filter.rbs +12 -2
  138. data/sig/generated/paper_trail_diff/historical_snapshot_store.rbs +36 -30
  139. data/sig/generated/paper_trail_diff/live_endpoint_batch_loader.rbs +5 -3
  140. data/sig/generated/paper_trail_diff/nested_comparator.rbs +10 -7
  141. data/sig/generated/paper_trail_diff/paper_trail_adapter.rbs +55 -48
  142. data/sig/generated/paper_trail_diff/preloaded_endpoint_batch_loader.rbs +9 -1
  143. data/sig/generated/paper_trail_diff/prepared_activity_index.rbs +52 -10
  144. data/sig/generated/paper_trail_diff/prepared_edge_loader.rbs +4 -12
  145. data/sig/generated/paper_trail_diff/prepared_history.rbs +40 -24
  146. data/sig/generated/paper_trail_diff/prepared_history_loader.rbs +15 -13
  147. data/sig/generated/paper_trail_diff/prepared_record_index.rbs +34 -2
  148. data/sig/generated/paper_trail_diff/prepared_state_association_reader.rbs +56 -11
  149. data/sig/generated/paper_trail_diff/recorded_changes.rbs +47 -0
  150. data/sig/generated/paper_trail_diff/recorded_class.rbs +22 -0
  151. data/sig/generated/paper_trail_diff/root_version_selection.rbs +2 -0
  152. data/sig/generated/paper_trail_diff/scope_condition.rbs +219 -0
  153. data/sig/generated/paper_trail_diff/scope_ranking.rbs +125 -0
  154. data/sig/generated/paper_trail_diff/scoped_analysis.rbs +6 -0
  155. data/sig/generated/paper_trail_diff/scoped_analysis_builder.rbs +8 -3
  156. data/sig/generated/paper_trail_diff/scoped_root_selection.rbs +49 -11
  157. data/sig/generated/paper_trail_diff/snapshot.rbs +8 -0
  158. data/sig/generated/paper_trail_diff/snapshot_normalizer.rbs +6 -0
  159. data/sig/generated/paper_trail_diff/support.rbs +20 -2
  160. data/sig/generated/paper_trail_diff/time_range.rbs +20 -2
  161. data/sig/generated/paper_trail_diff/time_version_range.rbs +4 -4
  162. data/sig/generated/paper_trail_diff/timeline_builder.rbs +2 -2
  163. data/sig/generated/paper_trail_diff/timeline_range.rbs +2 -0
  164. data/sig/generated/paper_trail_diff/timeline_snapshot_provider.rbs +17 -7
  165. data/sig/generated/paper_trail_diff/transaction_cut.rbs +94 -0
  166. data/sig/generated/paper_trail_diff/traversal_preparer.rbs +66 -8
  167. data/sig/generated/paper_trail_diff/version_association_candidate_scope.rbs +7 -0
  168. data/sig/generated/paper_trail_diff/version_boundary.rbs +20 -3
  169. data/sig/generated/paper_trail_diff/version_query.rbs +18 -2
  170. data/sig/generated/paper_trail_diff/version_range.rbs +4 -2
  171. data/sig/generated/paper_trail_diff/version_scope_filter.rbs +7 -4
  172. data/sig/generated/paper_trail_diff/version_sequence_diagnostics.rbs +16 -9
  173. data/sig/generated/paper_trail_diff/version_table.rbs +30 -0
  174. data/sig/generated/paper_trail_diff.rbs +47 -25
  175. metadata +62 -10
  176. data/lib/paper_trail_diff/activity_grouping.rb +0 -38
  177. data/lib/paper_trail_diff/batch_safety.rb +0 -55
  178. data/lib/paper_trail_diff/time_activity_timeline_builder.rb +0 -224
  179. data/sig/generated/paper_trail_diff/activity_grouping.rbs +0 -22
  180. data/sig/generated/paper_trail_diff/batch_safety.rbs +0 -24
  181. data/sig/generated/paper_trail_diff/time_activity_timeline_builder.rbs +0 -92
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: dfe7bccfe2f013af725d6ac92c772d357127d5a0c14cae72fac0000cb58fad62
4
- data.tar.gz: 308cc912a32875582ff8e083ec52016d4ca586ee75f3b0e36172360d2600b01d
3
+ metadata.gz: 4cc17a3d2f233d6f9bcc44605687ef4cabf1611f957ad41d0471b35236b8ab8d
4
+ data.tar.gz: e123b779da0c52350cb05b4ed18f8585626d8cbcf45e3c737cfe43777f7bcf14
5
5
  SHA512:
6
- metadata.gz: e948b33a959fc8ffdd00d7468819917f126b961c3daa4548f38260315dabab6fa36cddd9019b171c6aad306eae2b09485568591d5f2f07d42ba9a661e93bfd32
7
- data.tar.gz: 2ea2cae4b3147f1c4655e79d2ebe2a68202e991f61227718990ec9dcdce38e631f0122ae6fe510aac217ae15f54c1e223095e28148c08944614698a73c3c42dd
6
+ metadata.gz: 65f32e4a83fd05ba8cfece667be5842d41f9452ae84f49f495ff8ad0051b87c76ebddfb07c1a99c09227689eaa393286ca0737042bf6b6f7c6dffea0b77039bf
7
+ data.tar.gz: 217119550346fc0eed08759dd20aa1a2fb53bd71dde161e43ef1243f191159fc7c1225924a6c39059dda8e2df4c4b17f0f1abed694938a2824a89e722e88e0d7
data/CHANGELOG.md CHANGED
@@ -3,6 +3,636 @@
3
3
  All notable changes to this project will be documented in this file. The
4
4
  project follows [Semantic Versioning](https://semver.org/).
5
5
 
6
+ ## [0.15.0] - 2026-10-31
7
+
8
+ ### Breaking changes
9
+
10
+ - An association whose model keeps its versions, or its PT-AT version
11
+ associations, in different tables than its owner's raises
12
+ `UnsupportedAssociationError` in every method, and `association_paths`
13
+ leaves it out. History read through it was wrong: PT-AT records a child's
14
+ membership with the child's versions but reads it from the owner's tables,
15
+ so a child that moved to another owner was never reported as removed, and a
16
+ root with its own version table raised `ActiveRecord::StatementInvalid`.
17
+
18
+ - An association keyed on a column other than a primary key
19
+ (`primary_key: :legacy_id`), or a `has_many :through` with such a part,
20
+ raises `UnsupportedAssociationError` up front in every method, and
21
+ `association_paths` leaves it out. PT-AT records which record a child
22
+ pointed at by that record's ID, and history matched children by ID, so an
23
+ article's history showed another article's comments, and a comment's past
24
+ article was the wrong one. Comparisons against the current record were
25
+ right, so the same range disagreed with itself.
26
+ - An association path history cannot read, such as one with a scope written
27
+ as SQL text, a scope that takes the owner, or a condition on a string
28
+ column on MySQL or SQL Server, raises `UnsupportedAssociationError` in every
29
+ method that reads history, unless you pass the new `allow_approximate: true`.
30
+ The gem reads such a path with PT-AT, which rebuilds an association from its
31
+ current members and never checks the scope against them: a record that
32
+ entered the scope since was reported as a member it was not, so a comment
33
+ moved into `-> { where("position > 2") }` showed as changed rather than
34
+ added. Single-record methods did this without warning, and batch methods
35
+ described it only as costly.
36
+ - `include_deleted: true` keeps only the deleted records that met the
37
+ relation's conditions when they were destroyed, in both `deleted` and
38
+ `unreachable`. It returned every deleted record of the model that changed in
39
+ the window, so a report on one account's articles included other accounts'
40
+ deleted articles with their contents. The relation's conditions must be
41
+ plain conditions on the model's own columns; a join or SQL text raises
42
+ `ConfigurationError`.
43
+
44
+ ### Added
45
+
46
+ - `diagnose` reports every reason `compare` would refuse the same request as
47
+ an error, with `compare`'s message, so `ok?` is false whenever `compare`
48
+ would refuse. It said `ok?` for a path `compare` reads only approximately,
49
+ such as a scope written as SQL text, raised on an unknown or unsupported
50
+ association instead of reporting it, and checked only the join model a
51
+ `has_many :through` goes through first, not every model it reads. It
52
+ takes `allow_approximate:`, and with `true` reports such a path as an
53
+ `:approximate_association` warning. The new error codes are
54
+ `:unknown_association`, `:unsupported_association`, and
55
+ `:approximate_association`; an unversioned target's message now matches
56
+ `compare`'s.
57
+
58
+ - `diagnose` takes the current record as either endpoint, as `compare` does,
59
+ so `compare(version, record)` can be checked before it runs. Its version
60
+ checks then run from the version to the latest one. An endpoint that is
61
+ neither a version nor a saved record raises `InvalidEndpointError` naming
62
+ that, rather than `VersionMismatchError`.
63
+
64
+ - Activity steps list the events whose changes they show as `step.sources`,
65
+ oldest first. A step from `group: :transaction` lists every event in the
66
+ transaction, each with its own author, record, and version ID, where
67
+ `source_boundary` names only the first. `to_h(metadata: true)` adds a
68
+ `sources` list.
69
+ - `recorded_changes: true` on `activity_timeline`, on `analyze`, `analyze_many`,
70
+ and `analyze_scope` with `activity: true`, and on `report` gives each
71
+ boundary the changes its version recorded, as `recorded_changes(version)`
72
+ returns them. The versions are already loaded, so it adds no queries, and it
73
+ replaces the reference recipe that loaded every step's version again.
74
+ Without the option, `boundary.recorded_changes` raises `ConfigurationError`
75
+ rather than returning `nil`. Names in `ignore:` or `ignore: { all: }` are
76
+ left out, and so are names on the root path, `"$"`, for the root's own
77
+ versions. Names on an association path are not, because a child's version
78
+ does not say which path reached it.
79
+ - `change_rows` on an activity step, on an `Analysis` built with
80
+ `activity: true`, and on a `report` or `analyze_scope` result flattens
81
+ activity into `ChangeRow` objects: one per edited field, and one per record
82
+ that appeared or disappeared followed by its fields. Each names its record,
83
+ association path, and source version, and `to_h` gives a flat hash. It
84
+ replaces the README recipe for turning a report into rows, which had no rows
85
+ for whole records, so a record added or removed with only blank fields left
86
+ no trace.
87
+
88
+ - `associations:` takes what `includes` takes: a single name
89
+ (`associations: :comments`) or hashes of names to what to include below them
90
+ (`associations: [:author, { comments: :replies }]`), as well as the arrays of
91
+ names and dotted paths it took before.
92
+
93
+ - `nested_changes` compares two top-level arrays, as a `json` column can hold,
94
+ and reports one `ArrayChange` at the empty path, `[]`. It returned `{}`,
95
+ although arrays nested in an object were compared.
96
+
97
+ ### Changed
98
+
99
+ - The reference describes how PT-AT records HABTM membership and how the gem
100
+ credits it. A change made between two root versions is credited to the
101
+ step after the earlier one, so a checkpoint's capture is credited to whoever
102
+ saved the version before it; a checkpoint just before the change as well
103
+ credits it to its author. Only the first version an instance saves after
104
+ changing a HABTM is right; PT-AT never forgets the instance's changes, not
105
+ even on `reload`. A later save from it records the old membership, and the
106
+ gem reports members removed and added again that never left.
107
+
108
+ - The performance guide describes current behavior instead of logging each
109
+ past change: what the batch methods cost, what still grows with a report,
110
+ the version indexes, what costs a query per record, historical filters,
111
+ large reports, and how to measure. Its measurements were taken again. The
112
+ earlier ones remain in `benchmark/results/` and in the changelog.
113
+
114
+ - `historical_filter:` reads the history of the relation's records only, and
115
+ of deleted records, which a relation cannot test. It read every record of
116
+ the model that changed in the window, so a report on one account's articles
117
+ raised `BatchLimitExceededError` when another account had more matching
118
+ articles than `limit:`, and spent `max_filter_versions:` on their versions.
119
+ Matching deleted records no longer count toward `limit:` unless
120
+ `include_deleted: true` is given, as without a filter.
121
+
122
+ - The reference says how a record created without a version, such as one
123
+ imported with `insert_all`, and history pruned with `has_paper_trail
124
+ limit:` read.
125
+
126
+ - `IncompleteTimeRangeError` no longer advises the deprecated
127
+ `close_on: :current`. The quickstart and performance guide no longer say
128
+ that `has_many :through` or limited associations need the opt-ins, and the
129
+ reference says that `association_paths` lists paths that need
130
+ `allow_approximate: true`.
131
+
132
+ - The quickstart sets PaperTrail's `yaml_column_permitted_classes`. In a new
133
+ Rails 8.1 app, versions hold timestamps as `ActiveSupport::TimeWithZone`,
134
+ and the quickstart's first `reify` raised `Psych::DisallowedClass` without
135
+ it. Its documentation spec now reads a version in that form.
136
+
137
+ - The README and architecture guide recommend a second version index,
138
+ `(item_type, created_at, item_id)`. Batch methods with `since:` or
139
+ `within:` find changed records by type and time, which the one index they
140
+ recommended cannot narrow, so each report read every version of the model:
141
+ about 230 ms instead of 2 ms on PostgreSQL with 5 million versions.
142
+ - The gemspec requires Active Record 7.1 to 8.1. CI tests 7.2 through 8.1,
143
+ and the suite passes on 7.1. It named only PaperTrail, so Bundler could
144
+ install the gem with Active Record 6.1 or 7.0, whose relations and Arel
145
+ nodes the gem reads differently.
146
+ - `close_on:` is deprecated and warns through the new
147
+ `PaperTrailDiff.deprecator`. It has had no effect since a window began
148
+ closing on the current record by default; remove it. In a Rails app,
149
+ register the deprecator with
150
+ `Rails.application.deprecators[:paper_trail_diff] = PaperTrailDiff.deprecator`.
151
+ - `allow_expensive:` is deprecated and has no effect. It refused exactly the
152
+ paths `allow_approximate:` refuses, so batch methods needed both or
153
+ neither; `allow_approximate: true` alone now accepts such a path in every
154
+ method, and `UnsupportedBatchPathError` is no longer raised. Batch methods
155
+ refuse such a path before their first query, as before, now with
156
+ `UnsupportedAssociationError`.
157
+ - `reload_live_endpoints:` is deprecated and warns. It still works until it
158
+ is removed. Skipping the reload saves a query for the records and one per
159
+ association level in each call, 2 for 500 articles with their comments,
160
+ and reads values from objects that may be stale; it also needs every
161
+ requested association loaded, and reads limited ones again anyway. It was
162
+ on `compare`, `compare_many`, and `activity_timeline` only. Remove it.
163
+
164
+ ### Fixed
165
+
166
+ - A HABTM member created in the same transaction as the checkpoint that
167
+ records it is a member at that checkpoint, as a member attached there
168
+ already was. It was left out, because it had no state before the
169
+ transaction, so the checkpoint missed it and a comparison from the
170
+ checkpoint to now reported it added.
171
+
172
+ - `association_paths` leaves out an association whose target, or a model its
173
+ `has_many :through` goes through, has no `has_paper_trail`, such as the
174
+ `file_attachment` and `file_blob` that `has_one_attached` defines. Every
175
+ request that reads history refused them with `UnversionedAssociationError`,
176
+ so a settings screen built from the list offered paths that always failed.
177
+
178
+ - `diagnose` reports `:tied_version_timestamps`, and `compare` emits
179
+ `ambiguous_association_boundary.paper_trail_diff`, only when the request can
180
+ read a path with PT-AT: one history reads only approximately, a composite
181
+ foreign key, or a polymorphic `belongs_to`. PT-AT places association changes
182
+ by timestamp alone. For every other path, since 0.14.0, versions that share a
183
+ timestamp are ordered by ID, so a change between them is reported, yet both
184
+ warned that it could not be detected. A request refused for a path PT-AT
185
+ would read now raises before the notification.
186
+
187
+ - `timeline`, `activity_timeline`, and `analyze` read every version of a
188
+ model whose versions association has a scope
189
+ (`has_paper_trail versions: { scope: }`), as the other methods already did.
190
+ They read only the versions the scope kept, so a change saved in a version
191
+ it left out was credited to the next one kept: with a bot's edits hidden,
192
+ an editor's step showed the bot's later edit too, and the same record and
193
+ window gave different steps in `analyze` and `analyze_many`. A version the
194
+ scope leaves out is also accepted as an endpoint. To report only some
195
+ changes, pass `version_scope:`.
196
+
197
+ - Activity steps leave out the versions a record saved while it was outside
198
+ the root's tree. A comment edited on another article, then moved to this
199
+ one, brought that edit into the article's timeline as a step, and a
200
+ transaction group's `sources` listed it. Saved together with a comment added
201
+ to the article, the edit took the credit for the addition. The same went for
202
+ a comment edited after it moved away or left a scope, and for an author
203
+ renamed after the article changed authors. A version now counts when its
204
+ record is in the tree before or after its transaction. The versions of a
205
+ `has_many :through`'s join rows are all still kept.
206
+
207
+ - `timeline`, `activity_timeline`, `analyze`, and `analyze_many` raise
208
+ `InvalidEndpointError` naming what they were given when it is not a record
209
+ of a versioned model, such as `nil`, a model class, a relation, or a
210
+ version. They raised a bare `NoMethodError`, or said to provide `from` and
211
+ `to`. `report` names `since` when it is `nil` or a range.
212
+
213
+ - A scope ordered by a datetime, such as
214
+ `-> { order(created_at: :desc, id: :desc).limit(3) }`, is read from history
215
+ under Rails' default time-zone-aware attributes. Rails wraps those
216
+ attributes' types, which hid the datetime, so every method raised
217
+ `UnsupportedAssociationError` for the documented recipe.
218
+
219
+ - A `Date` bound of `within:` or `since:` is a whole day in `Time.zone`, and
220
+ a string a time in `Time.zone`, or in UTC without one. They were read in
221
+ the server's own zone, so the same window covered different hours on
222
+ different servers, and a same-day `Date..Date` window covered one instant
223
+ and found nothing.
224
+
225
+ - A `has_many :through` whose join model is not versioned raises
226
+ `UnversionedAssociationError` naming the join model when its history is
227
+ read, and `diagnose` reports it as an error, so `ok?` is false. A
228
+ comparison raised a bare `KeyError` while `diagnose` reported only a
229
+ warning.
230
+
231
+ - `reload_live_endpoints: false` reads an association with a `limit` or
232
+ `offset`, directly or in a part it goes through, or a scope that takes the
233
+ owner, again for each record. Active Record's `preload` applies the limit across all the records
234
+ it loads, so with three articles preloaded, two kept one comment each and
235
+ the third none, and their unchanged comments were reported as removed.
236
+
237
+ - A root and its associations that share one version table other than
238
+ PaperTrail's `versions` can be compared. Association lookups joined PT-AT's
239
+ version associations to the `versions` table whatever table the versions
240
+ were in, so every method raised `ActiveRecord::StatementInvalid`.
241
+
242
+ - A `within:` or `since:` window whose edge falls inside a transaction that
243
+ saved a version of the root record reports the whole transaction in the
244
+ later window. A window starting between a comment edit and the `touch: true`
245
+ article version saved with it showed the edit at the article's next change,
246
+ credited to that change's author, and the window ending there left it out;
247
+ when the article saved first, its version was in one window and the comment
248
+ edit in the other. Each root's edges move back to the transaction's start,
249
+ read in a fixed number of queries per batch.
250
+
251
+ - `activity_timeline`, and `analyze` with `activity: true`, no longer report a
252
+ child version saved in the same transaction as the root version that ends
253
+ the range. A `touch: true` parent version is saved this way after every
254
+ child save. PT-AT rebuilds the parent's associations at that version as they
255
+ were before the transaction, so the child's step was always empty and its
256
+ change was reported nowhere. The range now ends before that transaction, as
257
+ `compare` and `timeline` already did. End at a later version or at the
258
+ current record to include the change, with `group: :transaction` to credit it
259
+ to the child's version.
260
+ - A range that starts at a version now starts before that version's
261
+ transaction, as one that ends there already ended. A child version saved
262
+ earlier in the same transaction, such as the update behind a `touch: true`
263
+ parent version, was read after its change, so `compare`, `analyze`,
264
+ `timeline`, and `activity_timeline` from that version left the change out.
265
+ It was also missing from the range ending there, so a history split at that
266
+ version reported it nowhere. It is now inside the range that starts there.
267
+ - A past `within:` window in `activity_timeline`, and in `analyze`,
268
+ `analyze_many`, `analyze_scope`, and `report` with `activity: true`, no
269
+ longer includes association changes made after it. When the root had no
270
+ version after the window, the window closed on current state, so a comment
271
+ edited in August appeared in a July window, in its last step, `to_snapshot`,
272
+ and `diff`; with a later root version the same window was right. It now
273
+ closes on current state only when nothing on a requested path was recorded
274
+ after it. The reasoning in 0.8.0, that nothing had been recorded since,
275
+ checked only the root's own versions. `timeline`, and `analyze` without
276
+ `activity:`, still run their last step to the root's next version or the
277
+ current record; the reference now says so.
278
+ - Association scopes read from history now cover `IS NULL` and `IS NOT NULL`
279
+ on a column of any type, such as a soft-delete scope's
280
+ `where(deleted_at: nil)`, and `NOT` with SQL's rules for NULL, such as
281
+ `where.not(position: [1, nil])`. These were read with PT-AT before, so a
282
+ record restored from a soft delete showed as changed rather than added, and
283
+ batch methods refused them without `allow_expensive: true`. A condition on a
284
+ PostgreSQL `citext` column, which compares without regard to case, is no
285
+ longer read as exact text.
286
+ - A `historical_filter:` hash casts its values, and the recorded ones, to each
287
+ attribute's type before comparing them, as `where` does. An enum given as a
288
+ symbol (`{ status: :published }`), and a date or time read from a `json` or
289
+ `jsonb` version column, which PaperTrail returns as a string, never matched,
290
+ so the report silently selected nothing.
291
+ - Versions from two version tables saved in the same instant raise
292
+ `AmbiguousVersionOrderError`, as the reference promises, instead of being
293
+ ordered by their ids. Each table counts its ids separately, so their order
294
+ said nothing about which change came first, and an activity timeline built
295
+ from them could credit a change to the wrong step.
296
+ - `compare_many`, `analyze_many`, `analyze_scope`, and `report` load a
297
+ `has_one` of every current record in one query again, as before 0.14.0.
298
+ 0.14.0 meant to load only a `has_one` with a declared limit or offset per
299
+ record, but checked the association's scope, to which Active Record adds
300
+ `limit(1)` for every `has_one`, so every `has_one` cost one query per
301
+ record.
302
+ - `report`, `analyze_scope`, and `analyze_many` with `activity: true` no
303
+ longer read a root's current row once more for activity through a
304
+ `has_many :through` after its last version. The batch has already loaded
305
+ it, so the query count no longer grows with the number of roots.
306
+ - A snapshot's collections list their records by type, then ID, as the
307
+ reference says, wherever the snapshot was read from. Snapshots rebuilt from
308
+ history or carried through an activity timeline listed them in the order
309
+ they were found, and a ranked association in its query's order, so `to_h` of
310
+ the same state differed between methods. Diffs were already ordered.
311
+ - With a `json` or `jsonb` `object` column, an activity step no longer
312
+ reports an unchanged timestamp as changed. PaperTrail returns such a
313
+ column's times as strings, and a step after a child's update carried them
314
+ into the snapshot as they were, so the next step that read the child again
315
+ reported `created_at` changing from a string to the same time. Activity now
316
+ casts them as it does every other recorded state. The specs had covered the
317
+ JSON serializer on a text column only, which PaperTrail casts.
318
+
319
+ ### Development
320
+
321
+ - A new oracle suite, `rake spec_oracle`, checks rebuilt history against the
322
+ truth rather than against other gem methods. It makes seeded random edits to
323
+ an article graph one transaction at a time, records the live state after
324
+ each, and compares every endpoint, timeline step, activity step, window, and
325
+ batch result with those states. It also checks that two windows meeting
326
+ between transactions or inside one report each step once, scoped membership
327
+ against Active Record, and a tree of one model whose children have
328
+ encrypted, serialized, enum, custom-type, decimal, and JSON attributes.
329
+ `rake spec` runs it, so CI runs it on every database. `ORACLE_SEEDS` and
330
+ `ORACLE_STEPS` widen a run. See `docs/testing.md`.
331
+ - `PTD_PROBE_ALLOW_APPROXIMATE=1` makes the reconstruction probe pass
332
+ `allow_approximate: true`, so its PT-AT-read scenario runs rather than
333
+ raising, and neither benchmark passes the deprecated `close_on:` any more.
334
+ - On SQL Server the association specs keep their versions 5 ms apart. Specs
335
+ that compare the gem with PT-AT failed at random there: PT-AT compares
336
+ version times through SQL text, which the SQL Server adapter writes as
337
+ `datetime` values up to 1/300 s off, and after the host clock stepped back
338
+ the test clock packed versions microseconds apart until it caught up.
339
+ - The reporting benchmark loads the monotonic test clock, so its results no
340
+ longer depend on the host clock. A clock that stepped backwards, as WSL2's
341
+ does, could date a root's destroy before its last update, and
342
+ `deleted_roots` then raised `IncompleteTimeRangeError`. The seeded history
343
+ and query counts are unchanged. Allocations rise by under 1% in
344
+ `many_roots` and `retained_activity`, where the gem reads the clock once
345
+ per root. The investigation scripts that seed through the same workload
346
+ load the clock too; `scalar_cost.rb` freezes time in front of it, so its
347
+ parity check still sees one instant.
348
+
349
+ ## [0.14.0] - 2026-10-29
350
+
351
+ ### Breaking changes
352
+
353
+ - A `has_and_belongs_to_many` with a scope, or whose target has a default
354
+ scope, raises `UnsupportedAssociationError` up front in every method, and
355
+ `association_paths` leaves it out. PT-AT records a HABTM's members through
356
+ its scope when the owner saves, so a target that entered the scope between
357
+ saves was missing from history, and `activity_timeline` raised `KeyError`.
358
+ Replace it with a `has_many :through` a versioned join model.
359
+ - `report`, and `analyze_scope` with `activity: true`, also select a record
360
+ when only a record on one of its requested `associations:` changed in the
361
+ window: editing a comment selects its article. They used to skip it, although
362
+ `analyze_many` reports that activity. A report can therefore return more
363
+ records and reach `limit:` sooner. Nested paths count at every level,
364
+ `has_many :through` counts its join rows, and a child that moved selects its
365
+ old and new owner. Selection adds one query per association level, not per
366
+ record. Checkpoint analyses (`activity: false`) are unchanged: they compare a
367
+ record's own versions, so only those select it. To keep only records that
368
+ changed themselves, drop analyses whose `timeline` is empty. A record
369
+ selected through a HABTM path in a window that ends at the current record
370
+ raises `UnsupportedLiveActivityError`, as one that changed itself already
371
+ does.
372
+ - A path that continues past a polymorphic `belongs_to`, such as
373
+ `"notable.comments"`, raises `UnsupportedAssociationError`. The part after
374
+ it used to be ignored without a word.
375
+ - A HABTM below the root, such as `"tags.articles"`, `"author.articles.tags"`,
376
+ or `"comments.article.tags"`, raises `UnsupportedAssociationError` up front
377
+ in every method, naming the path and the HABTM. `association_paths` leaves
378
+ such a path out. PT-AT records HABTM membership only when its owner saves a
379
+ version, in rows that do not name the owner, so a root checkpoint holds the
380
+ root's membership alone. These paths read the root's rows instead and
381
+ returned a wrong diff. An article that joined a tag went unreported, and
382
+ against the current record every member read as added. A sibling article
383
+ reached through its author was given the root's tags. `activity_timeline`
384
+ raised `KeyError`. Only a path that led back to the root, like
385
+ `"comments.article.tags"`, read correctly; request `"tags"` instead.
386
+ - A root HABTM read at a version saved in the same transaction as a version of
387
+ another record with a HABTM of that name raises
388
+ `IncompleteAssociationHistoryError`, naming the association and the
389
+ transaction, when PT-AT recorded members there. Those rows do not say which
390
+ record they belong to, so the root used to read every such record's members
391
+ as its own: two articles updated in one transaction each gained the other's
392
+ tags, and an unchanged article reported them removed. It happened in every
393
+ method, with no error. A transaction where only one record with that
394
+ association saved a version, or where none recorded a member, reads as
395
+ before, and `diagnose` reports the shared case as `habtm_transaction_shared`.
396
+ Save HABTM owners' versions in separate transactions, as a
397
+ [checkpoint](docs/reference.md#saving-a-checkpoint) does.
398
+
399
+ ### Added
400
+
401
+ - `recorded_changes(version)` returns what PaperTrail stored with one version
402
+ in `object_changes`, as a frozen hash of `ValueChange` objects, typed by the
403
+ version's model. Unlike PaperTrail's `version.changeset`, it never loads the
404
+ record, so it costs no query per version and still types a deleted record's
405
+ values. It returns `nil` when nothing was recorded, and takes an `ignore:`
406
+ array that defaults to `updated_at`.
407
+
408
+ ### Changed
409
+
410
+ - Batch reads of a `has_many :through` and of a polymorphic `belongs_to` no
411
+ longer call `reify` on each root version. They are read from stored
412
+ attributes like other associations. In the reconstruction probe, `report`
413
+ over a through went from 7 `reify` calls per root to none and builds about
414
+ half as many model instances. Results are unchanged. A type that names no
415
+ class, an unversioned target, and a scope that cannot be read as conditions
416
+ still take the record path.
417
+ - Batch methods read an association scope, or a target's default scope, made
418
+ of plain conditions on the target's columns (equality, `IN`, `nil`, their
419
+ `where.not` forms, combined with `and` and `or`) from prepared history, so
420
+ they no longer need `allow_expensive: true` for it and its query count no
421
+ longer grows with the records. String conditions are read this way only on
422
+ SQLite and PostgreSQL. Scopes that take the owner and other conditions are
423
+ still rejected without the opt-in. A default-scoped model whose scope assigns
424
+ no attributes is read without `reify`.
425
+ - Batch methods also read a `limit` or `offset`, and the order of a `has_one`,
426
+ from prepared history when the order is total, reaching the primary key, and
427
+ sorts only by integer, boolean, or integer enum columns of the target. NULL
428
+ sorts as each adapter puts it by default. In the reconstruction probe,
429
+ `report` over `order(:id).limit(1)` went from 252 queries and 160 `reify`
430
+ calls at 20 roots, with the opt-in, to 32 queries and none without it. A
431
+ string order, an order with ties, and a `has_one :through` over a ranked
432
+ part are still rejected without the opt-in.
433
+ - Batch methods also rank by date columns, and by datetime columns when the
434
+ column declares a precision that history keeps and times are stored in UTC,
435
+ such as `order(created_at: :desc).limit(5)` with YAML history. JSON history
436
+ keeps milliseconds by default, so with it only a `datetime(3)` column is
437
+ read. A time-of-day column, and a datetime without a precision, are still
438
+ rejected without the opt-in.
439
+ - Batch methods read a `has_many :through` over a part with a `limit`,
440
+ `offset`, or `has_one` order, and one with its own `limit` or `offset`, from
441
+ prepared history without the opt-in.
442
+ - The README recipe for deleted records also reads each record as it was just
443
+ before deletion, which a record created inside the window has no other
444
+ snapshot of.
445
+ - The documentation now says where a change saved without a version, such as
446
+ with `update_columns`, appears: in the step for that record's previous
447
+ recorded change, credited to its author, anywhere in a range. It used to say
448
+ only that the last step of a range ending at the current record shows them,
449
+ and that a step's diff is exactly what its event changed. Ending a range at a
450
+ version leaves out only the writes after it. Specs pin this behavior, which
451
+ is unchanged.
452
+ - The README has a recipe that turns a report into one row per changed field,
453
+ with the record, whether it changed, appeared, or disappeared, and the step's
454
+ author, event, and time.
455
+ - Batch methods no longer need `allow_expensive: true` for a
456
+ `has_many :through` whose source is a `has_many`, such as an author's
457
+ comments through articles. It is read from prepared history like the other
458
+ associations, so its queries no longer grow with the records: the five-record
459
+ probe in `docs/performance.md` went from 200 queries to 20.
460
+
461
+ ### Fixed
462
+
463
+ - A `limit` or `offset` scope, or an ordered `has_one`, read at a version
464
+ returns the records its query returned then, when the order is total and
465
+ sorts by columns batch methods can rank. It used to start from
466
+ the association's current rows, so a range whose records later changed
467
+ reported the wrong ones: with comments `first` and `second` under
468
+ `order(:id).limit(1)`, destroying `first` and adding `third` reported
469
+ `third` added instead of `second`. Other ranked scopes still read the
470
+ current rows.
471
+ - A `has_many :through` reads its parts as its own query does, keeping their
472
+ conditions but not their `limit`, `offset`, or `has_one` cut. History used
473
+ to apply them, and read with the opt-in it could raise PT-AT's
474
+ `FoundMoreThanOne`; batched history kept only one record through a `has_one`
475
+ part. A through's own `limit` or `offset` counts a record reached through
476
+ two join records twice, as the query does.
477
+ - Batch comparisons with a current endpoint load a `has_many :through` over a
478
+ part with a `limit`, `offset`, or `has_one` per record. Active Record's
479
+ preloader applied the part's limit across every record in the batch, so a
480
+ record could show another's members or none.
481
+ - A record reached through two join records is one member of a current
482
+ association, as it already was of a historical one, so a through loaded per
483
+ record no longer raises a duplicate identity error.
484
+ - In a batch, a `has_one` with an `offset` is loaded per record at the current
485
+ end. The preloader applied the offset across all records at once, so a
486
+ record could show another record's member.
487
+ - Activity reports a change to a `belongs_to` target that is an STI subclass.
488
+ When the target was destroyed, or its `type` changed between a subclass and
489
+ another class, activity reported nothing while checkpoint analysis reported
490
+ it, because a target's version names only the base class. This includes the
491
+ same target further down a path, such as `"note.badge"`.
492
+ - An association that only an STI subclass declares can be requested on a
493
+ root of that subclass in every method. Without an `item_subtype` column on
494
+ versions, each version resolved to the base class, so every method raised
495
+ `UnknownAssociationError`. The subclass is now read from the type the
496
+ version stored, or for a `create`, from its recorded changes. A stored type
497
+ that names no class raises `InvalidEndpointError`.
498
+ - A `has_many :through` with `source_type:` holds only the records reached
499
+ through join records of that type, in every method. History used to ignore
500
+ the option, so a join record pointing at another type made its target a
501
+ member: a holder whose links named a tag reported the tag among its authors,
502
+ and the tag's changes opened activity steps and selected the holder in
503
+ `report`. The current record was read correctly, so a comparison with it
504
+ reported the tag as removed. A join record whose type changes now adds or
505
+ removes its target in the step of that version.
506
+ - A scoped or default-scoped association read from history now holds the
507
+ records that met the scope at each point. It used to ignore the scope's
508
+ conditions for history: a record that left the scope was reported as
509
+ changed instead of removed, one that entered it as changed instead of
510
+ added, and a record outside the scope could be reported as removed when it
511
+ was destroyed or moved. Activity reports entering or leaving the scope as
512
+ an addition or removal at the version that did it.
513
+ - `compare` and `compare_many` between two versions report a `has_many` child
514
+ that moved to another owner afterwards. They reported no change: the
515
+ comparison read associations through PT-AT, which finds children by the keys
516
+ their versions recorded after each change, so the child was not found at the
517
+ earlier version. Version pairs now read the same prepared history as a
518
+ comparison with the current record, including for a record that was deleted.
519
+ - Historical analysis through a polymorphic `belongs_to` works in every method.
520
+ Only comparisons between two versions used to work: timelines, analyses,
521
+ reports, and comparisons with the current record raised `ArgumentError`.
522
+ Batches load the targets with one query per target class. A target class
523
+ without `has_paper_trail` raises `UnversionedAssociationError` when a record
524
+ names it, rather than a `NoMethodError` from PT-AT, and a default-scoped
525
+ target class is read as its association returns it. A type that names no
526
+ class, such as one a renamed model left in its versions, raises
527
+ `IncompleteAssociationHistoryError` naming the record and the type, rather
528
+ than a `NameError` that names neither.
529
+ - Activity leaves out the `belongs_to` target a record moves to in the
530
+ version that closes the window. Its changes inside the window used to add
531
+ empty steps, attributed to a record the root never pointed at there.
532
+ - Activity reports a change to a `belongs_to` target, or to the source of a
533
+ `has_many :through`, when the record pointing at it did not change in the
534
+ window: an author renamed under an article nobody edited. It used to report
535
+ nothing. A record that changed its target in the window also reports
536
+ changes to the target it pointed at before.
537
+ - `include_deleted: true` with `activity: true` reports the association
538
+ activity of a deleted record that did not change itself in the window. Its
539
+ analysis used to be empty.
540
+ - History of an association to an STI subclass, such as
541
+ `has_many :pinned_badges, class_name: 'PinnedBadge'`, holds only that class
542
+ and its subclasses, as the live association does. It used to hold the
543
+ sibling classes' records too, so a range ending at the current record
544
+ reported them as removed. Activity used to report a sibling's changes under
545
+ the association too, and to open a step for each version of a sibling or of
546
+ its children.
547
+ - Activity reports a record whose STI type changed in the step of the version
548
+ that changed it, as a removal of the old type and an addition of the new,
549
+ and adds it to or removes it from an association to an STI subclass there.
550
+ It used to add the new type alongside the old one and leave the old one in
551
+ place until a later step, or to the end of a range ending at a version.
552
+ - `activity_timeline`, and `analyze` with `activity: true`, return no steps for
553
+ a range that ends at a version when `version_scope:` keeps none of its
554
+ versions, as a checkpoint timeline does. They used to raise `NoMethodError`.
555
+ - `analyze_scope` and `report` list `unreachable` in the same sorted order
556
+ whatever the type of `versions.item_id`. With a string `item_id` it used to
557
+ follow the database's order.
558
+ - On SQL Server, activity places a version saved within two milliseconds of a
559
+ window's start or end on the side it was saved. The window's bounds used to
560
+ be rounded to 1/300 second, so such a version could be read as outside the
561
+ window, or one just past its end as inside it.
562
+ - A `has_many :through` that goes through a `has_and_belongs_to_many`, as its
563
+ `through:`, its `source:`, or further down its chain, raises
564
+ `UnsupportedAssociationError` up front in every method, naming the path and
565
+ the HABTM. Comparing two versions used to raise `NoMethodError` from inside
566
+ PT-AT, and analyses `ActiveRecord::StatementInvalid`. A `has_many :through`
567
+ Active Record cannot follow at all, such as one through a polymorphic
568
+ `belongs_to`, likewise raises Active Record's own error in every method,
569
+ where historical work used to fail partway with `ArgumentError` or
570
+ `NoMethodError`.
571
+ - `association_paths` leaves out a `has_many :through` that goes through a
572
+ `has_and_belongs_to_many`, so every path it lists can be requested. It
573
+ decides with the same check a request makes. It used to list such a path,
574
+ and a settings screen built from it offered one that failed when picked. A
575
+ model it reaches with a `has_many :through` Active Record cannot follow,
576
+ such as one through a polymorphic `belongs_to`, raises Active Record's own
577
+ error, where discovery used to raise `ArgumentError`, `NameError`, or
578
+ `NoMethodError` from inside the reflection, or list a path that raised when
579
+ requested.
580
+ - A `has_many :through` whose source is a `has_many` follows records that
581
+ move. A comment moved to another article leaves the first article's author
582
+ and joins the other's, and an article that moves to another author takes its
583
+ comments with it. Analyses, timelines, and comparisons with the current
584
+ record used to report no change for such a move, and could report a record
585
+ that left and came back as changed. They read these associations through
586
+ PT-AT, which finds a record by the keys its later versions recorded.
587
+ - A `has_many :through` whose `through:` is itself a `has_many :through`, such
588
+ as `has_many :comment_reviewers, through: :comments, source: :reviewer` with
589
+ `comments` through `articles`, reports its changes in analyses, timelines,
590
+ and batches. It used to read as empty at every point, so it never reported a
591
+ change.
592
+
593
+ ### Development
594
+
595
+ - Mutation testing also covers `ScopeCondition`, which decides the records an
596
+ association scope admits. The reconstruction probe has a `scoped` scenario.
597
+ - The consistency specs also check that activity selection includes every
598
+ record whose analysis reports a change.
599
+ - Mutation testing also covers `TimeRange`, `VersionRange`,
600
+ `TimeVersionRange`, `BatchedRootVersions`, and `DeletedAnalysisBatch`, each
601
+ with a unit spec of its own; all 5,485 mutations across the fourteen classes
602
+ are caught.
603
+ - Mutation testing also covers `RecordedChanges`; all 257 of its mutations are
604
+ caught.
605
+ - Mutation testing also covers the association code: `ScopedRootSelection`,
606
+ `AssociationActivitySelection`, `AssociationActivityEdge`,
607
+ `ActivityTargetCandidateLoader`, `PreparedHistoryLoader`,
608
+ `PreparedEdgeLoader`, `ActivityTimelineBuilder`,
609
+ `ActivityTransactionGrouper`, and `BatchSafety`, each with a spec of its
610
+ own. All 10,732 mutations across the 24 classes are caught.
611
+ - Mutation testing also covers `AssociationTraversal`, which decides which
612
+ association paths a request accepts, with a spec of its own; all 764 of its
613
+ mutations are caught.
614
+ - Mutation testing also covers range and boundary handling:
615
+ `ActivityRange`, `VersionAssociationCandidateScope`, and
616
+ `PreparedActivityIndex`, each with a spec of its own; all 1,507 of their
617
+ mutations are caught.
618
+ - Mutation testing also covers `HabtmTransactionOwners`, which decides whether
619
+ a transaction's HABTM members can be read as one record's, with a spec of
620
+ its own.
621
+ - `benchmark/investigation/reconstruction.rb` runs again: the association
622
+ fixtures load the monotonic test clock they use. Its `prepared-through`
623
+ experiment and `benchmark/investigation/prepared_through_override.rb` are
624
+ removed, since the gem now reads those throughs that way.
625
+ - `spec/association/through_membership_spec.rb` writes out the expected
626
+ membership of a `has_many :through` with a `has_many` source over moves,
627
+ deletions, transactions, and changes saved without a version, alone and in
628
+ a batch.
629
+ - `ActivityEventRouteFinder` no longer checks for a polymorphic `belongs_to`
630
+ before following a path below it. Validation already rejects such a path,
631
+ so the check could not be reached.
632
+ - The `PreparedHistoryLoader` spec checks that an edge into a versioned model
633
+ with records stays prepared. A full mutation run of the 29 classes now
634
+ catches all 13,284 mutations.
635
+
6
636
  ## [0.13.1] - 2026-10-28
7
637
 
8
638
  ### Fixed