paper_trail_diff 0.17.1 → 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 +648 -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 +15 -23
  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 +214 -182
  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 +12 -10
  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 +9 -16
  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 +138 -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 +11 -5
  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
@@ -65,25 +65,16 @@ module PaperTrailDiff
65
65
  # : (versions: Array[untyped], live: PreparedRecordState?, ?live_record: untyped, ?state_loader: PreparedVersionStateLoader) -> void
66
66
  def initialize: (versions: Array[untyped], live: PreparedRecordState?, ?live_record: untyped, ?state_loader: PreparedVersionStateLoader) -> void
67
67
 
68
- # : (untyped) -> untyped
69
- def record_before: (untyped) -> untyped
70
-
71
- # A record created in the boundary's own transaction has no state before
72
- # it, yet a HABTM checkpoint saved later in that transaction records it as
73
- # a member. Such a member is read as it was created, at a boundary after
74
- # its creation; before it, the record did not exist yet.
75
- # : (untyped) -> untyped
76
- def record_created_in: (untyped) -> untyped
77
-
78
- # : (untyped) -> PreparedRecordState?
79
- def state_before: (untyped) -> PreparedRecordState?
68
+ # `ends` says where each transaction of the timeline being read takes
69
+ # effect. A record then reads as it stood before every transaction that
70
+ # ends at or after the boundary's own (see TransactionEnds); without it,
71
+ # as it stood before the boundary's transaction.
72
+ # : (untyped, ?TransactionEnds?) -> PreparedRecordState?
73
+ def state_before: (untyped, ?TransactionEnds?) -> PreparedRecordState?
80
74
 
81
75
  # A handled nil is known absence, not permission to query the current row.
82
- # : (untyped, ?direct: bool) -> [bool, untyped]
83
- def record_after: (untyped, ?direct: bool) -> [ bool, untyped ]
84
-
85
- # : () -> Array[untyped]
86
- def records: () -> Array[untyped]
76
+ # : (untyped) -> [bool, PreparedRecordState?]
77
+ def record_after: (untyped) -> [ bool, PreparedRecordState? ]
87
78
 
88
79
  # : () -> Array[PreparedRecordState]
89
80
  def states: () -> Array[PreparedRecordState]
@@ -97,11 +88,19 @@ module PaperTrailDiff
97
88
  # : (untyped, untyped) -> Array[PreparedRecordState]
98
89
  def states_across: (untyped, untyped) -> Array[PreparedRecordState]
99
90
 
91
+ # The states before the transaction of another record's version `first`
92
+ # and after the transaction of its version `last`: what this record was
93
+ # while that record's transaction began and once it had ended.
94
+ # : (untyped, untyped) -> Array[PreparedRecordState]
95
+ def states_around: (untyped, untyped) -> Array[PreparedRecordState]
96
+
100
97
  # : (untyped) -> [PreparedRecordState, PreparedRecordState]?
101
98
  def transition: (untyped) -> [ PreparedRecordState, PreparedRecordState ]?
102
99
 
103
100
  private
104
101
 
102
+ @effective: [ TransactionEnds, Array[untyped] ]?
103
+
105
104
  @live: PreparedRecordState?
106
105
 
107
106
  @live_record: untyped
@@ -116,6 +115,11 @@ module PaperTrailDiff
116
115
 
117
116
  @version_positions: Hash[String, Integer]
118
117
 
118
+ # The state before this record's first version past `boundary` and its
119
+ # transaction, or the live one.
120
+ # : (untyped) -> PreparedRecordState?
121
+ def state_after_transaction: (untyped) -> PreparedRecordState?
122
+
119
123
  # : (Integer) -> PreparedRecordState?
120
124
  def state_after: (Integer) -> PreparedRecordState?
121
125
 
@@ -124,7 +128,7 @@ module PaperTrailDiff
124
128
 
125
129
  # A version is eligible when it is at or after the boundary, or shares the
126
130
  # boundary's transaction. The first is monotonic over the chronological
127
- # list and the second is indexed, so neither rescans a long history once
131
+ # list and the other is indexed, so neither rescans a long history once
128
132
  # per boundary.
