paper_trail_diff 0.17.0 → 0.18.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (215) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +663 -0
  3. data/QUICKSTART.md +12 -14
  4. data/README.md +32 -30
  5. data/docs/architecture.md +65 -29
  6. data/docs/performance.md +161 -46
  7. data/docs/reference.md +495 -394
  8. data/docs/testing.md +9 -15
  9. data/lib/paper_trail_diff/activity_belongs_to_event_applier.rb +42 -9
  10. data/lib/paper_trail_diff/activity_boundary.rb +15 -6
  11. data/lib/paper_trail_diff/activity_child_candidate_loader.rb +91 -18
  12. data/lib/paper_trail_diff/activity_collection_event_applier.rb +14 -15
  13. data/lib/paper_trail_diff/activity_collection_record_updater.rb +18 -8
  14. data/lib/paper_trail_diff/activity_collection_route_updater.rb +12 -25
  15. data/lib/paper_trail_diff/activity_event.rb +53 -34
  16. data/lib/paper_trail_diff/activity_event_record_normalizer.rb +12 -26
  17. data/lib/paper_trail_diff/activity_event_record_resolver.rb +45 -32
  18. data/lib/paper_trail_diff/activity_event_snapshot_refresher.rb +26 -33
  19. data/lib/paper_trail_diff/activity_history.rb +28 -34
  20. data/lib/paper_trail_diff/activity_relationship.rb +3 -26
  21. data/lib/paper_trail_diff/activity_root_snapshot_refresher.rb +14 -8
  22. data/lib/paper_trail_diff/activity_snapshot_delta.rb +2 -3
  23. data/lib/paper_trail_diff/activity_snapshot_sequence.rb +92 -25
  24. data/lib/paper_trail_diff/activity_timeline_builder.rb +128 -77
  25. data/lib/paper_trail_diff/activity_transaction_applier.rb +49 -0
  26. data/lib/paper_trail_diff/activity_tree_filter.rb +70 -57
  27. data/lib/paper_trail_diff/activity_tree_places.rb +76 -0
  28. data/lib/paper_trail_diff/activity_version_collector.rb +45 -32
  29. data/lib/paper_trail_diff/activity_view.rb +2 -0
  30. data/lib/paper_trail_diff/analysis.rb +6 -5
  31. data/lib/paper_trail_diff/analysis_batch.rb +21 -17
  32. data/lib/paper_trail_diff/association_activity_edge.rb +99 -85
  33. data/lib/paper_trail_diff/association_activity_selection.rb +46 -14
  34. data/lib/paper_trail_diff/association_discovery.rb +4 -4
  35. data/lib/paper_trail_diff/association_key.rb +10 -18
  36. data/lib/paper_trail_diff/association_traversal.rb +72 -92
  37. data/lib/paper_trail_diff/batch_boundary_resolver.rb +1 -7
  38. data/lib/paper_trail_diff/batch_preload.rb +2 -3
  39. data/lib/paper_trail_diff/batched_root_analyses.rb +60 -25
  40. data/lib/paper_trail_diff/batched_root_analyzer.rb +5 -5
  41. data/lib/paper_trail_diff/batched_root_versions.rb +7 -30
  42. data/lib/paper_trail_diff/branch_snapshot_refresher.rb +19 -14
  43. data/lib/paper_trail_diff/candidate_table.rb +160 -0
  44. data/lib/paper_trail_diff/change_attribution.rb +35 -28
  45. data/lib/paper_trail_diff/collection_identity_index.rb +68 -24
  46. data/lib/paper_trail_diff/collection_transition.rb +3 -3
  47. data/lib/paper_trail_diff/comparison_batch.rb +13 -6
  48. data/lib/paper_trail_diff/database_time.rb +85 -0
  49. data/lib/paper_trail_diff/deleted_analysis_batch.rb +22 -23
  50. data/lib/paper_trail_diff/deleted_root_filter.rb +10 -6
  51. data/lib/paper_trail_diff/diagnostics.rb +26 -86
  52. data/lib/paper_trail_diff/endpoint.rb +37 -5
  53. data/lib/paper_trail_diff/engine.rb +1 -1
  54. data/lib/paper_trail_diff/errors.rb +0 -6
  55. data/lib/paper_trail_diff/exact_column_type.rb +96 -0
  56. data/lib/paper_trail_diff/historical_snapshot_store.rb +88 -83
  57. data/lib/paper_trail_diff/instrumentation.rb +0 -8
  58. data/lib/paper_trail_diff/live_endpoint_batch_loader.rb +1 -4
  59. data/lib/paper_trail_diff/live_graph_collector.rb +1 -3
  60. data/lib/paper_trail_diff/nested_comparator.rb +42 -10
  61. data/lib/paper_trail_diff/paper_trail_adapter.rb +55 -98
  62. data/lib/paper_trail_diff/prepared_activity_index.rb +235 -179
  63. data/lib/paper_trail_diff/prepared_child_candidates.rb +13 -3
  64. data/lib/paper_trail_diff/prepared_edge_loader.rb +11 -49
  65. data/lib/paper_trail_diff/prepared_history.rb +27 -177
  66. data/lib/paper_trail_diff/prepared_history_loader.rb +39 -57
  67. data/lib/paper_trail_diff/prepared_record_index.rb +221 -147
  68. data/lib/paper_trail_diff/prepared_snapshot_builder.rb +47 -42
  69. data/lib/paper_trail_diff/prepared_state_association_reader.rb +85 -62
  70. data/lib/paper_trail_diff/recorded_changes.rb +34 -10
  71. data/lib/paper_trail_diff/recorded_owner.rb +67 -0
  72. data/lib/paper_trail_diff/root_version_selection.rb +6 -2
  73. data/lib/paper_trail_diff/scope_condition.rb +120 -80
  74. data/lib/paper_trail_diff/scope_ranking.rb +14 -32
  75. data/lib/paper_trail_diff/scoped_analysis.rb +11 -6
  76. data/lib/paper_trail_diff/scoped_analysis_builder.rb +17 -11
  77. data/lib/paper_trail_diff/scoped_root_selection.rb +91 -85
  78. data/lib/paper_trail_diff/selection_window.rb +31 -0
  79. data/lib/paper_trail_diff/snapshot.rb +60 -58
  80. data/lib/paper_trail_diff/snapshot_members.rb +115 -0
  81. data/lib/paper_trail_diff/snapshot_normalizer.rb +0 -11
  82. data/lib/paper_trail_diff/step.rb +1 -5
  83. data/lib/paper_trail_diff/stored_form.rb +146 -0
  84. data/lib/paper_trail_diff/stored_json_values.rb +8 -5
  85. data/lib/paper_trail_diff/stored_time_precision.rb +67 -33
  86. data/lib/paper_trail_diff/stored_values.rb +35 -3
  87. data/lib/paper_trail_diff/support.rb +185 -35
  88. data/lib/paper_trail_diff/time_of_day.rb +13 -2
  89. data/lib/paper_trail_diff/time_range.rb +85 -11
  90. data/lib/paper_trail_diff/time_version_range.rb +5 -1
  91. data/lib/paper_trail_diff/timeline_builder.rb +5 -11
  92. data/lib/paper_trail_diff/timeline_range.rb +56 -19
  93. data/lib/paper_trail_diff/timeline_snapshot_provider.rb +31 -7
  94. data/lib/paper_trail_diff/total_order.rb +19 -5
  95. data/lib/paper_trail_diff/transaction_anchors.rb +138 -0
  96. data/lib/paper_trail_diff/transaction_cut.rb +67 -327
  97. data/lib/paper_trail_diff/transaction_ends.rb +194 -0
  98. data/lib/paper_trail_diff/traversal_preparer.rb +12 -24
  99. data/lib/paper_trail_diff/{approximate_paths.rb → unreadable_paths.rb} +8 -9
  100. data/lib/paper_trail_diff/value_objects.rb +8 -6
  101. data/lib/paper_trail_diff/version.rb +1 -1
  102. data/lib/paper_trail_diff/version_association_candidate_scope.rb +28 -4
  103. data/lib/paper_trail_diff/version_boundary.rb +0 -29
  104. data/lib/paper_trail_diff/version_query.rb +49 -1
  105. data/lib/paper_trail_diff/version_scope_filter.rb +74 -5
  106. data/lib/paper_trail_diff/version_sequence_diagnostics.rb +4 -31
  107. data/lib/paper_trail_diff/version_table.rb +8 -1
  108. data/lib/paper_trail_diff.rb +56 -110
  109. data/sig/generated/paper_trail_diff/activity_belongs_to_event_applier.rbs +24 -2
  110. data/sig/generated/paper_trail_diff/activity_boundary.rbs +6 -0
  111. data/sig/generated/paper_trail_diff/activity_child_candidate_loader.rbs +46 -5
  112. data/sig/generated/paper_trail_diff/activity_collection_event_applier.rbs +7 -4
  113. data/sig/generated/paper_trail_diff/activity_collection_record_updater.rbs +11 -2
  114. data/sig/generated/paper_trail_diff/activity_collection_route_updater.rbs +8 -6
  115. data/sig/generated/paper_trail_diff/activity_event.rbs +27 -18
  116. data/sig/generated/paper_trail_diff/activity_event_record_normalizer.rbs +7 -11
  117. data/sig/generated/paper_trail_diff/activity_event_record_resolver.rbs +26 -8
  118. data/sig/generated/paper_trail_diff/activity_event_snapshot_refresher.rbs +10 -2
  119. data/sig/generated/paper_trail_diff/activity_history.rbs +23 -26
  120. data/sig/generated/paper_trail_diff/activity_relationship.rbs +0 -6
  121. data/sig/generated/paper_trail_diff/activity_root_snapshot_refresher.rbs +5 -0
  122. data/sig/generated/paper_trail_diff/activity_snapshot_sequence.rbs +53 -10
  123. data/sig/generated/paper_trail_diff/activity_timeline_builder.rbs +64 -38
  124. data/sig/generated/paper_trail_diff/activity_transaction_applier.rbs +28 -0
  125. data/sig/generated/paper_trail_diff/activity_tree_filter.rbs +46 -38
  126. data/sig/generated/paper_trail_diff/activity_tree_places.rbs +45 -0
  127. data/sig/generated/paper_trail_diff/activity_version_collector.rbs +21 -11
  128. data/sig/generated/paper_trail_diff/analysis.rbs +6 -5
  129. data/sig/generated/paper_trail_diff/analysis_batch.rbs +8 -6
  130. data/sig/generated/paper_trail_diff/association_activity_edge.rbs +58 -45
  131. data/sig/generated/paper_trail_diff/association_activity_selection.rbs +20 -3
  132. data/sig/generated/paper_trail_diff/association_discovery.rbs +2 -2
  133. data/sig/generated/paper_trail_diff/association_key.rbs +2 -11
  134. data/sig/generated/paper_trail_diff/association_traversal.rbs +43 -44
  135. data/sig/generated/paper_trail_diff/batch_boundary_resolver.rbs +0 -2
  136. data/sig/generated/paper_trail_diff/batched_root_analyses.rbs +40 -17
  137. data/sig/generated/paper_trail_diff/batched_root_analyzer.rbs +2 -2
  138. data/sig/generated/paper_trail_diff/batched_root_versions.rbs +2 -11
  139. data/sig/generated/paper_trail_diff/branch_snapshot_refresher.rbs +12 -8
  140. data/sig/generated/paper_trail_diff/candidate_table.rbs +97 -0
  141. data/sig/generated/paper_trail_diff/change_attribution.rbs +21 -19
  142. data/sig/generated/paper_trail_diff/collection_identity_index.rbs +33 -13
  143. data/sig/generated/paper_trail_diff/collection_transition.rbs +2 -2
  144. data/sig/generated/paper_trail_diff/comparison_batch.rbs +5 -0
  145. data/sig/generated/paper_trail_diff/database_time.rbs +48 -0
  146. data/sig/generated/paper_trail_diff/deleted_analysis_batch.rbs +13 -15
  147. data/sig/generated/paper_trail_diff/deleted_root_filter.rbs +4 -0
  148. data/sig/generated/paper_trail_diff/diagnostics.rbs +13 -31
  149. data/sig/generated/paper_trail_diff/endpoint.rbs +14 -1
  150. data/sig/generated/paper_trail_diff/errors.rbs +0 -8
  151. data/sig/generated/paper_trail_diff/exact_column_type.rbs +51 -0
  152. data/sig/generated/paper_trail_diff/historical_snapshot_store.rbs +51 -31
  153. data/sig/generated/paper_trail_diff/instrumentation.rbs +0 -5
  154. data/sig/generated/paper_trail_diff/nested_comparator.rbs +21 -0
  155. data/sig/generated/paper_trail_diff/paper_trail_adapter.rbs +18 -29
  156. data/sig/generated/paper_trail_diff/prepared_activity_index.rbs +149 -94
  157. data/sig/generated/paper_trail_diff/prepared_child_candidates.rbs +10 -2
  158. data/sig/generated/paper_trail_diff/prepared_edge_loader.rbs +4 -21
  159. data/sig/generated/paper_trail_diff/prepared_history.rbs +22 -79
  160. data/sig/generated/paper_trail_diff/prepared_history_loader.rbs +24 -32
  161. data/sig/generated/paper_trail_diff/prepared_record_index.rbs +137 -63
  162. data/sig/generated/paper_trail_diff/prepared_snapshot_builder.rbs +22 -13
  163. data/sig/generated/paper_trail_diff/prepared_state_association_reader.rbs +41 -28
  164. data/sig/generated/paper_trail_diff/recorded_changes.rbs +19 -3
  165. data/sig/generated/paper_trail_diff/recorded_owner.rbs +39 -0
  166. data/sig/generated/paper_trail_diff/root_version_selection.rbs +4 -1
  167. data/sig/generated/paper_trail_diff/scope_condition.rbs +65 -52
  168. data/sig/generated/paper_trail_diff/scope_ranking.rbs +10 -23
  169. data/sig/generated/paper_trail_diff/scoped_analysis.rbs +11 -6
  170. data/sig/generated/paper_trail_diff/scoped_analysis_builder.rbs +7 -2
  171. data/sig/generated/paper_trail_diff/scoped_root_selection.rbs +49 -43
  172. data/sig/generated/paper_trail_diff/selection_window.rbs +19 -0
  173. data/sig/generated/paper_trail_diff/snapshot.rbs +37 -38
  174. data/sig/generated/paper_trail_diff/snapshot_members.rbs +58 -0
  175. data/sig/generated/paper_trail_diff/snapshot_normalizer.rbs +0 -4
  176. data/sig/generated/paper_trail_diff/stored_form.rbs +63 -0
  177. data/sig/generated/paper_trail_diff/stored_json_values.rbs +0 -2
  178. data/sig/generated/paper_trail_diff/stored_time_precision.rbs +33 -20
  179. data/sig/generated/paper_trail_diff/stored_values.rbs +18 -2
  180. data/sig/generated/paper_trail_diff/support.rbs +96 -16
  181. data/sig/generated/paper_trail_diff/time_of_day.rbs +4 -0
  182. data/sig/generated/paper_trail_diff/time_range.rbs +49 -4
  183. data/sig/generated/paper_trail_diff/time_version_range.rbs +3 -0
  184. data/sig/generated/paper_trail_diff/timeline_builder.rbs +3 -6
  185. data/sig/generated/paper_trail_diff/timeline_range.rbs +29 -8
  186. data/sig/generated/paper_trail_diff/timeline_snapshot_provider.rbs +17 -4
  187. data/sig/generated/paper_trail_diff/total_order.rbs +9 -3
  188. data/sig/generated/paper_trail_diff/transaction_anchors.rbs +80 -0
  189. data/sig/generated/paper_trail_diff/transaction_cut.rbs +43 -176
  190. data/sig/generated/paper_trail_diff/transaction_ends.rbs +124 -0
  191. data/sig/generated/paper_trail_diff/traversal_preparer.rbs +6 -11
  192. data/sig/generated/paper_trail_diff/{approximate_paths.rbs → unreadable_paths.rbs} +6 -7
  193. data/sig/generated/paper_trail_diff/value_objects.rbs +4 -2
  194. data/sig/generated/paper_trail_diff/version_association_candidate_scope.rbs +16 -2
  195. data/sig/generated/paper_trail_diff/version_boundary.rbs +0 -14
  196. data/sig/generated/paper_trail_diff/version_query.rbs +26 -0
  197. data/sig/generated/paper_trail_diff/version_scope_filter.rbs +28 -2
  198. data/sig/generated/paper_trail_diff/version_sequence_diagnostics.rbs +4 -15
  199. data/sig/generated/paper_trail_diff/version_table.rbs +4 -0
  200. data/sig/generated/paper_trail_diff.rbs +22 -23
  201. metadata +28 -20
  202. data/lib/paper_trail_diff/activity_target_candidate_loader.rb +0 -123
  203. data/lib/paper_trail_diff/fallback_paths.rb +0 -35
  204. data/lib/paper_trail_diff/habtm_transaction_owners.rb +0 -70
  205. data/lib/paper_trail_diff/historical_association_reifier.rb +0 -161
  206. data/lib/paper_trail_diff/historical_filter.rb +0 -210
  207. data/lib/paper_trail_diff/own_window.rb +0 -35
  208. data/lib/paper_trail_diff/prepared_association_reifier.rb +0 -51
  209. data/sig/generated/paper_trail_diff/activity_target_candidate_loader.rbs +0 -74
  210. data/sig/generated/paper_trail_diff/fallback_paths.rbs +0 -22
  211. data/sig/generated/paper_trail_diff/habtm_transaction_owners.rbs +0 -41
  212. data/sig/generated/paper_trail_diff/historical_association_reifier.rbs +0 -58
  213. data/sig/generated/paper_trail_diff/historical_filter.rbs +0 -96
  214. data/sig/generated/paper_trail_diff/own_window.rbs +0 -22
  215. data/sig/generated/paper_trail_diff/prepared_association_reifier.rbs +0 -27
