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
@@ -0,0 +1,80 @@
1
+ # Generated from lib/paper_trail_diff/transaction_anchors.rb with RBS::Inline
2
+
3
+ module PaperTrailDiff
4
+ # Tells apart transactions that share a number.
5
+ #
6
+ # PaperTrail numbers a transaction by the id of the first version it saved,
7
+ # in whichever version table that was, and writes the number on every
8
+ # version the transaction saves, in any table. Two tables count their ids
9
+ # apart, so a transaction that began in one can take the number of another
10
+ # that began elsewhere, and a table then holds versions of both under one
11
+ # number. Read by number alone, a window that starts inside the later one
12
+ # is read from where the earlier one began, which can be years before.
13
+ #
14
+ # The version a transaction saved first carries its own id as its number:
15
+ # its anchor, saved when the transaction began. Two versions of one number
16
+ # on either side of an instant belong to one transaction only when no
17
+ # anchor of that number lies between either of them and the instant.
18
+ #
19
+ # Only the version classes loaded when a history is read are known, so one
20
+ # that nothing has loaded yet is not consulted, nor is one in another
21
+ # database, whose table a statement here cannot read. An anchor that was
22
+ # pruned separates nothing, and two transactions of one number that ran at
23
+ # the same time are not told apart.
24
+ module TransactionAnchors
25
+ # A condition on versions of `table` that keeps those no anchor separates
26
+ # from the start. Nothing when the model's version table is the only one,
27
+ # where a number names one transaction.
28
+ # : (untyped, Time, ?untyped) -> untyped
29
+ def self.unbroken: (untyped, Time, ?untyped) -> untyped
30
+
31
+ # `relation` narrowed to the versions no anchor separates from the start.
32
+ # : (untyped, untyped, Time) -> untyped
33
+ def self.scope: (untyped, untyped, Time) -> untyped
34
+
35
+ # `relation` narrowed to the versions of the transactions that these
36
+ # versions (or the versions of these ids), saved after the start, belong
37
+ # to: of a number's versions before the start, those of the transaction
38
+ # that went on to save one of these.
39
+ # : (untyped, untyped, Time, Array[untyped]) -> untyped
40
+ def self.continued: (untyped, untyped, Time, Array[untyped]) -> untyped
41
+
42
+ # Those of the numbers that more than one transaction took: each the id
43
+ # of the first version of a transaction in more than one version table.
44
+ # None when the model's version table is the only one.
45
+ # : (untyped, Array[untyped]) -> Array[untyped]
46
+ def self.shared: (untyped, Array[untyped]) -> Array[untyped]
47
+
48
+ # The ids among these of the versions that began a transaction.
49
+ # : (untyped, Array[untyped]) -> Array[untyped]
50
+ def self.first_ids: (untyped, Array[untyped]) -> Array[untyped]
51
+
52
+ # The version classes whose ids can number a transaction of this one's
53
+ # versions, one for each table, in the order of their tables' names.
54
+ # : (untyped) -> Array[untyped]
55
+ def self.version_classes: (untyped) -> Array[untyped]
56
+
57
+ # Whether the candidate's ids number transactions the version class can
58
+ # read here: a version table in the same database, with ids of the type
59
+ # the number is kept as.
60
+ # : (untyped, untyped, untyped) -> bool
61
+ def self.numbers?: (untyped, untyped, untyped) -> bool
62
+
63
+ # No anchor of the version's number between the version and the start:
64
+ # none after a version saved before the start and before the start, and
65
+ # none after the start and up to a version saved after it, which the
66
+ # version's own anchor is when its transaction began there.
67
+ # : (untyped, Integer, Time, untyped) -> untyped
68
+ def self.none: (untyped, Integer, Time, untyped) -> untyped
69
+
70
+ # A version that carries its own id as its number, which is the number
71
+ # of the version of `table`.
72
+ # : (untyped, String, untyped) -> untyped
73
+ def self.numbering: (untyped, String, untyped) -> untyped
74
+
75
+ # An anchor saved after the version and before the start, or after the
76
+ # start and no later than the version.
77
+ # : (untyped, untyped, Time) -> untyped
78
+ def self.between: (untyped, untyped, Time) -> untyped
79
+ end
80
+ end
@@ -1,185 +1,52 @@
1
1
  # Generated from lib/paper_trail_diff/transaction_cut.rb with RBS::Inline