129
133
  #
130
134
  # "At or after" is decided by the version order rather than the timestamp
@@ -135,6 +139,22 @@ module PaperTrailDiff
135
139
  # : (untyped) -> Integer?
136
140
  def boundary_index: (untyped) -> Integer?
137
141
 
142
+ # The first version whose transaction ends at or after the boundary's.
143
+ # One record's versions end in the order they
144
+ # were saved, since a transaction holds a record it saved until it ends;
145
+ # where history says otherwise, a version counts as ending no earlier
146
+ # than those before it.
147
+ # : (untyped, TransactionEnds) -> Integer?
148
+ def effective_index: (untyped, TransactionEnds) -> Integer?
149
+
150
+ # Where each version takes effect: the last version of its transaction,
151
+ # or of an earlier version's when that one ends later.
152
+ # : (TransactionEnds) -> Array[untyped]
153
+ def effective_versions: (TransactionEnds) -> Array[untyped]
154
+
155
+ # : (TransactionEnds) -> Array[untyped]
156
+ def placed: (TransactionEnds) -> Array[untyped]
157
+
138
158
  # : (untyped) -> Integer?
139
159
  def transaction_index: (untyped) -> Integer?
140
160
 
@@ -153,23 +173,33 @@ module PaperTrailDiff
153
173
  # : (untyped, Array[untyped]) -> void
154
174
  def load: (untyped, Array[untyped]) -> void
155
175
 
156
- # : (untyped, Array[untyped], Array[untyped]) -> void
157
- def seed: (untyped, Array[untyped], Array[untyped]) -> void
176
+ # When the history was read from.
177
+ # : () -> untyped
178
+ attr_reader start_time: untyped
158
179
 
159
- # The transactions the versions held from the start onward belong to that
160
- # began before it, and where the earliest of them began; see
161
- # PreparedHistoryLoader. Nothing when none did.
162
- # : () -> [Array[Array[untyped]], untyped]?
163
- def opening: () -> [ Array[Array[untyped]], untyped ]?
180
+ # When it was read to, if it ends.
181
+ # : () -> untyped
182
+ attr_reader end_time: untyped
164
183
 
165
- # : (untyped, untyped, untyped) -> untyped
166
- def record_before: (untyped, untyped, untyped) -> untyped
184
+ # Where the transactions of these versions take effect, as their version
185
+ # tables record it (see RecordedTransactionEnds).
186
+ # : (Array[untyped]) -> TransactionEnds
187
+ def transaction_ends: (Array[untyped]) -> TransactionEnds
167
188
 
168
- # : (untyped, untyped, untyped) -> untyped
169
- def record_created_in: (untyped, untyped, untyped) -> untyped
189
+ # Reads for a root's timeline, each record as it stood before every
190
+ # transaction that had not ended at the boundary it is read at (see
191
+ # TransactionEnds).
192
+ # : (TransactionEnds) { () -> void } -> void
193
+ def reading: (TransactionEnds) { () -> void } -> void
170
194
 
171
- # : (untyped, untyped, untyped) -> [bool, PreparedRecordState?]
172
- def snapshot_state_before: (untyped, untyped, untyped) -> [ bool, PreparedRecordState? ]
195
+ # What a read is made with now, if a timeline is being read.
196
+ # : () -> TransactionEnds?
197
+ def reading_ends: () -> TransactionEnds?
198
+
199
+ # The record's state at the boundary, as a record of its class would
200
+ # hold it. The record must be loaded.
201
+ # : (untyped, untyped, untyped) -> PreparedRecordState?
202
+ def snapshot_state_before: (untyped, untyped, untyped) -> PreparedRecordState?
173
203
 
174
204
  # Typed as a reified record's attributes are. A JSON or JSONB `object`
175
205
  # column stores times and dates as strings, which PaperTrail does not cast
@@ -177,11 +207,10 @@ module PaperTrailDiff
177
207
  # : (untyped, untyped, untyped) -> [Hash[untyped, untyped], Hash[untyped, untyped]]?
