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
@@ -4,13 +4,11 @@
4
4
  module PaperTrailDiff
5
5
  # Query pieces shared by version lookups.
6
6
  module VersionQuery
7
- module_function
8
-
9
7
  # Oldest first. Ids break ties between versions written in the same
10
8
  # instant, and the timestamp comes first because ids need not follow time:
11
9
  # a UUID key does not.
12
10
  #: (untyped) -> untyped
13
- def chronological(relation)
11
+ def self.chronological(relation)
14
12
  relation.reorder(created_at: :asc, id: :asc)
15
13
  end
16
14
 
@@ -19,13 +17,13 @@ module PaperTrailDiff
19
17
  # leave some out: a history replayed without them credits their changes to
20
18
  # the next version kept.
21
19
  #: (untyped) -> untyped
22
- def for_model(model_class)
20
+ def self.for_model(model_class)
23
21
  model_class.paper_trail.version_class.where(item_type: model_class.base_class.name)
24
22
  end
25
23
 
26
24
  # The versions of the given items, read the same way.
27
25
  #: (untyped, untyped) -> untyped
28
- def for_items(model_class, ids)
26
+ def self.for_items(model_class, ids)
29
27
  for_model(model_class).where(item_id: ids)
30
28
  end
31
29
 
@@ -33,33 +31,35 @@ module PaperTrailDiff
33
31
  # no other version of the same item that the block accepts is earlier. A
34
32
  # correlated NOT EXISTS stays portable where window functions are not.
35
33
  #: (untyped) ?{ (untyped) -> untyped } -> untyped
36
- def no_earlier_version(table, &block)
37
- no_nearer_version(table, later: true, &block)
34
+ def self.no_earlier_version(table, &block)
35
+ exists(table) { |other| earlier_version(table, other, &block) }.not
38
36
  end
39
37
 
40
- # The same for either side of an instant: each item's earliest version
41
- # when the versions lie after it, and its latest when they lie before.
42
- #: (untyped, later: bool) ?{ (untyped) -> untyped } -> untyped
43
- def no_nearer_version(table, later:, &block)
44
- arel = Object.const_get(:Arel) #: untyped
45
- other = table.alias('paper_trail_diff_earlier_versions')
46
- arel.const_get(:SelectManager).new
47
- .from(other)
48
- .project(arel.sql('1'))
49
- .where(nearer_version(table, other, later: later, &block))
50
- .exists
51
- .not
38
+ # Whether a version exists that the block's condition accepts. The block
39
+ # is given the version table under a second name, beside `table`.
40
+ #: (untyped) { (untyped) -> untyped } -> untyped
41
+ def self.exists(table)
42
+ other = other_versions(table)
43
+ Support.arel::SelectManager.new.from(other).project('1').where(yield(other)).exists
52
44
  end
53
45
 
54
- #: (untyped, untyped, later: bool) ?{ (untyped) -> untyped } -> untyped
55
- def nearer_version(table, other, later:)
56
- created_at = other[:created_at]
57
- nearer = later ? created_at.lt(table[:created_at]) : created_at.gt(table[:created_at])
46
+ #: (untyped, untyped) ?{ (untyped) -> untyped } -> untyped
47
+ def self.earlier_version(table, other)
58
48
  same_item = other[:item_type].eq(table[:item_type])
59
49
  .and(other[:item_id].eq(table[:item_id]))
60
- .and(nearer)
50
+ .and(other[:created_at].lt(table[:created_at]))
61
51
  block_given? ? same_item.and(yield(other)) : same_item
62
52
  end
63
- private_class_method :nearer_version
53
+ private_class_method :earlier_version
54
+
55
+ # The version table under a second name, for a subquery over it. Any name
56
+ # serves, and SQLite even accepts an empty one other databases refuse, so
57
+ # no spec can tell the mutations apart.
58
+ # mutant:disable
59
+ #: (untyped) -> untyped
60
+ def self.other_versions(table)
61
+ table.alias('paper_trail_diff_other_versions')
62
+ end
63
+ private_class_method :other_versions
64
64
  end
65
65
  end
@@ -13,12 +13,12 @@ module PaperTrailDiff
13
13
  end
14
14
 
15
15
  # Keep both reconstruction boundaries and the step pairs a filter implies.
16
- #: () -> RootVersionPlan
17
- def select_plan_for_range
16
+ #: (?whole: bool) -> RootVersionPlan
17
+ def select_plan_for_range(whole: false)
18
18
  relation = validated_relation
19
19
  select_plan(
20
20
  relation.where(created_at: @from.created_at..@to.created_at),
21
- through: @to
21
+ through: @to, whole: whole
22
22
  )
23
23
  end
24
24
 
@@ -34,12 +34,13 @@ module PaperTrailDiff
34
34
  relation
