paper_trail_diff 0.16.0 → 0.17.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (206) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +566 -1
  3. data/README.md +42 -7
  4. data/docs/architecture.md +7 -5
  5. data/docs/performance.md +86 -38
  6. data/docs/reference.md +309 -92
  7. data/docs/testing.md +240 -32
  8. data/lib/paper_trail_diff/activity_belongs_to_event_applier.rb +2 -16
  9. data/lib/paper_trail_diff/activity_boundary.rb +55 -34
  10. data/lib/paper_trail_diff/activity_child_candidate_loader.rb +46 -57
  11. data/lib/paper_trail_diff/activity_collection_event_applier.rb +3 -13
  12. data/lib/paper_trail_diff/activity_collection_route_updater.rb +1 -1
  13. data/lib/paper_trail_diff/activity_event.rb +33 -21
  14. data/lib/paper_trail_diff/activity_event_record_resolver.rb +16 -116
  15. data/lib/paper_trail_diff/activity_event_route_finder.rb +29 -29
  16. data/lib/paper_trail_diff/activity_event_snapshot_refresher.rb +2 -7
  17. data/lib/paper_trail_diff/activity_history.rb +90 -49
  18. data/lib/paper_trail_diff/activity_range.rb +9 -35
  19. data/lib/paper_trail_diff/activity_root_snapshot_refresher.rb +74 -40
  20. data/lib/paper_trail_diff/activity_root_steps.rb +10 -13
  21. data/lib/paper_trail_diff/activity_scope_filter.rb +77 -0
  22. data/lib/paper_trail_diff/activity_snapshot_delta.rb +12 -15
  23. data/lib/paper_trail_diff/activity_snapshot_sequence.rb +37 -15
  24. data/lib/paper_trail_diff/activity_target_candidate_loader.rb +35 -43
  25. data/lib/paper_trail_diff/activity_timeline_builder.rb +194 -249
  26. data/lib/paper_trail_diff/activity_transaction_grouper.rb +3 -1
  27. data/lib/paper_trail_diff/activity_tree_filter.rb +54 -13
  28. data/lib/paper_trail_diff/activity_version_collector.rb +72 -138
  29. data/lib/paper_trail_diff/activity_view.rb +22 -11
  30. data/lib/paper_trail_diff/analysis.rb +19 -5
  31. data/lib/paper_trail_diff/analysis_batch.rb +16 -58
  32. data/lib/paper_trail_diff/approximate_paths.rb +4 -8
  33. data/lib/paper_trail_diff/association_activity_edge.rb +5 -24
  34. data/lib/paper_trail_diff/association_activity_selection.rb +10 -18
  35. data/lib/paper_trail_diff/association_discovery.rb +1 -6
  36. data/lib/paper_trail_diff/association_key.rb +9 -6
  37. data/lib/paper_trail_diff/association_traversal.rb +49 -6
  38. data/lib/paper_trail_diff/batch_boundary_resolver.rb +33 -42
  39. data/lib/paper_trail_diff/batch_preload.rb +2 -12
  40. data/lib/paper_trail_diff/batched_root_analyses.rb +72 -0
  41. data/lib/paper_trail_diff/batched_root_analyzer.rb +16 -14
  42. data/lib/paper_trail_diff/batched_root_versions.rb +25 -20
  43. data/lib/paper_trail_diff/branch_snapshot_refresher.rb +27 -31
  44. data/lib/paper_trail_diff/change_attribution.rb +314 -0
  45. data/lib/paper_trail_diff/change_row.rb +30 -10
  46. data/lib/paper_trail_diff/comparison_batch.rb +3 -4
  47. data/lib/paper_trail_diff/configuration.rb +1 -1
  48. data/lib/paper_trail_diff/deleted_analysis_batch.rb +22 -37
  49. data/lib/paper_trail_diff/deleted_root_filter.rb +3 -6
  50. data/lib/paper_trail_diff/deprecation.rb +4 -43
  51. data/lib/paper_trail_diff/diagnostics.rb +1 -2
  52. data/lib/paper_trail_diff/direct_record_state_loader.rb +8 -1
  53. data/lib/paper_trail_diff/endpoint.rb +78 -44
  54. data/lib/paper_trail_diff/errors.rb +2 -9
  55. data/lib/paper_trail_diff/fallback_paths.rb +2 -5
  56. data/lib/paper_trail_diff/habtm_transaction_owners.rb +5 -3
  57. data/lib/paper_trail_diff/historical_association_reifier.rb +3 -1
  58. data/lib/paper_trail_diff/historical_filter.rb +40 -15
  59. data/lib/paper_trail_diff/historical_snapshot_store.rb +80 -38
  60. data/lib/paper_trail_diff/instrumentation.rb +0 -8
  61. data/lib/paper_trail_diff/live_endpoint_batch_loader.rb +11 -7
  62. data/lib/paper_trail_diff/live_endpoint_provider.rb +7 -23
  63. data/lib/paper_trail_diff/live_graph_collector.rb +3 -3
  64. data/lib/paper_trail_diff/nested_comparator.rb +46 -19
  65. data/lib/paper_trail_diff/net_change.rb +276 -0
  66. data/lib/paper_trail_diff/own_window.rb +35 -0
  67. data/lib/paper_trail_diff/paper_trail_adapter.rb +40 -45
  68. data/lib/paper_trail_diff/prepared_activity_index.rb +170 -42
  69. data/lib/paper_trail_diff/prepared_child_candidates.rb +58 -0
  70. data/lib/paper_trail_diff/prepared_edge_loader.rb +43 -107
  71. data/lib/paper_trail_diff/prepared_history.rb +20 -31
  72. data/lib/paper_trail_diff/prepared_history_loader.rb +46 -9
  73. data/lib/paper_trail_diff/prepared_record_index.rb +137 -47
  74. data/lib/paper_trail_diff/prepared_snapshot_builder.rb +16 -0
  75. data/lib/paper_trail_diff/prepared_state_association_reader.rb +17 -19
  76. data/lib/paper_trail_diff/read_snapshot.rb +41 -19
  77. data/lib/paper_trail_diff/recorded_changes.rb +10 -11
  78. data/lib/paper_trail_diff/recorded_changes_reader.rb +60 -0
  79. data/lib/paper_trail_diff/recorded_class.rb +14 -19
  80. data/lib/paper_trail_diff/recorded_columns.rb +33 -0
  81. data/lib/paper_trail_diff/root_version_plan.rb +20 -22
  82. data/lib/paper_trail_diff/root_version_selection.rb +39 -29
  83. data/lib/paper_trail_diff/scope_condition.rb +7 -17
  84. data/lib/paper_trail_diff/scope_ranking.rb +16 -22
  85. data/lib/paper_trail_diff/scoped_analysis.rb +27 -4
  86. data/lib/paper_trail_diff/scoped_analysis_builder.rb +4 -3
  87. data/lib/paper_trail_diff/scoped_root_selection.rb +60 -41
  88. data/lib/paper_trail_diff/snapshot_normalizer.rb +18 -3
  89. data/lib/paper_trail_diff/stored_json_values.rb +52 -0
  90. data/lib/paper_trail_diff/stored_time_precision.rb +30 -18
  91. data/lib/paper_trail_diff/stored_values.rb +20 -0
  92. data/lib/paper_trail_diff/support.rb +185 -35
  93. data/lib/paper_trail_diff/time_of_day.rb +39 -0
  94. data/lib/paper_trail_diff/time_range.rb +37 -20
  95. data/lib/paper_trail_diff/time_version_range.rb +5 -10
  96. data/lib/paper_trail_diff/timeline_builder.rb +3 -3
  97. data/lib/paper_trail_diff/timeline_range.rb +18 -12
  98. data/lib/paper_trail_diff/timeline_snapshot_provider.rb +1 -1
  99. data/lib/paper_trail_diff/total_order.rb +55 -0
  100. data/lib/paper_trail_diff/transaction_cut.rb +192 -91
  101. data/lib/paper_trail_diff/traversal_preparer.rb +5 -8
  102. data/lib/paper_trail_diff/value_objects.rb +8 -4
  103. data/lib/paper_trail_diff/version.rb +1 -1
  104. data/lib/paper_trail_diff/version_association_candidate_scope.rb +1 -12
  105. data/lib/paper_trail_diff/version_boundary.rb +37 -21
  106. data/lib/paper_trail_diff/version_query.rb +25 -25
  107. data/lib/paper_trail_diff/version_range.rb +12 -16
  108. data/lib/paper_trail_diff/version_sequence_diagnostics.rb +32 -0
  109. data/lib/paper_trail_diff/version_table.rb +12 -8
  110. data/lib/paper_trail_diff.rb +28 -42
  111. data/sig/generated/paper_trail_diff/activity_belongs_to_event_applier.rbs +0 -8
  112. data/sig/generated/paper_trail_diff/activity_boundary.rbs +39 -17
  113. data/sig/generated/paper_trail_diff/activity_child_candidate_loader.rbs +19 -22
  114. data/sig/generated/paper_trail_diff/activity_collection_event_applier.rbs +0 -5
  115. data/sig/generated/paper_trail_diff/activity_event.rbs +25 -9
  116. data/sig/generated/paper_trail_diff/activity_event_record_resolver.rbs +6 -34
  117. data/sig/generated/paper_trail_diff/activity_event_route_finder.rbs +11 -4
  118. data/sig/generated/paper_trail_diff/activity_event_snapshot_refresher.rbs +0 -3
  119. data/sig/generated/paper_trail_diff/activity_history.rbs +54 -19
  120. data/sig/generated/paper_trail_diff/activity_range.rbs +6 -20
  121. data/sig/generated/paper_trail_diff/activity_root_snapshot_refresher.rbs +36 -2
  122. data/sig/generated/paper_trail_diff/activity_root_steps.rbs +6 -6
  123. data/sig/generated/paper_trail_diff/activity_scope_filter.rbs +51 -0
  124. data/sig/generated/paper_trail_diff/activity_snapshot_delta.rbs +5 -3
  125. data/sig/generated/paper_trail_diff/activity_snapshot_sequence.rbs +21 -3
  126. data/sig/generated/paper_trail_diff/activity_target_candidate_loader.rbs +19 -24
  127. data/sig/generated/paper_trail_diff/activity_timeline_builder.rbs +121 -127
  128. data/sig/generated/paper_trail_diff/activity_tree_filter.rbs +41 -8
  129. data/sig/generated/paper_trail_diff/activity_version_collector.rbs +42 -35
  130. data/sig/generated/paper_trail_diff/activity_view.rbs +16 -8
  131. data/sig/generated/paper_trail_diff/analysis.rbs +15 -6
  132. data/sig/generated/paper_trail_diff/analysis_batch.rbs +6 -24
  133. data/sig/generated/paper_trail_diff/association_activity_edge.rbs +0 -13
  134. data/sig/generated/paper_trail_diff/association_activity_selection.rbs +6 -9
  135. data/sig/generated/paper_trail_diff/association_discovery.rbs +0 -3
  136. data/sig/generated/paper_trail_diff/association_key.rbs +5 -0
  137. data/sig/generated/paper_trail_diff/association_traversal.rbs +26 -2
  138. data/sig/generated/paper_trail_diff/batch_boundary_resolver.rbs +17 -17
  139. data/sig/generated/paper_trail_diff/batch_preload.rbs +0 -4
  140. data/sig/generated/paper_trail_diff/batched_root_analyses.rbs +47 -0
  141. data/sig/generated/paper_trail_diff/batched_root_analyzer.rbs +9 -8
  142. data/sig/generated/paper_trail_diff/batched_root_versions.rbs +10 -6
  143. data/sig/generated/paper_trail_diff/branch_snapshot_refresher.rbs +11 -5
  144. data/sig/generated/paper_trail_diff/change_attribution.rbs +185 -0
  145. data/sig/generated/paper_trail_diff/change_row.rbs +22 -7
  146. data/sig/generated/paper_trail_diff/deleted_analysis_batch.rbs +11 -12
  147. data/sig/generated/paper_trail_diff/deleted_root_filter.rbs +0 -2
  148. data/sig/generated/paper_trail_diff/deprecation.rbs +4 -24
  149. data/sig/generated/paper_trail_diff/direct_record_state_loader.rbs +4 -0
  150. data/sig/generated/paper_trail_diff/endpoint.rbs +40 -16
  151. data/sig/generated/paper_trail_diff/errors.rbs +2 -11
  152. data/sig/generated/paper_trail_diff/habtm_transaction_owners.rbs +2 -1
  153. data/sig/generated/paper_trail_diff/historical_filter.rbs +20 -9
  154. data/sig/generated/paper_trail_diff/historical_snapshot_store.rbs +40 -10
  155. data/sig/generated/paper_trail_diff/instrumentation.rbs +0 -3
  156. data/sig/generated/paper_trail_diff/live_endpoint_batch_loader.rbs +3 -0
  157. data/sig/generated/paper_trail_diff/live_endpoint_provider.rbs +5 -8
  158. data/sig/generated/paper_trail_diff/live_graph_collector.rbs +2 -2
  159. data/sig/generated/paper_trail_diff/nested_comparator.rbs +20 -4
  160. data/sig/generated/paper_trail_diff/net_change.rbs +168 -0
  161. data/sig/generated/paper_trail_diff/own_window.rbs +22 -0
  162. data/sig/generated/paper_trail_diff/paper_trail_adapter.rbs +9 -6
  163. data/sig/generated/paper_trail_diff/prepared_activity_index.rbs +103 -14
  164. data/sig/generated/paper_trail_diff/prepared_child_candidates.rbs +39 -0
  165. data/sig/generated/paper_trail_diff/prepared_edge_loader.rbs +18 -35
  166. data/sig/generated/paper_trail_diff/prepared_history.rbs +9 -12
  167. data/sig/generated/paper_trail_diff/prepared_history_loader.rbs +28 -3
  168. data/sig/generated/paper_trail_diff/prepared_record_index.rbs +68 -14
  169. data/sig/generated/paper_trail_diff/prepared_snapshot_builder.rbs +12 -0
  170. data/sig/generated/paper_trail_diff/prepared_state_association_reader.rbs +6 -7
  171. data/sig/generated/paper_trail_diff/read_snapshot.rbs +27 -8
  172. data/sig/generated/paper_trail_diff/recorded_changes.rbs +4 -2
  173. data/sig/generated/paper_trail_diff/recorded_changes_reader.rbs +41 -0
  174. data/sig/generated/paper_trail_diff/recorded_class.rbs +7 -6
  175. data/sig/generated/paper_trail_diff/recorded_columns.rbs +21 -0
  176. data/sig/generated/paper_trail_diff/root_version_plan.rbs +8 -4
  177. data/sig/generated/paper_trail_diff/root_version_selection.rbs +27 -13
  178. data/sig/generated/paper_trail_diff/scope_condition.rbs +0 -2
  179. data/sig/generated/paper_trail_diff/scope_ranking.rbs +10 -10
  180. data/sig/generated/paper_trail_diff/scoped_analysis.rbs +19 -0
  181. data/sig/generated/paper_trail_diff/scoped_analysis_builder.rbs +2 -2
  182. data/sig/generated/paper_trail_diff/scoped_root_selection.rbs +37 -14
  183. data/sig/generated/paper_trail_diff/snapshot_normalizer.rbs +7 -0
  184. data/sig/generated/paper_trail_diff/stored_json_values.rbs +35 -0
  185. data/sig/generated/paper_trail_diff/stored_time_precision.rbs +19 -5
  186. data/sig/generated/paper_trail_diff/stored_values.rbs +13 -0
  187. data/sig/generated/paper_trail_diff/support.rbs +120 -23
  188. data/sig/generated/paper_trail_diff/time_of_day.rbs +21 -0
  189. data/sig/generated/paper_trail_diff/time_range.rbs +15 -8
  190. data/sig/generated/paper_trail_diff/time_version_range.rbs +2 -5
  191. data/sig/generated/paper_trail_diff/timeline_builder.rbs +2 -2
  192. data/sig/generated/paper_trail_diff/timeline_range.rbs +12 -7
  193. data/sig/generated/paper_trail_diff/total_order.rbs +32 -0
  194. data/sig/generated/paper_trail_diff/transaction_cut.rbs +111 -52
  195. data/sig/generated/paper_trail_diff/traversal_preparer.rbs +2 -2
  196. data/sig/generated/paper_trail_diff/value_objects.rbs +5 -1
  197. data/sig/generated/paper_trail_diff/version_association_candidate_scope.rbs +0 -7
  198. data/sig/generated/paper_trail_diff/version_boundary.rbs +15 -8
  199. data/sig/generated/paper_trail_diff/version_query.rbs +17 -10
  200. data/sig/generated/paper_trail_diff/version_range.rbs +6 -9
  201. data/sig/generated/paper_trail_diff/version_sequence_diagnostics.rbs +13 -0
  202. data/sig/generated/paper_trail_diff/version_table.rbs +3 -0
  203. data/sig/generated/paper_trail_diff.rbs +16 -16
  204. metadata +28 -6
  205. data/lib/paper_trail_diff/preloaded_endpoint_batch_loader.rb +0 -60
  206. data/sig/generated/paper_trail_diff/preloaded_endpoint_batch_loader.rbs +0 -32