@@ -7,18 +7,16 @@ module PaperTrailDiff
7
7
 
8
8
  attr_reader branches: Array[String]?
9
9
 
10
- # : (version: untyped, branches: Array[String]?, ?join: bool) -> void
11
- def initialize: (version: untyped, branches: Array[String]?, ?join: bool) -> void
10
+ # The branches under which the version is of a through's join row, which
11
+ # links the root to a target without being one. A record can be a join
12
+ # row under one branch and a member of another.
13
+ attr_reader joins: Array[String]
12
14
 
13
- # : () -> bool
14
- def root?: () -> bool
15
+ # : (version: untyped, branches: Array[String]?, ?joins: Array[String]) -> void
16
+ def initialize: (version: untyped, branches: Array[String]?, ?joins: Array[String]) -> void
15
17
 
16
- # Whether the version is of a through's join row, which links the root to
17
- # a target without being one.
18
18
  # : () -> bool
19
- def join?: () -> bool
20
-
21
- @join: bool
19
+ def root?: () -> bool
22
20
  end
23
21
 
24
22
  # Accumulates each version once while retaining every selected root branch.
@@ -51,16 +49,28 @@ module PaperTrailDiff
51
49
  # : (Array[ActivityEvent], untyped) -> Array[ActivityEvent]
