paper_trail_diff 0.15.0 → 0.17.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (206) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +724 -1
  3. data/README.md +43 -8
  4. data/docs/architecture.md +7 -5
  5. data/docs/performance.md +89 -32
  6. data/docs/reference.md +427 -96
  7. data/docs/testing.md +260 -32
  8. data/lib/paper_trail_diff/activity_belongs_to_event_applier.rb +2 -16
  9. data/lib/paper_trail_diff/activity_boundary.rb +55 -34
  10. data/lib/paper_trail_diff/activity_child_candidate_loader.rb +46 -57
  11. data/lib/paper_trail_diff/activity_collection_event_applier.rb +33 -11
  12. data/lib/paper_trail_diff/activity_collection_route_updater.rb +1 -1
  13. data/lib/paper_trail_diff/activity_event.rb +33 -21
  14. data/lib/paper_trail_diff/activity_event_record_resolver.rb +16 -116
  15. data/lib/paper_trail_diff/activity_event_route_finder.rb +49 -18
  16. data/lib/paper_trail_diff/activity_event_snapshot_refresher.rb +13 -7
  17. data/lib/paper_trail_diff/activity_history.rb +90 -49
  18. data/lib/paper_trail_diff/activity_range.rb +9 -35
  19. data/lib/paper_trail_diff/activity_root_snapshot_refresher.rb +104 -52
  20. data/lib/paper_trail_diff/activity_root_steps.rb +10 -13
  21. data/lib/paper_trail_diff/activity_scope_filter.rb +77 -0
  22. data/lib/paper_trail_diff/activity_snapshot_delta.rb +12 -15
  23. data/lib/paper_trail_diff/activity_snapshot_sequence.rb +37 -15
  24. data/lib/paper_trail_diff/activity_target_candidate_loader.rb +35 -43
  25. data/lib/paper_trail_diff/activity_timeline_builder.rb +200 -249
  26. data/lib/paper_trail_diff/activity_transaction_grouper.rb +3 -1
  27. data/lib/paper_trail_diff/activity_tree_filter.rb +54 -13
  28. data/lib/paper_trail_diff/activity_version_collector.rb +72 -138
  29. data/lib/paper_trail_diff/activity_view.rb +22 -11
  30. data/lib/paper_trail_diff/analysis.rb +39 -6
  31. data/lib/paper_trail_diff/analysis_batch.rb +16 -58
  32. data/lib/paper_trail_diff/approximate_paths.rb +4 -8
  33. data/lib/paper_trail_diff/association_activity_edge.rb +5 -24
  34. data/lib/paper_trail_diff/association_activity_selection.rb +10 -18
  35. data/lib/paper_trail_diff/association_discovery.rb +1 -6
  36. data/lib/paper_trail_diff/association_key.rb +9 -6
  37. data/lib/paper_trail_diff/association_traversal.rb +49 -6
  38. data/lib/paper_trail_diff/batch_boundary_resolver.rb +33 -42
  39. data/lib/paper_trail_diff/batch_preload.rb +2 -12
  40. data/lib/paper_trail_diff/batched_root_analyses.rb +72 -0
  41. data/lib/paper_trail_diff/batched_root_analyzer.rb +22 -14
  42. data/lib/paper_trail_diff/batched_root_versions.rb +25 -20
  43. data/lib/paper_trail_diff/branch_snapshot_refresher.rb +41 -42
  44. data/lib/paper_trail_diff/change_attribution.rb +314 -0
  45. data/lib/paper_trail_diff/change_row.rb +30 -10
  46. data/lib/paper_trail_diff/comparison_batch.rb +3 -4
  47. data/lib/paper_trail_diff/configuration.rb +1 -1
  48. data/lib/paper_trail_diff/deleted_analysis_batch.rb +22 -33
  49. data/lib/paper_trail_diff/deleted_root_filter.rb +29 -10
  50. data/lib/paper_trail_diff/deprecation.rb +4 -43
  51. data/lib/paper_trail_diff/diagnostics.rb +8 -7
  52. data/lib/paper_trail_diff/direct_record_state_loader.rb +8 -1
  53. data/lib/paper_trail_diff/endpoint.rb +78 -44
  54. data/lib/paper_trail_diff/errors.rb +2 -9
  55. data/lib/paper_trail_diff/fallback_paths.rb +2 -5
  56. data/lib/paper_trail_diff/habtm_transaction_owners.rb +5 -3
  57. data/lib/paper_trail_diff/historical_association_reifier.rb +3 -1
  58. data/lib/paper_trail_diff/historical_filter.rb +40 -15
  59. data/lib/paper_trail_diff/historical_snapshot_store.rb +80 -38
  60. data/lib/paper_trail_diff/instrumentation.rb +0 -8
  61. data/lib/paper_trail_diff/live_endpoint_batch_loader.rb +11 -7
  62. data/lib/paper_trail_diff/live_endpoint_provider.rb +7 -23
  63. data/lib/paper_trail_diff/live_graph_collector.rb +3 -3
  64. data/lib/paper_trail_diff/nested_comparator.rb +46 -19
  65. data/lib/paper_trail_diff/net_change.rb +276 -0
  66. data/lib/paper_trail_diff/own_window.rb +35 -0
  67. data/lib/paper_trail_diff/paper_trail_adapter.rb +119 -87
  68. data/lib/paper_trail_diff/prepared_activity_index.rb +182 -50
  69. data/lib/paper_trail_diff/prepared_child_candidates.rb +58 -0
  70. data/lib/paper_trail_diff/prepared_edge_loader.rb +43 -107
  71. data/lib/paper_trail_diff/prepared_history.rb +31 -36
  72. data/lib/paper_trail_diff/prepared_history_loader.rb +47 -12
  73. data/lib/paper_trail_diff/prepared_record_index.rb +143 -49
  74. data/lib/paper_trail_diff/prepared_snapshot_builder.rb +16 -0
  75. data/lib/paper_trail_diff/prepared_state_association_reader.rb +17 -19
  76. data/lib/paper_trail_diff/read_snapshot.rb +99 -0
  77. data/lib/paper_trail_diff/recorded_changes.rb +10 -11
  78. data/lib/paper_trail_diff/recorded_changes_reader.rb +60 -0
  79. data/lib/paper_trail_diff/recorded_class.rb +14 -19
  80. data/lib/paper_trail_diff/recorded_columns.rb +33 -0
  81. data/lib/paper_trail_diff/root_version_plan.rb +20 -22
  82. data/lib/paper_trail_diff/root_version_selection.rb +39 -29
  83. data/lib/paper_trail_diff/scope_condition.rb +92 -32
  84. data/lib/paper_trail_diff/scope_ranking.rb +27 -34
  85. data/lib/paper_trail_diff/scoped_analysis.rb +27 -4
  86. data/lib/paper_trail_diff/scoped_analysis_builder.rb +18 -7
  87. data/lib/paper_trail_diff/scoped_root_selection.rb +65 -39
  88. data/lib/paper_trail_diff/snapshot_normalizer.rb +18 -3
  89. data/lib/paper_trail_diff/stored_json_values.rb +52 -0
  90. data/lib/paper_trail_diff/stored_time_precision.rb +30 -18
  91. data/lib/paper_trail_diff/stored_values.rb +20 -0
  92. data/lib/paper_trail_diff/support.rb +185 -35
  93. data/lib/paper_trail_diff/time_of_day.rb +39 -0
  94. data/lib/paper_trail_diff/time_range.rb +40 -22
  95. data/lib/paper_trail_diff/time_version_range.rb +5 -10
  96. data/lib/paper_trail_diff/timeline_builder.rb +9 -3
  97. data/lib/paper_trail_diff/timeline_range.rb +18 -12
  98. data/lib/paper_trail_diff/timeline_snapshot_provider.rb +1 -1
  99. data/lib/paper_trail_diff/total_order.rb +55 -0
  100. data/lib/paper_trail_diff/transaction_cut.rb +235 -75
  101. data/lib/paper_trail_diff/traversal_preparer.rb +5 -8
  102. data/lib/paper_trail_diff/value_objects.rb +8 -4
  103. data/lib/paper_trail_diff/version.rb +1 -1
  104. data/lib/paper_trail_diff/version_association_candidate_scope.rb +1 -12
  105. data/lib/paper_trail_diff/version_boundary.rb +41 -23
  106. data/lib/paper_trail_diff/version_query.rb +25 -25
  107. data/lib/paper_trail_diff/version_range.rb +12 -16
  108. data/lib/paper_trail_diff/version_sequence_diagnostics.rb +36 -1
  109. data/lib/paper_trail_diff/version_table.rb +12 -8
  110. data/lib/paper_trail_diff.rb +32 -44
  111. data/sig/generated/paper_trail_diff/activity_belongs_to_event_applier.rbs +0 -8
  112. data/sig/generated/paper_trail_diff/activity_boundary.rbs +39 -17
  113. data/sig/generated/paper_trail_diff/activity_child_candidate_loader.rbs +19 -22
  114. data/sig/generated/paper_trail_diff/activity_collection_event_applier.rbs +13 -5
  115. data/sig/generated/paper_trail_diff/activity_event.rbs +25 -9
  116. data/sig/generated/paper_trail_diff/activity_event_record_resolver.rbs +6 -34
  117. data/sig/generated/paper_trail_diff/activity_event_route_finder.rbs +25 -4
  118. data/sig/generated/paper_trail_diff/activity_event_snapshot_refresher.rbs +6 -3
  119. data/sig/generated/paper_trail_diff/activity_history.rbs +54 -19
  120. data/sig/generated/paper_trail_diff/activity_range.rbs +6 -20
  121. data/sig/generated/paper_trail_diff/activity_root_snapshot_refresher.rbs +55 -10
  122. data/sig/generated/paper_trail_diff/activity_root_steps.rbs +6 -6
  123. data/sig/generated/paper_trail_diff/activity_scope_filter.rbs +51 -0
  124. data/sig/generated/paper_trail_diff/activity_snapshot_delta.rbs +5 -3
  125. data/sig/generated/paper_trail_diff/activity_snapshot_sequence.rbs +21 -3
  126. data/sig/generated/paper_trail_diff/activity_target_candidate_loader.rbs +19 -24
  127. data/sig/generated/paper_trail_diff/activity_timeline_builder.rbs +125 -127
  128. data/sig/generated/paper_trail_diff/activity_tree_filter.rbs +41 -8
  129. data/sig/generated/paper_trail_diff/activity_version_collector.rbs +42 -35
  130. data/sig/generated/paper_trail_diff/activity_view.rbs +16 -8
  131. data/sig/generated/paper_trail_diff/analysis.rbs +26 -5
  132. data/sig/generated/paper_trail_diff/analysis_batch.rbs +6 -24
  133. data/sig/generated/paper_trail_diff/association_activity_edge.rbs +0 -13
  134. data/sig/generated/paper_trail_diff/association_activity_selection.rbs +6 -9
  135. data/sig/generated/paper_trail_diff/association_discovery.rbs +0 -3
  136. data/sig/generated/paper_trail_diff/association_key.rbs +5 -0
  137. data/sig/generated/paper_trail_diff/association_traversal.rbs +26 -2
  138. data/sig/generated/paper_trail_diff/batch_boundary_resolver.rbs +17 -17
  139. data/sig/generated/paper_trail_diff/batch_preload.rbs +0 -4
  140. data/sig/generated/paper_trail_diff/batched_root_analyses.rbs +47 -0
  141. data/sig/generated/paper_trail_diff/batched_root_analyzer.rbs +13 -8
  142. data/sig/generated/paper_trail_diff/batched_root_versions.rbs +10 -6
  143. data/sig/generated/paper_trail_diff/branch_snapshot_refresher.rbs +16 -4
  144. data/sig/generated/paper_trail_diff/change_attribution.rbs +185 -0
  145. data/sig/generated/paper_trail_diff/change_row.rbs +22 -7
  146. data/sig/generated/paper_trail_diff/deleted_analysis_batch.rbs +11 -9
  147. data/sig/generated/paper_trail_diff/deleted_root_filter.rbs +9 -3
  148. data/sig/generated/paper_trail_diff/deprecation.rbs +4 -24
  149. data/sig/generated/paper_trail_diff/direct_record_state_loader.rbs +4 -0
  150. data/sig/generated/paper_trail_diff/endpoint.rbs +40 -16
  151. data/sig/generated/paper_trail_diff/errors.rbs +2 -11
  152. data/sig/generated/paper_trail_diff/habtm_transaction_owners.rbs +2 -1
  153. data/sig/generated/paper_trail_diff/historical_filter.rbs +20 -9
  154. data/sig/generated/paper_trail_diff/historical_snapshot_store.rbs +40 -10
  155. data/sig/generated/paper_trail_diff/instrumentation.rbs +0 -3
  156. data/sig/generated/paper_trail_diff/live_endpoint_batch_loader.rbs +3 -0
  157. data/sig/generated/paper_trail_diff/live_endpoint_provider.rbs +5 -8
  158. data/sig/generated/paper_trail_diff/live_graph_collector.rbs +2 -2
  159. data/sig/generated/paper_trail_diff/nested_comparator.rbs +20 -4
  160. data/sig/generated/paper_trail_diff/net_change.rbs +168 -0
  161. data/sig/generated/paper_trail_diff/own_window.rbs +22 -0
  162. data/sig/generated/paper_trail_diff/paper_trail_adapter.rbs +19 -6
  163. data/sig/generated/paper_trail_diff/prepared_activity_index.rbs +113 -17
  164. data/sig/generated/paper_trail_diff/prepared_child_candidates.rbs +39 -0
  165. data/sig/generated/paper_trail_diff/prepared_edge_loader.rbs +18 -35
  166. data/sig/generated/paper_trail_diff/prepared_history.rbs +15 -13
  167. data/sig/generated/paper_trail_diff/prepared_history_loader.rbs +28 -3
  168. data/sig/generated/paper_trail_diff/prepared_record_index.rbs +70 -15
  169. data/sig/generated/paper_trail_diff/prepared_snapshot_builder.rbs +12 -0
  170. data/sig/generated/paper_trail_diff/prepared_state_association_reader.rbs +6 -7
  171. data/sig/generated/paper_trail_diff/read_snapshot.rbs +62 -0
  172. data/sig/generated/paper_trail_diff/recorded_changes.rbs +4 -2
  173. data/sig/generated/paper_trail_diff/recorded_changes_reader.rbs +41 -0
  174. data/sig/generated/paper_trail_diff/recorded_class.rbs +7 -6
  175. data/sig/generated/paper_trail_diff/recorded_columns.rbs +21 -0
  176. data/sig/generated/paper_trail_diff/root_version_plan.rbs +8 -4
  177. data/sig/generated/paper_trail_diff/root_version_selection.rbs +27 -13
  178. data/sig/generated/paper_trail_diff/scope_condition.rbs +39 -9
  179. data/sig/generated/paper_trail_diff/scope_ranking.rbs +16 -16
  180. data/sig/generated/paper_trail_diff/scoped_analysis.rbs +19 -0
  181. data/sig/generated/paper_trail_diff/scoped_analysis_builder.rbs +9 -2
  182. data/sig/generated/paper_trail_diff/scoped_root_selection.rbs +40 -12
  183. data/sig/generated/paper_trail_diff/snapshot_normalizer.rbs +7 -0
  184. data/sig/generated/paper_trail_diff/stored_json_values.rbs +35 -0
  185. data/sig/generated/paper_trail_diff/stored_time_precision.rbs +19 -5
  186. data/sig/generated/paper_trail_diff/stored_values.rbs +13 -0
  187. data/sig/generated/paper_trail_diff/support.rbs +120 -23
  188. data/sig/generated/paper_trail_diff/time_of_day.rbs +21 -0
  189. data/sig/generated/paper_trail_diff/time_range.rbs +15 -7
  190. data/sig/generated/paper_trail_diff/time_version_range.rbs +2 -5
  191. data/sig/generated/paper_trail_diff/timeline_builder.rbs +6 -2
  192. data/sig/generated/paper_trail_diff/timeline_range.rbs +12 -7
  193. data/sig/generated/paper_trail_diff/total_order.rbs +32 -0
  194. data/sig/generated/paper_trail_diff/transaction_cut.rbs +131 -40
  195. data/sig/generated/paper_trail_diff/traversal_preparer.rbs +2 -2
  196. data/sig/generated/paper_trail_diff/value_objects.rbs +5 -1
  197. data/sig/generated/paper_trail_diff/version_association_candidate_scope.rbs +0 -7
  198. data/sig/generated/paper_trail_diff/version_boundary.rbs +17 -8
  199. data/sig/generated/paper_trail_diff/version_query.rbs +17 -10
  200. data/sig/generated/paper_trail_diff/version_range.rbs +6 -9
  201. data/sig/generated/paper_trail_diff/version_sequence_diagnostics.rbs +16 -0
  202. data/sig/generated/paper_trail_diff/version_table.rbs +3 -0
  203. data/sig/generated/paper_trail_diff.rbs +16 -16
  204. metadata +31 -7
  205. data/lib/paper_trail_diff/preloaded_endpoint_batch_loader.rb +0 -60
  206. data/sig/generated/paper_trail_diff/preloaded_endpoint_batch_loader.rbs +0 -32