2
2
 
3
3
  module PaperTrailDiff
4
- # Moves each edge of a wall-clock window that falls inside one of a root's
5
- # transactions back to where that transaction began, so the transaction is
6
- # wholly in the later window.
4
+ # Answers where a range of versions really starts: where the transactions
5
+ # of its roots' first versions began (`range_start`).
7
6
  #
8
7
  # PT-AT reads a root's associations at the start of the transaction of the
9
- # root version it reifies. A window starting just after a child saved its
10
- # part of such a transaction therefore starts from the state before that
11
- # child's change, and one ending there ends at it too, so the change belonged
12
- # to no window and surfaced at the next transaction, under its author.
13
- #
14
- # Only the root's own versions on either side of an edge are consulted:
15
- # rows locked by an update keep two transactions of one root from
16
- # interleaving, so a transaction holding a root version and crossing the edge
17
- # holds the root's nearest version on one side of it. One that saved the root
18
- # after the edge moves it. One that saved the root only before the edge moves
19
- # it only when it saved a record of a type on the requested paths after it,
20
- # which the root's history reads: without one, the root's change is in the
21
- # earlier window, where its version is, as selecting by a window's versions
22
- # finds it, and ScopedRootSelection selects the roots such a move brings into
23
- # a window. Each edge is moved from where it was asked for, never from where
24
- # another edge moved, so adjacent windows move their shared edge alike.
8
+ # root version it reifies, so a range that starts at a version starts
9
+ # before whatever that version's transaction saved earlier. A wall-clock
10
+ # window does not move: it reports the transactions that end inside it
11
+ # (see TransactionEnds and CrossingTransactions).
25
12
  module TransactionCut
26
- # One edge of a window. A strict edge keeps versions recorded at its
27
- # instant on the left, as an inclusive end does. A plain class rather than
28
- # Data.define, which arrived in Ruby 3.2 while this gem supports 3.1.
29
- class Edge
30
- # A window's start, which keeps versions recorded at it on the right.
31
- # : (TimeRange) -> Edge
32
- def self.start_of: (TimeRange) -> Edge
33
-
34
- # A window's end, strict when the window includes it; an endless window
35
- # has none.
36
- # : (TimeRange) -> Edge?
37
- def self.end_of: (TimeRange) -> Edge?
38
-
39
- # : (Time, bool) -> void
40
- def initialize: (Time, bool) -> void
41
-
42
- # : (untyped) -> untyped
43
- def left: (untyped) -> untyped
44
-
45
- # : (untyped) -> untyped
46
- def right: (untyped) -> untyped
47
-
48
- @strict: bool
49
-
50
- @time: Time
51
- end
52
-
53
- # The same as `windows` for a batch of roots, keyed by identity.
54
- # : (Array[untyped], TimeRange?, ?traversal: AssociationTraversal?) -> Hash[Array[String], TimeRange]
55
- def self.batch_windows: (Array[untyped], TimeRange?, ?traversal: AssociationTraversal?) -> Hash[Array[String], TimeRange]
56
-
57
- # Where history for a batch must be read from: the earliest moved start.
58
- # : (TimeRange?, Hash[Array[String], TimeRange]) -> Time?
59
- def self.earliest_start: (TimeRange?, Hash[Array[String], TimeRange]) -> Time?
60
-
61
- # The windows that move, keyed by root id. A root missing from the result
62
- # keeps the window as asked. `traversal` names the requested paths.
63
- # `records` may be ids. Each move is reported unless `report` is false,
64
- # for a reader that looks before the analysis that reports them.
65
- # : (untyped, Array[untyped], TimeRange, ?traversal: AssociationTraversal?, ?report: bool) -> Hash[String, TimeRange]
66
- def self.windows: (untyped, Array[untyped], TimeRange, ?traversal: AssociationTraversal?, ?report: bool) -> Hash[String, TimeRange]
67
-
68
- # Reads the windows of `model_class` ids for a range, unreported.
69
- # : (untyped, AssociationTraversal?) -> ^(Array[String], TimeRange) -> Hash[String, TimeRange]
70
- def self.reader: (untyped, AssociationTraversal?) -> ^(Array[String], TimeRange) -> Hash[String, TimeRange]
71
-
72
- # A transaction holds its rows only while it runs, so in history as an
73
- # application saves it an edge moves by moments. A longer move means a
74
- # long transaction or rewritten times, which only the application can
75
- # judge, so each move is reported rather than logged or refused.
76
- # : (untyped, String, TimeRange, TimeRange) -> void
77
- def self.report_move: (untyped, String, TimeRange, TimeRange) -> void
78
-
79
- # The model's versions in a window, and those saved before it in a
80
- # transaction that saved a record of one of `types` inside it, which
81
- # moves their root's window back to take them in: the versions that
82
- # select a root for the window. Without a window, every version does.
83
- # : (untyped, TimeRange?, Array[String]) -> untyped
84
- def self.window_versions: (untyped, TimeRange?, Array[String]) -> untyped
85
-
86
- # : (untyped, untyped, TimeRange, Array[String]) -> untyped
87
- def self.crossing_versions: (untyped, untyped, TimeRange, Array[String]) -> untyped
88
-
13
+ # A range starting at a version starts before that version's transaction,
14
+ # as PT-AT reads associations there. A version saved earlier in the same
15
+ # transaction, such as the child update behind a `touch: true` parent
16
+ # version, can be recorded before the start, so the start moves back to
17
+ # where each root's first transaction in the range began. History loaded
18
+ # from the start alone would read that child after its change.
19
+ # : (Array[untyped], untyped) -> untyped
20
+ def self.range_start: (Array[untyped], untyped) -> untyped
21
+
22
+ # The range then reads as a window from there would (see TransactionEnds):
23
+ # a transaction open where it starts takes effect where it ends, so what
24
+ # it saved before is read from where it began, in the version tables of
25
+ # the model and its paths.
26
+ # : (untyped, AssociationTraversal, untyped) -> untyped
27
+ def self.crossing_start: (untyped, AssociationTraversal, untyped) -> untyped
28
+
29
+ # A range that ends at a version ends where that version's transaction
30
+ # takes effect, at the last version it saved (see TransactionEnds), so
31
+ # what another transaction saved and committed before then is read, and
32
+ # a destroyed root's tree is read up to its destruction.
89
33
  # : (untyped) -> untyped