178
208
  def transition: (untyped, untyped, untyped) -> [ Hash[untyped, untyped], Hash[untyped, untyped] ]?
179
209
 
180
- # : (untyped, untyped, untyped, ?direct: bool) -> [bool, untyped]
181
- def record_after: (untyped, untyped, untyped, ?direct: bool) -> [ bool, untyped ]
182
-
183
- # : (untyped, Array[untyped]) -> Array[untyped]
184
- def records_for: (untyped, Array[untyped]) -> Array[untyped]
210
+ # The record as the version left it, completed as snapshot_state_before's
211
+ # state is. A handled nil is known absence: the version destroyed it.
212
+ # : (untyped, untyped, untyped) -> [bool, PreparedRecordState?]
213
+ def record_after: (untyped, untyped, untyped) -> [ bool, PreparedRecordState? ]
185
214
 
186
215
  # : (untyped, Array[untyped], String) -> Array[untyped]
187
216
  def attribute_values_for: (untyped, Array[untyped], String) -> Array[untyped]
@@ -200,30 +229,38 @@ module PaperTrailDiff
200
229
  # : (untyped, untyped, untyped, untyped) -> Array[Hash[untyped, untyped]]
201
230
  def typed_states_across: (untyped, untyped, untyped, untyped) -> Array[Hash[untyped, untyped]]
202
231
 
232
+ # A record's attributes around another record's transaction (see
233
+ # PreparedRecordSeries#states_around), typed as typed_states_across's.
234
+ # : (untyped, untyped, untyped, untyped) -> Array[Hash[untyped, untyped]]
235
+ def typed_states_around: (untyped, untyped, untyped, untyped) -> Array[Hash[untyped, untyped]]
236
+
203
237
  # : (untyped, untyped) -> bool
204
238
  def loaded?: (untyped, untyped) -> bool
205
239
 
206
240
  private
207
241
 
208
- # A model whose records need their own initialization is cast by
209
- # instantiating it, as reify does.
210
242
  # : (PreparedRecordState) -> Hash[untyped, untyped]
211
243
  def typed_attributes: (PreparedRecordState) -> Hash[untyped, untyped]
212
244
 
213
- # A state completed as a record of its class would hold it, or nil where
214
- # only instantiating can tell; each state is completed once.
215
- # : (PreparedRecordState) -> PreparedRecordState?
216
- def direct_state: (PreparedRecordState) -> PreparedRecordState?
245
+ # A state completed as a record of its class would hold it; each state is
246
+ # completed once. A model whose records need their own initialization is
247
+ # completed by instantiating it, as reify does.
248
+ # : (PreparedRecordState) -> PreparedRecordState
249
+ def direct_state: (PreparedRecordState) -> PreparedRecordState
217
250
 
218
251
  # : (untyped, String) -> bool
219
252
  def generated_reader?: (untyped, String) -> bool
220
253
 
221
254
  @direct_loader: DirectRecordStateLoader
222
255
 
223
- @direct_states: Hash[PreparedRecordState, PreparedRecordState?]
256
+ @direct_states: Hash[PreparedRecordState, PreparedRecordState]
224
257
 
225
258
  @end_time: untyped
226
259
 
260
+ @ends: TransactionEnds?
261
+
262
+ @recorded_ends: RecordedTransactionEnds
263
+
227
264
  @seeded_live_records: Hash[Array[String], untyped]
228
265
 
229
266
  @series: Hash[Array[String], PreparedRecordSeries]
@@ -265,32 +302,69 @@ module PaperTrailDiff
265
302
  def live_records_for: (untyped, Array[untyped]) -> Array[untyped]
266
303
  end
267
304
 