35
35
  end
36
36
 
37
- #: (untyped) -> RootVersionPlan
38
- def select_plan_through_current(current)
37
+ #: (untyped, ?whole: bool) -> RootVersionPlan
38
+ def select_plan_through_current(current, whole: false)
39
39
  Endpoint.validate_pair!(@record, current)
40
40
  relation = Endpoint.versions(@record)
41
41
  validate_boundary!(@from, relation, boundary: :from)
42
- select_plan(relation.where(created_at: @from.created_at..), live_endpoint: current)
42
+ select_plan(relation.where(created_at: @from.created_at..), live_endpoint: current,
43
+ whole: whole)
43
44
  end
44
45
 
45
46
  private
@@ -49,26 +50,21 @@ module PaperTrailDiff
49
50
  # @rbs @to: untyped
50
51
  # @rbs @version_scope: untyped
51
52
 
52
- #: (untyped, ?through: untyped, ?live_endpoint: untyped) -> RootVersionPlan
53
- def select_plan(relation, through: nil, live_endpoint: nil)
54
- in_range = ordered(relation.select do |version|
53
+ #: (untyped, whole: bool, ?through: untyped, ?live_endpoint: untyped) -> RootVersionPlan
54
+ def select_plan(relation, whole:, through: nil, live_endpoint: nil)
55
+ in_range = relation.select do |version|
55
56
  Support.compare_versions(@from, version) <= 0 &&
56
57
  (!through || Support.compare_versions(version, through) <= 0)
57
- end)
58
+ end
58
59
  RootVersionSelection.new(
59
60
  in_range: in_range,
60
61
  selected: VersionScopeFilter.new(@version_scope).call(relation, in_range),
61
62
  after_range: nil,
62
63
  windowed: false,
63
- filtered: !@version_scope.nil?, live_endpoint: live_endpoint
64
+ live_endpoint: live_endpoint, whole: whole
64
65
  ).call
65
66
  end
66
67
 
67
- #: (Array[untyped]) -> Array[untyped]
68
- def ordered(versions)
69
- Support.chronological_sort(versions)
70
- end
71
-
72
68
  #: (untyped, untyped, boundary: Symbol) -> void
73
69
  def validate_boundary!(requested, relation, boundary:)
74
70
  return if valid_boundary?(requested, relation)
@@ -21,6 +21,7 @@ module PaperTrailDiff
21
21
  versions = @from_version.class.transaction(requires_new: true) { ordered_range_versions }
22
22
  issues = [] #: Array[DiagnosticIssue?]
23
23
  issues << unorderable(versions)
24
+ issues << inverted(versions)
24
25
  issues << tied_timestamps(versions) if @fallback_selected
25
26
  issues.compact
26
27
  rescue StandardError
@@ -49,6 +50,37 @@ module PaperTrailDiff
49
50
  )
50
51
  end
51
52
 
53
+ # Versions are read in time order, and ids that count up in one table say
54
+ # which was saved first. A later version dated earlier was usually dated
55
+ # by PaperTrail at an `updated_at` the application set itself, and the
56
+ # history then reads it before the change it followed: an update dated
57
+ # before the record's create reads as the record deleted and created
58
+ # again. A time can also be right and the id wrong, as for versions
59
+ # imported from elsewhere, so this warns rather than refuses.
60
+ #: (Array[untyped]) -> DiagnosticIssue?
61
+ def inverted(versions)
62
+ pair = versions.each_cons(2).find do |left, right|
63
+ Support.orderable_tie?(left, right) && Integer(right.id) < Integer(left.id)
64
+ end
65
+ return unless pair
66
+
67
+ saved_last, saved_first = pair
68
+ DiagnosticIssue.new(
69
+ severity: :warning, code: :inverted_version_order,
70
+ message: inverted_message(saved_first, saved_last), version_id: saved_last.id
71
+ )
72
+ end
73
+
74
+ #: (untyped, untyped) -> String
75
+ def inverted_message(saved_first, saved_last)
76
+ "versions #{saved_first.id.inspect} and #{saved_last.id.inspect} were saved in that " \
77
+ 'order but are dated the other way round, at ' \
78
+ "#{saved_first.created_at.inspect} and #{saved_last.created_at.inspect}, and history " \
79
+ 'reads them in time order; if a save set updated_at itself, which PaperTrail then ' \
80
+ 'dates its version at, set has_paper_trail synchronize_version_creation_timestamp: ' \
81
+ 'false and correct the stored created_at'
82
+ end
83
+
52
84
  # Loaded history orders versions that share a timestamp by id, but PT-AT
53
85
  # places association changes by timestamp alone, so a path it reads loses
54
86
  # any change between such a pair. Unlike an unorderable sequence this is
