paper_trail_diff 0.17.1 → 0.18.1

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 +661 -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 +195 -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 +126 -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
@@ -3,11 +3,20 @@
3
3
  module PaperTrailDiff
4
4
  # Resolves and validates ActiveRecord reflections for a bounded association tree.
5
5
  class AssociationTraversal
6
+ # A join table has no versions, so its rows' history cannot be read.
7
+ HABTM_REASON: ::String
8
+
6
9
  # The class a `belongs_to` points at for this record, reading a polymorphic
7
10
  # type column when there is one. Nil when the record points at nothing.
8
11
  # : (untyped, untyped) -> untyped
9
12
  def self.belongs_to_target: (untyped, untyped) -> untyped
10
13
 
14
+ # Whether an unordered has_one through reads the target of its first
15
+ # join row. SQL Server plans the join from the target's table instead, so
16
+ # its LIMIT reads the target with the lowest key, as a plain has_one does.
17
+ # : (untyped) -> bool
18
+ def self.join_order?: (untyped) -> bool
19
+
11
20
  # A through with `source_type:` reaches only the join records whose type
12
21
  # column names that class, as Active Record's `where(type => source_type)`.
13
22
  # A through's `foreign_type` is its polymorphic source's.
@@ -36,37 +45,33 @@ module PaperTrailDiff
36
45
  # : (untyped, untyped) -> untyped
37
46
  def self.stored_target: (untyped, untyped) -> untyped
38
47
 
48
+ # The type an `as:` child stores for its owner. Active Record reads only
49
+ # this one, its owner's polymorphic name, which an STI subclass shares
50
+ # with its base class; a child typed with a subclass's name is no member.
51
+ # The declaring class shares the owner's base class, so it names it.
52
+ # : (untyped) -> String
53
+ def self.owner_type: (untyped) -> String
54
+
39
55
  # A type left by a renamed or removed model names no class. Active Record
40
56
  # and PT-AT raise a bare NameError for it, which does not say where it is.
41
57
  # : (untyped, untyped, String) -> untyped
42
58
  def self.polymorphic_target: (untyped, untyped, String) -> untyped
43
59
 
60
+ # : (untyped, untyped, untyped, untyped) -> bot
61
+ def self.unnamed_target!: (untyped, untyped, untyped, untyped) -> bot
62
+
44
63
  # Why a request cannot name this association of the model, or nil when it
45
- # can; `root` says whether the model is the record the request compares.
46
- # Discovery lists only the associations this accepts, so every path it
47
- # lists can be requested. A has_many :through Active Record cannot follow
48
- # raises Active Record's own error.
49
- # : (untyped, untyped, root: bool) -> String?
50
- def self.unsupported_reason: (untyped, untyped, root: bool) -> String?
51
-
52
- # History matches records by primary key, within one set of version tables.
64
+ # can. Discovery lists only the associations this accepts, so every path
65
+ # it lists can be requested. A has_many :through Active Record cannot
66
+ # follow raises Active Record's own error.
67
+ # : (untyped, untyped) -> String?
68
+ def self.unsupported_reason: (untyped, untyped) -> String?
69
+
70
+ # History matches records by primary key, within one set of version
71
+ # tables, and finds a child's owner where the child's versions recorded it.
53
72
  # : (untyped) -> String?
54
73
  def self.storage_reason: (untyped) -> String?
55
74
 
56
- # PT-AT records a HABTM's membership only when its owner saves a version,
57
- # in rows keyed by transaction and association name, not by owner. A root
58
- # checkpoint so holds the root's membership and no one else's: another
59
- # record's HABTM would read the root's rows, or none.
60
- # : (untyped) -> String
61
- def self.habtm_below_root: (untyped) -> String
62
-
63
- # PT-AT records a HABTM's membership by loading the association, scope and
64
- # target default scope applied, so a target outside the scope when the
65
- # owner saved is never recorded. One that enters it before the next save
66
- # is a member then that history cannot hold.
67
- # : (untyped, bool) -> String?
68
- def self.habtm_reason: (untyped, bool) -> String?
69
-
70
75
  # : (untyped, untyped) -> bool
71
76
  def self.paper_trail_versions?: (untyped, untyped) -> bool
72
77
 
@@ -95,6 +100,13 @@ module PaperTrailDiff
95
100
  # : (AssociationTree) -> void
96
101
  def initialize: (AssociationTree) -> void
97
102
 