268
- # Finds the transactions that crossed a history's start: those the versions
269
- # held from the start onward belong to that also saved versions before it,
270
- # of any record. One statement per 500 transactions.
271
- class OpeningTransactions
272
- # : (Hash[Array[String], PreparedRecordSeries], untyped) -> void
273
- def initialize: (Hash[Array[String], PreparedRecordSeries], untyped) -> void
305
+ # Finds where the earliest transaction open at a window's start began.
306
+ #
307
+ # A transaction open at the start saved a version before it and another
308
+ # from it onward. Either can be of a record the history does not hold, such
309
+ # as one the transaction moved out of the tree before the window and never
310
+ # saved again, so every such transaction of the tree's version tables is
311
+ # read, not only those of the versions held: one statement per table.
312
+ #
313
+ # Another version table can number a transaction as this one numbered an
314
+ # earlier one, so versions an anchor separates from the start are not read
315
+ # as one transaction's (see TransactionAnchors).
316
+ #
317
+ # Nothing is read past a window's end. A transaction that crosses it is
318
+ # placed by its last version, which its version table names (see
319
+ # RecordedTransactionEnds), so after the window.
320
+ class CrossingTransactions
321
+ # : (Enumerable[untyped], untyped) -> void
322
+ def initialize: (Enumerable[untyped], untyped) -> void
323
+
324
+ # Where the transactions open at `start` began, in these version tables;
325
+ # nil when none is open, or without a start.
326
+ # : (Enumerable[untyped], untyped) -> untyped
327
+ def self.reach: (Enumerable[untyped], untyped) -> untyped
328
+
329
+ # The same, in the version tables of the models of these names that
330
+ # PaperTrail tracks.
331
+ # : (Array[String], untyped) -> untyped
332
+ def self.open_among: (Array[String], untyped) -> untyped
333
+
334
+ # The same, in the version tables of a root model and of the records on
335
+ # its requested paths. A polymorphic belongs_to may reach a record of any
336
+ # class, so with one every version table is read.
337
+ # : (untyped, AssociationTraversal, untyped) -> untyped
338
+ def self.open_around: (untyped, AssociationTraversal, untyped) -> untyped
339
+
340
+ # One version class for each version table the application defines. An
341
+ # abstract class has no table of its own.
342
+ # : () -> Array[untyped]
343
+ def self.every_version_class: () -> Array[untyped]
274
344
 
275
- # Their keys, as ActivityTransactionGroups keys a version's, and when the
276
- # earliest began; nil when none crossed the start.
277
- # : () -> [Array[Array[untyped]], untyped]?
278
- def call: () -> [ Array[Array[untyped]], untyped ]?
345
+ # The versions of this table saved before `start` by the transactions
346
+ # open at it.
347
+ # : (untyped, untyped) -> untyped
348
+ def self.saved_before: (untyped, untyped) -> untyped
279
349
 
280
- private
350
+ # The versions saved from the start onward, of the transactions no anchor
351
+ # separates from it. A transaction's versions can be dated out of the
352
+ # order they were saved in, as when a callback saves other records before
353
+ # its own version, dated as its save began, so each is judged by its date.
354
+ # : (untyped, untyped) -> untyped
355
+ def self.later: (untyped, untyped) -> untyped
281
356
 
282
- # When each of these transactions saved its first version before the
283
- # start, for those that saved one there.
284
- # : (untyped, Array[untyped]) -> Array[[untyped, untyped]]
285
- def earliest: (untyped, Array[untyped]) -> Array[[ untyped, untyped ]]
357
+ # : () -> untyped
358
+ def call: () -> untyped
286
359
 
287
- @series: Hash[Array[String], PreparedRecordSeries]
360
+ private
288
361
 
289
362
  @start: untyped
290
363
 
291
- # The transactions of the versions held from the start onward, by version
292
- # class, since each version table numbers its own.
293
- # : () -> Hash[untyped, Array[untyped]]
294
- def transactions: () -> Hash[untyped, Array[untyped]]
364
+ @version_classes: Enumerable[untyped]
365
+
366
+ # When the earliest transaction open at the start began in this table.
367
+ # : (untyped) -> untyped
368
+ def open_at_start: (untyped) -> untyped
295
369
  end
296
370
  end
@@ -1,36 +1,45 @@
1
1
  # Generated from lib/paper_trail_diff/prepared_snapshot_builder.rb with RBS::Inline
2
2
 
3
3
  module PaperTrailDiff