52
50
  def self.before_closing: (Array[ActivityEvent], untyped) -> Array[ActivityEvent]
53
51
 
52
+ # Where the root's destruction takes effect, its tree is gone, so what a
53
+ # transaction that ended later saved there is no change of the root's,
54
+ # until the root is created again. The transaction that creates it again
55
+ # is the root's, from its first event, as for a root created afresh.
56
+ # : (Array[ActivityEvent]) -> Array[ActivityEvent]
57
+ def self.until_destroyed: (Array[ActivityEvent]) -> Array[ActivityEvent]
58
+
59
+ # The transactions of the root's versions that leave it in place.
60
+ # : (Array[ActivityEvent]) -> Array[Array[untyped]?]
61
+ def self.restoring_transactions: (Array[ActivityEvent]) -> Array[Array[untyped]?]
62
+
54
63
  # A version without a transaction shares one with nothing.
55
64
  # : (untyped) -> Array[untyped]?
56
65
  def self.transaction_key: (untyped) -> Array[untyped]?
57
66
 
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
67
+ # : (Array[ActivityEvent]) -> void
68
+ def initialize: (Array[ActivityEvent]) -> void
69
+
70
+ # The events of the event's transaction, in the order they are replayed.
71
+ # The event is in a transaction with others.
72
+ # : (ActivityEvent) -> Array[ActivityEvent]
73
+ def events_for: (ActivityEvent) -> Array[ActivityEvent]
64
74
 