90
- def self.transaction_versions: (untyped) -> untyped
91
-
92
- # : (untyped) -> bool
93
- def self.transactional?: (untyped) -> bool
94
-
95
- # Each root's earliest start among its transactions that cross the edge:
96
- # the one that saved its first version after the edge, which crosses when
97
- # it began before it, and the one that saved its last version before it,
98
- # which crosses when it saved a record of one of `types` after it.
99
- # : (untyped, Array[untyped], Edge, Array[String]) -> Hash[String, Time]
100
- def self.moved_edges: (untyped, Array[untyped], Edge, Array[String]) -> Hash[String, Time]
101
-
102
- # For each side of the edge, the roots its transactions hold next to the
103
- # edge, and where those that cross it began.
104
- # : (untyped, Array[untyped], Edge, Array[String]) -> Array[[Hash[untyped, Array[String]], Hash[untyped, Time]]]
105
- def self.crossing: (untyped, Array[untyped], Edge, Array[String]) -> Array[[ Hash[untyped, Array[String]], Hash[untyped, Time] ]]
106
-
107
- # The roots whose versions next to the edge each transaction holds, those
108
- # after the edge and those before it.
109
- # : (untyped, Array[untyped], Edge) -> [Hash[untyped, Array[String]], Hash[untyped, Array[String]]]
110
- def self.nearest_roots: (untyped, Array[untyped], Edge) -> [ Hash[untyped, Array[String]], Hash[untyped, Array[String]] ]
111
-
112
- # The roots of the rows, by the transaction each row names.
113
- # : (Array[[String, untyped, bool]]) -> Hash[untyped, Array[String]]
114
- def self.by_transaction: (Array[[ String, untyped, bool ]]) -> Hash[untyped, Array[String]]
115
-
116
- # Each root's nearest versions on either side of an edge, as [id,
117
- # transaction, after the edge] rows; versions tied at the nearest instant
118
- # are all kept. One statement per slice: a grouped pass over the roots'
119
- # versions finds both instants, and a join reads the versions saved at
120
- # either. A lookup per root, joined by UNION ALL, took SQL Server about a
121
- # second per 200 roots to compile. Rows read without a model come back as
122
- # the adapter returns them, so the transaction is cast as the grouped
123
- # query's keys are.
124
- #
125
- # The ids go to the adapter as bound parameters. Written into the
126
- # statement, they made each slice's text new to SQL Server, which compiled
127
- # it again, at about 0.05 ms per id.
128
- # : (untyped, Array[untyped], Edge) -> Array[[String, untyped, bool]]
129
- def self.nearest: (untyped, Array[untyped], Edge) -> Array[[ String, untyped, bool ]]
130
-
131
- # The roots' versions saved in a transaction at either nearest instant,
132
- # each with whether it is the one after the edge.
133
- # : (untyped, Array[untyped], Edge) -> untyped
134
- def self.nearest_query: (untyped, Array[untyped], Edge) -> untyped
135
-
136
- # 1 for a version saved at the instant after the edge, 0 for one before.
137
- # Only the 1 is read (see after_edge?), so another value or alias, or none,
138
- # answers the same.
139
- # mutant:disable
140
- # : (untyped, untyped) -> untyped
141
- def self.after_edge: (untyped, untyped) -> untyped
142
-
143
- # Whether after_edge flagged a row as saved after the edge. Adapters
144
- # return the flag as an Integer or a String, so any spelling that reads
145
- # only 1 as after answers the same.
146
- # mutant:disable
147
- # : (untyped) -> bool
148
- def self.after_edge?: (untyped) -> bool
149
-
150
- # Each root's latest instant before the edge and earliest after it, from
151
- # every version, saved in a transaction or not.
152
- # : (untyped, Edge) -> untyped
153
- def self.nearest_instants: (untyped, Edge) -> untyped
154
-
155
- # The latest or earliest of the times on one side of the edge.
156
- # : (untyped, untyped, untyped) -> untyped
157
- def self.side_instant: (untyped, untyped, untyped) -> untyped
158
-
159
- # The same root's versions saved at either of its instants.
160
- # : (untyped, untyped) -> untyped
161
- def self.at_either: (untyped, untyped) -> untyped
162
-
163
- # Where each transaction that saved a version before the edge began; with
164
- # `types`, only one that also saved a record of one of them after it.
165
- # : (untyped, Array[untyped], Edge, ?Array[String]?) -> Hash[untyped, Time]
166
- def self.crossing_starts: (untyped, Array[untyped], Edge, ?Array[String]?) -> Hash[untyped, Time]
167
-
168
- # Those of the transactions that saved a version of a record of one of
169
- # `types` on the edge's later side. A subquery apart from the outer one,
170
- # rather than an EXISTS correlated with it, so the database finds them
171
- # once by transaction: SQLite answered the correlated form by scanning
172
- # every later version of the types for each version before the edge, with
173
- # the README's indexes 17 s for 450 transactions on 114,000 versions.
174
- # Only the outer query's transactions are read, so the database can find
175
- # them by transaction rather than read every later version of the types;
176
- # the outer query keeps only those anyway, so no spec can tell the
177
- # mutation that drops them apart.
178
- # mutant:disable
179
- # : (untyped, Array[untyped], Edge, Array[String]) -> untyped
180
- def self.saved_later: (untyped, Array[untyped], Edge, Array[String]) -> untyped
181
-
182
- # : (TimeRange, Time?, Time?) -> TimeRange
183
- def self.moved: (TimeRange, Time?, Time?) -> TimeRange
34
+ def self.range_end: (untyped) -> untyped
35
+
36
+ # When ranges ending at these versions all end (see range_end): the
37
+ # latest time any of their transactions takes effect; nil for none.
38
+ # : (Array[untyped]) -> untyped
39
+ def self.ends_at: (Array[untyped]) -> untyped
40
+
41
+ # Each root's first version at or after the start, where a transaction
42
+ # saved it.
43
+ # : (Array[untyped], untyped) -> Array[untyped]
44
+ def self.opening_versions: (Array[untyped], untyped) -> Array[untyped]
45
+
46
+ # When the earliest of the transactions of these versions began. Of
47
+ # transactions that share a number, only the one each version is in
48
+ # counts (see TransactionAnchors).
49
+ # : (Array[untyped], untyped) -> untyped
50
+ def self.transaction_start: (Array[untyped], untyped) -> untyped
184
51
  end