@@ -3,9 +3,13 @@
3
3
  module PaperTrailDiff
4
4
  # Reconstructs selected root branches and merges them into a prior immutable snapshot.
5
5
  class BranchSnapshotRefresher
6
- # : (tree: AssociationTree, 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) -> void
7
- def initialize: (tree: AssociationTree, 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) -> void
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
8
8
 
9
+ # Without associations there is no prepared history, so nothing but the
10
+ # version's own record could say what it left, and that misses a change
11
+ # saved after it without a version. A full snapshot reads the next
12
+ # recorded state instead, and with no branches to carry it costs no more.
9
13
  # : (untyped, untyped, RecordSnapshot?, event: ActivityEvent) -> RecordSnapshot?
10
14
  def advance_root: (untyped, untyped, RecordSnapshot?, event: ActivityEvent) -> RecordSnapshot?
11
15
 
@@ -32,12 +36,20 @@ module PaperTrailDiff
32
36
 
33
37
  @tree: AssociationTree
34
38
 
35
- # : (Array[untyped], RecordSnapshot, Array[String], ActivityEvent?, bool) -> [bool, RecordSnapshot?]
36
- def incremental_event: (Array[untyped], RecordSnapshot, Array[String], ActivityEvent?, bool) -> [ bool, RecordSnapshot? ]
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]
37
44
 