103
+ # Where the earliest transaction open at `start` began, in the version
104
+ # tables of the model and of the records on its paths; nil when none was
105
+ # open, without a start, or without paths (see CrossingTransactions). A
106
+ # call reads every root of a model from one answer, so it is asked once.
107
+ # : (untyped, untyped) -> untyped
108
+ def reach_before: (untyped, untyped) -> untyped
109
+
98
110
  # : (untyped) -> void
99
111
  def validate!: (untyped) -> void
100
112
 
@@ -104,25 +116,17 @@ module PaperTrailDiff
104
116
  # The names the versions of the records on the requested paths are stored
105
117
  # under: each association's class and every part a through passes. A
106
118
  # polymorphic belongs_to names its target's class only in each record, so
107
- # it adds none.
119
+ # it adds none (see #polymorphic_paths?).
108
120
  # : (untyped) -> Array[String]
109
121
  def path_types: (untyped) -> Array[String]
110
122
 
111
- # : (untyped, untyped) -> void
112
- def ensure_habtm_history!: (untyped, untyped) -> void
113
-
114
- # Every snapshot of a version asks, so each class's answer is kept; the
115
- # tree and the class decide it. Reading it again each time answers the
116
- # same, which is why mutant leaves the cache alone.
117
- # mutant:disable
118
- # : (untyped) -> Array[String]
119
- def habtm_paths: (untyped) -> Array[String]
123
+ # Whether a path passes a polymorphic belongs_to, whose targets may be of
124
+ # any class.
125
+ # : (untyped) -> bool
126
+ def polymorphic_paths?: (untyped) -> bool
120
127
 
121
- # HABTM join rows have no versions of their own, so membership changes
122
- # cannot be split into events once a range runs past the last root version
123
- # into live state.
124
- # : (untyped) -> void
125
- def reject_live_habtm_activity!: (untyped) -> void
128
+ # : (untyped) -> Array[untyped]
129
+ def path_parts: (untyped) -> Array[untyped]
126
130
 
127
131
  # A model and a tree resolve to the same reflections wherever they are
128
132
  # read: a tree is only ever walked from one place, the root tree at the
@@ -139,8 +143,6 @@ module PaperTrailDiff
139
143
 
140
144
  private
141
145
 
142
- @habtm_paths: Hash[untyped, Array[String]]
143
-
144
146
  @reflection_cache: Hash[AssociationTree, Hash[untyped, Array[untyped]]]
145
147
 
146
148
  @tree: AssociationTree
@@ -159,10 +161,7 @@ module PaperTrailDiff
159
161
  # : (untyped, AssociationTree, String) -> Array[untyped]
160
162
  def requested_reflections: (untyped, AssociationTree, String) -> Array[untyped]
161
163
 
162
- # : (untyped, String, String, root: bool) -> untyped
163
- def resolve_reflection: (untyped, String, String, root: bool) -> untyped
164
-
165
- # : (untyped) -> bool
166
- def habtm_reflection?: (untyped) -> bool
164
+ # : (untyped, String, String) -> untyped
165
+ def resolve_reflection: (untyped, String, String) -> untyped
167
166
  end
168
167
  end
@@ -5,8 +5,6 @@ module PaperTrailDiff
5
5
  # of a model class. Left to the caller this is a per-root lookup, which
6
6
  # reintroduces exactly the queries a batched comparison exists to remove.
7
7
  class BatchBoundaryResolver
8
- BOUNDARIES: untyped
9
-
10
8
  # : (untyped) -> bool
11
9
  def self.symbolic?: (untyped) -> bool
12
10
 
@@ -3,45 +3,68 @@
3
3
  module PaperTrailDiff
4
4
  # Prepares the association history of a batch's roots, once per model class
5
5
  # across every version the batch replays, then analyzes each root from its
6
- # plan over its own window. AnalysisBatch and DeletedAnalysisBatch differ
7
- # only in how they find their roots and plans.
6
+ # plan over the batch's window. AnalysisBatch and DeletedAnalysisBatch
7
+ # differ only in how they find their roots and plans.
8
8
  class BatchedRootAnalyses