185
52
  end
@@ -0,0 +1,124 @@
1
+ # Generated from lib/paper_trail_diff/transaction_ends.rb with RBS::Inline
2
+
3
+ module PaperTrailDiff
4
+ # Where each transaction of a root's timeline takes effect: at the last
5
+ # version it saved, of any record, as `recorded` holds it (see
6
+ # RecordedTransactionEnds), or among the timeline's own versions where a
7
+ # number is shared (see TransactionAnchors). A root read without its
8
+ # associations is read without them: its versions take effect where they
9
+ # were saved, since row locks keep two transactions from interleaving the
10
+ # versions of one record.
11
+ #
12
+ # Two transactions that save in one tree at the same time interleave their
13
+ # versions, yet neither sees what the other has not committed, and one may
14
+ # undo its own changes before it ends, such as a comment it created and
15
+ # deleted again. Rows locked by a write keep two open transactions from
16
+ # saving one record, so wherever the order of two transactions matters, the
17
+ # one that saved its last version first also ended first. A timeline that
18
+ # places every version of a transaction at its last one therefore reads the
19
+ # transactions one after another, as if none had overlapped: a record reads
20
+ # as it stood before every transaction that had not ended yet, and each
21
+ # change is reported with its own transaction's.
22
+ #
23
+ # A version saved outside a transaction takes effect where it was saved.
24
+ #
25
+ # Every history, of a window or of a range of versions, is read from where
26
+ # the transactions open at its start began (see PreparedHistoryLoader), so
27
+ # what a root reports does not depend on what else a batch read with it.
28
+ class TransactionEnds
29
+ # : (Array[untyped], ?Hash[Array[untyped], untyped]?) -> void
30
+ def initialize: (Array[untyped], ?Hash[Array[untyped], untyped]?) -> void
31
+
32
+ # The last of the versions of each transaction, and of those outside one,
33
+ # by transaction key.
34
+ # : (Array[untyped]) -> Hash[Array[untyped]?, untyped]
35
+ def self.lasts: (Array[untyped]) -> Hash[Array[untyped]?, untyped]
36
+
37
+ # The last version of the version's transaction, or the version itself.
38
+ # : (untyped) -> untyped
39
+ def last: (untyped) -> untyped
40
+
41
+ # Where a boundary takes effect, and when: at the last version of a
42
+ # version's transaction, or where a live record was read, since no
43
+ # transaction is keyed by a model that is not a version class. Every
44
+ # record of a snapshot is read at one boundary, so the last answer is
45
+ # kept.
46
+ # : (untyped) -> [untyped, untyped]
47
+ def target: (untyped) -> [ untyped, untyped ]
48
+
49
+ # Orders versions by where their transactions end, then as they were
50
+ # saved.
51
+ # : (untyped) -> Array[untyped]
52
+ def sort_key: (untyped) -> Array[untyped]
53
+
54
+ @held: Array[untyped]
55
+
56
+ @last: Hash[Array[untyped]?, untyped]
57
+
58
+ @recorded: Hash[Array[untyped], untyped]?
59
+ end
60
+
61
+ # Reads where transactions end from their version tables: the last version
62
+ # each saved there, of any record.
63
+ #
64
+ # A transaction can go on to save a record a timeline does not hold, such
65
+ # as one it moved out of the tree, and which records a timeline holds
66
+ # depends on where it is read from. Were a transaction placed at the last
67
+ # of the versions held, two windows could place it differently, and what it
68
+ # did would be reported in neither or in both.
69
+ #
70
+ # The versions held are asked about together, a statement for 500
71
+ # transactions, and one more for those whose last version is not held.
72
+ # The last version is the latest dated, ids breaking a tie, as every
73
+ # window compares versions by date: a callback that saves other records
74
+ # before its own version dates that one first, as its save began. A number
75
+ # that transactions of two version tables took is not read (see
76
+ # TransactionAnchors), and its versions are placed at the last held.
77
+ class RecordedTransactionEnds
78
+ # : () -> void
79
+ def initialize: () -> void
80
+
81
+ # The last version of each transaction asked about so far, by transaction
82
+ # key, once those of `versions` are among them. They are asked about along
83
+ # with every version the block returns, so that a history is read at once.
84
+ # A version saved outside a transaction is read beside the history's
85
+ # others, wherever their transactions end, so it asks about them all; a
86
+ # live record asks nothing.
87
+ # : (Array[untyped]) { () -> Array[untyped] } -> Hash[Array[untyped], untyped]
88
+ def call: (Array[untyped]) { () -> Array[untyped] } -> Hash[Array[untyped], untyped]
89
+
90
+ private
91
+
92
+ @asked: Set[Array[untyped]]
93
+
94
+ @ends: Hash[Array[untyped], untyped]
95
+
96
+ # : (untyped) -> bool
97
+ def answered?: (untyped) -> bool
98
+
99
+ # : (untyped) -> bool
100
+ def asked?: (untyped) -> bool
101
+
102
+ # : (Array[untyped]) -> void
103
+ def ask: (Array[untyped]) -> void
104
+
105
+ # Notes the last version of each of these transactions: the one held
106
+ # where it is, and the one read otherwise.
107
+ # : (untyped, Array[untyped], Hash[untyped, Array[untyped]]) -> void
108
+ def read: (untyped, Array[untyped], Hash[untyped, Array[untyped]]) -> void
109
+
110
+ # The id of each transaction's last version: of those dated latest, the
111
+ # one versions sort last by id.
112
+ # : (untyped, Array[untyped]) -> Hash[untyped, untyped]
113
+ def latest: (untyped, Array[untyped]) -> Hash[untyped, untyped]
114
+
115
+ # When the transaction of a version of `table` saved its latest dated.
116
+ # : (untyped) -> untyped
117
+ def newest: (untyped) -> untyped
118
+
119
+ # The last versions not held, read only for what places them. With
120
+ # none missing, the relation reads nothing.
121
+ # : (untyped, Hash[untyped, untyped], Hash[untyped, Array[untyped]]) -> Array[untyped]
122
+ def other: (untyped, Hash[untyped, untyped], Hash[untyped, Array[untyped]]) -> Array[untyped]
123
+ end
124
+ end
@@ -34,8 +34,8 @@ module PaperTrailDiff
34
34
  # : (untyped) -> Array[untyped]