65
75
  # An event outside a transaction, or in one it was not given, keeps its
66
76
  # own.
@@ -70,8 +80,7 @@ module PaperTrailDiff
70
80
  # : (ActivityEvent) -> bool
71
81
  def isolated?: (ActivityEvent) -> bool
72
82
 
73
- # Whether two events were saved in one transaction that began inside the
74
- # history.
83
+ # Whether two events were saved in one transaction.
75
84
  # : (ActivityEvent, ActivityEvent) -> bool
76
85
  def shared?: (ActivityEvent, ActivityEvent) -> bool
77
86
 
@@ -81,7 +90,7 @@ module PaperTrailDiff
81
90
 
82
91
  @group_sizes: Hash[Array[untyped]?, Integer]
83
92
 
84
- @opening: Array[untyped]
93
+ @groups: Hash[Array[untyped]?, Array[ActivityEvent]]
85
94
 
86
95
  # : (Hash[Array[untyped]?, Array[ActivityEvent]]) -> Hash[Array[untyped]?, Array[String]?]
87
96
  def build_groups: (Hash[Array[untyped]?, Array[ActivityEvent]]) -> Hash[Array[untyped]?, Array[String]?]
@@ -1,19 +1,15 @@
1
1
  # Generated from lib/paper_trail_diff/activity_event_record_normalizer.rb with RBS::Inline
2
2
 
3
3
  module PaperTrailDiff
4
- # Normalizes one event record with the historical reader for its boundary.
4
+ # Normalizes the state an event left, with its selected associations as
5
+ # the event's boundary reads them.
5
6
  class ActivityEventRecordNormalizer
6
- # : (?association_reader: untyped) -> void
7
- def initialize: (?association_reader: untyped) -> void
7
+ # : (member_snapshot: untyped) -> void
8
+ def initialize: (member_snapshot: untyped) -> void
8
9
 
9
- # : (untyped, reflection: untyped, subtree: AssociationTree, path: String, normalizer: SnapshotNormalizer, root_endpoint: untyped, context_endpoint: untyped) -> RecordSnapshot?
10
- def call: (untyped, reflection: untyped, subtree: AssociationTree, path: String, normalizer: SnapshotNormalizer, root_endpoint: untyped, context_endpoint: untyped) -> RecordSnapshot?
10
+ # : (PreparedRecordState, reflection: untyped, subtree: AssociationTree, path: String, normalizer: SnapshotNormalizer, context_endpoint: untyped) -> RecordSnapshot
11
+ def call: (PreparedRecordState, reflection: untyped, subtree: AssociationTree, path: String, normalizer: SnapshotNormalizer, context_endpoint: untyped) -> RecordSnapshot
11
12
 
12
- private
13
-
14
- @association_reader: untyped
15
-
16
- # : (untyped, habtm_version: untyped) -> HistoricalAssociationReifier
17
- def historical_reader: (untyped, habtm_version: untyped) -> HistoricalAssociationReifier
13
+ @member_snapshot: untyped
18
14
  end
19
15
  end
@@ -7,11 +7,11 @@ module PaperTrailDiff
7
7
  def initialize: (?record_transition: untyped, ?prepared_record_after: untyped) -> void
8
8
 
9
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.
13
- # : (untyped, ?direct: bool) -> untyped
14
- def record_after: (untyped, ?direct: bool) -> untyped
10
+ # any change saved after the version without one of its own. Every event
11
+ # comes from versions the prepared history loaded, so it answers without
12
+ # a query.
13
+ # : (untyped) -> PreparedRecordState?
14
+ def record_after: (untyped) -> PreparedRecordState?
15
15
 
16
16
  # : (untyped) -> ActivitySnapshotDelta?
17
17
  def snapshot_delta: (untyped) -> ActivitySnapshotDelta?
@@ -27,13 +27,31 @@ module PaperTrailDiff
27
27
 
28
28
  @record_transition: untyped
29
29
 
30
- # : (untyped) -> untyped
31
- def recorded_after: (untyped) -> untyped
32
-
33
30
  # : (untyped) -> untyped
34
31
  def prepared_changeset: (untyped) -> untyped
35
32
 
33
+ # PaperTrail's own changeset holds the changes in a
34
+ # HashWithIndifferentAccess, which turns every hash inside a value into
35
+ # one with string keys, so a `serialize`d hash edited from symbol keys to
36
+ # strings would read as no change. Keys are strings already here.
36
37
  # : (untyped, untyped, untyped) -> untyped
37
38
  def standard_changeset: (untyped, untyped, untyped) -> untyped
39
+
40
+ # PaperTrail's version model decodes its own column; a version that is
41
+ # not one holds the serializer's text.
42
+ # : (untyped) -> untyped
43
+ def stored_changes: (untyped) -> untyped
44
+
45
+ # : (untyped) -> bool
46
+ def json_column?: (untyped) -> bool
47
+
48
+ # PaperTrail writes a `json` or `jsonb` column without its attribute
49
+ # serializer and reads it back the same way, so a decimal, a date and a
50
+ # time are still the strings JSON gave. Each is cast as assigning it to
51
+ # the record would, which is how a version's stored state is read. A
52
+ # `serialize`d value stays as JSON wrote it, which is the form every
53
+ # account of it is read in (StoredJsonValues).
54
+ # : (untyped, untyped) -> untyped
55
+ def cast: (untyped, untyped) -> untyped
38
56
  end
39
57
  end
@@ -3,8 +3,8 @@
3
3
  module PaperTrailDiff
4
4
  # Dispatches safe descendant events to focused immutable snapshot appliers.
5
5
  class ActivityEventSnapshotRefresher
6
- # : (traversal: AssociationTraversal, pool: SnapshotPool, components: untyped, ?association_reader: untyped, ?record_transition: untyped, ?prepared_record_after: untyped) -> void
7
- def initialize: (traversal: AssociationTraversal, pool: SnapshotPool, components: untyped, ?association_reader: untyped, ?record_transition: untyped, ?prepared_record_after: untyped) -> void
6
+ # : (traversal: AssociationTraversal, pool: SnapshotPool, components: untyped, member_snapshot: untyped, ?record_transition: untyped, ?prepared_record_after: untyped) -> void
7
+ def initialize: (traversal: AssociationTraversal, pool: SnapshotPool, components: untyped, member_snapshot: untyped, ?record_transition: untyped, ?prepared_record_after: untyped) -> void
8
8
 
