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
@@ -1,16 +1,16 @@
1
1
  # Generated from lib/paper_trail_diff/activity_child_candidate_loader.rb with RBS::Inline
2
2
 
3
3
  module PaperTrailDiff
4
- # Loads direct-child identities active at or after one activity boundary.
4
+ # Loads the children of a has_many or has_one that its owners had from a
5
+ # start onward, from PT-AT's version associations and the live rows.
6
+ # Prepared history and activity both read children through it. A composite
7
+ # foreign key reads none, as loaded history cannot index it.
5
8
  class ActivityChildCandidateLoader
6
- # : (untyped, Array[untyped], untyped, ActivityRange) -> void
7
- def initialize: (untyped, Array[untyped], untyped, ActivityRange) -> void
9
+ # : (untyped, Array[untyped], untyped, untyped) -> void
10
+ def initialize: (untyped, Array[untyped], untyped, untyped) -> void
8
11
 
9
- # : () -> Array[untyped]
10
- def call: () -> Array[untyped]
11
-
12
- # One shared query retains the owner and timestamp needed to partition a
13
- # batch's candidates back into each root's exact activity range.
12
+ # Queries shared by a batch's roots keep the owner and timestamp needed to
13
+ # partition its candidates back into each root's exact activity range.
14
14
  # : () -> Array[Array[untyped]]
15
15
  def historical_rows: () -> Array[Array[untyped]]
16
16
 
@@ -19,31 +19,28 @@ module PaperTrailDiff
19
19
 
20
20
  private
21
21
 
22
+ @foreign_key: String?
23
+
22
24
  @parent_class: untyped
23
25
 
24
26
  @parent_ids: Array[untyped]
25
27
 
26
- @range: ActivityRange
27
-
28
28
  @reflection: untyped
29
29
 
30
+ @start_at: untyped
31
+
30
32
  # : (Array[Array[untyped]]) -> Array[Array[untyped]]
31
33
  def typed_rows: (Array[Array[untyped]]) -> Array[Array[untyped]]
32
34
 
33
- # : () -> Array[untyped]
34
- def historical_ids: () -> Array[untyped]
35
-
36
- # : (untyped) -> untyped
37
- def historical_relation: (untyped) -> untyped
38
-
39
- # : (untyped) -> VersionAssociationCandidateScope
40
- def candidate_scope: (untyped) -> VersionAssociationCandidateScope
35
+ # Each statement reads the children of 500 owners.
36
+ # : () -> Enumerator[Array[untyped], untyped]
37
+ def owner_slices: () -> Enumerator[Array[untyped], untyped]
41
38
 
42
- # : () -> Array[untyped]
43
- def current_ids: () -> Array[untyped]
39
+ # : (untyped, String, Array[untyped]) -> untyped
40
+ def historical_relation: (untyped, String, Array[untyped]) -> untyped
44
41
 
45
- # : () -> String
46
- def child_item_type: () -> String
42
+ # : (untyped, untyped) -> Array[Array[untyped]]
43
+ def pluck_rows: (untyped, untyped) -> Array[Array[untyped]]
47
44
 
48
45
  # : () -> Array[String?]
49
46
  def parent_types: () -> Array[String?]
@@ -25,11 +25,6 @@ module PaperTrailDiff
25
25
  # : (RecordSnapshot, Array[untyped], untyped, ActivitySnapshotDelta?, Array[untyped], SnapshotNormalizer, Array[untyped], ?direct: bool) -> RecordSnapshot
26
26
  def apply_route: (RecordSnapshot, Array[untyped], untyped, ActivitySnapshotDelta?, Array[untyped], SnapshotNormalizer, Array[untyped], ?direct: bool) -> RecordSnapshot
27
27
 
28
- # Any edit can move a record into or out of a scope, so a scoped route's
29
- # branch is read again from history instead.
30
- # : (Array[Array[untyped]]) -> bool
31
- def scoped_route?: (Array[Array[untyped]]) -> bool
32
-
33
28
  # : (Array[Array[untyped]], untyped) -> bool
34
29
  def unsafe_through_membership_event?: (Array[Array[untyped]], untyped) -> bool
35
30
 
@@ -55,27 +55,43 @@ module PaperTrailDiff
55
55
  # : (untyped) -> Array[untyped]?
56
56
  def self.transaction_key: (untyped) -> Array[untyped]?
57
57
 