35
35
  def self.through_models: (untyped) -> Array[untyped]
36
36
 
37
- # : (traversal: AssociationTraversal, ?allow_approximate: bool) -> void
38
- def initialize: (traversal: AssociationTraversal, ?allow_approximate: bool) -> void
37
+ # : (traversal: AssociationTraversal) -> void
38
+ def initialize: (traversal: AssociationTraversal) -> void
39
39
 
40
40
  # : (untyped, historical: bool) -> void
41
41
  def call: (untyped, historical: bool) -> void
@@ -48,8 +48,6 @@ module PaperTrailDiff
48
48
 
49
49
  private
50
50
 
51
- @allow_approximate: bool
52
-
53
51
  @refusals: Hash[Array[untyped], Array[Refusal]]
54
52
 
55
53
  @traversal: AssociationTraversal
@@ -62,14 +60,11 @@ module PaperTrailDiff
62
60
  # : (untyped) -> Refusal?
63
61
  def traversal_refusal: (untyped) -> Refusal?
64
62
 
65
- # A path prepared history cannot read is read with PT-AT, which rebuilds
66
- # an association from its current members, swapping in older versions of
67
- # them. A record that entered the association since, such as one moved
68
- # into a scope or restored from a soft delete, then reads as a member it
69
- # was not, and one that left reads as missing. Only a caller who accepts
70
- # that may read such a path.
63
+ # History tells who was in an association at a past point by testing each
64
+ # record's stored values against its scope, so it reads only a scope made
65
+ # of plain conditions on the target's own columns.
71
66
  # : (untyped) -> Array[Refusal]