9
9
  # : (SnapshotPool, untyped) -> void
10
10
  def configure_appliers: (SnapshotPool, untyped) -> void
@@ -18,17 +18,25 @@ module PaperTrailDiff
18
18
  # : (ActivityEventRecordNormalizer) -> ActivityBelongsToEventApplier
19
19
  def belongs_to_applier: (ActivityEventRecordNormalizer) -> ActivityBelongsToEventApplier
20
20
 
21
+ # Nothing is applied for a record with places of two kinds in the tree,
22
+ # since an event is applied at those of one kind only (see
23
+ # ActivityTreePlaces).
21
24
  # : (untyped, untyped, RecordSnapshot, Array[String], ActivityEvent?) -> [bool, RecordSnapshot?]
22
25
  def call: (untyped, untyped, RecordSnapshot, Array[String], ActivityEvent?) -> [ bool, RecordSnapshot? ]
23
26
 
24
27
  private
25
28
 
29
+ # : (untyped, Array[untyped], RecordSnapshot, Array[String], ActivityEvent) -> [bool, RecordSnapshot?]
30
+ def apply: (untyped, Array[untyped], RecordSnapshot, Array[String], ActivityEvent) -> [ bool, RecordSnapshot? ]
31
+
26
32
  @belongs_to_applier: ActivityBelongsToEventApplier
27
33
 
28
34
  @collection_applier: ActivityCollectionEventApplier
29
35
 
30
36
  @components: untyped
31
37
 
38
+ @places: ActivityTreePlaces
39
+
32
40
  @record_resolver: ActivityEventRecordResolver
33
41
 
34
42
  @relationship: ActivityRelationship
@@ -34,10 +34,11 @@ module PaperTrailDiff
34
34
  # the current record. Any other range ends at a root event, or at events
35
35
  # after a window whose steps are not reported, so nothing reads it.
36
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
37
+ # the root, whose steps credit each change row to the version that made
38
+ # it (see ChangeAttribution). `filtered` says a version filter chooses the
39
+ # reported steps, so that the history ends after the last change it keeps.
40
+ # : (Array[untyped], Array[ActivityEvent], untyped, view: ActivityView, include_step: untyped, root: RecordReference, ends: TransactionEnds, ?current: untyped, ?closing: RecordSnapshot?, ?filtered: bool) -> void
41
+ def initialize: (Array[untyped], Array[ActivityEvent], untyped, view: ActivityView, include_step: untyped, root: RecordReference, ends: TransactionEnds, ?current: untyped, ?closing: RecordSnapshot?, ?filtered: bool) -> void
41
42
 
42
43
  # : () -> ActivityHistory
43
44
  def call: () -> ActivityHistory
@@ -48,16 +49,18 @@ module PaperTrailDiff
48
49
 
49
50
  @current: untyped
50
51
 
52
+ @ends: TransactionEnds
53
+
51
54
  @events: Array[ActivityEvent]
52
55
 
56
+ @filtered: bool
57
+
53
58
  @first_pending: bool
54
59
 
55
60
  @first_snapshot: RecordSnapshot?
56
61
 
57
62
  @include_step: untyped
58
63
 
59
- @opening: Array[Array[untyped]]?
60
-
61
64
  @passed_reported: bool?
62
65
 
63
66
  @previous_attribution: ChangeAttribution?
@@ -68,7 +71,7 @@ module PaperTrailDiff
68
71
 
69
72
  @previous_snapshot: RecordSnapshot?
70
73
 
71
- @root: RecordReference?
74
+ @root: RecordReference
72
75
 
73
76
  @root_snapshots: Hash[Array[untyped], RecordSnapshot?]
74
77
 
@@ -91,33 +94,27 @@ module PaperTrailDiff
91
94
  def sequence: () -> ActivitySnapshotSequence
92
95
 
93
96
  # A left-out event bounds nothing. A reported step it would have opened
94
- # still moves the reported range's end past it, to the next boundary.
97
+ # still moves the reported range's end past it, to the next boundary,
98
+ # unless a version filter chooses the steps: the event changed nothing
99
+ # the root shows, so the last change the filter keeps is still the end.
95
100
  #
96
101
  # 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.
102
+ # events left out before it are of records outside the root's tree, and
103
+ # change nothing the root shows (see ActivityTreeFilter). And a version
104
+ # filter starts it at the first change it keeps.
102
105
  # : (ActivityEvent, RecordSnapshot?, bool) -> void
103
106
  def consume: (ActivityEvent, RecordSnapshot?, bool) -> void
104
107
 
105
108
  # Inside a transaction a record's change can surface at a later event
106
109
  # than its own, so the rows of a step its boundary opens are read with
107
110
  # 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]]
111
+ # : (ActivityEvent, ActivityBoundary) -> ChangeAttribution
112
+ def attribution: (ActivityEvent, ActivityBoundary) -> ChangeAttribution
113
+
114
+ # The boundaries kept so far of the event's transaction. A version saved
115
+ # outside a transaction is a transaction of its own.
116
+ # : (ActivityEvent) -> ChangeAttribution::Transaction
117
+ def transaction_of: (ActivityEvent) -> ChangeAttribution::Transaction
121
118
 
122
119
  # : (ActivityEvent) -> void
123
120
  def pass: (ActivityEvent) -> void
@@ -14,13 +14,7 @@ module PaperTrailDiff
14
14
  # : (untyped, untyped, Symbol) -> bool
15
15
  def sti_member?: (untyped, untyped, Symbol) -> bool
16
16
 
17
- # : (untyped, untyped, state: Symbol) -> Array[String]
18
- def relationship_owner_values: (untyped, untyped, state: Symbol) -> Array[String]
19
-
20
17
  # : (untyped, untyped, state: Symbol) -> untyped
21
18
  def event_attribute: (untyped, untyped, state: Symbol) -> untyped
22
-
23
- # : (untyped, RecordSnapshot) -> Array[String]
24
- def owner_types: (untyped, RecordSnapshot) -> Array[String]
25
19
  end
26
20
  end
@@ -15,6 +15,9 @@ module PaperTrailDiff
15
15
 
16
16
  private
17
17
 
18
+ # : (untyped) -> bool
19
+ def root_only?: (untyped) -> bool
20
+
18
21
  # The snapshot at a root version starts from the state stored in that
19
22
  # version, and the next one from the state at its own root endpoint. Where
20
23
  # prepared history built both from those states, the two are compared
@@ -49,6 +52,8 @@ module PaperTrailDiff
49
52
 
50
53
  @partial_snapshotter: untyped
51
54
 
55
+ @places: ActivityTreePlaces
56
+
52
57
  @record_after: untyped
53
58
 
54
59
  @record_transition: untyped