9
- # A root whose window moved to the start of a transaction crossing its
10
- # edge has its window in `windows`; the others take `time_range`.
11
- # : (time_range: TimeRange?, windows: Hash[Array[String], TimeRange], history_preparer: untyped, analyzer: untyped) -> void
12
- def initialize: (time_range: TimeRange?, windows: Hash[Array[String], TimeRange], history_preparer: untyped, analyzer: untyped) -> void
9
+ # `planner` selects the roots' plans over a window. On associations, a
10
+ # window's history is read from where the earliest transaction open at
11
+ # its start began. With `activity`, the roots are planned from there too,
12
+ # and each reports the transactions that end inside the window (see
13
+ # TransactionEnds). Without it each root version is reported where it
14
+ # was saved, so the roots are planned over the window as it is. `reach`
15
+ # answers where that transaction began, for a model and a window's start
16
+ # (see AssociationTraversal#reach_before).
17
+ # : (time_range: TimeRange?, planner: untyped, history_preparer: untyped, analyzer: untyped, activity: bool, reach: untyped) -> void
18
+ def initialize: (time_range: TimeRange?, planner: untyped, history_preparer: untyped, analyzer: untyped, activity: bool, reach: untyped) -> void
13
19
 
14
20
  # Preparation reads the roots' current association state as a fallback,
15
21
  # so a batch that has already loaded them passes them as `loaded`, rather
16
22
  # than have preparation walk that state one root at a time.
17
- # : (Array[untyped], Hash[Array[String], RootVersionPlan], ?loaded: Hash[Array[String], untyped]) -> Hash[Array[String], Analysis]
18
- def call: (Array[untyped], Hash[Array[String], RootVersionPlan], ?loaded: Hash[Array[String], untyped]) -> Hash[Array[String], Analysis]
23
+ # : (Array[untyped], ?loaded: Hash[Array[String], untyped]) -> Hash[Array[String], Analysis]
24
+ def call: (Array[untyped], ?loaded: Hash[Array[String], untyped]) -> Hash[Array[String], Analysis]
19
25
 
20
26
  private
21
27
 
28
+ @activity: bool
29
+
22
30
  @analyzer: untyped
23
31
 
24
32
  @history_preparer: untyped
25
33
 
34
+ @planner: untyped
35
+
36
+ @reach: untyped
37
+
26
38
  @time_range: TimeRange?
27
39
 
28
- @windows: Hash[Array[String], TimeRange]
40
+ # The plans the roots are read with: over the window, or with activity
41
+ # from where the earliest transaction open at its start began. The
42
+ # history is read from there either way.
43
+ # : (Array[untyped], Hash[Array[String], untyped]) -> Hash[Array[String], RootVersionPlan]
44
+ def prepare: (Array[untyped], Hash[Array[String], untyped]) -> Hash[Array[String], RootVersionPlan]
45
+
46
+ # : (untyped, TimeRange) -> TimeRange
47
+ def widened: (untyped, TimeRange) -> TimeRange
29
48
 
30
49
  # Roots that close on their current state are prepared even without a
31
50
  # version in the window, since their descendants may have changed there.
32
- # : (Array[untyped], Hash[Array[String], RootVersionPlan], Hash[Array[String], untyped]) -> void
33
- def prepare: (Array[untyped], Hash[Array[String], RootVersionPlan], Hash[Array[String], untyped]) -> void
51
+ # : (Array[untyped], Hash[Array[String], RootVersionPlan], Hash[Array[String], untyped], TimeRange?) -> void
52
+ def prepare_history: (Array[untyped], Hash[Array[String], RootVersionPlan], Hash[Array[String], untyped], TimeRange?) -> void
53
+
54
+ # Each root as the batch loaded it, where it did.
55
+ # : (Array[untyped], Hash[Array[String], untyped]) -> Array[untyped]
56
+ def current: (Array[untyped], Hash[Array[String], untyped]) -> Array[untyped]
34
57
 
35
58
  # A plan closing on the live record reads history up to now; the others
36
- # stop at the window's end or at the last version they replay past it, so
37
- # a past window does not load everything since.
38
- # : (Array[untyped], live: bool) -> Hash[Symbol, untyped]
39
- def preparation_range: (Array[untyped], live: bool) -> Hash[Symbol, untyped]
59
+ # stop at the window's end or where the transactions of the versions they
60
+ # replay past it end, so a past window does not load everything since.
61
+ # : (Array[untyped], TimeRange?, live: bool) -> Hash[Symbol, untyped]
62
+ def preparation_range: (Array[untyped], TimeRange?, live: bool) -> Hash[Symbol, untyped]
40
63
 
41
64
  # A root with no versions in range has nothing to report, which is an
42
65
  # empty result rather than a failed request -- unless it closes on its
43
66
  # current state, where its descendants may still have moved.
44
- # : (untyped, RootVersionPlan, TimeRange?) -> Analysis
45
- def analysis: (untyped, RootVersionPlan, TimeRange?) -> Analysis
67
+ # : (untyped, RootVersionPlan) -> Analysis
68
+ def analysis: (untyped, RootVersionPlan) -> Analysis
46
69
  end
47
70
  end