4
- # Normalizes supported recorded graphs without historical ActiveRecord instances.
4
+ # Normalizes recorded graphs from prepared history, reading each member's
5
+ # state without rebuilding its record.
5
6
  class PreparedSnapshotBuilder
6
7
  # : (AssociationTraversal) -> void
7
8
  def initialize: (AssociationTraversal) -> void
8
9
 
9
- # : (untyped, untyped, tree: AssociationTree, normalizer: SnapshotNormalizer, history: PreparedHistory?) -> [bool, RecordSnapshot?]
10
- def call: (untyped, untyped, tree: AssociationTree, normalizer: SnapshotNormalizer, history: PreparedHistory?) -> [ bool, RecordSnapshot? ]
10
+ # : (untyped, untyped, tree: AssociationTree, normalizer: SnapshotNormalizer, history: PreparedHistory?) -> RecordSnapshot?
11
+ def call: (untyped, untyped, tree: AssociationTree, normalizer: SnapshotNormalizer, history: PreparedHistory?) -> RecordSnapshot?
11
12
 
12
13
  # The state `call` builds a version's snapshot from, or nil when the
13
- # version stored none or must be reified.
14
+ # version stored none. A model whose records need their own
15
+ # initialization is read by reifying it, once per version.
14
16
  # : (untyped) -> PreparedRecordState?
15
17
  def state: (untyped) -> PreparedRecordState?
16
18
 
17
19
  # The current row of a root, given as its state, with its associations as
18
- # `boundary` reads them. Its attributes are the record's own, as the record
19
- # path normalizes them, so its model need not be plain; its members are
20
- # read as a version's are.
21
- # : (PreparedRecordState, untyped, tree: AssociationTree, normalizer: SnapshotNormalizer, history: PreparedHistory?) -> [bool, RecordSnapshot?]
22
- def live: (PreparedRecordState, untyped, tree: AssociationTree, normalizer: SnapshotNormalizer, history: PreparedHistory?) -> [ bool, RecordSnapshot? ]
20
+ # `boundary` reads them. Its attributes are the record's own, as the
21
+ # current snapshot normalizes them, so its model need not be plain; its
22
+ # members are read as a version's are.
23
+ # : (PreparedRecordState, untyped, tree: AssociationTree, normalizer: SnapshotNormalizer, history: PreparedHistory?) -> RecordSnapshot
24
+ def live: (PreparedRecordState, untyped, tree: AssociationTree, normalizer: SnapshotNormalizer, history: PreparedHistory?) -> RecordSnapshot
25
+
26
+ # A state at `path` of the tree, with the associations `tree` selects
27
+ # below it as `boundary` reads them.
28
+ # : (PreparedRecordState, untyped, AssociationTree, SnapshotNormalizer, PreparedHistory?, path: String, ?incoming: untyped) -> RecordSnapshot
29
+ def build: (PreparedRecordState, untyped, AssociationTree, SnapshotNormalizer, PreparedHistory?, path: String, ?incoming: untyped) -> RecordSnapshot
23
30
 
24
31
  private
25
32
 
26
33
  @loader: DirectRecordStateLoader
27
34
 
35
+ @reified: Hash[Array[untyped], PreparedRecordState?]
36
+
28
37
  @traversal: AssociationTraversal
29
38
 
30
- # : (PreparedRecordState, untyped, AssociationTree, SnapshotNormalizer, PreparedHistory?, path: String, ?incoming: untyped) -> [bool, RecordSnapshot?]
31
- def build: (PreparedRecordState, untyped, AssociationTree, SnapshotNormalizer, PreparedHistory?, path: String, ?incoming: untyped) -> [ bool, RecordSnapshot? ]
39
+ # : (untyped) -> PreparedRecordState?
40
+ def reified_state: (untyped) -> PreparedRecordState?
32
41
 
33
- # : (PreparedRecordState, untyped, untyped, AssociationTree, SnapshotNormalizer, PreparedHistory, String) -> [bool, AssociationSnapshot?]
34
- def association: (PreparedRecordState, untyped, untyped, AssociationTree, SnapshotNormalizer, PreparedHistory, String) -> [ bool, AssociationSnapshot? ]
42
+ # : (PreparedRecordState, untyped, untyped, AssociationTree, SnapshotNormalizer, PreparedHistory, String) -> AssociationSnapshot
43
+ def association: (PreparedRecordState, untyped, untyped, AssociationTree, SnapshotNormalizer, PreparedHistory, String) -> AssociationSnapshot
35
44
  end