38
45
  # : (untyped, untyped, RecordSnapshot, Array[String], ActivityEvent) -> RecordSnapshot?
39
46
  def refresh_independent_branches: (untyped, untyped, RecordSnapshot, Array[String], ActivityEvent) -> RecordSnapshot?
40
47
 
48
+ # The snapshot with these branches read again from history, or a full
49
+ # snapshot when they cannot be read alone.
50
+ # : (untyped, untyped, RecordSnapshot, Array[String]) -> RecordSnapshot?
51
+ def refreshed: (untyped, untyped, RecordSnapshot, Array[String]) -> RecordSnapshot?
52
+
41
53
  # : (untyped, untyped, Array[String]) -> RecordSnapshot?
42
54
  def partial_snapshot: (untyped, untyped, Array[String]) -> RecordSnapshot?
43
55
 
@@ -0,0 +1,185 @@
1
+ # Generated from lib/paper_trail_diff/change_attribution.rb with RBS::Inline
2
+
3
+ module PaperTrailDiff
4
+ # Credits each change row to the version that made its change, which need
5
+ # not be its step's source: a transaction group starts at one record's
6
+ # event, and inside a transaction a record's change can surface at a later
7
+ # event than its own (see ActivityTransactionGrouper).
8
+ #
9
+ # The versions a record saved in the step's transaction, up to the step's
10
+ # last source, made its changes there. A field's change follows what they
11
+ # recorded of it: each run of recorded changes is credited to the version
12
+ # that ended it, or the whole change to the last of the record's versions
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.
17
+ #
18
+ # With recorded changes read, the part of a field's change that those
19
+ # versions did not record is split off and credited to an unversioned
20
+ # source. It was saved without a version, as with `update_columns`, and
21
+ # history reads it into the state the next version stores, or the current
22
+ # row, so it shows up beside the change before it. Only what the versions
23
+ # show is split off. The row stays whole where they cannot:
24
+ #
25
+ # - a version that recorded nothing, such as a `touch`, or a table without
26
+ # `object_changes`;
27
+ # - 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.
31
+ class ChangeAttribution
32
+ # A transaction's boundaries, in the order the history kept them. Every
33
+ # step the transaction opens shares the one list and reads the boundaries
34
+ # before its own sources, so a long transaction costs one list rather
35
+ # than one for each step. A record's boundaries are found through an
36
+ # index, built when rows are first read, once the history is complete.
37
+ # A step's own sources are kept the same way, so a transaction group's
38
+ # rows name each source's record once rather than once for each record.
39
+ class Transaction
40
+ # : (?Array[ActivityBoundary]) -> void
41
+ def initialize: (?Array[ActivityBoundary]) -> void
42
+
43
+ # : (ActivityBoundary) -> void
44
+ def add: (ActivityBoundary) -> void
45
+
46
+ # : () -> Integer
47
+ def length: () -> Integer
48
+
49
+ # The record's boundaries among the first `count`, in order. The block
50
+ # names a boundary's record. The index is built whole before it is
51
+ # kept, so readers on two threads build the same one.
52
+ # : (Array[String], Integer) { (ActivityBoundary) -> Array[String] } -> Array[ActivityBoundary]
53
+ def of: (Array[String], Integer) { (ActivityBoundary) -> Array[String] } -> Array[ActivityBoundary]
54
+
55
+ private
56
+
57
+ @boundaries: Array[ActivityBoundary]
58
+
59
+ @positions: Hash[Array[String], Array[Integer]]?
60
+
61
+ # : (^(ActivityBoundary) -> Array[String]) -> Hash[Array[String], Array[Integer]]
62
+ def index: (^(ActivityBoundary) -> Array[String]) -> Hash[Array[String], Array[Integer]]
63
+ end
64
+
65
+ # `root` is the record the timeline is about, which rows name by leaving
66
+ # `record` nil. `transaction` holds the boundaries of the step's
67
+ # transaction, of which the first `preceding` came before its sources;
68
+ # `complete` says whether the history holds every version that
69
+ # transaction saved before them.
70
+ # : (root: RecordReference, sources: Array[ActivityBoundary], complete: bool, transaction: Transaction, ?preceding: Integer) -> void
71
+ def initialize: (root: RecordReference, sources: Array[ActivityBoundary], complete: bool, transaction: Transaction, ?preceding: Integer) -> void
72
+
73
+ # The same transaction, read through a transaction group's sources.
74
+ # : (Array[ActivityBoundary]) -> ChangeAttribution
75
+ def with_sources: (Array[ActivityBoundary]) -> ChangeAttribution
76
+
77
+ # The row as the rows it splits into, each credited to its change's
78
+ # source: one row, unless part of its change was saved without a version.
79
+ # : (ChangeRow) -> Array[ChangeRow]
80
+ def call: (ChangeRow) -> Array[ChangeRow]
81
+
82
+ private
83
+
84
+ @complete: bool
85
+
86
+ @preceding: Integer
87
+
88
+ @root: RecordReference
89
+
90
+ @sources: Transaction
91
+
92
+ @transaction: Transaction
93
+
94
+ @versions: Hash[Array[String], Array[ActivityBoundary]]
95
+
96
+ # A field's change follows what the record's versions recorded of it,
97
+ # from the value the row starts at (see #relevant): each run of recorded
98
+ # changes is one row, credited to the version that ended it, and a value
99
+ # that moved where they do not meet was saved without a version. Where
100
+ # the row's start leads to no version, the move to the first of them is
101
+ # told apart only when the history holds the whole transaction.
102
+ # : (ChangeRow, Array[ActivityBoundary]) -> Array[ChangeRow]
103
+ def changed: (ChangeRow, Array[ActivityBoundary]) -> Array[ChangeRow]
104
+
105
+ # The changes that make up the row's: from the last one that left the
106
+ # row's starting value; or else those after the last that reached it,
107
+ # which an earlier step reported; or else all of them.
108
+ # : (Array[[ActivityBoundary, ValueChange]], untyped) -> Array[[ActivityBoundary, ValueChange]]
109
+ def relevant: (Array[[ ActivityBoundary, ValueChange ]], untyped) -> Array[[ ActivityBoundary, ValueChange ]]
110
+
111
+ # A field none of the versions recorded changed without one, when they
112
+ # record every change of it they make.
113
+ # : (ChangeRow, Array[ActivityBoundary]) -> Array[ChangeRow]
114
+ def unrecorded: (ChangeRow, Array[ActivityBoundary]) -> Array[ChangeRow]
115
+
116
+ # Only a record's own create says what it was created with. A field the
117
+ # create left out held its default, which no version records, so a value
118
+ # there can be the default or a later write: the row stays whole, or runs
119
+ # from nothing to what the versions after the create recorded.
120
+ # : (ChangeRow, Array[ActivityBoundary]) -> Array[ChangeRow]
121
+ def added: (ChangeRow, Array[ActivityBoundary]) -> Array[ChangeRow]
122
+
123
+ # The value's path from `start` to `finish` as links of [from, to,
124
+ # version], with nil for no version: each recorded change, and between
125
+ # them whatever moved without one. A first change that does not start
126
+ # where the row does joins the row's start unless `trusted`.
127
+ # : (untyped, untyped, Array[[ActivityBoundary, ValueChange]], bool) -> Array[[untyped, untyped, ActivityBoundary?]]
128
+ def chain: (untyped, untyped, Array[[ ActivityBoundary, ValueChange ]], bool) -> Array[[ untyped, untyped, ActivityBoundary? ]]
129
+
130
+ # A move from `value` to `to` that no version recorded, as a link; returns
131
+ # where it ends.
132
+ # : (Array[[untyped, untyped, ActivityBoundary?]], untyped, untyped) -> untyped
133
+ def bridge: (Array[[ untyped, untyped, ActivityBoundary? ]], untyped, untyped) -> untyped
134
+
135
+ # : (untyped, untyped, ActivityBoundary?) -> [untyped, untyped, ActivityBoundary?]
136
+ def link: (untyped, untyped, ActivityBoundary?) -> [ untyped, untyped, ActivityBoundary? ]
137
+
138
+ # Consecutive links of the same kind as one: recorded ones credited to the
139
+ # last of their versions.
140
+ # : (Array[[untyped, untyped, ActivityBoundary?]]) -> Array[[untyped, untyped, ActivityBoundary?]]
141
+ def merge: (Array[[ untyped, untyped, ActivityBoundary? ]]) -> Array[[ untyped, untyped, ActivityBoundary? ]]
142
+
143
+ # The first link keeps the row's own change, so an added field starts
144
+ # from nothing; its later values are changes to it.
145
+ # : (ChangeRow, Array[[untyped, untyped, ActivityBoundary?]], Symbol) -> Array[ChangeRow]
146
+ def rows_for: (ChangeRow, Array[[ untyped, untyped, ActivityBoundary? ]], Symbol) -> Array[ChangeRow]
147
+
148
+ # : (ChangeRow, Array[ActivityBoundary]) -> ChangeRow
149
+ def removed: (ChangeRow, Array[ActivityBoundary]) -> ChangeRow
150
+
151
+ # The changes the versions recorded of a field, each with its version:
152
+ # nil when one of them recorded nothing, or their changes were not read.
153
+ # : (Array[ActivityBoundary], String?) -> Array[[ActivityBoundary, ValueChange]]?
154
+ def recorded_changes: (Array[ActivityBoundary], String?) -> Array[[ ActivityBoundary, ValueChange ]]?
155
+
156
+ # A row about a whole record has no field name, which no version records.
157
+ # : (Array[ActivityBoundary]) -> Array[Hash[untyped, ValueChange]]?
158
+ def recorded: (Array[ActivityBoundary]) -> Array[Hash[untyped, ValueChange]]?
159
+
160
+ # : (ChangeRow) -> bool
161
+ def recorded_column?: (ChangeRow) -> bool
162
+
163
+ # The record's boundaries in the step's transaction, up to its last
164
+ # source, read once for each record.
165
+ # : (RecordReference) -> Array[ActivityBoundary]
166
+ def versions_of: (RecordReference) -> Array[ActivityBoundary]
167
+
168
+ # A record's base class and id, which name its row whichever subclass a
169
+ # snapshot or a version gives.
170
+ # : (RecordReference) -> Array[String]
171
+ def identity: (RecordReference) -> Array[String]
172
+
173
+ # : (String) -> String
174
+ def base_name: (String) -> String
175
+
176
+ # : (ChangeRow) -> ActivityBoundary
177
+ def unversioned: (ChangeRow) -> ActivityBoundary
178
+
179
+ # : (ChangeRow, ActivityBoundary) -> ChangeRow
180
+ def credit: (ChangeRow, ActivityBoundary) -> ChangeRow
181
+
182
+ # : (ChangeRow, source: ActivityBoundary, ?change: Symbol, ?from: untyped, ?to: untyped) -> ChangeRow
183
+ def copy: (ChangeRow, source: ActivityBoundary, ?change: Symbol, ?from: untyped, ?to: untyped) -> ChangeRow
184
+ end
185
+ end
@@ -21,12 +21,22 @@ module PaperTrailDiff
21
21
 