72
- def approximate_refusals: (untyped) -> Array[Refusal]
67
+ def unreadable_refusals: (untyped) -> Array[Refusal]
73
68
 
74
69
  # A model PaperTrail never versioned has no history to reconstruct, so a
75
70
  # comparison over it can only ever answer "nothing changed" -- which is a
@@ -1,18 +1,17 @@
1
- # Generated from lib/paper_trail_diff/approximate_paths.rb with RBS::Inline
1
+ # Generated from lib/paper_trail_diff/unreadable_paths.rb with RBS::Inline
2
2
 
3
3
  module PaperTrailDiff
4
- # The requested paths prepared history cannot read exactly, each with why.
5
- # PT-AT reads such a path instead, one record at a time, when the caller
6
- # passes `allow_approximate: true`.
7
- module ApproximatePaths
4
+ # The requested paths history cannot read, each with why: who was in one
5
+ # at a past point cannot be told, so a request that reads history refuses it.
6
+ module UnreadablePaths
8
7
  # : (AssociationTraversal, untyped) -> Array[[String, String]]
9
8
  def self.call: (AssociationTraversal, untyped) -> Array[[ String, String ]]
10
9
 
11
10
  # A has_many through reads its parts' conditions only, at any depth. A
12
11
  # has_one through over a ranked part is refused whole, so its parts, too,