@@ -9,8 +9,8 @@ module PaperTrailDiff
9
9
  # : (timeline_snapshotter: untyped, activity_snapshotter: untyped, preparer: untyped, activity: bool, view: ActivityView, traversal: AssociationTraversal) -> void
10
10
  def initialize: (timeline_snapshotter: untyped, activity_snapshotter: untyped, preparer: untyped, activity: bool, view: ActivityView, traversal: AssociationTraversal) -> void
11
11
 
12
- # `window` is the root's window as the batch moved it to transaction edges,
13
- # or nil when the batch reads each root's whole history.
12
+ # `window` is the batch's window, or nil when it reads each root's whole
13
+ # history.
14
14
  # : (untyped, RootVersionPlan, TimeRange?) -> Analysis
15
15
  def call: (untyped, RootVersionPlan, TimeRange?) -> Analysis
16
16
 
@@ -6,8 +6,8 @@ module PaperTrailDiff
6
6
  # every root are supported: a shared wall-clock window, or each root's own
7
7
  # whole history.
8
8
  class BatchedRootVersions
9
- # : (Array[untyped], time_range: TimeRange?, version_scope: untyped, live_endpoints: Hash[Array[String], untyped]?, context_required: bool, whole: bool, windows: Hash[Array[String], TimeRange]) -> void
10
- def initialize: (Array[untyped], time_range: TimeRange?, version_scope: untyped, live_endpoints: Hash[Array[String], untyped]?, context_required: bool, whole: bool, windows: Hash[Array[String], TimeRange]) -> void
9
+ # : (Array[untyped], time_range: TimeRange?, version_scope: untyped, live_endpoints: Hash[Array[String], untyped]?, context_required: bool, whole: bool) -> void
10
+ def initialize: (Array[untyped], time_range: TimeRange?, version_scope: untyped, live_endpoints: Hash[Array[String], untyped]?, context_required: bool, whole: bool) -> void
11
11
 
12
12
  # Returns a plan per record identity.
13
13
  # : () -> Hash[Array[String], RootVersionPlan]
@@ -27,22 +27,13 @@ module PaperTrailDiff
27
27
 
28
28
  @whole: bool
29
29
 
30
- @windows: Hash[Array[String], TimeRange]
31
-
32
30
  # Each statement reads the versions of 500 roots.
33
31
  # : (untyped, Array[untyped], Hash[Array[String], RootVersionPlan]) -> void
34
32
  def select_model: (untyped, Array[untyped], Hash[Array[String], RootVersionPlan]) -> void
35
33
 
36
- # Each root's own versions, and the first after its window (see OwnWindow).
37
- # : (Array[String], String, Hash[String, Array[untyped]], Hash[String, untyped]) -> [Array[untyped], untyped]
38
- def own_window: (Array[String], String, Hash[String, Array[untyped]], Hash[String, untyped]) -> [ Array[untyped], untyped ]
39
-
40
34
  # : (untyped, Array[untyped]) -> [Hash[String, Array[untyped]], Set[untyped]?, Hash[String, untyped]]
41
35
  def model_versions: (untyped, Array[untyped]) -> [ Hash[String, Array[untyped]], Set[untyped]?, Hash[String, untyped] ]
42
36
 
43
- # : (Array[untyped]) -> TimeRange?
44
- def widest_range: (Array[untyped]) -> TimeRange?
45
-
46
37
  # : (Array[untyped], untyped, Set[untyped]?, untyped) -> RootVersionPlan
47
38
  def versions_for: (Array[untyped], untyped, Set[untyped]?, untyped) -> RootVersionPlan
48
39
 
@@ -3,8 +3,8 @@
3
3
  module PaperTrailDiff
4
4
  # Reconstructs selected root branches and merges them into a prior immutable snapshot.
5
5
  class BranchSnapshotRefresher
6
- # : (ignore_policy: IgnorePolicy, traversal: AssociationTraversal, pool: SnapshotPool, normalizer: SnapshotNormalizer, full_snapshotter: untyped, partial_snapshotter: untyped, association_reader: untyped, record_transition: untyped, ?prepared_record_after: untyped, ?root_state: untyped) -> void
7
- def initialize: (ignore_policy: IgnorePolicy, traversal: AssociationTraversal, pool: SnapshotPool, normalizer: SnapshotNormalizer, full_snapshotter: untyped, partial_snapshotter: untyped, association_reader: untyped, record_transition: untyped, ?prepared_record_after: untyped, ?root_state: untyped) -> void
6
+ # : (ignore_policy: IgnorePolicy, traversal: AssociationTraversal, pool: SnapshotPool, normalizer: SnapshotNormalizer, full_snapshotter: untyped, partial_snapshotter: untyped, member_snapshot: untyped, record_transition: untyped, ?prepared_record_after: untyped, ?root_state: untyped) -> void
7
+ def initialize: (ignore_policy: IgnorePolicy, traversal: AssociationTraversal, pool: SnapshotPool, normalizer: SnapshotNormalizer, full_snapshotter: untyped, partial_snapshotter: untyped, member_snapshot: untyped, record_transition: untyped, ?prepared_record_after: untyped, ?root_state: untyped) -> void
8
8
 