58
- # : (Array[ActivityEvent]) -> void
59
- def initialize: (Array[ActivityEvent]) -> void
60
-
58
+ # An `opening` transaction began before the history's start, so its
59
+ # versions there are not events, yet the state after it has their changes
60
+ # (see PreparedHistoryLoader#reload). The snapshot after
61
+ # it is read whole rather than refreshed from its events alone.
62
+ # : (Array[ActivityEvent], ?opening: Array[Array[untyped]]) -> void
63
+ def initialize: (Array[ActivityEvent], ?opening: Array[Array[untyped]]) -> void
64
+
65
+ # An event outside a transaction, or in one it was not given, keeps its
66
+ # own.
61
67
  # : (ActivityEvent) -> Array[String]?
62
68
  def branches_for: (ActivityEvent) -> Array[String]?
63
69
 
64
70
  # : (ActivityEvent) -> bool
65
71
  def isolated?: (ActivityEvent) -> bool
66
72
 
73
+ # Whether two events were saved in one transaction that began inside the
74
+ # history.
75
+ # : (ActivityEvent, ActivityEvent) -> bool
76
+ def shared?: (ActivityEvent, ActivityEvent) -> bool
77
+
67
78
  private
68
79
 
69
- @branches: Hash[Array[untyped], Array[String]?]
80
+ @branches: Hash[Array[untyped]?, Array[String]?]
81
+
82
+ @group_sizes: Hash[Array[untyped]?, Integer]
70
83
 
71
- @group_sizes: Hash[Array[untyped], Integer]
84
+ @opening: Array[untyped]
72
85
 
73
- # : (Hash[Array[untyped], Array[ActivityEvent]]) -> Hash[Array[untyped], Array[String]?]
74
- def build_groups: (Hash[Array[untyped], Array[ActivityEvent]]) -> Hash[Array[untyped], Array[String]?]
86
+ # : (Hash[Array[untyped]?, Array[ActivityEvent]]) -> Hash[Array[untyped]?, Array[String]?]
87
+ def build_groups: (Hash[Array[untyped]?, Array[ActivityEvent]]) -> Hash[Array[untyped]?, Array[String]?]
75
88
 
76
- # : (Array[ActivityEvent]) -> Hash[Array[untyped], Array[ActivityEvent]]
77
- def grouped_events: (Array[ActivityEvent]) -> Hash[Array[untyped], Array[ActivityEvent]]
89
+ # The events of each transaction; one outside a transaction is in none.
90
+ # : (Array[ActivityEvent]) -> Hash[Array[untyped]?, Array[ActivityEvent]]
91
+ def grouped_events: (Array[ActivityEvent]) -> Hash[Array[untyped]?, Array[ActivityEvent]]
78
92
 
93
+ # A transaction with a root event is read as the root's; every other
94
+ # event has branches.
79
95
  # : (Array[ActivityEvent]) -> Array[String]?
80
96
  def group_branches: (Array[ActivityEvent]) -> Array[String]?
81
97
 
@@ -3,32 +3,19 @@
3
3
  module PaperTrailDiff
4
4
  # Reconstructs an event's post-change record or immutable scalar delta.
5
5
  class ActivityEventRecordResolver
6
- RECORD_AFTER_HANDLERS: untyped
7
-
8
6
  # : (?record_transition: untyped, ?prepared_record_after: untyped) -> void
9
7
  def initialize: (?record_transition: untyped, ?prepared_record_after: untyped) -> void
10
8
 
9
+ # The record as the version left it: the state recorded next, which holds
10
+ # any change saved after the version without one of its own. Prepared
11
+ # history answers without a query; without it, the next version or the
12
+ # live row does.
11
13
  # : (untyped, ?direct: bool) -> untyped
12
14
  def record_after: (untyped, ?direct: bool) -> untyped
13
15
 
14
- # : (untyped) -> [bool, untyped]
15
- def direct_after: (untyped) -> [ bool, untyped ]
16
-
17
- # : (untyped) -> untyped
18
- def fallback_record_after: (untyped) -> untyped
19
-
20
16
  # : (untyped) -> ActivitySnapshotDelta?
21
17
  def snapshot_delta: (untyped) -> ActivitySnapshotDelta?
22
18
 
23
- # : (untyped) -> untyped
24
- def changed_record_after: (untyped) -> untyped
25
-
26
- # : (untyped) -> untyped
27
- def created_record_after: (untyped) -> untyped
28
-
29
- # : (untyped) -> untyped
30
- def updated_record_after: (untyped) -> untyped
31
-
32
19
  # Mirrors PaperTrail's changeset deserialization without resolving
33
20
  # +version.item+, which would issue one live-record query per event.