36
45
  end
@@ -9,8 +9,8 @@ module PaperTrailDiff
9
9
 
10
10
  # Unranked, as a part of a has_many through is read, it returns every row
11
11
  # the part's conditions admit, a record reached twice appearing twice.
12
- # : (PreparedRecordState, untyped, untyped, ?ranked: bool) -> [bool, Array[PreparedRecordState]]
13
- def call: (PreparedRecordState, untyped, untyped, ?ranked: bool) -> [ bool, Array[PreparedRecordState] ]
12
+ # : (PreparedRecordState, untyped, untyped, ?ranked: bool) -> Array[PreparedRecordState]
13
+ def call: (PreparedRecordState, untyped, untyped, ?ranked: bool) -> Array[PreparedRecordState]
14
14
 
15
15
  private
16
16
 
@@ -20,35 +20,47 @@ module PaperTrailDiff
20
20
 
21
21
  @records: PreparedRecordIndex
22
22
 
23
- # A polymorphic target's class is known only once a record names it, so
24
- # `target` reads its scope for each record instead.
25
- # : (untyped, bool) -> bool
26
- def supported?: (untyped, bool) -> bool
27
-
28
23
  # : (PreparedRecordState, untyped, bool, ?untyped) -> bool
29
24
  def in_scope?: (PreparedRecordState, untyped, bool, ?untyped) -> bool
30
25
 
31
- # A type that names no class, or a class whose scope cannot be read as
32
- # conditions, is left to the record path, which raises for the first and
33
- # reads the second through its association.
34
- # : (PreparedRecordState, untyped, untyped, bool) -> [bool, Array[PreparedRecordState]]
35
- def target: (PreparedRecordState, untyped, untyped, bool) -> [ bool, Array[PreparedRecordState] ]
26
+ # : (PreparedRecordState, untyped, untyped, bool) -> Array[PreparedRecordState]
27
+ def target: (PreparedRecordState, untyped, untyped, bool) -> Array[PreparedRecordState]
28
+
29
+ # A polymorphic key with no type names no target, as Active Record reads it.
30
+ # : (PreparedRecordState, untyped) -> bool
31
+ def untyped?: (PreparedRecordState, untyped) -> bool
32
+
33
+ # : (PreparedRecordState, untyped, untyped, bool) -> untyped
34
+ def target_class: (PreparedRecordState, untyped, untyped, bool) -> untyped
35
+
36
+ # A polymorphic target's class is known only from the owner's type
37
+ # column, so TraversalPreparer cannot check it up front: the type may name
38
+ # no class, or one with no versions or a default scope history cannot read.
39
+ # : (PreparedRecordState, untyped, untyped, untyped) -> bot
40
+ def unreadable!: (PreparedRecordState, untyped, untyped, untyped) -> bot
36
41
 
37
- # The members of each join record the owner had at the boundary, as
38
- # PreparedHistory#through_records reads them from records. Under
39
- # `source_type:`, only join records of that type count. A has_many
40
- # through reads its parts unranked, as its query does.
41
- # : (PreparedRecordState, untyped, untyped, bool) -> [bool, Array[PreparedRecordState]]
42
- def through: (PreparedRecordState, untyped, untyped, bool) -> [ bool, Array[PreparedRecordState] ]
42
+ # : (String, untyped) -> bot
43
+ def unversioned!: (String, untyped) -> bot
44
+
45
+ # A target class that is an STI subclass reads no sibling's row, as Active
46
+ # Record's type condition reads none.
47
+ # : (PreparedRecordState, untyped, bool, untyped) -> bool
48
+ def target?: (PreparedRecordState, untyped, bool, untyped) -> bool
49
+
50
+ # The members of each join record the owner had at the boundary. Under
51
+ # `source_type:`, only join records of that type count. A through reads
52
+ # its parts unranked, as its one query joins every row of each.
53
+ # : (PreparedRecordState, untyped, untyped, bool) -> Array[PreparedRecordState]
54
+ def through: (PreparedRecordState, untyped, untyped, bool) -> Array[PreparedRecordState]
43
55
 