9
9
  # Without associations there is no prepared history, so nothing but the
10
10
  # version's own record could say what it left, and that misses a change
@@ -16,8 +16,18 @@ module PaperTrailDiff
16
16
  # : (untyped, untyped, RecordSnapshot?, Array[String], ?event: ActivityEvent?, ?isolated: bool) -> RecordSnapshot?
17
17
  def call: (untyped, untyped, RecordSnapshot?, Array[String], ?event: ActivityEvent?, ?isolated: bool) -> RecordSnapshot?
18
18
 
19
+ # The snapshot after a transaction that saved several records: each of
20
+ # its events applied in turn to the record it saved, as an event alone in
21
+ # its transaction is. Where one cannot be applied that way, the
22
+ # transaction's branches are read again instead, or the whole snapshot
23
+ # when the root is among the records it saved (`branches` is nil).
24
+ # : (untyped, untyped, RecordSnapshot, Array[String]?, Array[ActivityEvent]) -> RecordSnapshot?
25
+ def apply_transaction: (untyped, untyped, RecordSnapshot, Array[String]?, Array[ActivityEvent]) -> RecordSnapshot?
26
+
19
27
  private
20
28
 
29
+ @applier: ActivityTransactionApplier
30
+
21
31
  @components: Hash[Array[String], [ AssociationTree, SnapshotNormalizer ]]
22
32
 
23
33
  @event_refresher: ActivityEventSnapshotRefresher
@@ -36,12 +46,6 @@ module PaperTrailDiff
36
46
 
37
47
  @tree: AssociationTree
38
48
 
39
- # A root version's HABTM members include any created earlier in its
40
- # transaction. A range ending at that version leaves those creations out
41
- # as events, so the branch is read again there, whatever event led to it.
42
- # : (untyped, untyped, Array[String]) -> Array[String]
43
- def with_habtm: (untyped, untyped, Array[String]) -> Array[String]
44
-
45
49
  # : (untyped, untyped, RecordSnapshot, Array[String], ActivityEvent) -> RecordSnapshot?
46
50
  def refresh_independent_branches: (untyped, untyped, RecordSnapshot, Array[String], ActivityEvent) -> RecordSnapshot?
47
51
 