data/docs/testing.md CHANGED
@@ -16,15 +16,41 @@ correct.
16
16
 
17
17
  For reporting workloads, query counts, reconstruction cost, and memory readings,
18
18
  see [Reporting performance](performance.md). Those measurements run separately
19
- from the correctness suite and have no timing-based CI gate.
19
+ from the correctness suite and have no timing-based CI gate; the
20
+ [SQL work](#sql-work) spec checks how a report's SQL grows instead.
20
21
 
21
22
  CI keeps the Ruby 3.1–4.0 and PaperTrail 16/17 compatibility matrix on SQLite,
22
23
  including Windows runs. Separate Linux jobs run both core and association suites
23
24
  on PostgreSQL 17, MySQL 8.4, and SQL Server 2019 and 2022 with Ruby 4.0 and
24
- PaperTrail 17.
25
+ PaperTrail 17. The SQL Server 2022 job's database allows snapshot isolation
26
+ and the 2019 job's does not, so each call's `SNAPSHOT` read is run both ways.
25
27
  The SQL jobs exercise the same regressions, including joined-column ordering,
26
28
  duplicate roots, pagination, and historical association reconstruction.
27
29
 
30
+ ## JSON history
31
+
32
+ PaperTrail writes history with YAML unless an app sets its JSON serializer, so
33
+ the suites do too. To run them with JSON history instead:
34
+
35
+ ```console
36
+ PAPER_TRAIL_DIFF_SERIALIZER=json mise exec -- bundle exec rake spec
37
+ ```
38
+
39
+ A CI job runs them that way on Ruby 4.0 and PaperTrail 17. The PaperTrail 16
40
+ jobs run Active Support 8.0, whose JSON encoder passes a keyword
41
+ (`quirks_mode:`) that json 3 rejects, and the SQL Server adapter hands the
42
+ encoder a value it refuses, so nothing can be written as JSON there, and the
43
+ specs that switch to JSON themselves skip.
44
+
45
+ Write a fixture version with `PaperTrail.serializer.dump`, not `to_yaml`, so it
46
+ holds what either run's history would. An example about YAML history itself
47
+ is tagged `history: :yaml` and keeps YAML in both runs. JSON keeps times to
48
+ milliseconds by default, so an oracle's truth, read from live rows, cuts times
49
+ to the digits history keeps (`HistorySerializer.as_stored`), as the gem does
50
+ when it compares a live row with history. A scope that orders or bounds a
51
+ time more finely than that is refused under JSON, and the specs that read one
52
+ leave it out there.
53
+
28
54
  ## Consistency checks
29
55
 
30
56
  `spec/association/consistency_spec.rb` and `spec/integration/consistency_spec.rb`
@@ -34,8 +60,24 @@ agrees: `analyze`, `analyze_many`, and `analyze_scope`; checkpoint and activity
34
60
  modes; `compare` and `timeline` against `analyze`; and that activity steps
35
61
  chain into the final state. They run over random windows as well as the whole
36
62
  history, with integer and string `versions.item_id`, YAML and JSON history, and
37
- a `has_paper_trail skip:` column. When one fails, its seed reproduces it. Add a
38
- variant here when a bug turns out to depend on a schema or configuration.
63
+ a `has_paper_trail skip:` column. When one fails, its seed reproduces it, and
64
+ `ORACLE_SHRINK=1` reduces it, as for the oracles (see
65
+ [Reducing a failure](#reducing-a-failure)). Add a variant here when a bug
66
+ turns out to depend on a schema or configuration.
67
+
68
+ ## SQL work
69
+
70
+ A statement whose plan reads a report's window again for each of its roots'
71
+ versions passes every correctness check and shows only at scale.
72
+ `spec/association/report_sql_work_spec.rb` reports on articles with their
73
+ comments, with the README's indexes, since plans depend on them. It then adds
74
+ other records' history to the window and reports again. It runs each SELECT
75
+ again on its own and reads the steps SQLite's virtual machine took, which are
76
+ the same on every run for the same data and SQLite version. It fails when
77
+ each added version costs the report more than 100 steps: about 27 when it was
78
+ written, and about 380 with the correlated subquery that once took a report
79
+ of 10,000 articles from 6 to 44 ms an article. The failure lists the
80
+ statements that grew most. It runs on SQLite only.
39
81
 
40
82
  ## Oracle checks
41
83
 
@@ -55,8 +97,11 @@ share passes. `spec/oracle` compares them with the truth instead:
55
97
  are compared with the recorded states. Two windows that meet between
56
98
  transactions, or inside one, must report each step once, as the window
57
99
  spanning both does, through both `activity_timeline` and `analyze_many`.
100
+ The transactions take turns between no author, `alice`, and `bob`, and
101
+ the same windows filtered to alice's versions must report exactly the
102
+ unfiltered steps of the transactions she saved a version in.
58
103
 
59
- Four more generators cover other shapes. `scoped_membership_spec.rb` moves
104
+ Five more generators cover other shapes. `scoped_membership_spec.rb` moves
60
105
  notes in and out of scoped associations (conditions, order, limit, and
61
106
  offset) and compares the members at every version with Active Record's own
62
107
  answer. `tree_history_spec.rb` edits a tree of one model, so a root can sit
@@ -70,8 +115,13 @@ detaches, creates, renames, and destroys tags between checkpoints. HABTM
70
115
  membership is known only at root versions, so it expects what the
71
116
  [reference](reference.md#habtm-limitation) describes: at each point, the
72
117
  members the next root version recorded, as each was then, and only once it
73
- exists. These three read the expected states with plain Active Record, not
74
- through the gem.
118
+ exists. `shapes_history_spec.rb` edits two boards and the records around them:
119
+ a polymorphic owner, cards that use single-table inheritance and change type,
120
+ comments that move between boards and cards (`as:`), labels with a default
121
+ scope, and scoped and ranked associations to the cards. Its checks, in
122
+ `spec/support/graph_oracle.rb`, follow any model's associations, so a new
123
+ shape needs only models and edits. These four read the expected states with
124
+ plain Active Record, not through the gem.
75
125
 
76
126
  `replay_differential_spec.rb` checks activity against the gem's own full
77
127
  snapshots instead. Activity carries each snapshot forward from the previous
@@ -84,22 +134,143 @@ Mutant cannot check that carrying forward: a mutation that turns it off
84
134
  falls back to a full snapshot, which gives the same answers, more slowly. This
85
135
  check is what catches one that gives a different answer.
86
136
 
137
+ `unversioned_writes_spec.rb` mixes saves with `update_columns` writes,
138
+ several to a transaction, and logs every write. Each change row must match
139
+ the write that made it: one credited to a version ends at a value that
140
+ version recorded, one credited to no version at a value an `update_columns`
141
+ wrote, and such a write whose value is read again has a row of its own.
142
+ With only the rows of versions kept, each article and comment must end at
143
+ the value of its last recorded save.
144
+
145
+ Every oracle that reads an activity timeline from end to end also checks its
146
+ net changes (`spec/support/net_changes_check.rb`). With every row kept, each
147
+ record's `before` and `after` must be its state where the step of its first
148
+ row starts and where the timeline ends, read from the whole snapshot tree,
149
+ and the record must be listed exactly when the two differ.
150
+
87
151
  ```console
88
152
  mise exec -- bundle exec rake spec_oracle
89
153
  ORACLE_SEEDS=1..200 ORACLE_STEPS=40 mise exec -- bundle exec rake spec_oracle
90
154
  ```
91
155
 
92
- The default seeds keep the run to a few seconds; `rake spec` includes it, so
156
+ The 200-seed run is about 4,000 examples and takes three hours or more in one
157
+ process. Its database is in memory, so you can split it by seed range and run
158
+ the parts side by side, each in its own shell: `ORACLE_SEEDS=1..25`, then
159
+ `26..50`, and so on. Eight such parts took about 25 minutes. Check that each
160
+ part ran all its examples: a run stopped early, by `timeout` for example,
161
+ still ends with "N examples, 0 failures" for the ones it ran. Adding
162
+ `SPEC_OPTS=--dry-run` to the same command prints how many there should be.
163
+
164
+ The default seeds keep the run short; `rake spec` includes it, so
93
165
  the database jobs run it too. Mutant does not, because it would slow every
94
- mutation. A failure prints its seed and the transactions it made. To fix one,
95
- reproduce it with that seed, reduce it to the few edits that matter, and add
96
- that as a named spec beside the code it covers, so the cause is readable
97
- without the generator.
166
+ mutation. A failure prints its seed, the transactions it made, its first five
167
+ mismatches (`ORACLE_SHOW=50` prints more), and the command that reduces it.
168
+
169
+ A scheduled workflow, `.github/workflows/oracle.yml`, runs 200 more seeds each
170
+ night with `ORACLE_STEPS=40`, in eight jobs of 25. The seeds move on 200 a day
171
+ from seed 201, so each night tries histories no run has; run by hand, the
172
+ workflow takes the first of its 200 seeds as `first_seed`. A job reduces the
173
+ first two examples that fail and keeps its log and `tmp/oracle` as an
174
+ artifact: copy that `tmp/oracle` into a checkout and run the `Replay it:`
175
+ command from the log.
98
176
 
99
177
  When a bug turns out to depend on a schema, configuration, or kind of edit,
100
178
  add it to the generator or as a new context, so the whole class of bug stays
101
179
  covered.
102
180
 
181
+ ### Reducing a failure
182
+
183
+ `ORACLE_SHRINK=1` cuts a failing history down to the few steps that matter, in
184
+ the oracles and the consistency checks alike. A failure ends with the command,
185
+ which runs that example alone with the settings that decide its history:
186
+
187
+ ```console
188
+ ORACLE_SEEDS=103 ORACLE_SHRINK=1 mise exec -- bundle exec rspec 'spec/oracle/shapes_history_spec.rb[1:1]'
189
+ ```
190
+
191
+ The generators draw their random choices through `Oracle.random(seed)`
192
+ (`spec/support/oracle_choices.rb`). It hands out what `Random.new(seed)`
193
+ would, so a seed builds the history it always has, and it keeps each draw,
194
+ grouped by step. When an example fails, the reducer
195
+ (`spec/support/oracle_reducer.rb`) runs it again with runs of steps left out,
196
+ then with each remaining choice set to the first one, such as the first
197
+ operation in a generator's list. An example that builds a history for each
198
+ seed, such as the article oracle's windows that meet inside a transaction,
199
+ first loses whole histories, half of them at a time, since every run builds
200
+ them all. The reducer keeps each change that fails with the same first
201
+ mismatch, numbers aside, and stops when no change helps or after
202
+ `ORACLE_SHRINK_RUNS` runs (300 by default). Leaving a step out keeps the
203
+ other steps' choices as they were, though they may then act on different
204
+ records. `ORACLE_SHRINK_EXAMPLES` caps how many failing examples one run
205
+ reduces; the others just print the command.
206
+
207
+ The example then fails with the reduced history: how many steps were left,
208
+ the versions it wrote if it built one history, its mismatches, and a command
209
+ that replays it from a file in `tmp/oracle`, followed by the original
210
+ failure. Tried against a bug injected into activity's carry-forward, it
211
+ brought one example of each generator from 20 to 66 steps down to 2 to 5, in
212
+ 21 to 38 runs, taking from 4 seconds to 5 minutes; the shapes oracle's checks
213
+ are the slowest. Write the reduced history as a named spec beside the code it
214
+ covers, so the cause is readable without the generator.
215
+
216
+ A generator runs each loop of random steps as `@random.steps(count) { ... }`
217
+ rather than `count.times`, so the reducer can tell its steps apart. A new
218
+ generator should too.
219
+
220
+ ## Comparison properties
221
+
222
+ The oracles compute the change they expect with `PaperTrailDiff::Engine`, so a
223
+ bug in the engine itself passes them. `spec/unit/engine_properties_spec.rb`
224
+ checks the engine on its own, over a few hundred generated pairs of snapshots
225
+ (`spec/support/snapshot_cases.rb`): attributes, to-one records and
226
+ collections two levels deep, with mixed id types, and collections carried
227
+ forward one record at a time, as activity builds them. For every pair:
228
+
229
+ - an equal snapshot built separately, with its keys and records in another
230
+ order, compares as no change;
231
+ - the diff, applied to the first snapshot, gives the second, so it misses no
232
+ change and reports none wrongly (`spec/support/diff_algebra.rb` applies a
233
+ diff from its hash alone, without the engine);
234
+ - comparing the other way gives the opposite diff;
235
+ - every change reported is a real one, in attribute name and record order;
236
+ - a collection carried forward reports what the same collection built whole
237
+ does;
238
+ - nothing in the diff can be changed.
239
+
240
+ `spec/unit/nested_comparator_properties_spec.rb` does the same for the values
241
+ inside a JSON column, including JSON text, symbol keys, and arrays, which are
242
+ reported by membership.
243
+
244
+ `spec/unit/net_changes_properties_spec.rb` checks the fold behind
245
+ `net_changes`, over generated histories of a few records
246
+ (`spec/support/snapshot_world.rb`) in which a record has one state wherever a
247
+ snapshot reaches it: comments that come and go, replies that move between
248
+ comments, an author who reviews several, and tags. For every history:
249
+
250
+ - the rows of a run of steps fold into each record's change from the run's
251
+ first state to its last, whether the run is passed alone or picked out of
252
+ the whole history by the rows kept;
253
+ - the root comes first, then each record in the order of its first kept
254
+ change, with each source once;
255
+ - kept alone, the rows that move records in and out leave each record as its
256
+ last move left it;
257
+ - a record that stayed changes only in fields a kept row set.
258
+
259
+ They take about a second and run with the unit specs. Each is named after
260
+ what it checks rather than its class, so mutant, which runs only the specs
261
+ that name a mutated class, leaves them out: run with every mutation of
262
+ `Engine`, `NestedComparator`, `NetChange`, and `NetChanges`, they nearly
263
+ doubled its work, from 15 to 27 minutes of worker time, while the classes'
264
+ own specs kill every mutation without them. Name a new property spec the
265
+ same way.
266
+ A failure names its case. The cases start small and grow, so the first one
267
+ that fails is a small one. `PROPERTY_SEED` and `PROPERTY_CASES` choose other
268
+ and more cases:
269
+
270
+ ```console
271
+ PROPERTY_SEED=2 PROPERTY_CASES=5000 mise exec -- bundle exec rspec spec/unit/engine_properties_spec.rb
272
+ ```
273
+
103
274
  ## Mutation testing
104
275
 
105
276
  [Mutant](https://github.com/mbj/mutant) changes the library one expression at
@@ -107,31 +278,48 @@ a time and expects a spec to fail each time. A change that every spec still
107
278
  passes is behavior nothing checks. `mutant.yml` lists the classes it mutates:
108
279
 
109
280
  - what counts as a change: `Engine`, `CollectionComparator`,
110
- `CollectionIdentityIndex`, and `NestedComparator`;
111
- - which columns are compared: `SnapshotNormalizer` and `SnapshotPool`;
281
+ `CollectionIdentityIndex`, `NestedComparator`, and `CollectionTransition`;
282
+ - which columns are compared, and how precisely times are: `SnapshotNormalizer`,
283
+ `SnapshotPool`, and `StoredTimePrecision`;
284
+ - which endpoints a call accepts, and which item and model each names:
285
+ `Endpoint` and `EndpointKind`;
112
286
  - which versions a range reads: `TimeRange`, `TimelineRange`, `VersionRange`,
113
- `TimeVersionRange`, and `RootVersionPlan`;
114
- - which versions a batch or filter reads: `BatchedRootVersions`,
115
- `DeletedAnalysisBatch`, and `HistoricalFilter`;
116
- - what a version recorded: `RecordedChanges`;
287
+ `TimeVersionRange`, `RootVersionSelection`, `RootVersionPlan`,
288
+ `TransactionCut`, `OpeningTransactions`, `VersionBoundary`, and
289
+ `VersionQuery`;
290
+ - which versions a batch or filter reads: `AnalysisBatch`,
291
+ `BatchedRootVersions`, `BatchedRootAnalyses`, `BatchBoundaryResolver`,
292
+ `DeletedAnalysisBatch`, `HistoricalFilter`, and `VersionScopeFilter`;
293
+ - whether a read sees one database snapshot: `ReadSnapshot`;
294
+ - what a version recorded: `RecordedChanges`, `RecordedChangesReader`, and
295
+ `RecordedClass`;
117
296
  - how a step flattens into rows: `ChangeRow` and `ChangeRows`;
118
- - which records a scope or report selects: `ScopedRootSelection`,
119
- `AssociationActivitySelection`, `AssociationActivityEdge`, and
120
- `DeletedRootFilter`;
297
+ - which records a scope or report selects, and in what order:
298
+ `ScopedRootSelection`, `TotalOrder`, `AssociationActivitySelection`,
299
+ `AssociationActivityEdge`, and `DeletedRootFilter`;
121
300
  - which children and targets a record had at each point:
122
- `PreparedHistoryLoader`, `PreparedEdgeLoader`,
123
- `ActivityTargetCandidateLoader`, and `PreparedActivityIndex`;
301
+ `PreparedHistoryLoader`, `PreparedEdgeLoader`, `ActivityChildCandidateLoader`,
302
+ `PreparedChildCandidates`, `ActivityTargetCandidateLoader`, and
303
+ `PreparedActivityIndex`;
124
304
  - where an activity range starts and ends, and which association history its
125
305
  query reads: `ActivityRange` and `VersionAssociationCandidateScope`;
126
- - what activity a record shows: `ActivityTimelineBuilder` and
127
- `ActivityTransactionGrouper`;
128
- - which association paths a request accepts: `AssociationTraversal` and
129
- `AssociationKey`;
306
+ - what activity a record shows: `ActivityTimelineBuilder`,
307
+ `ActivityVersionCollector`, `ActivityHistoryBuilder`, `ActivityRootSteps`,
308
+ `ActivityTransactionGrouper`, `ActivityTransactionGroups`,
309
+ `ActivityTreeFilter`, `ActivityScopeFilter`, and `ActivityView`;
310
+ - what an update did to a record, and whether it moved the record to another
311
+ owner: `ActivitySnapshotDelta`;
312
+ - where in a carried snapshot an event's record sits: `ActivityEventRouteFinder`;
313
+ - which association paths a request accepts: `AssociationTraversal`,
314
+ `AssociationKey`, and `VersionTable`;
130
315
  - whether a transaction's HABTM members are one record's:
131
316
  `HabtmTransactionOwners`;
132
- - which association paths history cannot read exactly: `ApproximatePaths`;
317
+ - which association paths history cannot read exactly, and whether a request
318
+ reads one with PT-AT: `ApproximatePaths` and `FallbackPaths`;
133
319
  - which records an association scope admits, and how it ranks them:
134
- `ScopeCondition` and `ScopeRanking`.
320
+ `ScopeCondition` and `ScopeRanking`;
321
+ - the helpers these share, which order versions, name records, and copy
322
+ values: `Support`.
135
323
 
136
324
  The specs for the classes that read the database use tables of their own
137
325
  (`spec/support/filter_database.rb`, `spec/support/normalizer_database.rb`,
@@ -150,14 +338,32 @@ behavior can still name the class it checks with metadata, as the activity
150
338
  window specs do: `RSpec.describe 'Activity over a window', mutant_expression:
151
339
  'PaperTrailDiff::ActivityTimelineBuilder'`.
152
340
 
341
+ Mutant runs an example it picks whatever its `if:` or `unless:` metadata
342
+ says. An example that needs one database calls `skip` on the others instead,
343
+ as `spec/unit/read_snapshot_spec.rb` does for SQL Server.
344
+
153
345
  Mutant counts a mutation that runs past its time limit as caught, so
154
346
  `mutant.yml` sets the limit well above the time the whole suite takes. With
155
347
  mutant's 5-second default, mutations no spec caught were reported as caught.
156
348
 
349
+ A group nested for one method, such as `describe '.call'`, names that method,
350
+ and mutant then runs only that group for it, so the group must catch every
351
+ mutation in the method by itself. A private method gets every example of its
352
+ class. Mutant cannot reach a method that `module_function` defines: it mutates
353
+ the private copy no caller uses. The mutated modules define their methods with
354
+ `def self.` instead.
355
+
157
356
  In CI, a pull request mutates only the methods it changes. The full set runs
158
357
  nightly in `.github/workflows/mutation.yml`, and only when `main` has a commit
159
358
  that has not passed yet. Start it by hand from the Actions tab with "Run
160
- workflow".
359
+ workflow". Both split the methods across four jobs with
360
+ `script/mutant_shard.rb`, which takes every fourth method in mutant's listing,
361
+ so that a class holding most of a run's methods is split as well. To run one
362
+ shard locally, as the pull request job does:
363
+
364
+ ```console
365
+ BUNDLE_GEMFILE=gemfiles/mutant.gemfile mise exec -- ruby script/mutant_shard.rb 0 4 origin/main
366
+ ```
161
367
 
162
368
  Mutant needs Ruby 3.3 or newer, so it has its own bundle:
163
369
 
@@ -193,8 +399,10 @@ increasing, in whole microseconds, for the test process. ActiveRecord
193
399
  timestamps, PaperTrail's `created_at`, and windows built from `Time.now` all
194
400
  read it, so they stay consistent however the host clock moves. The benchmark
195
401
  workload, `benchmark/support/workload.rb`, loads it too, because a step back
196
- could date a root's destroy before its last update. It affects only the specs
197
- and the benchmark; the gem itself reads the ordinary clock.
402
+ could date a root's destroy before its last update, and so does the run of
403
+ `examples/demo.rb` in `spec/association/demo_script_spec.rb`, whose versions
404
+ are saved microseconds apart. It affects only the specs, the benchmark, and
405
+ that run; the gem and the demo itself read the ordinary clock.
198
406
 
199
407
  ## Other databases locally
200
408
 
@@ -23,9 +23,9 @@ module PaperTrailDiff
23
23
  return [false, nil] unless %w[update destroy].include?(version.event.to_s)
24
24
 
25
25
  routes = @route_finder.belongs_to_routes(
26
- endpoint_model_class(root_endpoint), tree, version.item_type.to_s
26
+ RecordedClass.of_endpoint(root_endpoint), tree, version.item_type.to_s
27
27
  )
28
- return [false, nil] if routes.empty? || scoped_route?(routes)
28
+ return [false, nil] if routes.empty? || ActivityEventRouteFinder.scoped_route?(routes)
29
29
 
30
30
  snapshot = previous
31
31
  routes.each do |route|
@@ -43,15 +43,6 @@ module PaperTrailDiff
43
43
  # @rbs @record_resolver: ActivityEventRecordResolver
44
44
  # @rbs @record_normalizer: ActivityEventRecordNormalizer
45
45
 
46
- # An edit can move a target into or out of a scope, which a replacement
47
- # in place cannot show, so a scoped route's branch is read again instead.
48
- #: (Array[Array[untyped]]) -> bool
49
- def scoped_route?(routes)
50
- routes.any? do |route|
51
- route.any? { |entry| ScopeCondition.scoped_path?(entry.fetch(1)) }
52
- end
53
- end
54
-
55
46
  #: (Array[untyped], untyped, SnapshotNormalizer, untyped, untyped) -> RecordSnapshot?
56
47
  def normalized_route_record(route, version, normalizer, root_endpoint, context_endpoint)
57
48
  record = @record_resolver.record_after(version, direct: route.last.fetch(2).empty?)
@@ -117,10 +108,5 @@ module PaperTrailDiff
117
108
  model = AssociationTraversal.named_class(record.type.to_s)
118
109
  !model.nil? && model.base_class == Endpoint.model_class(version).base_class
119
110
  end
120
-
121
- #: (untyped) -> untyped
122
- def endpoint_model_class(endpoint)
123
- Endpoint.version?(endpoint) ? RecordedClass.for(endpoint) : endpoint.class
124
- end
125
111
  end
126
112
  end
@@ -26,26 +26,16 @@ module PaperTrailDiff
26
26
  private_constant :NOT_READ, :NOT_READ_MESSAGE
27
27
 
28
28
  class << self
29
- # `recorded:` names the attributes to leave out of the version's recorded
30
- # changes, or is nil when they were not asked for. Reading them decodes
31
- # `object_changes`, which a caller who does not want them should not pay.
32
- #: (untyped, ?recorded: Array[String]?) -> ActivityBoundary
29
+ # `recorded:` reads the version's recorded changes, or is nil when they
30
+ # were not asked for. Reading them decodes `object_changes`, which waits
31
+ # until a caller reads them, and which one who never does should not pay.
32
+ #: (untyped, ?recorded: RecordedChangesReader?) -> ActivityBoundary
33
33
  def from_version(version, recorded: nil)
34
- new(
35
- kind: :version,
36
- version_id: version.id,
37
- item_type: version.item_type,
38
- item_id: version.item_id,
39
- recorded_at: version.created_at,
40
- event: version.event,
41
- whodunnit: version.whodunnit,
42
- transaction_id: VersionBoundary.transaction_id(version),
43
- recorded_changes: recorded_changes(version, recorded)
44
- )
34
+ of_version(version, :version, recorded)
45
35
  end
46
36
 
47
37
  # The current record has no version, so it recorded nothing.
48
- #: (untyped, captured_at: untyped, ?recorded: Array[String]?) -> ActivityBoundary
38
+ #: (untyped, captured_at: untyped, ?recorded: RecordedChangesReader?) -> ActivityBoundary
49
39
  def current(record, captured_at:, recorded: nil)
50
40
  new(
51
41
  kind: :current,
@@ -60,10 +50,26 @@ module PaperTrailDiff
60
50
  # The state a `destroy` version leaves behind. A version records the state
61
51
  # before its own event, so the boundary built from a destroy version still
62
52
  # holds the record; this one is the absence that follows it.
63
- #: (untyped, ?recorded: Array[String]?) -> ActivityBoundary
53
+ #: (untyped, ?recorded: RecordedChangesReader?) -> ActivityBoundary
64
54
  def destroyed(version, recorded: nil)
55
+ of_version(version, :destroyed, recorded)
56
+ end
57
+
58
+ # Where a change saved without a version came from, such as an
59
+ # `update_columns` call: no version, event, author or time recorded it,
60
+ # so it has none to report. A change row names it as its source.
61
+ #: (item_type: String, item_id: untyped) -> ActivityBoundary
62
+ def unversioned(item_type:, item_id:)
63
+ new(kind: :unversioned, version_id: nil, item_type: item_type, item_id: item_id,
64
+ recorded_at: nil, recorded_changes: nil)
65
+ end
66
+
67
+ private
68
+
69
+ #: (untyped, Symbol, RecordedChangesReader?) -> ActivityBoundary
70
+ def of_version(version, kind, recorded)
65
71
  new(
66
- kind: :destroyed,
72
+ kind: kind,
67
73
  version_id: version.id,
68
74
  item_type: version.item_type,
69
75
  item_id: version.item_id,
@@ -75,18 +81,17 @@ module PaperTrailDiff
75
81
  )
76
82
  end
77
83
 
78
- private
79
-
80
- #: (untyped, Array[String]?) -> untyped
81
- def recorded_changes(version, ignore)
82
- return NOT_READ if ignore.nil?
84
+ #: (untyped, RecordedChangesReader?) -> untyped
85
+ def recorded_changes(version, reader)
86
+ return NOT_READ if reader.nil?
83
87
 
84
- RecordedChanges.call(version, ignore: ignore)
88
+ RecordedChangesReader::Pending.new(reader, version)
85
89
  end
86
90
  end
87
91
 
88
92
  # `recorded_changes:` takes what `PaperTrailDiff.recorded_changes` returns
89
- # for the version; leave it out when they were not read.
93
+ # for the version, or a RecordedChangesReader::Pending that reads it when
94
+ # first asked; leave it out when they were not read.
90
95
  #: (kind: Symbol, version_id: untyped, item_type: untyped, item_id: untyped, recorded_at: untyped, ?event: untyped, ?whodunnit: untyped, ?transaction_id: untyped, ?recorded_changes: untyped) -> void
91
96
  def initialize( # rubocop:disable Metrics/ParameterLists
92
97
  kind:,
@@ -121,7 +126,8 @@ module PaperTrailDiff
121
126
  def recorded_changes
122
127
  raise ConfigurationError, NOT_READ_MESSAGE unless recorded_changes?
123
128
 
124
- @recorded_changes
129
+ changes = @recorded_changes
130
+ changes.is_a?(RecordedChangesReader::Pending) ? changes.value : changes
125
131
  end
126
132
 
127
133
  # Whether this boundary's recorded changes were read.
@@ -145,6 +151,11 @@ module PaperTrailDiff
145
151
  kind == :destroyed
146
152
  end
147
153
 
154
+ #: () -> bool
155
+ def unversioned?
156
+ kind == :unversioned
157
+ end
158
+
148
159
  #: (?metadata: bool) -> Hash[Symbol, untyped]
149
160
  def to_h(metadata: false)
150
161
  value = {
@@ -160,7 +171,7 @@ module PaperTrailDiff
160
171
  record: record.to_h)
161
172
  return value unless recorded_changes?
162
173
 
163
- value.merge(recorded_changes: @recorded_changes&.transform_values(&:to_h))
174
+ value.merge(recorded_changes: recorded_changes&.transform_values(&:to_h))
164
175
  end
165
176
  end
166
177
 
@@ -181,30 +192,38 @@ module PaperTrailDiff
181
192
  # which holds every event in it: an attribution that names only the first
182
193
  # would credit the rest of the save to whoever opened it.
183
194
  attr_reader :sources #: Array[ActivityBoundary]
195
+ # @api private
196
+ # What credits this step's change rows, which a transaction group extends
197
+ # over the steps it merges.
198
+ attr_reader :attribution #: ChangeAttribution?
184
199
 
185
200
  # Compares two reconstructed states and keeps them only when asked, which is
186
201
  # every caller's shape: the diff always comes from the pair, the pair itself
187
202
  # is retained on request.
188
- #: (from_boundary: ActivityBoundary, to_boundary: ActivityBoundary, from_snapshot: RecordSnapshot?, to_snapshot: RecordSnapshot?, retain: bool, ?sources: Array[ActivityBoundary]?) -> ActivityStep
189
- def self.between(from_boundary:, to_boundary:, from_snapshot:, to_snapshot:, retain:, sources: nil) # rubocop:disable Metrics/ParameterLists, Layout/LineLength
203
+ #: (from_boundary: ActivityBoundary, to_boundary: ActivityBoundary, from_snapshot: RecordSnapshot?, to_snapshot: RecordSnapshot?, retain: bool, ?sources: Array[ActivityBoundary]?, ?attribution: ChangeAttribution?) -> ActivityStep
204
+ def self.between(from_boundary:, to_boundary:, from_snapshot:, to_snapshot:, retain:, sources: nil, attribution: nil) # rubocop:disable Metrics/ParameterLists, Layout/LineLength
190
205
  new(
191
206
  from_boundary: from_boundary,
192
207
  to_boundary: to_boundary,
193
208
  diff: Engine.compare(from_snapshot, to_snapshot),
194
209
  from_snapshot: (from_snapshot if retain),
195
210
  to_snapshot: (to_snapshot if retain),
196
- sources: sources
211
+ sources: sources,
212
+ attribution: attribution
197
213
  )
198
214
  end
199
215
 
200
- #: (from_boundary: ActivityBoundary, to_boundary: ActivityBoundary, diff: Diff, ?from_snapshot: RecordSnapshot?, ?to_snapshot: RecordSnapshot?, ?sources: Array[ActivityBoundary]?) -> void
201
- def initialize(from_boundary:, to_boundary:, diff:, from_snapshot: nil, to_snapshot: nil, sources: nil) # rubocop:disable Metrics/ParameterLists, Layout/LineLength
216
+ # `attribution` credits each change row to the version that made it (see
217
+ # ChangeAttribution); without it, every row names `source_boundary`.
218
+ #: (from_boundary: ActivityBoundary, to_boundary: ActivityBoundary, diff: Diff, ?from_snapshot: RecordSnapshot?, ?to_snapshot: RecordSnapshot?, ?sources: Array[ActivityBoundary]?, ?attribution: ChangeAttribution?) -> void
219
+ def initialize(from_boundary:, to_boundary:, diff:, from_snapshot: nil, to_snapshot: nil, sources: nil, attribution: nil) # rubocop:disable Metrics/ParameterLists, Layout/LineLength
202
220
  @from_boundary = from_boundary
203
221
  @to_boundary = to_boundary
204
222
  @diff = diff
205
223
  @from_snapshot = from_snapshot
206
224
  @to_snapshot = to_snapshot
207
225
  @sources = (sources || [from_boundary]).dup.freeze
226
+ @attribution = attribution
208
227
  freeze
209
228
  end
210
229
 
@@ -218,10 +237,12 @@ module PaperTrailDiff
218
237
  #: () -> ActivityBoundary
219
238
  def source_boundary = from_boundary
220
239
 
221
- # The diff as flat rows, each attributed to `source_boundary`.
240
+ # The diff as flat rows, each credited to the event that made its change:
241
+ # the version of the row's record that recorded it, an unversioned source
242
+ # for a part saved without a version, or else `source_boundary`.
222
243
  #: () -> Array[ChangeRow]
223
244
  def change_rows
224
- ChangeRows.call(diff, source: source_boundary)
245
+ ChangeRows.call(diff, source: source_boundary, attribution: @attribution)
225
246
  end
226
247
 
227
248
  # `metadata: true` also lists `sources`, since who made a change is