22
22
  attr_reader to: untyped
23
23
 
24
- # The step's source boundary: for a transaction group, its first event.
24
+ # The event that made the change: the version of the row's record that
25
+ # recorded it, or a source of kind `:unversioned` for a change saved
26
+ # without a version. A row the step's own events do not account for, such
27
+ # as a record joining a collection through another record's change, names
28
+ # the step's source boundary.
25
29
  attr_reader source: ActivityBoundary
26
30
 
27
31
  # : (change: Symbol, association_path: Array[String], association_kind: Symbol?, record: RecordReference?, attribute: String?, from: untyped, to: untyped, source: ActivityBoundary) -> void
28
32
  def initialize: (change: Symbol, association_path: Array[String], association_kind: Symbol?, record: RecordReference?, attribute: String?, from: untyped, to: untyped, source: ActivityBoundary) -> void
29
33
 
34
+ # Whether the change was saved without a version, such as with
35
+ # `update_columns`, which PaperTrail never recorded. Only told apart with
36
+ # `recorded_changes: true`.
37
+ # : () -> bool
38
+ def unversioned?: () -> bool
39
+
30
40
  # The source's identifying fields sit beside the change rather than nested,
31
41
  # so the hash is one row of a table as it stands.
32
42
  # : () -> Hash[Symbol, untyped]