13
12
  # are checked for conditions alone.
14
- # : (untyped, ranked: bool) -> String?
15
- def self.fallback_reason: (untyped, ranked: bool) -> String?
13
+ # : (untyped) -> String?
14
+ def self.path_reason: (untyped) -> String?
16
15
 
17
16
  # A scope prepared history can read as conditions on stored attributes
18
17
  # is batched like any other path. A polymorphic target's class, and so
@@ -46,7 +46,8 @@ module PaperTrailDiff
46
46
 
47
47
  # Elements of `left` with no counterpart left in `right`, matching by value
48
48
  # and respecting duplicates, so ["a", "a"] -> ["a"] reports one removal
49
- # rather than none.
49
+ # rather than none. Each element is counted rather than searched for, so
50
+ # the work grows with the arrays' length, not its square.
50
51
  # : (Array[untyped], Array[untyped]) -> Array[untyped]
51
52
  def self.surplus: (Array[untyped], Array[untyped]) -> Array[untyped]
52
53
 
@@ -55,7 +56,8 @@ module PaperTrailDiff
55
56
  # : () -> bool
56
57
  def reordered?: () -> bool
57
58
 
58
- # The same elements in the same order, with keys read as strings.
59
+ # The same elements in the same order, with keys read as strings and
60
+ # every NaN alike.
59
61
  # : () -> bool
60
62
  def empty?: () -> bool
61
63
 
@@ -23,11 +23,17 @@ module PaperTrailDiff
23
23
  # A version saved before the start names the state there unless a later
24
24
  # one saved before the start replaced it. PT-AT stores the keys a version
25
25
  # saved, and a start inside a transaction reads each record as it stood
26
- # before the transaction, so a later version that the record's
27
- # transaction across the start saved before it replaced nothing yet.
28
- # Without the version before it, a record that this transaction moved
29
- # away is not found, nor is the transaction (see
30
- # PreparedHistoryLoader#reload).
26
+ # before the transaction, so a later version that a transaction across
27
+ # the start saved before it replaced nothing yet. Without the version
28
+ # before it, a record that this transaction moved away is not found, nor
29
+ # is the transaction (see CrossingTransactions).
30
+ #
31
+ # The transaction crosses the start by a version of any record, not only
32
+ # of this one: one that moved a comment away before the start and saved
33
+ # only the comment's reply after it is found by the reply, which hangs
34
+ # under the comment as it stood before. A transaction that went on to
35
+ # save nothing in the tree brings a candidate the history loads and no
36
+ # snapshot holds (see PreparedActivityIndex#eligible_version?).
31
37
  # : (untyped) -> String
32
38
  def condition_sql: (untyped) -> String
33
39
 
@@ -13,20 +13,6 @@ module PaperTrailDiff
13
13
  # : (untyped, untyped, ?time: untyped, ?boundary_time: untyped) -> bool
14
14
  def self.at_or_after?: (untyped, untyped, ?time: untyped, ?boundary_time: untyped) -> bool
15
15
 
16
- # A range starting at a version starts before that version's transaction,
17
- # as PT-AT reads associations there. A version saved earlier in the same
18
- # transaction, such as the child update behind a `touch: true` parent
19
- # version, can be recorded before the start, so the start moves back to
20
- # the earliest version of each root's first transaction in the range.
21
- # History loaded from the start alone would read that child after its
22
- # change. The transactions go 500 to a statement.
23
- # : (Array[untyped], untyped) -> untyped
24
- def self.transaction_start: (Array[untyped], untyped) -> untyped
25
-
26
- # The transaction of each root's first version at or after the start.
27
- # : (Array[untyped], untyped) -> Array[untyped]
28
- def self.opening_transactions: (Array[untyped], untyped) -> Array[untyped]
29
-
30
16
  # A custom version class need not carry the column, and PaperTrail leaves