@@ -0,0 +1,97 @@
1
+ # Generated from lib/paper_trail_diff/candidate_table.rb with RBS::Inline
2
+
3
+ module PaperTrailDiff
4
+ # Holds a selection's candidate ids where every page of the selection can
5
+ # join them, so that no page lists them.
6
+ #
7
+ # Each page of a plucked selection repeats its candidates, and SQL Server
8
+ # compiles a statement with its values written in afresh: with 10,000 ids a
9
+ # page took about 0.7 s, and with 20,000 a page could outlast the adapter's
10
+ # default timeout. On SQL Server, a long list is written once into a
11
+ # temporary table, and each page selects from it instead. Other databases
12
+ # take the list as before: they parse it quickly, and the table would cost
13
+ # them statements of their own.
14
+ #
15
+ # Active Record counts the table's statements as writes, so a read that
16
+ # prevents writes, as a replica read through Rails' automatic role switching
17
+ # does, takes the list instead.
18
+ #
19
+ # A temporary table belongs to the connection that made it, so the block runs
20
+ # on one connection, and the table is dropped when it returns or raises,
21
+ # even when filling it is what failed. A
22
+ # reconnect inside the block, as Active Record makes to retry a read after
23
+ # losing the connection, loses the table, and the read then fails naming it.
24
+ module CandidateTable
25
+ # More ids than this go to a table: one statement's worth, as the gem
26
+ # lists elsewhere, compiles quickly.
27
+ THRESHOLD: Integer
28
+
29
+ # SQL Server inserts at most 1,000 rows in one VALUES list.
30
+ ROWS_PER_INSERT: ::Integer
31
+
32
+ # Yields the ids as they were given, or, on SQL Server with more than
33
+ # THRESHOLD of them, a relation that selects them from a table, which a
34
+ # condition such as `where(id: ...)` reads as a subquery.
35
+ # : [T] (untyped, Array[String]) { (untyped) -> T } -> T
36
+ def self.with: [T] (untyped, Array[String]) { (untyped) -> T } -> T
37
+
38
+ # Yields the subqueries as they were given, or, on SQL Server, one
39
+ # relation that selects their ids from a table each fills in turn.
40
+ #
41
+ # A page that matches its rows against several subqueries joined by OR
42
+ # has SQL Server plan them as one statement: with 1,600 orders and the
43
+ # subqueries for their line items, it ran a line items' subquery again
44
+ # for each order and took about 38 s, though each subquery alone took
45
+ # under 0.2 s. Filled one statement at a time, each subquery runs once,
46
+ # and every page then reads one keyed table. The ids stay in the
47
+ # database, so a busy window costs no list in Ruby.
48
+ # : [T] (untyped, Array[untyped]) { (Array[untyped]) -> T } -> T
49
+ def self.union: [T] (untyped, Array[untyped]) { (Array[untyped]) -> T } -> T
50
+
51
+ # : (untyped) -> bool
52
+ def self.table?: (untyped) -> bool
53
+
54
+ # The table is dropped even when making or filling it is what failed.
55
+ # : [T] (untyped, untyped) { (String) -> T } -> T
56
+ def self.temporary: [T] (untyped, untyped) { (String) -> T } -> T
57
+
58
+ # A condition such as `where(id: ...)` reads this as a subquery.
59
+ # : (untyped, String) -> untyped
60
+ def self.selection: (untyped, String) -> untyped
61
+
62
+ # The column takes the key's type and collation, so that comparing the two
63
+ # neither converts every row nor meets tempdb's collation.
64
+ # : (untyped, untyped, String) -> void
65
+ def self.create: (untyped, untyped, String) -> void
66
+
67
+ # : (untyped, untyped, String, Array[String]) -> void
68
+ def self.insert_values: (untyped, untyped, String, Array[String]) -> void
69
+
70
+ # : (untyped, String, untyped) -> void
71
+ def self.insert_selected: (untyped, String, untyped) -> void
72
+
73
+ # The source selects one column. An id already in the table, or none, is
74
+ # left out, so the key holds each once.
75
+ #
76
+ # The statement starts with WITH rather than INSERT. The adapter reads the
77
+ # table of every statement that starts with INSERT from the catalog, to
78
+ # learn whether it has an identity column. For a temporary table that is a
79
+ # query on tempdb's catalog, which another report's DROP TABLE can hold
80
+ # locks on: two reports at the same time deadlocked there, and SQL Server
81
+ # killed one of them.
82
+ # : (untyped, String, String) -> void
83
+ def self.insert: (untyped, String, String) -> void
84
+
85
+ # The table can be gone already: a timeout that cost the connection,
86
+ # which Active Record then reconnected, takes it along. A failed drop is
87
+ # not raised, so that the error that ended the block is the one the caller
88
+ # sees; a table left behind goes when its connection closes.
89
+ # : (untyped, String) -> void
90
+ def self.drop: (untyped, String) -> void
91
+
92
+ # The adapter writes an integer type with its size in bytes, as
93
+ # `bigint(8)`, which SQL Server does not accept back.
94
+ # : (untyped) -> String
95
+ def self.column_type: (untyped) -> String
96
+ end
97
+ end
@@ -11,9 +11,10 @@ module PaperTrailDiff
11
11
  # recorded of it: each run of recorded changes is credited to the version
12
12
  # that ended it, or the whole change to the last of the record's versions
13
13
  # when what they recorded was not read. A record that appeared or
14
- # disappeared is credited to its own create or destroy. Any other row keeps
15
- # the step's source: a record that joined a collection or became a to-one
16
- # target through another record's change, for one.
14
+ # disappeared is credited to its own create or destroy, or else to the
15
+ # last of its versions there, as a record that moved by its own update.
16
+ # Any other row keeps the step's source: a record that joined a collection
17
+ # or became a to-one target through another record's change, for one.
17
18
  #
18
19
  # With recorded changes read, the part of a field's change that those
19
20
  # versions did not record is split off and credited to an unversioned
@@ -25,9 +26,7 @@ module PaperTrailDiff
25
26
  # - a version that recorded nothing, such as a `touch`, or a table without
26
27
  # `object_changes`;
27
28
  # - a column PaperTrail is told not to record (see RecordedColumns);