@@ -50,23 +60,28 @@ module PaperTrailDiff
50
60
  #
51
61
  # Two kinds of entry add nothing a row would show. One that only groups
52
62
  # others (an edited record, an association, a relationship) is left out,
53
- # because the rows under it name the same record. A blank field of an added
63
+ # because the rows under it name the same record. A nil field of an added
54
64
  # or removed record is left out too, because the record's own row already
55
- # says it appeared or disappeared.
65
+ # says it appeared or disappeared; an empty string or false is a value.
56
66
  class ChangeRows
57
67
  RECORD_ENTRIES: untyped
58
68
 
59
- # : (Diff, source: ActivityBoundary) -> Array[ChangeRow]
60
- def self.call: (Diff, source: ActivityBoundary) -> Array[ChangeRow]
69
+ # `attribution` credits each row to the event that made its change, and
70
+ # can split one in two (see ChangeAttribution); without it, every row is
71
+ # credited to `source`.
72
+ # : (Diff, source: ActivityBoundary, ?attribution: ChangeAttribution?) -> Array[ChangeRow]
73
+ def self.call: (Diff, source: ActivityBoundary, ?attribution: ChangeAttribution?) -> Array[ChangeRow]
61
74
 
62
- # : (ActivityBoundary) -> void
63
- def initialize: (ActivityBoundary) -> void
75
+ # : (ActivityBoundary, ChangeAttribution?) -> void
76
+ def initialize: (ActivityBoundary, ChangeAttribution?) -> void
64
77
 