@@ -21,6 +21,14 @@ module PaperTrailDiff
21
21
  # : (untyped, untyped) -> RecordSnapshot?
22
22
  def call: (untyped, untyped) -> RecordSnapshot?
23
23
 
24
+ # See HistoricalSnapshotStore#range_end_of.
25
+ # : (untyped, untyped) -> untyped
26
+ def range_end: (untyped, untyped) -> untyped
27
+
28
+ # See HistoricalSnapshotStore#reach_before.
29
+ # : (untyped, untyped) -> untyped
30
+ def reach_before: (untyped, untyped) -> untyped
31
+
24
32
  @last: PreparedActivitySnapshots?
25
33
 
26
34
  @refresher: untyped
@@ -42,8 +50,10 @@ module PaperTrailDiff
42
50
  # : () -> PreparedActivityIndex?
43
51
  def activity_index: () -> PreparedActivityIndex?
44
52
 
45
- # : () -> Array[Array[untyped]]
46
- def opening_transactions: () -> Array[Array[untyped]]
53
+ # Reads with where each transaction of a root's timeline takes effect
54
+ # (see TransactionEnds).
55
+ # : (TransactionEnds) { () -> void } -> void
56
+ def reading: (TransactionEnds) { () -> void } -> void
47
57
 
48
58
  # : (untyped, untyped) -> RecordSnapshot?
49
59
  def call: (untyped, untyped) -> RecordSnapshot?
@@ -54,6 +64,9 @@ module PaperTrailDiff
54
64
  # : (untyped, untyped, RecordSnapshot?, event: ActivityEvent) -> RecordSnapshot?
55
65
  def advance_root: (untyped, untyped, RecordSnapshot?, event: ActivityEvent) -> RecordSnapshot?
56
66
 
67
+ # : (untyped, untyped, RecordSnapshot, Array[String]?, Array[ActivityEvent]) -> RecordSnapshot?
68
+ def apply_transaction: (untyped, untyped, RecordSnapshot, Array[String]?, Array[ActivityEvent]) -> RecordSnapshot?
69
+
57
70
  # The branches a refresh rebuilds, with this root's history.
58
71
  # : (untyped, untyped, tree: AssociationTree, normalizer: SnapshotNormalizer) -> RecordSnapshot?
59
72
  def custom: (untyped, untyped, tree: AssociationTree, normalizer: SnapshotNormalizer) -> RecordSnapshot?
@@ -63,14 +76,15 @@ module PaperTrailDiff
63
76
  # : (untyped) -> PreparedRecordState?
64
77
  def root_state: (untyped) -> PreparedRecordState?
65
78
 
66
- # : (untyped, habtm_version: untyped) -> untyped
67
- def association_reader: (untyped, habtm_version: untyped) -> untyped
79
+ # See HistoricalSnapshotStore#member.
80
+ # : (PreparedRecordState, untyped, tree: AssociationTree, path: String, incoming: untyped, normalizer: SnapshotNormalizer) -> RecordSnapshot
81
+ def member: (PreparedRecordState, untyped, tree: AssociationTree, path: String, incoming: untyped, normalizer: SnapshotNormalizer) -> RecordSnapshot
68
82
 
69
83
  # : (untyped) -> [Hash[untyped, untyped], Hash[untyped, untyped]]?
70
84
  def record_transition: (untyped) -> [ Hash[untyped, untyped], Hash[untyped, untyped] ]?
71
85
 
72
- # : (untyped, ?direct: bool) -> [bool, untyped]
73
- def record_after: (untyped, ?direct: bool) -> [ bool, untyped ]
86
+ # : (untyped) -> [bool, PreparedRecordState?]
87
+ def record_after: (untyped) -> [ bool, PreparedRecordState? ]
74
88
 
75
89
  @refresher: untyped
76
90
 
@@ -81,16 +95,22 @@ module PaperTrailDiff
81
95
 
82
96
  # Builds chronological snapshots, refreshing only branches affected by prior events.
83
97
  class ActivitySnapshotSequence
84
- # : (Array[untyped], Array[ActivityEvent], untyped, ?current: untyped) -> void
85
- def initialize: (Array[untyped], Array[ActivityEvent], untyped, ?current: untyped) -> void
98
+ # `ends` places the events' transactions, as the events were ordered by.
99
+ # : (Array[untyped], Array[ActivityEvent], untyped, ends: TransactionEnds, ?current: untyped) -> void
100
+ def initialize: (Array[untyped], Array[ActivityEvent], untyped, ends: TransactionEnds, ?current: untyped) -> void
86
101
 
87
102
  # : () { (ActivityEvent, RecordSnapshot?) -> void } -> void
88
103
  def each: () { (ActivityEvent, RecordSnapshot?) -> void } -> void
89
104
 
90
105
  private
91
106
 
107
+ # : (ActivityEvent) { (ActivityEvent, RecordSnapshot?) -> void } -> void
108
+ def replay: (ActivityEvent) { (ActivityEvent, RecordSnapshot?) -> void } -> void
109
+
92
110
  @current: untyped
93
111
 
112
+ @ends: TransactionEnds
113
+
94
114
  @events: Array[ActivityEvent]
95
115
 
96
116
  @root_endpoints: Hash[untyped, untyped]
@@ -104,17 +124,40 @@ module PaperTrailDiff
104
124
  # : (ActivityEvent, ActivityEvent, RecordSnapshot?) -> RecordSnapshot?
105
125
  def transition_snapshot: (ActivityEvent, ActivityEvent, RecordSnapshot?) -> RecordSnapshot?
106
126
 
127
+ # A transaction that saved several records is read whole once it ends:
128
+ # until then the records it saved read as they stood before it began, so
129
+ # the snapshot is the same from one of its events to the next. At the
130
+ # event after its last, each of its versions is applied to the record it
131
+ # saved, rather than reading their branches again, which costs every
132
+ # record in them. `branches` are those of a transaction without a root
133
+ # event, and nil for one with.
134
+ # : (ActivityEvent, ActivityEvent, RecordSnapshot, Array[String]?) -> RecordSnapshot?
135
+ def transaction_snapshot: (ActivityEvent, ActivityEvent, RecordSnapshot, Array[String]?) -> RecordSnapshot?
136
+
107
137
  # A transaction with a root event is read whole once it ends. Until then,
108
138
  # PT-AT reads the records it saved as they stood before it began, so from
109
139
  # one descendant's event to the next in the same transaction the snapshot
110
140
  # is the same, and from the root's event to a descendant's only the root's
111
141
  # own version applies, as when it is alone in its transaction. A create
112
142
  # 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.
143
+ # transaction changed, such as HABTM membership, so at a root event those
144
+ # branches are read again. At the event after the transaction's last,
145
+ # each of its versions is applied to the record it saved.
115
146
  # : (ActivityEvent, ActivityEvent, RecordSnapshot?) -> RecordSnapshot?