28
- # - a field a create left out, which held its default when created;
29
- # - the start of a transaction that began before the history's start (see
30
- # PreparedHistoryLoader#reload), whose earlier versions were not read.
29
+ # - a field a create left out, which held its default when created.
31
30
  class ChangeAttribution
32
31
  # A transaction's boundaries, in the order the history kept them. Every
33
32
  # step the transaction opens shares the one list and reads the boundaries
@@ -68,11 +67,9 @@ module PaperTrailDiff
68
67
 
69
68
  # `root` is the record the timeline is about, which rows name by leaving
70
69
  # `record` nil. `transaction` holds the boundaries of the step's
71
- # transaction, of which the first `preceding` came before its sources;
72
- # `complete` says whether the history holds every version that
73
- # transaction saved before them.
74
- # : (root: RecordReference, sources: Array[ActivityBoundary], complete: bool, transaction: Transaction, ?preceding: Integer) -> void
75
- def initialize: (root: RecordReference, sources: Array[ActivityBoundary], complete: bool, transaction: Transaction, ?preceding: Integer) -> void
70
+ # transaction, of which the first `preceding` came before its sources.
71
+ # : (root: RecordReference, sources: Array[ActivityBoundary], transaction: Transaction, ?preceding: Integer) -> void
72
+ def initialize: (root: RecordReference, sources: Array[ActivityBoundary], transaction: Transaction, ?preceding: Integer) -> void
76
73
 
77
74
  # The same transaction, read through a transaction group's sources.
78
75
  # : (Array[ActivityBoundary]) -> ChangeAttribution
@@ -85,8 +82,6 @@ module PaperTrailDiff
85
82
 
86
83
  private
87
84
 
88
- @complete: bool
89
-
90
85
  @preceding: Integer
91
86
 
92
87
  @root: RecordReference
@@ -100,9 +95,7 @@ module PaperTrailDiff
100
95
  # A field's change follows what the record's versions recorded of it,
101
96
  # from the value the row starts at (see #relevant): each run of recorded
102
97
  # changes is one row, credited to the version that ended it, and a value
103
- # that moved where they do not meet was saved without a version. Where
104
- # the row's start leads to no version, the move to the first of them is
105
- # told apart only when the history holds the whole transaction.
98
+ # that moved where they do not meet was saved without a version.
106
99
  # : (ChangeRow, Array[ActivityBoundary]) -> Array[ChangeRow]
107
100
  def changed: (ChangeRow, Array[ActivityBoundary]) -> Array[ChangeRow]
108
101
 
@@ -1,29 +1,49 @@
1
1
  # Generated from lib/paper_trail_diff/collection_identity_index.rb with RBS::Inline
2
2
 
3
3
  module PaperTrailDiff
4
- # Immutable positions for one collection membership and ordering.
4
+ # Finds records in a collection held in type, then ID, order, as an
5
+ # association snapshot holds its records, by searching that order. A table
6
+ # of every record's position would be built again for each event that
7
+ # changed who is in the collection, which made a replay's time grow with
8
+ # its events times the collection's size.
5
9
  class CollectionIdentityIndex
6
- # : (Array[untyped]) -> void
7
- def initialize: (Array[untyped]) -> void
10
+ # A search builds a sort key for each record it looks at, so a collection
11
+ # of up to this many records is quicker to read through. Most nested
12
+ # collections are that small, and a tree is looked through for each event.
13
+ READ_THROUGH: ::Integer
8
14
 
9
- # : (String, untyped) -> Integer?
10
- def position: (String, untyped) -> Integer?
15
+ # : (Array[RecordSnapshot]) -> void
16
+ def initialize: (Array[RecordSnapshot]) -> void
11
17
 
18
+ # Ids match by their text: a version's item_id can arrive as a string
19
+ # where the record's id is an integer. The first match in the order is
20
+ # the one found, however it is looked for.
21
+ # : (untyped, untyped) -> Integer?
22
+ def position: (untyped, untyped) -> Integer?
23
+
24
+ # The position of the only record with this id, whatever its type.
12
25
  # : (untyped) -> Integer?
13
26
  def position_for_id: (untyped) -> Integer?
14
27
 
15
- private
28
+ # Where a record of this type and id is, or would be put to keep the order.
29
+ # : (untyped, untyped) -> Integer
30
+ def insertion: (untyped, untyped) -> Integer
16
31
 
17
- @id_positions: Hash[String, Integer?]
32
+ private
18
33
 
19
- @identities: Set[Array[untyped]]
34
+ @records: Array[RecordSnapshot]
20
35
 