34
21
  # : (untyped, untyped) -> untyped
@@ -36,31 +23,16 @@ module PaperTrailDiff
36
23
 
37
24
  private
38
25
 
39
- @direct_loader: DirectRecordStateLoader
40
-
41
26
  @prepared_record_after: untyped
42
27
 
43
28
  @record_transition: untyped
44
29
 
45
- # : (untyped) -> PreparedRecordState?
46
- def direct_record_after: (untyped) -> PreparedRecordState?
47
-
48
- # Without `item_subtype` a version names only the STI base class, and a
49
- # change can move the row to another class, so the type the row holds
50
- # after the change decides. A type that names no class has no direct
51
- # state; the caller falls back to reifying the record.
52
- # : (untyped, Hash[untyped, untyped]) -> untyped
53
- def class_after: (untyped, Hash[untyped, untyped]) -> untyped
30
+ # : (untyped) -> untyped
31
+ def recorded_after: (untyped) -> untyped
54
32
 
55
33
  # : (untyped) -> untyped
56
34
  def prepared_changeset: (untyped) -> untyped
57
35
 
58
- # : (untyped, untyped) -> Hash[untyped, untyped]
59
- def after_attributes: (untyped, untyped) -> Hash[untyped, untyped]
60
-
61
- # : (untyped, untyped) -> untyped
62
- def apply_changes: (untyped, untyped) -> untyped
63
-
64
36
  # : (untyped, untyped, untyped) -> untyped
65
37
  def standard_changeset: (untyped, untyped, untyped) -> untyped
66
38
  end
@@ -3,6 +3,12 @@
3
3
  module PaperTrailDiff
4
4
  # Finds explicitly selected collection and belongs-to routes for one event type.
5
5
  class ActivityEventRouteFinder
6
+ # An edit can move a record into or out of a scope, which a change in
7
+ # place cannot show, so an event on a scoped route has its branch read
8
+ # again from history instead.
9
+ # : (Array[Array[untyped]]) -> bool
10
+ def self.scoped_route?: (Array[Array[untyped]]) -> bool
11
+
6
12
  # : (AssociationTraversal) -> void
7
13
  def initialize: (AssociationTraversal) -> void
8
14
 
@@ -28,6 +34,8 @@ module PaperTrailDiff
28
34
 
29
35
  @traversal: AssociationTraversal
30
36
 
37
+ # Validation rejects a path that continues past a polymorphic target, so
38
+ # only a target of one class has a subtree to search.
31
39
  # : (untyped, AssociationTree, String, String) -> bool
32
40
  def through_part_below?: (untyped, AssociationTree, String, String) -> bool
33
41
 
@@ -36,19 +44,18 @@ module PaperTrailDiff
36
44
 
37
45
  # Timelines interleave event types, so every requested combination is
38
46
  # retained. Model, tree, and path are fixed per adapter, leaving one entry
39
- # per selected item type.
47
+ # per selected item type. The strings are kept as frozen copies, which a
48
+ # caller cannot change.
40
49
  # : (Hash[Array[untyped], Array[Array[untyped]]], untyped, AssociationTree, String, String, Symbol) -> Array[Array[untyped]]
41
50
  def cached: (Hash[Array[untyped], Array[Array[untyped]]], untyped, AssociationTree, String, String, Symbol) -> Array[Array[untyped]]
42
51
 
43
- # : (Array[untyped]) -> Array[untyped]
44
- def cache_key: (Array[untyped]) -> Array[untyped]
45
-
46
52
  # : (Array[Array[untyped]]) -> Array[Array[untyped]]
47
53
  def freeze_routes: (Array[Array[untyped]]) -> Array[Array[untyped]]
48
54
 
49
55
  # : (untyped, AssociationTree, String, Symbol, path: String) -> Array[Array[untyped]]
50
56
  def routes: (untyped, AssociationTree, String, Symbol, path: String) -> Array[Array[untyped]]
51
57
 
58
+ # Each reflection is of a child the tree names.
52
59
  # : (untyped, AssociationTree, String, Symbol, String) -> Array[Array[untyped]]
53
60
  def routes_for_reflection: (untyped, AssociationTree, String, Symbol, String) -> Array[Array[untyped]]
54
61
 
@@ -46,8 +46,5 @@ module PaperTrailDiff
46
46
 
47
47
  # : (untyped, untyped) -> untyped
48
48
  def deserialized_changeset: (untyped, untyped) -> untyped
49
-
50
- # : (untyped) -> untyped
51
- def endpoint_model_class: (untyped) -> untyped
52
49
  end