65
78
  # : (Diff) -> Array[ChangeRow]
66
79
  def call: (Diff) -> Array[ChangeRow]
67
80
 
68
81
  private
69
82
 
83
+ @attribution: ChangeAttribution?
84
+
70
85
  @source: ActivityBoundary
71
86
 
72
87
  # : (TraversalEntry) -> ChangeRow?
@@ -5,8 +5,10 @@ module PaperTrailDiff
5
5
  class DeletedAnalysisBatch
6
6
  # `context_required` reads a root that did not change in the window from
7
7
  # the version after it, so its associations' activity can be reported.
8
- # : (untyped, identities: Array[Array[String]], time_range: TimeRange?, analyzer: untyped, history_preparer: untyped, version_scope: untyped, context_required: bool) -> void
9
- def initialize: (untyped, identities: Array[Array[String]], time_range: TimeRange?, analyzer: untyped, history_preparer: untyped, version_scope: untyped, context_required: bool) -> void
8
+ # `traversal` names the requested paths, which decide where a window's
9
+ # edges move (see TransactionCut).
10
+ # : (untyped, identities: Array[Array[String]], time_range: TimeRange?, analyzer: untyped, history_preparer: untyped, version_scope: untyped, context_required: bool, traversal: AssociationTraversal?) -> void
11
+ def initialize: (untyped, identities: Array[Array[String]], time_range: TimeRange?, analyzer: untyped, history_preparer: untyped, version_scope: untyped, context_required: bool, traversal: AssociationTraversal?) -> void
10
12
 
11
13
  # : () -> Hash[Array[String], Analysis?]
12
14
  def call: () -> Hash[Array[String], Analysis?]
@@ -28,10 +30,15 @@ module PaperTrailDiff
28
30
 
29
31
  @time_range: TimeRange?
30
32
 
33
+ @traversal: AssociationTraversal?
34
+
31
35
  @version_scope: untyped
32
36
 
33
37
  # A root destroyed before the window had no state inside it to read, so
34
- # only the others take the version after the window as context.
38
+ # only the others take the version after the window as context. Every
39
+ # root replays the whole of its window for activity on associations: one
40
+ # whose destroy saved in a transaction that crossed the window's start
41
+ # has the destroy inside its moved window.
35
42
  # : (Array[untyped], Array[untyped], Hash[Array[String], TimeRange]) -> Hash[Array[String], RootVersionPlan]
36
43
  def plans: (Array[untyped], Array[untyped], Hash[Array[String], TimeRange]) -> Hash[Array[String], RootVersionPlan]
37
44
 
@@ -44,13 +51,8 @@ module PaperTrailDiff
44
51
  # : (Array[untyped]) -> Array[untyped]
45
52
  def historical_roots: (Array[untyped]) -> Array[untyped]
46
53
 
54
+ # Each statement reads the destroys of 500 records.
47
55
  # : () -> Array[untyped]
48
56
  def destroy_versions: () -> Array[untyped]
49
-
50
- # : (Array[untyped], Hash[Array[String], TimeRange]) -> Hash[Symbol, untyped]
51
- def preparation_range: (Array[untyped], Hash[Array[String], TimeRange]) -> Hash[Symbol, untyped]
52
-
53
- # : (Array[untyped], Hash[Array[String], RootVersionPlan], Hash[Array[String], TimeRange]) -> void
54
- def prepare: (Array[untyped], Hash[Array[String], RootVersionPlan], Hash[Array[String], TimeRange]) -> void
55
57
  end
56
58
  end
@@ -9,9 +9,13 @@ module PaperTrailDiff
9
9
  # : (untyped) -> void
10
10
  def initialize: (untyped) -> void
11
11
 
12
+ # nil when the relation's conditions cannot be read.
13
+ # : (untyped) -> DeletedRootFilter?
14
+ def self.readable: (untyped) -> DeletedRootFilter?
15
+
12
16
  # A root whose destroy PaperTrail did not record has no state to test
13
- # and stays, as it has no state to report either. One whose destroy
14
- # recorded no state is left out.
17
+ # and stays, as it has no state to report either, unless the relation
18
+ # selects nothing. One whose destroy recorded no state is left out.
15
19
  # : (Array[Array[String]]) -> Array[Array[String]]
16
20
  def call: (Array[Array[String]]) -> Array[Array[String]]
17
21
 
@@ -32,7 +36,9 @@ module PaperTrailDiff
32
36
  # : (Hash[String, untyped]?) -> bool
33
37
  def selected?: (Hash[String, untyped]?) -> bool
34
38
 
35
- # The state each root held before its latest destroy.
39
+ # The state each root held before its latest destroy, read in slices: a
40
+ # report lists every deleted root it reached, and SQL Server cannot plan an
41
+ # IN list of thousands.
36
42
  # : (Array[String]) -> Hash[String, Hash[String, untyped]?]