21
- @serialized_positions: Hash[Array[String], Integer]
36
+ # : (RecordSnapshot, String, String) -> bool
37
+ def match?: (RecordSnapshot, String, String) -> bool
22
38
 
23
- # : (untyped, Integer) -> void
24
- def register: (untyped, Integer) -> void
39
+ # The values an id of this text may be held as, the number first, as
40
+ # records sort a number before the string that prints like it. Text that
41
+ # reads as no number gives nil, which no record found by text matches.
42
+ # : (String) -> Array[untyped]
43
+ def forms: (String) -> Array[untyped]
25
44
 
26
- # : (untyped, Integer) -> void
27
- def register_id: (untyped, Integer) -> void
45
+ # Each type the collection holds, found by searching for where the next begins.
46
+ # : () { (String) -> void } -> void
47
+ def each_type: () { (String) -> void } -> void
28
48
  end
29
49
  end
@@ -7,7 +7,7 @@ module PaperTrailDiff
7
7
 
8
8
  attr_reader after: RecordSnapshot?
9
9
 
10
- # The origin is recorded by serial rather than by reference, because
10
+ # The origin is recorded by its serial rather than by reference, because
11
11
  # holding it would retain every earlier snapshot at the same path for the
12
12
  # whole timeline.
13
13
  # : (from: AssociationSnapshot, before: RecordSnapshot?, after: RecordSnapshot?) -> void
@@ -16,6 +16,6 @@ module PaperTrailDiff
16
16
  # : (AssociationSnapshot) -> bool
17
17
  def from?: (AssociationSnapshot) -> bool
18
18
 
19
- @from_serial: Integer
19
+ @from_serial: Object
20
20
  end
21
21
  end
@@ -64,6 +64,11 @@ module PaperTrailDiff
64
64
  # that later moved to another owner. Such roots are prepared from identity
65
65
  # alone, like deleted ones. Their history still reads the live rows it
66
66
  # needs: a record's current row is its state after its last version.
67
+ #
68
+ # A root's versions share one history, which spans both: a root whose
69
+ # STI class changed between them is prepared as the class of the later.
70
+ # Prepared apart, each history would begin at its own version, and the
71
+ # earlier would miss what changed below the root before the later.
67
72
  # : (Array[untyped]) -> void
68
73
  def prepare_version_roots!: (Array[untyped]) -> void
69
74
 
@@ -0,0 +1,48 @@
1
+ # Generated from lib/paper_trail_diff/database_time.rb with RBS::Inline
2
+
3
+ module PaperTrailDiff
4
+ # Reads a date, or text, given for a datetime column as the database keeps
5
+ # it: in Active Record's default time zone, not Time.zone.
6
+ #
7
+ # Active Record leaves a date assigned to a datetime column on the instance
8
+ # as it was given when time zone aware attributes are off, or when
9
+ # `update_columns` writes it, and PaperTrail stores it from there. The
10
+ # database keeps midnight in its own zone, and `where` sends text or a date
11
+ # to the database as it is. Read through the attribute instead, a date
12
+ # would be midnight in Time.zone, or not a time at all.
13
+ module DatabaseTime
14
+ # A date as JSON writes one, with no time.
15
+ DATE_TEXT: ::Regexp
16
+
17
+ # The same date in stored text: YAML writes it as a bare value at the
18
+ # end of its line, JSON as quoted text.
19
+ STORED_DATE: ::Regexp
20
+
21
+ # A stored value of a datetime column, with a date in it read as
22
+ # midnight where the database keeps it. A change's values are a pair.
23
+ # : (untyped) -> untyped
24
+ def self.stored: (untyped) -> untyped
25
+
26
+ # A date or text given for a datetime column, as the database reads it
27
+ # when `where` sends it: in its own time zone, unless the text names its
28
+ # offset. Anything else, and text that names no time, is returned as it
29
+ # is.
30
+ # : (untyped) -> untyped
31
+ def self.cast: (untyped) -> untyped
32
+
33
+ # Whether a version's stored attributes hold a date with no time for a
34
+ # model with a datetime column, which only then is read again.
35
+ # : (untyped, untyped) -> bool
36
+ def self.stored_date?: (untyped, untyped) -> bool
37
+
38
+ # A Date; the packaged signatures name only core types.
39
+ # : (untyped) -> Time
40
+ def self.midnight: (untyped) -> Time
41
+
42
+ # : () -> bool
43
+ def self.local?: () -> bool
44
+
45
+ # : (String) -> untyped
46
+ def self.written_date: (String) -> untyped
47
+ end
48
+ end