53
50
  end
@@ -15,8 +15,14 @@ module PaperTrailDiff
15
15
 
16
16
  attr_reader last_event_snapshot: RecordSnapshot?
17
17
 
18
- # : (steps: Array[ActivityStep], root_snapshots: Hash[Array[untyped], RecordSnapshot?], first_snapshot: RecordSnapshot?, last_snapshot: RecordSnapshot?, ?last_boundary: ActivityBoundary?, ?last_event_snapshot: RecordSnapshot?) -> void
19
- def initialize: (steps: Array[ActivityStep], root_snapshots: Hash[Array[untyped], RecordSnapshot?], first_snapshot: RecordSnapshot?, last_snapshot: RecordSnapshot?, ?last_boundary: ActivityBoundary?, ?last_event_snapshot: RecordSnapshot?) -> void
18
+ # The event of `last_boundary`.
19
+ attr_reader last_event: ActivityEvent?
20
+
21
+ # What credits the rows of a step `last_boundary` opens.
22
+ attr_reader last_attribution: ChangeAttribution?
23
+
24
+ # : (steps: Array[ActivityStep], root_snapshots: Hash[Array[untyped], RecordSnapshot?], first_snapshot: RecordSnapshot?, last_snapshot: RecordSnapshot?, ?last_boundary: ActivityBoundary?, ?last_event_snapshot: RecordSnapshot?, ?last_event: ActivityEvent?, ?last_attribution: ChangeAttribution?) -> void
25
+ def initialize: (steps: Array[ActivityStep], root_snapshots: Hash[Array[untyped], RecordSnapshot?], first_snapshot: RecordSnapshot?, last_snapshot: RecordSnapshot?, ?last_boundary: ActivityBoundary?, ?last_event_snapshot: RecordSnapshot?, ?last_event: ActivityEvent?, ?last_attribution: ChangeAttribution?) -> void
20
26
 
21
27
  # : () -> ActivityHistory
22
28
  def self.empty: () -> ActivityHistory
@@ -27,8 +33,11 @@ module PaperTrailDiff
27
33
  # `closing` is the snapshot after the last event when the range closes on
28
34
  # the current record. Any other range ends at a root event, or at events
29
35
  # after a window whose steps are not reported, so nothing reads it.
30
- # : (Array[untyped], Array[ActivityEvent], untyped, view: ActivityView, ?current: untyped, ?include_step: untyped, ?closing: RecordSnapshot?) -> void
31
- def initialize: (Array[untyped], Array[ActivityEvent], untyped, view: ActivityView, ?current: untyped, ?include_step: untyped, ?closing: RecordSnapshot?) -> void
36
+ # `include_step` says whether an event's step is reported. `root` names
37
+ # the root, whose steps then credit each change row to the version that
38
+ # made it (see ChangeAttribution).
39
+ # : (Array[untyped], Array[ActivityEvent], untyped, view: ActivityView, include_step: untyped, ?current: untyped, ?closing: RecordSnapshot?, ?root: RecordReference?) -> void
40
+ def initialize: (Array[untyped], Array[ActivityEvent], untyped, view: ActivityView, include_step: untyped, ?current: untyped, ?closing: RecordSnapshot?, ?root: RecordReference?) -> void
32
41
 
33
42
  # : () -> ActivityHistory
34
43
  def call: () -> ActivityHistory
@@ -41,11 +50,17 @@ module PaperTrailDiff
41
50
 
42
51
  @events: Array[ActivityEvent]
43
52
 
53
+ @first_pending: bool
54
+
44
55
  @first_snapshot: RecordSnapshot?
45
56
 
46
57
  @include_step: untyped
47
58
 
48
- @passed_reported: bool
59
+ @opening: Array[Array[untyped]]?
60
+
61
+ @passed_reported: bool?
62
+
63
+ @previous_attribution: ChangeAttribution?
49
64
 
50
65
  @previous_boundary: ActivityBoundary?
51
66
 
@@ -53,6 +68,8 @@ module PaperTrailDiff
53
68
 
54
69
  @previous_snapshot: RecordSnapshot?
55
70
 
71
+ @root: RecordReference?
72
+
56
73
  @root_snapshots: Hash[Array[untyped], RecordSnapshot?]
57
74
 
58
75
  @root_versions: Array[untyped]
@@ -63,10 +80,9 @@ module PaperTrailDiff
63
80
 
64
81
  @steps: Array[ActivityStep]
65
82
 
66
- @view: ActivityView
83
+ @transactions: Hash[Array[untyped], ChangeAttribution::Transaction]
67
84
 