37
43
  def destroyed_states: (Array[String]) -> Hash[String, Hash[String, untyped]?]
38
44
 
@@ -1,35 +1,15 @@
1
1
  # Generated from lib/paper_trail_diff/deprecation.rb with RBS::Inline
2
2
 
3
3
  module PaperTrailDiff
4
- # Warns about options that do nothing any more and will be removed. In a
5
- # Rails app, register the deprecator to configure it with the app's own:
4
+ # Warns about options that are deprecated and will be removed. None is now,
5
+ # but the deprecator stays, so that an app that registered it still boots
6
+ # and hears of the next one. In a Rails app, register it to configure it
7
+ # with the app's own:
6
8
  #
7
9
  # Rails.application.deprecators[:paper_trail_diff] = PaperTrailDiff.deprecator
8
10
  module Deprecation
9
- CLOSE_ON: ::String
10
-
11
- ALLOW_EXPENSIVE: ::String
12
-
13
- RELOAD_LIVE_ENDPOINTS: ::String
14
-
15
11
  # Required when first used, as the library loads nothing it does not need.
16
12
  # : () -> untyped
17
13
  def self.deprecator: () -> untyped
18
-
19
- # The one value close_on: took. It named what ends a wall-clock window,
20
- # so it was meaningless without one, and until it is removed it is still
21
- # checked as it was.
22
- CLOSE_ON_CURRENT: ::Symbol
23
-
24
- # : (Symbol?, untyped) -> void
25
- def self.close_on!: (Symbol?, untyped) -> void
26
-
27
- # : (untyped) -> void
28
- def self.allow_expensive!: (untyped) -> void
29
-
30
- # The value to use: the option still works until it is removed, and nil
31
- # stands for its old default.
32
- # : (untyped) -> untyped
33
- def self.reload_live_endpoints!: (untyped) -> untyped
34
14
  end
35
15
  end
@@ -7,6 +7,8 @@ module PaperTrailDiff
7
7
  # : () -> void
8
8
  def initialize: () -> void
9
9
 
10
+ # Each version is read once: activity reads a root's version again at
11
+ # every event it bounds, and decoding it is most of the cost.
10
12
  # : (untyped) -> PreparedRecordState?
11
13
  def call: (untyped) -> PreparedRecordState?
12
14
 
@@ -19,6 +21,8 @@ module PaperTrailDiff
19
21
 
20
22
  @loader: PreparedVersionStateLoader
21
23
 
24
+ @states: Hash[Array[untyped], PreparedRecordState?]
25
+
22
26
  @supported: Hash[untyped, bool]
23
27
 
24
28
  # : (untyped) -> bool
@@ -4,7 +4,7 @@ module PaperTrailDiff
4
4
  # Validates and describes explicit PaperTrail-version and live-record endpoints.
5
5
  module Endpoint
6
6
  # : (untyped, untyped) -> void
7
- def self?.validate_pair!: (untyped, untyped) -> void
7
+ def self.validate_pair!: (untyped, untyped) -> void
8
8
 
9
9
  # Two versions carry no visible cue about which is earlier, so transposing
10
10
  # them is easy to do by accident and impossible to detect afterwards: the
@@ -13,44 +13,68 @@ module PaperTrailDiff
13
13
  # change is `from`. A current-record endpoint is exempt: it is self-evidently
14
14
  # the live state, so putting it first is a deliberate reverse comparison.
15
15
  # : (untyped, untyped) -> void
16
- def self?.validate_order!: (untyped, untyped) -> void
16
+ def self.validate_order!: (untyped, untyped) -> void
17
17
 
18
18
  # : (untyped, untyped) -> bool
19
- def self?.reversed_versions?: (untyped, untyped) -> bool
19
+ def self.reversed_versions?: (untyped, untyped) -> bool
20
20
 
21
21
  # : (untyped) -> void
22
- def self?.validate!: (untyped) -> void
22
+ def self.validate!: (untyped) -> void
23
23
 
24
24
  # The record a method reads the history of: a record, saved or destroyed,
25
25
  # of a model PaperTrail versions.
26
26
  # : (untyped) -> void
27
- def self?.validate_root!: (untyped) -> void
27
+ def self.validate_root!: (untyped) -> void
28
28
 
29
- # A relation is named rather than inspected, which would load it.
30
- # : (untyped) -> String
31
- def self?.described: (untyped) -> String
29
+ # What a message names the value as. A relation is named rather than
30
+ # inspected, which would load it, and by the name Active Record gives its
31
+ # class. A class without a name is printed, as a class given itself is.
32
+ # : (untyped) -> (String | Module)
33
+ def self.described: (untyped) -> (String | Module)
32
34
 
33
35
  # : (untyped) -> bool
34
- def self?.version?: (untyped) -> bool
36
+ def self.version?: (untyped) -> bool
35
37
 
36
38
  # : (untyped) -> bool
37
- def self?.record?: (untyped) -> bool
39
+ def self.record?: (untyped) -> bool
38
40
 
39
41
  # : (untyped) -> Array[String]
40
- def self?.identity: (untyped) -> Array[String]
42
+ def self.identity: (untyped) -> Array[String]
41
43
 
42
44
  # : (untyped) -> untyped
43
- def self?.model_class: (untyped) -> untyped
45
+ def self.model_class: (untyped) -> untyped
46
+
47
+ # : (String) -> untyped
48
+ def self.model_named: (String) -> untyped
49
+
50
+ # Whether the version has an `item_subtype` to read. An Active Record
51
+ # version is asked whether it was read with the column, which costs less
52
+ # than respond_to? (see Support.per_model) and answers for this row: a
53
+ # version a caller read without the column has none.
54
+ # : (untyped) -> bool
55
+ def self.subtyped?: (untyped) -> bool
44
56
 
45
57
  # Every PaperTrail version of the record, whatever scope its versions
46
- # association has.
58
+ # association has. Active Record reads a record given as an item_id as its
59
+ # id, so mutant cannot tell `record` from `record.id` here.
60
+ # mutant:disable
47
61
  # : (untyped) -> untyped