@@ -25,20 +25,24 @@ module PaperTrailDiff
25
25
  # and an unversioned target has no history to compare.
26
26
  #: (untyped) -> untyped
27
27
  def self.separate_part(reflection)
28
- if reflection.through_reflection?
29
- return [reflection.through_reflection, reflection.source_reflection].filter_map do |part|
30
- separate_part(part)
31
- end.first
28
+ [reflection, *AssociationTraversal.through_parts(reflection)].find do |part|
29
+ !part.through_reflection? && separate?(part)
32
30
  end
33
- return if reflection.polymorphic?
31
+ end
32
+ private_class_method :separate_part
33
+
34
+ #: (untyped) -> bool
35
+ def self.separate?(reflection)
36
+ return false if reflection.polymorphic?
34
37
 
35
38
  owner = reflection.active_record
36
39
  target = reflection.klass
37
- return unless Support.versioned?(owner) && Support.versioned?(target)
40
+ return false unless Support.versioned?(owner) && Support.versioned?(target)
41
+ return false if tables(owner) == tables(target)
38
42
 
39
- reflection unless tables(owner) == tables(target)
43
+ true
40
44
  end
41
- private_class_method :separate_part
45
+ private_class_method :separate?
42
46
 
43
47
  # PT-AT's version association rows joined to the versions they were saved
44
48
  # with. Its `belongs_to :version` names PaperTrail's default class whatever
@@ -7,6 +7,9 @@ require_relative 'paper_trail_diff/version'
7
7
  require_relative 'paper_trail_diff/support'
8
8
  require_relative 'paper_trail_diff/version_query'
9
9
  require_relative 'paper_trail_diff/stored_time_precision'
10
+ require_relative 'paper_trail_diff/stored_json_values'
11
+ require_relative 'paper_trail_diff/time_of_day'
12
+ require_relative 'paper_trail_diff/stored_values'
10
13
  require_relative 'paper_trail_diff/version_boundary'
11
14
  require_relative 'paper_trail_diff/instrumentation'
12
15
  require_relative 'paper_trail_diff/deprecation'
@@ -53,7 +56,6 @@ require_relative 'paper_trail_diff/prepared_association_reifier'
53
56
  require_relative 'paper_trail_diff/live_association_reader'
54
57
  require_relative 'paper_trail_diff/batch_preload'
55
58
  require_relative 'paper_trail_diff/live_endpoint_batch_loader'
56
- require_relative 'paper_trail_diff/preloaded_endpoint_batch_loader'
57
59
  require_relative 'paper_trail_diff/live_endpoint_provider'
58
60
  require_relative 'paper_trail_diff/live_graph_collector'
59
61
  require_relative 'paper_trail_diff/batch_boundary_resolver'
@@ -61,12 +63,14 @@ require_relative 'paper_trail_diff/comparison_batch'
61
63
  require_relative 'paper_trail_diff/root_version_plan'
62
64
  require_relative 'paper_trail_diff/version_scope_filter'
63
65
  require_relative 'paper_trail_diff/root_version_selection'
66
+ require_relative 'paper_trail_diff/own_window'
64
67
  require_relative 'paper_trail_diff/batched_root_versions'
65
68
  require_relative 'paper_trail_diff/snapshot_normalizer'
66
69
  require_relative 'paper_trail_diff/historical_snapshot_store'
67
70
  require_relative 'paper_trail_diff/timeline_snapshot_provider'
68
71
  require_relative 'paper_trail_diff/activity_event_record_resolver'
69
72
  require_relative 'paper_trail_diff/recorded_changes'
73
+ require_relative 'paper_trail_diff/recorded_changes_reader'
70
74
  require_relative 'paper_trail_diff/activity_event_route_finder'
71
75
  require_relative 'paper_trail_diff/activity_relationship'
72
76
  require_relative 'paper_trail_diff/activity_collection_route_change'
@@ -79,17 +83,23 @@ require_relative 'paper_trail_diff/activity_event_snapshot_refresher'
79
83
  require_relative 'paper_trail_diff/activity_root_snapshot_refresher'
80
84
  require_relative 'paper_trail_diff/branch_snapshot_refresher'
81
85
  require_relative 'paper_trail_diff/activity_boundary'
86
+ require_relative 'paper_trail_diff/recorded_columns'
87
+ require_relative 'paper_trail_diff/change_attribution'
88
+ require_relative 'paper_trail_diff/activity_scope_filter'
82
89
  require_relative 'paper_trail_diff/activity_view'
83
90
  require_relative 'paper_trail_diff/activity_transaction_grouper'
91
+ require_relative 'paper_trail_diff/net_change'
84
92
  require_relative 'paper_trail_diff/step'