68
- # : () -> void
69
- def reset: () -> void
85
+ @view: ActivityView
70
86
 
71
87
  # : () -> ActivityTreeFilter
72
88
  def filter: () -> ActivityTreeFilter
@@ -76,25 +92,44 @@ module PaperTrailDiff
76
92
 
77
93
  # A left-out event bounds nothing. A reported step it would have opened
78
94
  # still moves the reported range's end past it, to the next boundary.
95
+ #
96
+ # The history starts at the first kept event whose step is reported. The
97
+ # events left out before it change nothing the root shows, unless they are
98
+ # of a transaction that crossed the window's start and has no event kept
99
+ # here: the snapshot at them is the state before that transaction, whose
100
+ # changes the window before this one reports (see ActivityTreeFilter). And
101
+ # a version filter starts it at the first change it keeps.
79
102
  # : (ActivityEvent, RecordSnapshot?, bool) -> void
80
103
  def consume: (ActivityEvent, RecordSnapshot?, bool) -> void
81
104
 
105
+ # Inside a transaction a record's change can surface at a later event
106
+ # than its own, so the rows of a step its boundary opens are read with
107
+ # the boundaries its transaction kept before it (see ChangeAttribution).
108
+ # : (ActivityEvent, ActivityBoundary) -> ChangeAttribution?
109
+ def attribution: (ActivityEvent, ActivityBoundary) -> ChangeAttribution?
110
+
111
+ # The boundaries kept so far of the event's transaction, and whether the
112
+ # history holds all of it. A version saved outside a transaction is a
113
+ # transaction of its own.
114
+ # : (ActivityEvent) -> [ChangeAttribution::Transaction, bool]
115
+ def transaction_of: (ActivityEvent) -> [ ChangeAttribution::Transaction, bool ]
116
+
117
+ # The transactions that began before the history did (see
118
+ # PreparedHistoryLoader#reload).
119
+ # : () -> Array[Array[untyped]]
120
+ def opening: () -> Array[Array[untyped]]
121
+
82
122
  # : (ActivityEvent) -> void
83
123
  def pass: (ActivityEvent) -> void
84
124
 
85
- # : (RecordSnapshot?) -> void
86
- def capture_first: (RecordSnapshot?) -> void
125
+ # : (ActivityEvent, RecordSnapshot?) -> void
126
+ def capture_first: (ActivityEvent, RecordSnapshot?) -> void
127
+
128
+ # : (ActivityEvent) -> bool
129
+ def reported?: (ActivityEvent) -> bool
87
130
 
131
+ # The step from the previous boundary, which `consume` has, to this one.
88
132
  # : (ActivityBoundary, RecordSnapshot?) -> void
89
133
  def append_step: (ActivityBoundary, RecordSnapshot?) -> void
90
-
91
- # : () -> bool
92
- def include_previous_step?: () -> bool
93
-
94
- # : () -> RecordSnapshot?
95
- def final_snapshot: () -> RecordSnapshot?
96
-
97
- # : (untyped) -> Array[untyped]
98
- def version_key: (untyped) -> Array[untyped]
99
134
  end
100
135
  end
@@ -5,28 +5,18 @@ module PaperTrailDiff
5
5
  class ActivityRange
6
6
  attr_reader start_time: untyped
7
7
 
8
- attr_reader end_time: untyped
9
-
10
8
  # : (untyped, untyped) -> void
11
9
  def initialize: (untyped, untyped) -> void
12
10
 
13
11
  # : (untyped) -> bool
14
12
  def include?: (untyped) -> bool
15
13
 
16
- # Narrows an Active Record version relation by timestamp, and to the
17
- # start's transaction. Exact tie-breaking remains in #include? so this
18
- # works for integer, UUID, and custom version IDs.
19
- # : (untyped) -> untyped
20
- def scope: (untyped) -> untyped
21
-
22
- # : () -> bool
23
- def current_end?: () -> bool
24
-
25
- # Whether the state a version recorded after its change held inside the
26
- # range. A range ending at a version ends at the state before it, so the
27
- # change that version records is past the end, unlike #include?.
28
- # : (untyped, untyped) -> bool
29
- def recorded_before_end?: (untyped, untyped) -> bool
14
+ # A range starting at a version starts before that version's transaction,
15
+ # where PT-AT reads its associations. A version saved earlier in it, such
16
+ # as the child update behind a `touch: true` parent version, is a change
17
+ # inside the range.
18
+ # : (untyped) -> bool
19
+ def opening?: (untyped) -> bool
30
20
 