116
147
  def rebuilt_snapshot: (ActivityEvent, ActivityEvent, RecordSnapshot?) -> RecordSnapshot?
117
148
 
149
+ # From the root's event to the next in its transaction: a second version
150
+ # of the root is read again, and a descendant's event takes only the
151
+ # root's own version.
152
+ # : (ActivityEvent, ActivityEvent, RecordSnapshot) -> RecordSnapshot?
153
+ def within_transaction: (ActivityEvent, ActivityEvent, RecordSnapshot) -> RecordSnapshot?
154
+
155
+ # The snapshot at a root's event, from the one at a descendant's event
156
+ # before it in its transaction: the same, but for the branches the
157
+ # root's version itself records.
158
+ # : (ActivityEvent, RecordSnapshot) -> RecordSnapshot?
159
+ def carried_snapshot: (ActivityEvent, RecordSnapshot) -> RecordSnapshot?
160
+
118
161
  # : (ActivityEvent) -> bool
119
162
  def incremental_root?: (ActivityEvent) -> bool
120
163
 
@@ -15,10 +15,7 @@ module PaperTrailDiff
15
15
  # : (untyped, range: TimelineRange, snapshotter: untyped, view: ActivityView, traversal: AssociationTraversal) -> void
16
16
  def initialize: (untyped, range: TimelineRange, snapshotter: untyped, view: ActivityView, traversal: AssociationTraversal) -> void
17
17
 
18
- # : () -> Array[ActivityStep]
19
- def build: () -> Array[ActivityStep]
20
-
21
- # The window the range covers once its edges have moved to transactions.
18
+ # The window the range covers, as it was asked for.
22
19
  # : () -> TimeRange?
23
20
  def window: () -> TimeRange?
24
21
 
@@ -29,8 +26,12 @@ module PaperTrailDiff
29
26
 
30
27
  private
31
28
 
29
+ @ends: TransactionEnds?
30
+
32
31
  @filter: ActivityScopeFilter?
33
32
 
33
+ @opening: Array[untyped]?
34
+
34
35
  @range: TimelineRange
35
36
 
36
37
  @record: untyped
@@ -45,9 +46,6 @@ module PaperTrailDiff
45
46
 
46
47
  @view: ActivityView
47
48
 
48
- # : () -> Array[ActivityStep]
49
- def no_steps: () -> Array[ActivityStep]
50
-
51
49
  # Each kind of range replays into the same things, or into nil when it
52
50
  # reports no step: its plan and history, the steps it reports, ending with
53
51
  # the one that closes the range after its last event, the state it ends
@@ -56,9 +54,6 @@ module PaperTrailDiff
56
54
  # : (RootVersionPlan, ActivityHistory, ActivityStep?, RecordSnapshot?, ?RecordSnapshot?, ?untyped) -> [RootVersionPlan, ActivityHistory, Array[ActivityStep], RecordSnapshot?, RecordSnapshot?, untyped]?
57
55
  def replayed: (RootVersionPlan, ActivityHistory, ActivityStep?, RecordSnapshot?, ?RecordSnapshot?, ?untyped) -> [ RootVersionPlan, ActivityHistory, Array[ActivityStep], RecordSnapshot?, RecordSnapshot?, untyped ]?
58
56
 
59
- # : ([RootVersionPlan, ActivityHistory, Array[ActivityStep], RecordSnapshot?, RecordSnapshot?, untyped]?) -> Array[ActivityStep]
60
- def steps_of: ([ RootVersionPlan, ActivityHistory, Array[ActivityStep], RecordSnapshot?, RecordSnapshot?, untyped ]?) -> Array[ActivityStep]
61
-
62
57
  # A range that reports no step is empty, whatever its replay read: a
63
58
  # version filter may keep nothing in it, or only the version that ends it,
64
59
  # which opens no step, and a range may run from a version to itself.
@@ -75,6 +70,13 @@ module PaperTrailDiff
75
70
  # : () -> [RootVersionPlan, ActivityHistory, Array[ActivityStep], RecordSnapshot?, RecordSnapshot?, untyped]?
76
71
  def version_replay: () -> [ RootVersionPlan, ActivityHistory, Array[ActivityStep], RecordSnapshot?, RecordSnapshot?, untyped ]?
77
72
 
73
+ # Whether the root, whose destroy a range closes on, was restored after
74
+ # it, saved again under its id. The range from that destroy then reports
75
+ # the removal, in its step to the restoring version, so a range meeting
76
+ # it there leaves the removal to it.
77
+ # : (ActivityEvent) -> bool
78
+ def restored?: (ActivityEvent) -> bool
79
+
78
80
  # Activity replays every root version in the range, even those a version
79
81
  # filter leaves out, so that each change it keeps is read as the whole
80
82
  # history shows it. Only a window reads a context: an explicit range
@@ -83,13 +85,21 @@ module PaperTrailDiff
83
85
  def select_plan: () -> RootVersionPlan
84
86
 
85
87
  # Whether the event's step is reported: it is inside the range, and a
86
- # version filter keeps it. With associations the filter keeps whole
87
- # transactions (see ActivityScopeFilter). On the root alone it keeps the
88
- # root's versions, as `timeline` does, and so does a plan without one, but
89
- # for the version it holds only to reveal the last change in it.
88
+ # version filter keeps it. A window holds an event when it holds the last
89
+ # version of the event's transaction (see TransactionEnds); an explicit
90
+ # range holds every event it collected. With
91
+ # associations the filter keeps whole transactions (see
92
+ # ActivityScopeFilter). On the root alone it keeps the root's versions, as
93
+ # `timeline` does, and so does a plan without one, but for the version it
94
+ # holds only to reveal the last change in it.
90
95
  # : (ActivityEvent, RootVersionPlan) -> bool
91
96
  def reported?: (ActivityEvent, RootVersionPlan) -> bool
92
97
 
98
+ # A window holds the transactions that end inside it; an explicit range
99
+ # those that end where its first version's does, or later.
100
+ # : (untyped) -> bool
101
+ def in_range?: (untyped) -> bool
102
+
93
103
  # The explicit live endpoint and a batch's live closing endpoint use the
94
104
  # same selected plan, which replays every version through to the current
95
105
  # record, a version filter or not.
@@ -105,10 +115,20 @@ module PaperTrailDiff
105
115
  # : (RootVersionPlan, ?RecordSnapshot?, ?untyped) -> ActivityHistory
106
116
  def history_until: (RootVersionPlan, ?RecordSnapshot?, ?untyped) -> ActivityHistory
107
117
 