31
17
  # it nil outside a transaction. Both read as "no transaction here", which
32
18
  # groups with nothing.
@@ -20,6 +20,13 @@ module PaperTrailDiff
20
20
  # : (untyped, untyped) -> untyped
21
21
  def self.for_items: (untyped, untyped) -> untyped
22
22
 
23
+ # The versions of the version's item saved after it, ids breaking a tie.
24
+ # : (untyped, untyped) -> untyped
25
+ def self.after: (untyped, untyped) -> untyped
26
+
27
+ # : (untyped) -> untyped
28
+ def self.later_id: (untyped) -> untyped
29
+
23
30
  # Keeps each item's earliest version among those the block also accepts:
24
31
  # no other version of the same item that the block accepts is earlier. A
25
32
  # correlated NOT EXISTS stays portable where window functions are not.
@@ -31,6 +38,19 @@ module PaperTrailDiff
31
38
  # : (untyped) { (untyped) -> untyped } -> untyped
32
39
  def self.exists: (untyped) { (untyped) -> untyped } -> untyped
33
40
 
41
+ # Whether the item's versions say it was created after `time`: a create
42
+ # saved after it that no version of the item precedes. An item with an
43
+ # earlier version was there before, whatever created it again, and one
44
+ # with no create may have been.
45
+ # : (untyped, untyped, untyped, untyped) -> untyped
46
+ def self.created_after: (untyped, untyped, untyped, untyped) -> untyped
47
+
48
+ # : (untyped, untyped, untyped) -> untyped
49
+ def self.first_create_after: (untyped, untyped, untyped) -> untyped
50
+
51
+ # : (untyped, untyped) -> untyped
52
+ def self.any: (untyped, untyped) -> untyped
53
+
34
54
  # : (untyped, untyped) ?{ (untyped) -> untyped } -> untyped
35
55
  def self.earlier_version: (untyped, untyped) ?{ (untyped) -> untyped } -> untyped
36
56
 
@@ -40,5 +60,11 @@ module PaperTrailDiff
40
60
  # mutant:disable
41
61
  # : (untyped) -> untyped
42
62
  def self.other_versions: (untyped) -> untyped
63
+
64
+ # The version table under a name of its own for `created_after`, beside
65
+ # `other_versions`. As for that, no spec can tell its mutations apart.
66
+ # mutant:disable
67
+ # : (untyped) -> untyped
68
+ def self.created_versions: (untyped) -> untyped
43
69
  end
44
70
  end
@@ -6,9 +6,35 @@ module PaperTrailDiff
6
6
  # caller, because the one that reveals the last selected mutation is drawn
7
7
  # from them.
8
8
  class VersionScopeFilter
9
- # A filter is a callable that narrows the version relation.
9
+ # The filter, checked once where it is given: a callable that takes the
10
+ # version relation, and that wherever it is called returns it narrowed,
11
+ # or an array of its versions. A relation on another table would be read
12
+ # for its ids all the same, and choose the versions that happen to share
13
+ # them.
10
14
  # : (untyped) -> untyped
11
- def self.validated: (untyped) -> untyped
15
+ def self.checked: (untyped) -> untyped
16
+
17
+ # A proc that is not a lambda takes any number of arguments.
18
+ # : (untyped) -> bool
19
+ def self.takes_relation?: (untyped) -> bool
20
+
21
+ # : (untyped, untyped) -> untyped
22
+ def self.narrowed: (untyped, untyped) -> untyped
23
+
24
+ # The versions of `relation` that activity on associations reports under
25
+ # the filter (see ActivityScopeFilter): those it keeps, and those of a
26
+ # transaction it keeps a version of, of any record in their table. A
27
+ # table without transactions keeps each version alone.
28
+ # : (untyped, untyped) -> untyped
29
+ def self.whole_transactions: (untyped, untyped) -> untyped
30
+
31
+ # A column of what the filter returned, read in the database where it
32
+ # returned a relation.
33
+ # : (untyped, Symbol) -> untyped
34
+ def self.values: (untyped, Symbol) -> untyped
35
+
36
+ # : (untyped) -> bool
37
+ def self.versions?: (untyped) -> bool
12
38
 
13
39
  # : (untyped) -> void
14
40
  def initialize: (untyped) -> void