48
- def self?.versions: (untyped) -> untyped
62
+ def self.versions: (untyped) -> untyped
49
63
 
50
64
  # : (untyped) -> untyped
51
- def self?.reload_record: (untyped) -> untyped
65
+ def self.reload_record: (untyped) -> untyped
52
66
 
53
67
  # : (untyped) -> void
54
- def self?.validate_record!: (untyped) -> void
68
+ def self.validate_record!: (untyped) -> void
69
+ end
70
+
71
+ # Whether a value is a version, a record, or neither, answered once for
72
+ # each Active Record class (see Support.per_model).
73
+ module EndpointKind
74
+ # : (untyped) -> Symbol
75
+ def self.call: (untyped) -> Symbol
76
+
77
+ # : (untyped) -> Symbol
78
+ def self.classify: (untyped) -> Symbol
55
79
  end
56
80
  end
@@ -25,15 +25,12 @@ module PaperTrailDiff
25
25
  class InvalidEndpointError < Error
26
26
  end
27
27
 
28
- # Raised when reload opt-out encounters an association that was not preloaded.
29
- class UnloadedAssociationError < InvalidEndpointError
30
- end
31
-
32
28
  # Raised when a timeline boundary is absent or the requested range is reversed.
33
29
  class InvalidTimelineRangeError < Error
34
30
  end
35
31
 
36
- # Raised when `within` is not a finite, chronological range of time-like values.
32
+ # Raised when `within` is not a chronological range of time-like values with
33
+ # a beginning.
37
34
  class InvalidTimeRangeError < InvalidTimelineRangeError
38
35
  end
39
36
 
@@ -54,12 +51,6 @@ module PaperTrailDiff
54
51
  class FilterLimitExceededError < Error
55
52
  end
56
53
 
57
- # No longer raised: `allow_approximate: true` alone accepts the paths it
58
- # refused. Kept until `allow_expensive:` is removed, so code that rescues it
59
- # still loads.
60
- class UnsupportedBatchPathError < ConfigurationError
61
- end
62
-
63
54
  # Raised when a requested ActiveRecord association does not exist.
64
55
  class UnknownAssociationError < Error
65
56
  end
@@ -10,7 +10,8 @@ module PaperTrailDiff
10
10
  def initialize: (untyped, untyped) -> void
11
11
 
12
12
  # The given transactions (one id or several) in which more than one
13
- # possible owner saved a version, as strings.
13
+ # possible owner saved a version, as strings. Each statement reads up to
14
+ # 500 of them.
14
15
  # : (untyped) -> Array[String]
15
16
  def shared: (untyped) -> Array[String]
16
17
 
@@ -8,13 +8,15 @@ module PaperTrailDiff
8
8
  # the window supply the state at its start and after every change but the
9
9
  # last. The state after the last change lives in the first version after
10
10
  # the window, or in the live row when nothing follows; a destroy leaves none.
11
+ #
12
+ # Each candidate is read over the window its analysis covers, which a
13
+ # transaction crossing an edge moves (see TransactionCut). `windows` gives
14
+ # the moved ones, keyed by id, for a slice of candidates and the window.
11
15
  class HistoricalFilter
12
16
  DEFAULT_VERSION_LIMIT: ::Integer
13
17
 
14
- CANDIDATE_BATCH: ::Integer
15
-
16
- # : (untyped, predicate: untyped, time_range: TimeRange?, limit: Integer, max_versions: Integer) -> void
17
- def initialize: (untyped, predicate: untyped, time_range: TimeRange?, limit: Integer, max_versions: Integer) -> void
18
+ # : (untyped, predicate: untyped, time_range: TimeRange?, limit: Integer, max_versions: Integer, windows: ^(Array[String], TimeRange) -> Hash[String, TimeRange]) -> void
19
+ def initialize: (untyped, predicate: untyped, time_range: TimeRange?, limit: Integer, max_versions: Integer, windows: ^(Array[String], TimeRange) -> Hash[String, TimeRange]) -> void
18
20
 
19
21
  # More matches than the limit raise, unless the caller does not count
20
22
  # them: candidates it only lists, such as deleted roots.
@@ -37,6 +39,8 @@ module PaperTrailDiff
37
39
 
38
40
  @time_range: TimeRange?
39
41
 
42
+ @windows: ^(Array[String], TimeRange) -> Hash[String, TimeRange]
43
+
40
44
  # : (untyped) -> untyped
41
45
  def validate_predicate: (untyped) -> untyped
42
46
 
@@ -51,15 +55,22 @@ module PaperTrailDiff
51
55
  # : (untyped) -> Integer
52
56
  def validate_budget: (untyped) -> Integer
53
57
 
54
- # : (Array[String]) -> Hash[String, Array[untyped]]
55
- def candidate_versions: (Array[String]) -> Hash[String, Array[untyped]]
58
+ # Each candidate's versions in its own window, read from the earliest
59
+ # moved start, and the first past each end that moved.
60
+ # : (Array[String]) -> [Hash[String, Array[untyped]], Hash[String, untyped]]
61
+ def own_versions: (Array[String]) -> [ Hash[String, Array[untyped]], Hash[String, untyped] ]
62
+
63
+ # : (Array[String], TimeRange?) -> Hash[String, Array[untyped]]
64
+ def candidate_versions: (Array[String], TimeRange?) -> Hash[String, Array[untyped]]
56
65
 
57
66
  # : (Array[untyped], untyped) -> boolish
58
67
  def held?: (Array[untyped], untyped) -> boolish
59
68
 
60
- # What each candidate held after its last change in the window.
61
- # : (Array[String], Hash[String, Array[untyped]]) -> Hash[String, untyped]
62
- def closing_states: (Array[String], Hash[String, Array[untyped]]) -> Hash[String, untyped]
69
+ # What each candidate held after its last change in the window: the
70
+ # first version past an end that moved, read already, or past the end as
71
+ # asked, or the live row.
72
+ # : (Array[String], Hash[String, Array[untyped]], Hash[String, untyped]) -> Hash[String, untyped]
73
+ def closing_states: (Array[String], Hash[String, Array[untyped]], Hash[String, untyped]) -> Hash[String, untyped]
63
74
 
64
75
  # : (Array[String]) -> Hash[String, untyped]
65
76
  def trailing_versions: (Array[String]) -> Hash[String, untyped]