118
+ # The range starts before its first version's transaction took effect:
119
+ # what another transaction saved before it is part of the starting state
120
+ # if that transaction ended first, and is reported if it ended later. A
121
+ # range that ends at a version ends before that version's transaction
122
+ # took effect, so what took effect after it is left out.
123
+ # : (Array[ActivityEvent], RootVersionPlan, closes: bool) -> Array[ActivityEvent]
124
+ def by_transaction_end: (Array[ActivityEvent], RootVersionPlan, closes: bool) -> Array[ActivityEvent]
125
+
108
126
  # The range's events up to its last root version, or to the instant the
109
127
  # live record it closes on was read, with the history they are read from.
110
- # : (RootVersionPlan, untyped) -> [Array[ActivityEvent], untyped]
111
- def range_events: (RootVersionPlan, untyped) -> [ Array[ActivityEvent], untyped ]
128
+ # A window is read from where the earliest transaction open at its start
129
+ # began; a range of versions names no start.
130
+ # : (RootVersionPlan, untyped, ?start_at: untyped) -> [Array[ActivityEvent], untyped]
131
+ def range_events: (RootVersionPlan, untyped, ?start_at: untyped) -> [ Array[ActivityEvent], untyped ]
112
132
 
113
133
  # : () -> [RecordSnapshot?, untyped]
114
134
  def capture_current: () -> [ RecordSnapshot?, untyped ]
@@ -125,12 +145,25 @@ module PaperTrailDiff
125
145
  # A window closing on current state runs to the instant it is captured,
126
146
  # not to the last root version, or descendants that moved after that
127
147
  # version would be missing from a report that claims to reach now.
148
+ #
149
+ # The events are read from where the transactions across the window's
150
+ # start began, and replayed whole; the window reports those whose
151
+ # transactions end inside it. The live record is read only once something
152
+ # in the window is reported.
128
153
  # : () -> [RootVersionPlan, ActivityHistory, Array[ActivityStep], RecordSnapshot?, RecordSnapshot?, untyped]?
129
154
  def window_replay: () -> [ RootVersionPlan, ActivityHistory, Array[ActivityStep], RecordSnapshot?, RecordSnapshot?, untyped ]?
130
155
 
131
- # The live record is read only once something in the window is reported.
132
- # : (RootVersionPlan, untyped, untyped) -> [RootVersionPlan, ActivityHistory, Array[ActivityStep], RecordSnapshot?, RecordSnapshot?, untyped]?
133
- def window_activity: (RootVersionPlan, untyped, untyped) -> [ RootVersionPlan, ActivityHistory, Array[ActivityStep], RecordSnapshot?, RecordSnapshot?, untyped ]?
156
+ # The plan of every root version the window's transactions saved, its
157
+ # events, their history, and when the live record it closes on was read;
158
+ # nil when there is nothing to replay. The window is planned and read
159
+ # from where the earliest transaction open at its start began, which may
160
+ # have destroyed a root that has no version in the window itself. A
161
+ # batch has planned and read its roots so already.
162
+ # : () -> [RootVersionPlan, Array[ActivityEvent], untyped, untyped]?
163
+ def window_events: () -> [ RootVersionPlan, Array[ActivityEvent], untyped, untyped ]?
164
+
165
+ # : (RootVersionPlan, **untyped) -> [Array[ActivityEvent], untyped, untyped]
166
+ def events_through: (RootVersionPlan, **untyped) -> [ Array[ActivityEvent], untyped, untyped ]
134
167
 
135
168
  # The step that closes the range after its last event, which is reported
136
169
  # as that event's step would be. It runs from the last boundary the
@@ -154,23 +187,17 @@ module PaperTrailDiff
154
187
  # : (ActivityEvent?, RootVersionPlan, untyped, untyped) -> ActivityBoundary?
155
188
  def closing_boundary: (ActivityEvent?, RootVersionPlan, untyped, untyped) -> ActivityBoundary?
156
189
 
157
- # : () -> void
158
- def reject_live_habtm!: () -> void
159
-
160
190
  # : () -> RecordedChangesReader?
161
191
  def root_recorded: () -> RecordedChangesReader?
162
192
 
163
- # A window prepares from its start, explicit endpoints from their first
164
- # version.
165
- # : (Array[untyped], end_at: untyped) -> untyped
166
- def prepare_history: (Array[untyped], end_at: untyped) -> untyped
167
-
168
- # A window collects from its start, explicit endpoints from their first
169
- # version. Explicit endpoints also stop before the rest of the closing
170
- # version's transaction (see ActivityTransactionGroups.before_closing); a
171
- # window keeps every event it collected and reports only those inside it.
172
- # : (Array[untyped], untyped, range_end: untyped) -> Array[ActivityEvent]
173
- def collect_events: (Array[untyped], untyped, range_end: untyped) -> Array[ActivityEvent]
193
+ # Events are collected from where the history starts, which is where the
194
+ # transactions across the range's start began. Without a history only
195
+ # root versions are collected, all of them in the range. Explicit
196
+ # endpoints also stop before the rest of the closing version's
197
+ # transaction (see ActivityTransactionGroups.before_closing); a window
198
+ # keeps every event it collected and reports only those inside it.
199
+ # : (Array[untyped], untyped, range_end: untyped, closing: untyped) -> Array[ActivityEvent]
200
+ def collect_events: (Array[untyped], untyped, range_end: untyped, closing: untyped) -> Array[ActivityEvent]
174
201
 
175
202
  # A version filter reads its answers for a batch's history once, for the
176
203
  # first root that history serves.
@@ -180,8 +207,10 @@ module PaperTrailDiff
180
207
  # Events after the last root version read the root from the live record
181
208
  # when the range closes on it. Explicit endpoints report every step their
182
209
  # plan does, as their range includes every version.
183
- # : (RootVersionPlan, Array[ActivityEvent], untyped, current: untyped, closing: RecordSnapshot?) -> ActivityHistory
184
- def replay: (RootVersionPlan, Array[ActivityEvent], untyped, current: untyped, closing: RecordSnapshot?) -> ActivityHistory
210
+ # `wide` holds every root version among the events, which a window's plan
211
+ # need not.
212
+ # : (RootVersionPlan, RootVersionPlan, Array[ActivityEvent], untyped, current: untyped, closing: RecordSnapshot?) -> ActivityHistory
213
+ def replay: (RootVersionPlan, RootVersionPlan, Array[ActivityEvent], untyped, current: untyped, closing: RecordSnapshot?) -> ActivityHistory
185
214
 
186
215
  # The root as a change row's `record` would name it. A root is a record,
187
216
  # or a deleted one rebuilt from its destroy (see DeletedAnalysisBatch).
@@ -190,8 +219,5 @@ module PaperTrailDiff
190
219
  # mutant:disable
191
220
  # : () -> RecordReference
192
221
  def root_reference: () -> RecordReference
193
-
194
- # : (Array[ActivityStep]) -> Array[ActivityStep]
195
- def present: (Array[ActivityStep]) -> Array[ActivityStep]
196
222
  end
197
223
  end