44
56
  # The through's own scope applies after its parts' scopes, to each row,
45
57
  # and a ranked read then keeps a record reached twice as one member.
46
58
  # : (untyped, Array[PreparedRecordState], bool) -> Array[PreparedRecordState]
47
59
  def through_members: (untyped, Array[PreparedRecordState], bool) -> Array[PreparedRecordState]
48
60
 
49
- # A has_one keeps the first of its records.
50
- # : (untyped, Array[PreparedRecordState]) -> Array[PreparedRecordState]
51
- def first_if_one: (untyped, Array[PreparedRecordState]) -> Array[PreparedRecordState]
61
+ # A has_one keeps one of its records (see ScopeCondition#first).
62
+ # : (untyped, ScopeCondition, Array[PreparedRecordState]) -> Array[PreparedRecordState]
63
+ def first_if_one: (untyped, ScopeCondition, Array[PreparedRecordState]) -> Array[PreparedRecordState]
52
64
 
53
65
  # : (untyped, PreparedRecordState) -> bool
54
66
  def typed_join?: (untyped, PreparedRecordState) -> bool
@@ -59,19 +71,20 @@ module PaperTrailDiff
59
71
 
60
72
  # The scope's condition and the owner's id are read once for all the
61
73
  # owner's children, which are read at every boundary.
62
- # : (PreparedRecordState, untyped, untyped, bool) -> [bool, Array[PreparedRecordState]]
63
- def children: (PreparedRecordState, untyped, untyped, bool) -> [ bool, Array[PreparedRecordState] ]
74
+ # : (PreparedRecordState, untyped, untyped, bool) -> Array[PreparedRecordState]
75
+ def children: (PreparedRecordState, untyped, untyped, bool) -> Array[PreparedRecordState]
64
76
 
65
77
  # : (untyped, String) -> Array[untyped]
66
78
  def ids_for: (untyped, String) -> Array[untyped]
67
79
 
68
- # : (PreparedRecordState, PreparedRecordState, String, untyped, ScopeCondition) -> bool
69
- def member?: (PreparedRecordState, PreparedRecordState, String, untyped, ScopeCondition) -> bool
80
+ # : (PreparedRecordState, String, untyped, ScopeCondition) -> bool
81
+ def member?: (PreparedRecordState, String, untyped, ScopeCondition) -> bool
82
+
83
+ # An `as:` child names its owner by type as well.
84
+ # : (Hash[String, untyped], untyped) -> bool
85
+ def owner_typed?: (Hash[String, untyped], untyped) -> bool
70
86
 
71
87
  # : (PreparedRecordState) -> String
72
88
  def owner_id: (PreparedRecordState) -> String
73
-
74
- # : (PreparedRecordState, untyped, untyped) -> bool
75
- def matching_type?: (PreparedRecordState, untyped, untyped) -> bool
76
89
  end
77
90
  end
@@ -10,7 +10,9 @@ module PaperTrailDiff
10
10
  #
11
11
  # PaperTrail's `version.changeset` finds the model through `version.item`,
12
12
  # which is a query per version and nothing at all once the record is deleted.
13
- # The version already names its model, so neither is needed here.
13
+ # The version already names its model, and an STI subclass's types are
14
+ # read from the class it recorded (see RecordedClass), so neither is needed
15
+ # here.
14
16
  class RecordedChanges
15
17
  IGNORE_NAMES_REQUIRED: ::String
16
18
 
@@ -36,13 +38,27 @@ module PaperTrailDiff
36
38
  def ignored_names: () -> Array[String]
37
39
 
38
40
  # Without the column, or with it left empty for this version, nothing was
39
- # recorded. That is not the same answer as a recorded empty changeset.
41
+ # recorded. That is not the same answer as a recorded empty changeset. A
42
+ # version need not be an Active Record model, as for compare.
40
43
  # : () -> bool