31
21
  private
32
22
 
@@ -40,10 +30,6 @@ module PaperTrailDiff
40
30
 
41
31
  @start_time: untyped
42
32
 
43
- # A range starting at a version starts before that version's transaction,
44
- # where PT-AT reads its associations. A version saved earlier in it, such
45
- # as the child update behind a `touch: true` parent version, is a change
46
- # inside the range.
47
33
  # : (untyped, Array[untyped]) -> bool
48
34
  def after_start?: (untyped, Array[untyped]) -> bool
49
35
 
@@ -3,14 +3,46 @@
3
3
  module PaperTrailDiff
4
4
  # Advances scalar-only root events while retaining already reconstructed associations.
5
5
  class ActivityRootSnapshotRefresher
6
- # : (tree: AssociationTree, traversal: AssociationTraversal, normalizer: SnapshotNormalizer, record_after: untyped, changeset: untyped, partial_snapshotter: untyped, ?record_transition: untyped) -> void
7
- def initialize: (tree: AssociationTree, traversal: AssociationTraversal, normalizer: SnapshotNormalizer, record_after: untyped, changeset: untyped, partial_snapshotter: untyped, ?record_transition: untyped) -> void
6
+ # `root_state` gives the state a root endpoint's snapshot is built from,
7
+ # where prepared history builds it.
8
+ # : (traversal: AssociationTraversal, normalizer: SnapshotNormalizer, record_after: untyped, changeset: untyped, partial_snapshotter: untyped, ?record_transition: untyped, ?root_state: untyped) -> void
9
+ def initialize: (traversal: AssociationTraversal, normalizer: SnapshotNormalizer, record_after: untyped, changeset: untyped, partial_snapshotter: untyped, ?record_transition: untyped, ?root_state: untyped) -> void
8
10
 
11
+ # `previous` is the snapshot at the root's `event`, and the result the one
12
+ # at the next event, whose root is read at `root_endpoint`.
9
13
  # : (untyped, untyped, RecordSnapshot?, ActivityEvent) -> [bool, RecordSnapshot?]
10
14
  def call: (untyped, untyped, RecordSnapshot?, ActivityEvent) -> [ bool, RecordSnapshot? ]
11
15
 
12
16
  private
13
17
 
18
+ # The snapshot at a root version starts from the state stored in that
19
+ # version, and the next one from the state at its own root endpoint. Where
20
+ # prepared history built both from those states, the two are compared
21
+ # directly; nothing else needs to be decoded. Otherwise the version's
22
+ # recorded change and the record after it are read.
23
+ # : (RecordSnapshot, untyped, untyped) -> [untyped, Array[String]]?
24
+ def target: (RecordSnapshot, untyped, untyped) -> [ untyped, Array[String] ]?
25
+
26
+ # The state at the next event and the branches whose reads the root's
27
+ # change between the two states can alter. A change of STI class can
28
+ # change the associations themselves, so it is rebuilt in full.
29
+ # : (RecordSnapshot, untyped, PreparedRecordState, PreparedRecordState) -> [PreparedRecordState, Array[String]]?
30
+ def state_target: (RecordSnapshot, untyped, PreparedRecordState, PreparedRecordState) -> [ PreparedRecordState, Array[String] ]?
31
+
32
+ # The names of the columns whose values differ between two sets of them.
33
+ # : (Hash[untyped, untyped], Hash[untyped, untyped]) -> Array[String]
34
+ def differing: (Hash[untyped, untyped], Hash[untyped, untyped]) -> Array[String]
35
+
36
+ # The record after a root version and the branches its change reaches, or
37
+ # nil when the version cannot be applied to the previous snapshot alone.
38
+ # : (RecordSnapshot, untyped) -> [untyped, Array[String]]?
39
+ def advance_target: (RecordSnapshot, untyped) -> [ untyped, Array[String] ]?
40
+
41
+ # The previous snapshot with the record's attributes and any branches read
42
+ # again, or the previous snapshot itself when nothing differs.
43
+ # : (RecordSnapshot, untyped, RecordSnapshot?) -> RecordSnapshot
44
+ def advanced: (RecordSnapshot, untyped, RecordSnapshot?) -> RecordSnapshot
45
+
14
46
  @changeset: untyped
15
47
 
16
48
  @normalizer: SnapshotNormalizer
@@ -23,6 +55,8 @@ module PaperTrailDiff
23
55
 
24
56
  @relationship_reflections: Hash[String, Array[untyped]]
25
57
 