85
93
  require_relative 'paper_trail_diff/analysis'
86
94
  require_relative 'paper_trail_diff/activity_root_steps'
95
+ require_relative 'paper_trail_diff/batched_root_analyses'
87
96
  require_relative 'paper_trail_diff/analysis_batch'
88
97
  require_relative 'paper_trail_diff/deleted_analysis_batch'
89
98
  require_relative 'paper_trail_diff/scoped_analysis'
90
99
  require_relative 'paper_trail_diff/historical_filter'
91
100
  require_relative 'paper_trail_diff/association_activity_edge'
92
101
  require_relative 'paper_trail_diff/association_activity_selection'
102
+ require_relative 'paper_trail_diff/total_order'
93
103
  require_relative 'paper_trail_diff/scoped_root_selection'
94
104
  require_relative 'paper_trail_diff/deleted_root_filter'
95
105
  require_relative 'paper_trail_diff/scoped_analysis_builder'
@@ -104,6 +114,7 @@ require_relative 'paper_trail_diff/timeline_builder'
104
114
  require_relative 'paper_trail_diff/activity_range'
105
115
  require_relative 'paper_trail_diff/activity_event'
106
116
  require_relative 'paper_trail_diff/activity_child_candidate_loader'
117
+ require_relative 'paper_trail_diff/prepared_child_candidates'
107
118
  require_relative 'paper_trail_diff/activity_target_candidate_loader'
108
119
  require_relative 'paper_trail_diff/activity_version_collector'
109
120
  require_relative 'paper_trail_diff/activity_snapshot_sequence'
@@ -151,45 +162,35 @@ module PaperTrailDiff # rubocop:disable Metrics/ModuleLength
151
162
 
152
163
  class << self # rubocop:disable Metrics/ClassLength
153
164
  # Compares net state between explicit PaperTrail-version or current-record endpoints.