41
44
  def recorded?: () -> bool
42
45
 
46
+ # An adapter may name its changes with symbols.
47
+ # : (untyped) -> Hash[String, untyped]
48
+ def named: (untyped) -> Hash[String, untyped]
49
+
43
50
  # Primary keys identify the record rather than describe it, as in a diff.
44
51
  # Each side is read as a step's diff reads it (see StoredValues), so a
45
- # value compares equal to the state the change produced.
52
+ # value compares equal to the state the change produced. A name the model
53
+ # no longer has, such as a column since dropped, is left out, as a diff
54
+ # leaves it out. So is a change whose sides read alike, as a diff compares
55
+ # them: Rails records a value assigned in another form than the column
56
+ # keeps, such as a time of day with another date, though the row holds
57
+ # what it held.
58
+ # Each side of the changes in the form the database stores it.
59
+ # : (untyped, Hash[String, untyped]) -> [Hash[String, untyped], Hash[String, untyped]]
60
+ def stored_sides: (untyped, Hash[String, untyped]) -> [ Hash[String, untyped], Hash[String, untyped] ]
61
+
46
62
  # : (untyped, untyped, Array[String]) -> Hash[String, ValueChange]
47
63
  def value_changes: (untyped, untyped, Array[String]) -> Hash[String, ValueChange]
48
64
  end
@@ -0,0 +1,39 @@
1
+ # Generated from lib/paper_trail_diff/recorded_owner.rb with RBS::Inline
2
+
3
+ module PaperTrailDiff
4
+ # PT-AT records a child's owner on the child's own versions, once for each
5
+ # belongs_to the child declares: the owner's id under the foreign key's
6
+ # name, with the class that belongs_to names. A has_many or has_one is read
7
+ # back from those rows.
8
+ module RecordedOwner
9
+ # The names a row may hold for an owner of this class. A polymorphic key
10
+ # names the owner's base class. A plain belongs_to names the class it was
11
+ # declared with, which under single-table inheritance may be any class of
12
+ # the owner's table and not the owner's own. A row with no type is
13
+ # anyone's.
14
+ # : (untyped, untyped) -> Array[String?]
15
+ def self.types: (untyped, untyped) -> Array[String?]
16
+
17
+ # Why history cannot say which records left a has_many or has_one, or a
18
+ # part of a through: its target declares no belongs_to on the foreign
19
+ # key, so no version of a target names an owner. Such a path would show
20
+ # the records it holds now, and none that was destroyed or moved away.
21
+ # : (untyped) -> String?
22
+ def self.unsupported_reason: (untyped) -> String?
23
+
24
+ # A belongs_to is recorded on the owner's own versions, and
25
+ # a through by its parts. A target without versions is refused for that.
26
+ # : (untyped) -> bool
27
+ def self.unrecorded?: (untyped) -> bool
28
+
29
+ # The classes named by the belongs_to associations on the reflection's
30
+ # foreign key, as its target declares them or a subclass of its target
31
+ # does.
32
+ # : (untyped) -> Array[String]
33
+ def self.declared_types: (untyped) -> Array[String]
34
+
35
+ # The model's belongs_to associations on the reflection's foreign key.
36
+ # : (untyped, untyped) -> Array[untyped]
37
+ def self.inverses: (untyped, untyped) -> Array[untyped]
38
+ end
39
+ end
@@ -57,7 +57,10 @@ module PaperTrailDiff
57
57
  # An activity view still needs a root to reconstruct from even when no root
58
58
  # version falls inside the window, because descendants may have moved. With
59
59
  # no later version, a window closing on current state reads the root from
60
- # the live record, which is then its state throughout the window.
60
+ # the live record, which is then its state throughout the window. With
61
+ # neither, the root was gone before the window began, and it reports
62
+ # nothing. Over a whole history, a root with no versions at all has none
63
+ # to report either, as when it is read alone (see TimelineRange#unresolved?).
61
64
  # : () -> RootVersionPlan
62
65
  def without_selection: () -> RootVersionPlan
63
66