58
+ @root_state: untyped
59
+
26
60
  @traversal: AssociationTraversal
27
61
 
28
62
  @tree: AssociationTree
@@ -5,14 +5,14 @@ module PaperTrailDiff
5
5
  # so a combined result does not reconstruct the same boundaries twice.
6
6
  module ActivityRootSteps
7
7
  # A window closing on current state ends at the live record, which no
8
- # version-keyed snapshot can supply, so that endpoint is passed in.
8
+ # version-keyed snapshot can supply, so that endpoint is passed in. A plan
9
+ # that replays versions a filter left out reports the steps of the ones it
10
+ # kept, as `timeline` does. Every version a plan names is a root event of
11
+ # the history, which keeps its snapshot.
9
12
  # : (RootVersionPlan, Hash[Array[untyped], RecordSnapshot?], ?closing_snapshot: RecordSnapshot?, ?captured_at: untyped) -> Array[Step]
10
- def self?.call: (RootVersionPlan, Hash[Array[untyped], RecordSnapshot?], ?closing_snapshot: RecordSnapshot?, ?captured_at: untyped) -> Array[Step]
13
+ def self.call: (RootVersionPlan, Hash[Array[untyped], RecordSnapshot?], ?closing_snapshot: RecordSnapshot?, ?captured_at: untyped) -> Array[Step]
11
14
 
12
15
  # : (untyped, Hash[Array[untyped], RecordSnapshot?], RecordSnapshot?) -> RecordSnapshot?
13
- def self?.snapshot_for: (untyped, Hash[Array[untyped], RecordSnapshot?], RecordSnapshot?) -> RecordSnapshot?
14
-
15
- # : (untyped) -> Array[untyped]
16
- def self?.version_key: (untyped) -> Array[untyped]
16
+ def self.snapshot_for: (untyped, Hash[Array[untyped], RecordSnapshot?], RecordSnapshot?) -> RecordSnapshot?
17
17
  end
18
18
  end
@@ -0,0 +1,51 @@
1
+ # Generated from lib/paper_trail_diff/activity_scope_filter.rb with RBS::Inline
2
+
3
+ module PaperTrailDiff
4
+ # Which events a `version_scope:` reports in activity on associations.
5
+ #
6
+ # PT-AT reads a transaction's records as they stood before it began, so the
7
+ # changes a transaction saved surface together in its last step rather than
8
+ # each in the step of its own version (see ActivityTransactionGrouper). No
9
+ # step inside a transaction can be credited to one version of it, and
10
+ # leaving one out would lose the changes it carried. A transaction is
11
+ # therefore reported whole when the filter keeps any version saved in it, of
12
+ # whichever record, and a version saved outside a transaction when the
13
+ # filter keeps that version. Both are answered from the version tables, so
14
+ # every window and every way of asking reads the same transaction alike.
15
+ #
16
+ # One filter serves a request. It reads the answers for each history once,
17
+ # in one statement per version table and 500 transactions or versions, and
18
+ # the roots a batch prepared together share them.
19
+ class ActivityScopeFilter
20
+ # : (untyped) -> void
21
+ def initialize: (untyped) -> void
22
+
23
+ # Reads the answers for every version `history` holds, once for each
24
+ # history, and for those of `versions` it does not hold.
25
+ # : (PreparedHistory?, Array[untyped]) -> void
26
+ def prepare: (PreparedHistory?, Array[untyped]) -> void
27
+
28
+ # Whether the filter keeps a version of `version`'s transaction, or
29
+ # `version` itself when it was saved outside one. `prepare` reads it first.
30
+ # : (untyped) -> bool
31
+ def kept?: (untyped) -> bool
32
+
33
+ private
34
+
35
+ @histories: Set[PreparedHistory]
36
+
37
+ @scope: untyped
38
+
39
+ @transactions: Hash[Array[untyped], bool]
40
+
41
+ @versions: Hash[Array[untyped], bool]
42
+
43
+ # : (Array[untyped]) -> void
44
+ def read: (Array[untyped]) -> void
45
+
46
+ # Records which of the distinct `values` of `column` the filter keeps
47
+ # versions with.
48
+ # : (untyped, Hash[Array[untyped], bool], String, Array[untyped], Symbol) -> void
49
+ def read_kept: (untyped, Hash[Array[untyped], bool], String, Array[untyped], Symbol) -> void
50
+ end
51
+ end
@@ -15,6 +15,11 @@ module PaperTrailDiff
15
15
  # : (untyped) -> untyped
16
16
  def after_value: (untyped) -> untyped