154
- #: (untyped, untyped, ?associations: association_option, ?ignore: ignore_option, ?reload_live_endpoints: bool?, ?allow_approximate: bool) -> Diff
155
- def compare( # rubocop:disable Metrics/ParameterLists
165
+ #: (untyped, untyped, ?associations: association_option, ?ignore: ignore_option, ?allow_approximate: bool) -> Diff
166
+ def compare(
156
167
  from_version,
157
168
  to_version,
158
169
  associations: [],
159
170
  ignore: DEFAULT_IGNORED_ATTRIBUTES,
160
- reload_live_endpoints: nil,
161
171
  allow_approximate: false
162
172
  )
163
173
  PaperTrailAdapter.new(
164
- associations: associations,
165
- ignore: ignore,
166
- reload_live_endpoints: Deprecation.reload_live_endpoints!(reload_live_endpoints),
167
- allow_approximate: allow_approximate
174
+ associations: associations, ignore: ignore, allow_approximate: allow_approximate
168
175
  ).compare(from_version, to_version)
169
176
  end
170
177
 
171
178
  # Compares many independent endpoint pairs while batching current-record loading.
172
- #: (Array[comparison_input], ?associations: association_option, ?ignore: ignore_option, ?reload_live_endpoints: bool?, ?allow_expensive: bool?, ?allow_approximate: bool) -> comparison_results
173
- def compare_many( # rubocop:disable Metrics/ParameterLists
179
+ #: (Array[comparison_input], ?associations: association_option, ?ignore: ignore_option, ?allow_approximate: bool) -> comparison_results
180
+ def compare_many(
174
181
  comparisons,
175
182
  associations: [],
176
183
  ignore: DEFAULT_IGNORED_ATTRIBUTES,
177
- reload_live_endpoints: nil,
178
- allow_expensive: nil,
179
184
  allow_approximate: false
180
185
  )
181
- Deprecation.allow_expensive!(allow_expensive)
182
186
  PaperTrailAdapter.new(
183
- associations: associations,
184
- ignore: ignore,
185
- reload_live_endpoints: Deprecation.reload_live_endpoints!(reload_live_endpoints),
186
- allow_approximate: allow_approximate
187
+ associations: associations, ignore: ignore, allow_approximate: allow_approximate
187
188
  ).compare_many(comparisons)
188
189
  end
189
190
 
190
191
  # Compares every adjacent reconstructed state in an inclusive version range,
191
192
  # by default the record's whole history through its current state.
192
- #: (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: association_option, ?ignore: ignore_option, ?version_scope: untyped, ?close_on: Symbol?, ?allow_approximate: bool) -> Array[Step]
193
+ #: (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: association_option, ?ignore: ignore_option, ?version_scope: untyped, ?allow_approximate: bool) -> Array[Step]
193
194
  def timeline( # rubocop:disable Metrics/ParameterLists
194
195
  record,
195
196
  from: nil,
@@ -198,10 +199,8 @@ module PaperTrailDiff # rubocop:disable Metrics/ModuleLength
198
199
  associations: [],
199
200
  ignore: DEFAULT_IGNORED_ATTRIBUTES,
200
201
  version_scope: nil,
201
- close_on: nil,
202
202
  allow_approximate: false
203
203
  )
204
- Deprecation.close_on!(close_on, within)
205
204
  PaperTrailAdapter.new(
206
205
  associations: associations, ignore: ignore, allow_approximate: allow_approximate
207
206
  ).timeline(
@@ -214,7 +213,7 @@ module PaperTrailDiff # rubocop:disable Metrics/ModuleLength
214
213
  end
215
214
 
216
215
  # Compares adjacent root and selected-descendant activity boundaries.
217
- #: (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: association_option, ?ignore: ignore_option, ?reload_live_endpoints: bool?, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool, ?group: Symbol?, ?recorded_changes: bool, ?allow_approximate: bool) -> Array[ActivityStep]
216
+ #: (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: association_option, ?ignore: ignore_option, ?version_scope: untyped, ?snapshots: bool, ?group: Symbol?, ?recorded_changes: bool, ?allow_approximate: bool) -> Array[ActivityStep]
218
217
  def activity_timeline( # rubocop:disable Metrics/ParameterLists
219
218
  record,
220
219
  from: nil,
@@ -222,18 +221,14 @@ module PaperTrailDiff # rubocop:disable Metrics/ModuleLength
222
221
  within: nil,
223
222
  associations: [],
224
223
  ignore: DEFAULT_IGNORED_ATTRIBUTES,
225
- reload_live_endpoints: nil,
226
224
  version_scope: nil,
227
- close_on: nil,
228
225
  snapshots: false,
229
226
  group: nil,
230
227
  recorded_changes: false,
231
228
  allow_approximate: false
232
229
  )
233
- Deprecation.close_on!(close_on, within)
234
230
  PaperTrailAdapter.new(
235
231
  associations: associations, ignore: ignore,
236
- reload_live_endpoints: Deprecation.reload_live_endpoints!(reload_live_endpoints),
237
232
  recorded_changes: recorded_changes, allow_approximate: allow_approximate
238
233
  ).activity_timeline(
239
234
  record,
@@ -247,7 +242,7 @@ module PaperTrailDiff # rubocop:disable Metrics/ModuleLength
247
242
  end
248
243
 
249
244
  # Builds an endpoint diff and root-checkpoint timeline while normalizing each version once.
250
- #: (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: association_option, ?ignore: ignore_option, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool, ?group: Symbol?, ?recorded_changes: bool, ?allow_approximate: bool) -> Analysis
245
+ #: (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: association_option, ?ignore: ignore_option, ?activity: bool, ?version_scope: untyped, ?snapshots: bool, ?group: Symbol?, ?recorded_changes: bool, ?allow_approximate: bool) -> Analysis
251
246
  def analyze( # rubocop:disable Metrics/ParameterLists
252
247
  record,
253
248
  from: nil,
@@ -257,13 +252,11 @@ module PaperTrailDiff # rubocop:disable Metrics/ModuleLength
257
252
  ignore: DEFAULT_IGNORED_ATTRIBUTES,
258
253
  activity: false,
259
254
  version_scope: nil,
260
- close_on: nil,
261
255
  snapshots: false,
262
256
  group: nil,
263
257
  recorded_changes: false,
264
258
  allow_approximate: false
265
259
  )
266
- Deprecation.close_on!(close_on, within)
267
260
  PaperTrailAdapter.new(
268
261
  associations: associations, ignore: ignore, recorded_changes: recorded_changes,
269
262
  allow_approximate: allow_approximate
@@ -284,7 +277,7 @@ module PaperTrailDiff # rubocop:disable Metrics/ModuleLength
284
277
  # returns a frozen Hash keyed by identity. Roots with nothing to report in
285
278
  # the window return an empty `Analysis`. To let a relation choose the
286
279
  # records, use `analyze_scope`.
287
- #: (Array[untyped], ?within: untyped, ?associations: association_option, ?ignore: ignore_option, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool, ?group: Symbol?, ?allow_expensive: bool?, ?recorded_changes: bool, ?allow_approximate: bool) -> Hash[identity, Analysis]
280
+ #: (Array[untyped], ?within: untyped, ?associations: association_option, ?ignore: ignore_option, ?activity: bool, ?version_scope: untyped, ?snapshots: bool, ?group: Symbol?, ?recorded_changes: bool, ?allow_approximate: bool) -> Hash[identity, Analysis]
288
281
  def analyze_many( # rubocop:disable Metrics/ParameterLists
289
282
  records,
290
283
  within: nil,
@@ -292,15 +285,11 @@ module PaperTrailDiff # rubocop:disable Metrics/ModuleLength
292
285
  ignore: DEFAULT_IGNORED_ATTRIBUTES,
293
286
  activity: false,
294
287
  version_scope: nil,
295
- close_on: nil,
296
288
  snapshots: false,
297
289
  group: nil,
298
- allow_expensive: nil,
299
290
  recorded_changes: false,
300
291
  allow_approximate: false
301
292
  )
302
- Deprecation.close_on!(close_on, within)
303
- Deprecation.allow_expensive!(allow_expensive)
304
293
  PaperTrailAdapter.new(
305
294
  associations: associations, ignore: ignore,
306
295
  recorded_changes: recorded_changes, allow_approximate: allow_approximate
@@ -334,7 +323,7 @@ module PaperTrailDiff # rubocop:disable Metrics/ModuleLength
334
323
  # Note also that a relation selects on current state, not on state during
335
324
  # the window: `where(status: 'published')` means published *now*, which is a
336
325
  # different set from what was published while the window was open.
337
- #: (untyped, limit: Integer?, ?within: untyped, ?associations: association_option, ?ignore: ignore_option, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool, ?group: Symbol?, ?historical_filter: untyped, ?max_filter_versions: Integer, ?include_deleted: bool, ?allow_expensive: bool?, ?recorded_changes: bool, ?allow_approximate: bool) -> ScopedAnalysis
326
+ #: (untyped, limit: Integer?, ?within: untyped, ?associations: association_option, ?ignore: ignore_option, ?activity: bool, ?version_scope: untyped, ?snapshots: bool, ?group: Symbol?, ?historical_filter: untyped, ?max_filter_versions: Integer, ?include_deleted: bool, ?recorded_changes: bool, ?allow_approximate: bool) -> ScopedAnalysis
338
327
  def analyze_scope( # rubocop:disable Metrics/ParameterLists
339
328
  scope,
340
329
  limit:,
@@ -343,18 +332,14 @@ module PaperTrailDiff # rubocop:disable Metrics/ModuleLength
343
332
  ignore: DEFAULT_IGNORED_ATTRIBUTES,
344
333
  activity: false,
345
334
  version_scope: nil,
346
- close_on: nil,
347
335
  snapshots: false,
348
336
  group: nil,
349
337
  historical_filter: nil,
350
338
  max_filter_versions: HistoricalFilter::DEFAULT_VERSION_LIMIT,
351
339
  include_deleted: false,
352
- allow_expensive: nil,
353
340
  recorded_changes: false,
354
341
  allow_approximate: false
355
342
  )
356
- Deprecation.close_on!(close_on, within)
357
- Deprecation.allow_expensive!(allow_expensive)
358
343
  adapter = PaperTrailAdapter.new(associations: associations, ignore: ignore,
359
344
  recorded_changes: recorded_changes,
360
345
  allow_approximate: allow_approximate)
@@ -370,12 +355,12 @@ module PaperTrailDiff # rubocop:disable Metrics/ModuleLength
370
355
  # for every root that changed or whose requested associations did.
371
356
  # Historical windows remain explicit on analyze_scope; this entry point is
372
357
  # deliberately named for a report through now rather than an as-of query.
373
- #: (untyped, since: untyped, limit: Integer, ?associations: association_option, ?ignore: ignore_option, ?version_scope: untyped, ?snapshots: bool, ?group: Symbol?, ?include_deleted: bool, ?historical_filter: untyped, ?max_filter_versions: Integer, ?allow_expensive: bool?, ?recorded_changes: bool, ?allow_approximate: bool) -> ScopedAnalysis
358
+ #: (untyped, since: untyped, limit: Integer, ?associations: association_option, ?ignore: ignore_option, ?version_scope: untyped, ?snapshots: bool, ?group: Symbol?, ?include_deleted: bool, ?historical_filter: untyped, ?max_filter_versions: Integer, ?recorded_changes: bool, ?allow_approximate: bool) -> ScopedAnalysis
374
359
  def report( # rubocop:disable Metrics/ParameterLists
375
360
  scope, since:, limit:, associations: [], ignore: DEFAULT_IGNORED_ATTRIBUTES,
376
361
  version_scope: nil, snapshots: false, group: nil, include_deleted: false,
377
362
  historical_filter: nil, max_filter_versions: HistoricalFilter::DEFAULT_VERSION_LIMIT,
378
- allow_expensive: nil, recorded_changes: false, allow_approximate: false
363
+ recorded_changes: false, allow_approximate: false
379
364
  )
380
365
  # A range here would become the start of another range.
381
366
  if since.nil? || since.is_a?(Range)
@@ -383,13 +368,14 @@ module PaperTrailDiff # rubocop:disable Metrics/ModuleLength
383
368
  'pass it as `within:` to analyze_scope'
384
369
  end
385
370
 
371
+ # Endless, so a version a server dated ahead of this one's clock is in it.
386
372
  analyze_scope(
387
373
  scope,
388
- within: since..Time.now.utc, limit: limit, associations: associations,
374
+ within: (since..), limit: limit, associations: associations,
389
375
  ignore: ignore, activity: true, version_scope: version_scope, snapshots: snapshots,
390
376
  group: group,
391
377
  include_deleted: include_deleted, historical_filter: historical_filter,
392
- max_filter_versions: max_filter_versions, allow_expensive: allow_expensive,
378
+ max_filter_versions: max_filter_versions,
393
379
  recorded_changes: recorded_changes, allow_approximate: allow_approximate
394
380
  )
395
381
  end
@@ -17,11 +17,6 @@ module PaperTrailDiff
17
17
 
18
18
  @route_finder: ActivityEventRouteFinder
19
19
 
20
- # An edit can move a target into or out of a scope, which a replacement
21
- # in place cannot show, so a scoped route's branch is read again instead.
22
- # : (Array[Array[untyped]]) -> bool
23
- def scoped_route?: (Array[Array[untyped]]) -> bool
24
-
25
20
  # : (Array[untyped], untyped, SnapshotNormalizer, untyped, untyped) -> RecordSnapshot?
26
21
  def normalized_route_record: (Array[untyped], untyped, SnapshotNormalizer, untyped, untyped) -> RecordSnapshot?
27
22
 
@@ -39,8 +34,5 @@ module PaperTrailDiff
39
34
  # row whose type changes is replaced by a record of another class.
40
35
  # : (RecordSnapshot, untyped) -> bool
41
36
  def same_table?: (RecordSnapshot, untyped) -> bool
42
-
43
- # : (untyped) -> untyped
44
- def endpoint_model_class: (untyped) -> untyped
45
37
  end
46
38
  end
@@ -32,27 +32,37 @@ module PaperTrailDiff
32
32
 
33
33
  NOT_READ_MESSAGE: ::String
34
34
 
35
- # `recorded:` names the attributes to leave out of the version's recorded
36
- # changes, or is nil when they were not asked for. Reading them decodes
37
- # `object_changes`, which a caller who does not want them should not pay.
38
- # : (untyped, ?recorded: Array[String]?) -> ActivityBoundary
39
- def self.from_version: (untyped, ?recorded: Array[String]?) -> ActivityBoundary
35
+ # `recorded:` reads the version's recorded changes, or is nil when they
36
+ # were not asked for. Reading them decodes `object_changes`, which waits
37
+ # until a caller reads them, and which one who never does should not pay.
38
+ # : (untyped, ?recorded: RecordedChangesReader?) -> ActivityBoundary
39
+ def self.from_version: (untyped, ?recorded: RecordedChangesReader?) -> ActivityBoundary
40
40
 
41
41
  # The current record has no version, so it recorded nothing.
42
- # : (untyped, captured_at: untyped, ?recorded: Array[String]?) -> ActivityBoundary
43
- def self.current: (untyped, captured_at: untyped, ?recorded: Array[String]?) -> ActivityBoundary
42
+ # : (untyped, captured_at: untyped, ?recorded: RecordedChangesReader?) -> ActivityBoundary
43
+ def self.current: (untyped, captured_at: untyped, ?recorded: RecordedChangesReader?) -> ActivityBoundary
44
44
 
45
45
  # The state a `destroy` version leaves behind. A version records the state
46
46
  # before its own event, so the boundary built from a destroy version still
47
47
  # holds the record; this one is the absence that follows it.
48
- # : (untyped, ?recorded: Array[String]?) -> ActivityBoundary
49
- def self.destroyed: (untyped, ?recorded: Array[String]?) -> ActivityBoundary
48
+ # : (untyped, ?recorded: RecordedChangesReader?) -> ActivityBoundary
49
+ def self.destroyed: (untyped, ?recorded: RecordedChangesReader?) -> ActivityBoundary
50
50
 
51
- # : (untyped, Array[String]?) -> untyped
52
- private def self.recorded_changes: (untyped, Array[String]?) -> untyped
51
+ # Where a change saved without a version came from, such as an
52
+ # `update_columns` call: no version, event, author or time recorded it,
53
+ # so it has none to report. A change row names it as its source.
54
+ # : (item_type: String, item_id: untyped) -> ActivityBoundary
55
+ def self.unversioned: (item_type: String, item_id: untyped) -> ActivityBoundary
56
+
57
+ # : (untyped, Symbol, RecordedChangesReader?) -> ActivityBoundary
58
+ private def self.of_version: (untyped, Symbol, RecordedChangesReader?) -> ActivityBoundary
59
+
60
+ # : (untyped, RecordedChangesReader?) -> untyped
61
+ private def self.recorded_changes: (untyped, RecordedChangesReader?) -> untyped
53
62
 
54
63
  # `recorded_changes:` takes what `PaperTrailDiff.recorded_changes` returns
55
- # for the version; leave it out when they were not read.
64
+ # for the version, or a RecordedChangesReader::Pending that reads it when
65
+ # first asked; leave it out when they were not read.
56
66
  # : (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
57
67
  def initialize: (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
58
68
 
@@ -77,6 +87,9 @@ module PaperTrailDiff
77
87
  # : () -> bool
78
88
  def destroyed?: () -> bool
79
89
 
90
+ # : () -> bool
91
+ def unversioned?: () -> bool
92
+
80
93
  # : (?metadata: bool) -> Hash[Symbol, untyped]
81
94
  def to_h: (?metadata: bool) -> Hash[Symbol, untyped]
82
95
  end
@@ -104,14 +117,21 @@ module PaperTrailDiff
104
117
  # would credit the rest of the save to whoever opened it.
105
118
  attr_reader sources: Array[ActivityBoundary]
106
119
 
120
+ # @api private
121
+ # What credits this step's change rows, which a transaction group extends
122
+ # over the steps it merges.
123
+ attr_reader attribution: ChangeAttribution?
124
+
107
125
  # Compares two reconstructed states and keeps them only when asked, which is
108
126
  # every caller's shape: the diff always comes from the pair, the pair itself
109
127
  # is retained on request.
110
- # : (from_boundary: ActivityBoundary, to_boundary: ActivityBoundary, from_snapshot: RecordSnapshot?, to_snapshot: RecordSnapshot?, retain: bool, ?sources: Array[ActivityBoundary]?) -> ActivityStep
111
- def self.between: (from_boundary: ActivityBoundary, to_boundary: ActivityBoundary, from_snapshot: RecordSnapshot?, to_snapshot: RecordSnapshot?, retain: bool, ?sources: Array[ActivityBoundary]?) -> ActivityStep
128
+ # : (from_boundary: ActivityBoundary, to_boundary: ActivityBoundary, from_snapshot: RecordSnapshot?, to_snapshot: RecordSnapshot?, retain: bool, ?sources: Array[ActivityBoundary]?, ?attribution: ChangeAttribution?) -> ActivityStep
129
+ def self.between: (from_boundary: ActivityBoundary, to_boundary: ActivityBoundary, from_snapshot: RecordSnapshot?, to_snapshot: RecordSnapshot?, retain: bool, ?sources: Array[ActivityBoundary]?, ?attribution: ChangeAttribution?) -> ActivityStep
112
130
 
113
- # : (from_boundary: ActivityBoundary, to_boundary: ActivityBoundary, diff: Diff, ?from_snapshot: RecordSnapshot?, ?to_snapshot: RecordSnapshot?, ?sources: Array[ActivityBoundary]?) -> void
114
- def initialize: (from_boundary: ActivityBoundary, to_boundary: ActivityBoundary, diff: Diff, ?from_snapshot: RecordSnapshot?, ?to_snapshot: RecordSnapshot?, ?sources: Array[ActivityBoundary]?) -> void
131
+ # `attribution` credits each change row to the version that made it (see
132
+ # ChangeAttribution); without it, every row names `source_boundary`.
133
+ # : (from_boundary: ActivityBoundary, to_boundary: ActivityBoundary, diff: Diff, ?from_snapshot: RecordSnapshot?, ?to_snapshot: RecordSnapshot?, ?sources: Array[ActivityBoundary]?, ?attribution: ChangeAttribution?) -> void
134
+ def initialize: (from_boundary: ActivityBoundary, to_boundary: ActivityBoundary, diff: Diff, ?from_snapshot: RecordSnapshot?, ?to_snapshot: RecordSnapshot?, ?sources: Array[ActivityBoundary]?, ?attribution: ChangeAttribution?) -> void
115
135
 
116
136
  # : () -> bool
117
137
  def empty?: () -> bool
@@ -121,7 +141,9 @@ module PaperTrailDiff
121
141
  # : () -> ActivityBoundary
122
142
  def source_boundary: () -> ActivityBoundary
123
143
 
124
- # The diff as flat rows, each attributed to `source_boundary`.
144
+ # The diff as flat rows, each credited to the event that made its change:
145
+ # the version of the row's record that recorded it, an unversioned source
146
+ # for a part saved without a version, or else `source_boundary`.
125
147
  # : () -> Array[ChangeRow]
126
148
  def change_rows: () -> Array[ChangeRow]
127
149