17
17
 
18
+ # Compared as text, so an id read as a string matches one read as an
19
+ # integer.
20
+ # : (untyped) -> bool
21
+ def changed?: (untyped) -> bool
22
+
18
23
  # : (untyped) -> bool
19
24
  def relationship_changed?: (untyped) -> bool
20
25
 
@@ -24,9 +29,6 @@ module PaperTrailDiff
24
29
 
25
30
  @before_attributes: Hash[String, untyped]
26
31
 
27
- # : (Hash[untyped, untyped]) -> Hash[String, untyped]
28
- def normalize_hash: (Hash[untyped, untyped]) -> Hash[String, untyped]
29
-
30
32
  # : (untyped) -> Array[untyped]
31
33
  def relationship_keys: (untyped) -> Array[untyped]
32
34
  end
@@ -13,6 +13,8 @@ module PaperTrailDiff
13
13
  # share these snapshots too, and the caches their refresher builds. They
14
14
  # are the same for any root with that history, so reusing them depends on
15
15
  # nothing but the history.
16
+ #
17
+ # A `start_at` is a window's; a range of versions starts at its first.
16
18
  # : (untyped, Array[untyped], ?start_at: untyped, ?end_at: untyped) -> PreparedActivitySnapshots
17
19
  def prepare: (untyped, Array[untyped], ?start_at: untyped, ?end_at: untyped) -> PreparedActivitySnapshots
18
20
 
@@ -40,6 +42,9 @@ module PaperTrailDiff
40
42
  # : () -> PreparedActivityIndex?
41
43
  def activity_index: () -> PreparedActivityIndex?
42
44
 
45
+ # : () -> Array[Array[untyped]]
46
+ def opening_transactions: () -> Array[Array[untyped]]
47
+
43
48
  # : (untyped, untyped) -> RecordSnapshot?
44
49
  def call: (untyped, untyped) -> RecordSnapshot?
45
50
 
@@ -53,6 +58,11 @@ module PaperTrailDiff
53
58
  # : (untyped, untyped, tree: AssociationTree, normalizer: SnapshotNormalizer) -> RecordSnapshot?
54
59
  def custom: (untyped, untyped, tree: AssociationTree, normalizer: SnapshotNormalizer) -> RecordSnapshot?
55
60
 
61
+ # The state this root's snapshot at an endpoint is built from, where
62
+ # prepared history builds it.
63
+ # : (untyped) -> PreparedRecordState?
64
+ def root_state: (untyped) -> PreparedRecordState?
65
+
56
66
  # : (untyped, habtm_version: untyped) -> untyped
57
67
  def association_reader: (untyped, habtm_version: untyped) -> untyped
58
68
 
@@ -74,9 +84,6 @@ module PaperTrailDiff
74
84
  # : (Array[untyped], Array[ActivityEvent], untyped, ?current: untyped) -> void
75
85
  def initialize: (Array[untyped], Array[ActivityEvent], untyped, ?current: untyped) -> void
76
86
 
77
- # : () -> Array[RecordSnapshot?]
78
- def call: () -> Array[RecordSnapshot?]
79
-
80
87
  # : () { (ActivityEvent, RecordSnapshot?) -> void } -> void
81
88
  def each: () { (ActivityEvent, RecordSnapshot?) -> void } -> void
82
89
 
@@ -97,6 +104,17 @@ module PaperTrailDiff
97
104
  # : (ActivityEvent, ActivityEvent, RecordSnapshot?) -> RecordSnapshot?
98
105
  def transition_snapshot: (ActivityEvent, ActivityEvent, RecordSnapshot?) -> RecordSnapshot?
99
106
 
107
+ # A transaction with a root event is read whole once it ends. Until then,
108
+ # PT-AT reads the records it saved as they stood before it began, so from
109
+ # one descendant's event to the next in the same transaction the snapshot
110
+ # is the same, and from the root's event to a descendant's only the root's
111
+ # own version applies, as when it is alone in its transaction. A create
112
+ # leaves nothing to advance. The root's version can record what the
113
+ # transaction changed, such as HABTM membership, so a snapshot at a root
114
+ # event is rebuilt.
115
+ # : (ActivityEvent, ActivityEvent, RecordSnapshot?) -> RecordSnapshot?
116
+ def rebuilt_snapshot: (ActivityEvent, ActivityEvent, RecordSnapshot?) -> RecordSnapshot?
117
+
100
118
  # : (ActivityEvent) -> bool
101
119
  def incremental_root?: (ActivityEvent) -> bool
102
120