paper_trail_diff 0.14.0 → 0.16.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 (150) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +501 -0
  3. data/QUICKSTART.md +21 -4
  4. data/README.md +59 -56
  5. data/docs/architecture.md +32 -11
  6. data/docs/performance.md +125 -391
  7. data/docs/reference.md +470 -117
  8. data/docs/testing.md +83 -7
  9. data/lib/paper_trail_diff/activity_boundary.rb +83 -26
  10. data/lib/paper_trail_diff/activity_child_candidate_loader.rb +2 -1
  11. data/lib/paper_trail_diff/activity_collection_event_applier.rb +33 -1
  12. data/lib/paper_trail_diff/activity_event.rb +41 -10
  13. data/lib/paper_trail_diff/activity_event_route_finder.rb +31 -0
  14. data/lib/paper_trail_diff/activity_event_snapshot_refresher.rb +12 -1
  15. data/lib/paper_trail_diff/activity_history.rb +34 -9
  16. data/lib/paper_trail_diff/activity_range.rb +18 -3
  17. data/lib/paper_trail_diff/activity_root_snapshot_refresher.rb +43 -25
  18. data/lib/paper_trail_diff/activity_snapshot_sequence.rb +76 -37
  19. data/lib/paper_trail_diff/activity_target_candidate_loader.rb +5 -5
  20. data/lib/paper_trail_diff/activity_timeline_builder.rb +272 -111
  21. data/lib/paper_trail_diff/activity_transaction_grouper.rb +2 -1
  22. data/lib/paper_trail_diff/activity_tree_filter.rb +114 -0
  23. data/lib/paper_trail_diff/activity_version_collector.rb +7 -5
  24. data/lib/paper_trail_diff/activity_view.rb +69 -0
  25. data/lib/paper_trail_diff/analysis.rb +37 -6
  26. data/lib/paper_trail_diff/analysis_batch.rb +25 -31
  27. data/lib/paper_trail_diff/approximate_paths.rb +48 -0
  28. data/lib/paper_trail_diff/association_activity_edge.rb +6 -6
  29. data/lib/paper_trail_diff/association_discovery.rb +9 -1
  30. data/lib/paper_trail_diff/association_key.rb +56 -0
  31. data/lib/paper_trail_diff/association_traversal.rb +13 -4
  32. data/lib/paper_trail_diff/batch_boundary_resolver.rb +3 -4
  33. data/lib/paper_trail_diff/batch_preload.rb +53 -0
  34. data/lib/paper_trail_diff/batched_root_analyzer.rb +18 -14
  35. data/lib/paper_trail_diff/batched_root_versions.rb +38 -14
  36. data/lib/paper_trail_diff/branch_snapshot_refresher.rb +19 -16
  37. data/lib/paper_trail_diff/change_row.rb +133 -0
  38. data/lib/paper_trail_diff/collection_comparator.rb +5 -32
  39. data/lib/paper_trail_diff/configuration.rb +35 -12
  40. data/lib/paper_trail_diff/deleted_analysis_batch.rb +23 -19
  41. data/lib/paper_trail_diff/deleted_root_filter.rb +101 -0
  42. data/lib/paper_trail_diff/deprecation.rb +61 -0
  43. data/lib/paper_trail_diff/diagnostics.rb +86 -99
  44. data/lib/paper_trail_diff/endpoint.rb +26 -3
  45. data/lib/paper_trail_diff/errors.rb +3 -1
  46. data/lib/paper_trail_diff/fallback_paths.rb +38 -0
  47. data/lib/paper_trail_diff/historical_association_reifier.rb +2 -4
  48. data/lib/paper_trail_diff/historical_filter.rb +19 -10
  49. data/lib/paper_trail_diff/historical_snapshot_store.rb +57 -67
  50. data/lib/paper_trail_diff/live_endpoint_batch_loader.rb +1 -35
  51. data/lib/paper_trail_diff/nested_comparator.rb +19 -18
  52. data/lib/paper_trail_diff/paper_trail_adapter.rb +198 -166
  53. data/lib/paper_trail_diff/preloaded_endpoint_batch_loader.rb +13 -1
  54. data/lib/paper_trail_diff/prepared_activity_index.rb +17 -13
  55. data/lib/paper_trail_diff/prepared_edge_loader.rb +2 -1
  56. data/lib/paper_trail_diff/prepared_history.rb +15 -1
  57. data/lib/paper_trail_diff/prepared_history_loader.rb +2 -3
  58. data/lib/paper_trail_diff/prepared_record_index.rb +42 -7
  59. data/lib/paper_trail_diff/read_snapshot.rb +77 -0
  60. data/lib/paper_trail_diff/root_version_selection.rb +4 -2
  61. data/lib/paper_trail_diff/scope_condition.rb +157 -32
  62. data/lib/paper_trail_diff/scope_ranking.rb +23 -14
  63. data/lib/paper_trail_diff/scoped_analysis.rb +11 -0
  64. data/lib/paper_trail_diff/scoped_analysis_builder.rb +29 -11
  65. data/lib/paper_trail_diff/scoped_root_selection.rb +29 -16
  66. data/lib/paper_trail_diff/snapshot.rb +16 -1
  67. data/lib/paper_trail_diff/support.rb +29 -2
  68. data/lib/paper_trail_diff/time_range.rb +39 -16
  69. data/lib/paper_trail_diff/timeline_builder.rb +13 -7
  70. data/lib/paper_trail_diff/timeline_range.rb +9 -1
  71. data/lib/paper_trail_diff/timeline_snapshot_provider.rb +24 -17
  72. data/lib/paper_trail_diff/transaction_cut.rb +240 -0
  73. data/lib/paper_trail_diff/traversal_preparer.rb +134 -29
  74. data/lib/paper_trail_diff/version.rb +1 -1
  75. data/lib/paper_trail_diff/version_boundary.rb +41 -10
  76. data/lib/paper_trail_diff/version_query.rb +34 -10
  77. data/lib/paper_trail_diff/version_scope_filter.rb +9 -10
  78. data/lib/paper_trail_diff/version_sequence_diagnostics.rb +35 -17
  79. data/lib/paper_trail_diff/version_table.rb +60 -0
  80. data/lib/paper_trail_diff.rb +101 -57
  81. data/sig/generated/paper_trail_diff/activity_boundary.rbs +54 -19
  82. data/sig/generated/paper_trail_diff/activity_collection_event_applier.rbs +13 -0
  83. data/sig/generated/paper_trail_diff/activity_event.rbs +25 -4
  84. data/sig/generated/paper_trail_diff/activity_event_route_finder.rbs +14 -0
  85. data/sig/generated/paper_trail_diff/activity_event_snapshot_refresher.rbs +6 -0
  86. data/sig/generated/paper_trail_diff/activity_history.rbs +21 -6
  87. data/sig/generated/paper_trail_diff/activity_range.rbs +9 -2
  88. data/sig/generated/paper_trail_diff/activity_root_snapshot_refresher.rbs +21 -10
  89. data/sig/generated/paper_trail_diff/activity_snapshot_sequence.rbs +48 -9
  90. data/sig/generated/paper_trail_diff/activity_timeline_builder.rbs +138 -30
  91. data/sig/generated/paper_trail_diff/activity_tree_filter.rbs +73 -0
  92. data/sig/generated/paper_trail_diff/activity_version_collector.rbs +2 -0
  93. data/sig/generated/paper_trail_diff/activity_view.rbs +42 -0
  94. data/sig/generated/paper_trail_diff/analysis.rbs +24 -5
  95. data/sig/generated/paper_trail_diff/analysis_batch.rbs +8 -15
  96. data/sig/generated/paper_trail_diff/approximate_paths.rbs +23 -0
  97. data/sig/generated/paper_trail_diff/association_discovery.rbs +5 -0
  98. data/sig/generated/paper_trail_diff/association_key.rbs +29 -0
  99. data/sig/generated/paper_trail_diff/association_traversal.rbs +4 -0
  100. data/sig/generated/paper_trail_diff/batch_preload.rbs +29 -0
  101. data/sig/generated/paper_trail_diff/batched_root_analyzer.rbs +13 -10
  102. data/sig/generated/paper_trail_diff/batched_root_versions.rbs +14 -4
  103. data/sig/generated/paper_trail_diff/branch_snapshot_refresher.rbs +6 -0
  104. data/sig/generated/paper_trail_diff/change_row.rbs +86 -0
  105. data/sig/generated/paper_trail_diff/collection_comparator.rbs +2 -16
  106. data/sig/generated/paper_trail_diff/configuration.rbs +19 -3
  107. data/sig/generated/paper_trail_diff/deleted_analysis_batch.rbs +11 -8
  108. data/sig/generated/paper_trail_diff/deleted_root_filter.rbs +56 -0
  109. data/sig/generated/paper_trail_diff/deprecation.rbs +35 -0
  110. data/sig/generated/paper_trail_diff/diagnostics.rbs +37 -30
  111. data/sig/generated/paper_trail_diff/endpoint.rbs +11 -2
  112. data/sig/generated/paper_trail_diff/errors.rbs +3 -1
  113. data/sig/generated/paper_trail_diff/fallback_paths.rbs +22 -0
  114. data/sig/generated/paper_trail_diff/historical_filter.rbs +12 -2
  115. data/sig/generated/paper_trail_diff/historical_snapshot_store.rbs +33 -28
  116. data/sig/generated/paper_trail_diff/live_endpoint_batch_loader.rbs +0 -15
  117. data/sig/generated/paper_trail_diff/nested_comparator.rbs +10 -7
  118. data/sig/generated/paper_trail_diff/paper_trail_adapter.rbs +64 -52
  119. data/sig/generated/paper_trail_diff/preloaded_endpoint_batch_loader.rbs +9 -1
  120. data/sig/generated/paper_trail_diff/prepared_activity_index.rbs +11 -4
  121. data/sig/generated/paper_trail_diff/prepared_history.rbs +10 -0
  122. data/sig/generated/paper_trail_diff/prepared_record_index.rbs +20 -2
  123. data/sig/generated/paper_trail_diff/read_snapshot.rbs +43 -0
  124. data/sig/generated/paper_trail_diff/root_version_selection.rbs +2 -0
  125. data/sig/generated/paper_trail_diff/scope_condition.rbs +81 -15
  126. data/sig/generated/paper_trail_diff/scope_ranking.rbs +14 -6
  127. data/sig/generated/paper_trail_diff/scoped_analysis.rbs +6 -0
  128. data/sig/generated/paper_trail_diff/scoped_analysis_builder.rbs +14 -2
  129. data/sig/generated/paper_trail_diff/scoped_root_selection.rbs +16 -7
  130. data/sig/generated/paper_trail_diff/snapshot.rbs +8 -0
  131. data/sig/generated/paper_trail_diff/support.rbs +15 -0
  132. data/sig/generated/paper_trail_diff/time_range.rbs +24 -9
  133. data/sig/generated/paper_trail_diff/timeline_builder.rbs +6 -2
  134. data/sig/generated/paper_trail_diff/timeline_range.rbs +2 -0
  135. data/sig/generated/paper_trail_diff/timeline_snapshot_provider.rbs +17 -7
  136. data/sig/generated/paper_trail_diff/transaction_cut.rbs +126 -0
  137. data/sig/generated/paper_trail_diff/traversal_preparer.rbs +66 -8
  138. data/sig/generated/paper_trail_diff/version_boundary.rbs +22 -3
  139. data/sig/generated/paper_trail_diff/version_query.rbs +18 -2
  140. data/sig/generated/paper_trail_diff/version_scope_filter.rbs +4 -5
  141. data/sig/generated/paper_trail_diff/version_sequence_diagnostics.rbs +19 -9
  142. data/sig/generated/paper_trail_diff/version_table.rbs +30 -0
  143. data/sig/generated/paper_trail_diff.rbs +29 -26
  144. metadata +49 -11
  145. data/lib/paper_trail_diff/activity_grouping.rb +0 -38
  146. data/lib/paper_trail_diff/batch_safety.rb +0 -63
  147. data/lib/paper_trail_diff/time_activity_timeline_builder.rb +0 -223
  148. data/sig/generated/paper_trail_diff/activity_grouping.rbs +0 -22
  149. data/sig/generated/paper_trail_diff/batch_safety.rbs +0 -30
  150. data/sig/generated/paper_trail_diff/time_activity_timeline_builder.rbs +0 -92
@@ -41,28 +41,49 @@ module PaperTrailDiff
41
41
  end
42
42
 
43
43
  # Performs read-only checks for known PaperTrail/PT-AT reconstruction hazards.
44
+ #
45
+ # The endpoints are a comparison's: two versions, or a version and the
46
+ # current record, in either order. Two current records read no history, so
47
+ # nothing is checked.
44
48
  class HistoryDiagnostics
45
- # : (untyped, untyped, associations: Array[String | Symbol]) -> void
46
- def initialize: (untyped, untyped, associations: Array[String | Symbol]) -> void
49
+ STOPPING_CODES: untyped
50
+
51
+ # : (untyped, untyped, associations: association_option, ?allow_approximate: bool) -> void
52
+ def initialize: (untyped, untyped, associations: association_option, ?allow_approximate: bool) -> void
47
53
 
48
54
  # : () -> DiagnosticReport
49
55
  def call: () -> DiagnosticReport
50
56
 
51
57
  private
52
58
 
53
- @from_version: untyped
59
+ # Each refusal a comparison would raise is an error, so `ok?` is false
60
+ # exactly when one would. The checks after them read reflections that must
61
+ # resolve and PT-AT records that must be there.
62
+ # : (untyped) -> void
63
+ def inspect_associations: (untyped) -> void
64
+
65
+ @allow_approximate: bool
54
66
 
55
67
  @issues: Array[DiagnosticIssue]
56
68
 
57
- @to_version: untyped
69
+ @preparer: TraversalPreparer
70
+
71
+ @traversal: AssociationTraversal
58
72
 
59
73
  @tree: AssociationTree
60
74
 
61
- # : () -> untyped
62
- def validated_model_class: () -> untyped
75
+ @versions: Array[untyped]
76
+
77
+ # The endpoints that are versions, in the order given.
78
+ # : (untyped, untyped) -> Array[untyped]
79
+ def validated_versions: (untyped, untyped) -> Array[untyped]
63
80
 
64
81
  # : (Array[Array[untyped]]) -> void
65
- def inspect_targets: (Array[Array[untyped]]) -> void
82
+ def inspect_polymorphic_targets: (Array[Array[untyped]]) -> void
83
+
84
+ # Accepted, but read the way `allow_approximate:` describes.
85
+ # : (untyped) -> void
86
+ def inspect_approximate_paths: (untyped) -> void
66
87
 
67
88
  # : (untyped, Array[Array[untyped]]) -> void
68
89
  def inspect_habtm: (untyped, Array[Array[untyped]]) -> void
@@ -72,8 +93,15 @@ module PaperTrailDiff
72
93
  # : (untyped, Array[Array[untyped]]) -> void
73
94
  def inspect_shared_transactions: (untyped, Array[Array[untyped]]) -> void
74
95
 
75
- # : () -> void
76
- def inspect_version_sequence: () -> void
96
+ # With the current record as one endpoint there is one version, and the
97
+ # sequence runs on from it.
98
+ # : (untyped) -> void
99
+ def inspect_version_sequence: (untyped) -> void
100
+
101
+ # Only a path PT-AT reads can lose a change between tied versions, and a
102
+ # traversal that does not resolve reads nothing at all.
103
+ # : (untyped) -> bool
104
+ def fallback_selected?: (untyped) -> bool
77
105
 
78
106
  # : (untyped) -> void
79
107
  def inspect_checkpoint_timestamp: (untyped) -> void
@@ -81,30 +109,9 @@ module PaperTrailDiff
81
109
  # : (Array[String]) -> void
82
110
  def inspect_transaction_metadata: (Array[String]) -> void
83
111
 
84
- # : (untyped, String) -> void
85
- def inspect_versioned_model: (untyped, String) -> void
86
-
87
- # : (untyped, String) -> void
88
- def inspect_through_model: (untyped, String) -> void
89
-
90
- # : (untyped) -> bool
91
- def model_versioned?: (untyped) -> bool
92
-
93
112
  # : (untyped) -> bool
94
113
  def synchronized_timestamp_disabled?: (untyped) -> bool
95
114
 
96
- # : () -> bool
97
- def association_tracking_available?: () -> bool
98
-
99
- # : (untyped) -> Array[String]
100
- def version_identity: (untyped) -> Array[String]
101
-
102
- # : (untyped) -> String
103
- def version_type: (untyped) -> String
104
-
105
- # : () -> String
106
- def tracking_unavailable_message: () -> String
107
-
108
115
  # : (Symbol, String, ?String?, ?untyped) -> void
109
116
  def add_error: (Symbol, String, ?String?, ?untyped) -> void
110
117
 
@@ -21,6 +21,15 @@ module PaperTrailDiff
21
21
  # : (untyped) -> void
22
22
  def self?.validate!: (untyped) -> void
23
23
 
24
+ # The record a method reads the history of: a record, saved or destroyed,
25
+ # of a model PaperTrail versions.
26
+ # : (untyped) -> void
27
+ def self?.validate_root!: (untyped) -> void
28
+
29
+ # A relation is named rather than inspected, which would load it.
30
+ # : (untyped) -> String
31
+ def self?.described: (untyped) -> String
32
+
24
33
  # : (untyped) -> bool
25
34
  def self?.version?: (untyped) -> bool
26
35
 
@@ -33,8 +42,8 @@ module PaperTrailDiff
33
42
  # : (untyped) -> untyped
34
43
  def self?.model_class: (untyped) -> untyped
35
44
 
36
- # The record's own PaperTrail versions, under whatever name the model gave
37
- # the association.
45
+ # Every PaperTrail version of the record, whatever scope its versions
46
+ # association has.
38
47
  # : (untyped) -> untyped
39
48
  def self?.versions: (untyped) -> untyped
40
49
 
@@ -54,7 +54,9 @@ module PaperTrailDiff
54
54
  class FilterLimitExceededError < Error
55
55
  end
56
56
 
57
- # A batch selected a known expensive association without explicitly opting in.
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.
58
60
  class UnsupportedBatchPathError < ConfigurationError
59
61
  end
60
62
 
@@ -0,0 +1,22 @@
1
+ # Generated from lib/paper_trail_diff/fallback_paths.rb with RBS::Inline
2
+
3
+ module PaperTrailDiff
4
+ # Whether a request may read a path with PT-AT's reifier rather than from
5
+ # loaded history. PT-AT places association changes by timestamp alone, so
6
+ # only such a path can miss a change between two versions that share one;
7
+ # loaded history orders those versions by id.
8
+ module FallbackPaths
9
+ # A path history reads only approximately counts when it is allowed: a
10
+ # request that does not allow it is refused before anything is read.
11
+ # : (AssociationTraversal, untyped, approximate: bool) -> bool
12
+ def self.any?: (AssociationTraversal, untyped, approximate: bool) -> bool
13
+
14
+ # Loaded history cannot index a composite foreign key, and a polymorphic
15
+ # belongs_to's target, with its default scope, is known only per record.
16
+ # : (untyped) -> bool
17
+ def self.per_record?: (untyped) -> bool
18
+
19
+ # : (untyped) -> bool
20
+ def self.composite_key?: (untyped) -> bool
21
+ end
22
+ end
@@ -16,8 +16,10 @@ module PaperTrailDiff
16
16
  # : (untyped, predicate: untyped, time_range: TimeRange?, limit: Integer, max_versions: Integer) -> void
17
17
  def initialize: (untyped, predicate: untyped, time_range: TimeRange?, limit: Integer, max_versions: Integer) -> void
18
18
 
19
- # : (Array[String]) -> Array[String]
20
- def call: (Array[String]) -> Array[String]
19
+ # More matches than the limit raise, unless the caller does not count
20
+ # them: candidates it only lists, such as deleted roots.
21
+ # : (Array[String], ?counted: bool) -> Array[String]
22
+ def call: (Array[String], ?counted: bool) -> Array[String]
21
23
 
22
24
  private
23
25
 
@@ -38,6 +40,14 @@ module PaperTrailDiff
38
40
  # : (untyped) -> untyped
39
41
  def validate_predicate: (untyped) -> untyped
40
42
 
43
+ # Expected and recorded values compare as the attribute casts them, as
44
+ # `where` reads its values: an enum's symbol names its stored value, and a
45
+ # `json` or `jsonb` version column, which PaperTrail does not cast, holds
46
+ # dates and times as strings. Casting also copies a mutable value, so the
47
+ # filter keeps its own.
48
+ # : (String, untyped) -> untyped
49
+ def cast: (String, untyped) -> untyped
50
+
41
51
  # : (untyped) -> Integer
42
52
  def validate_budget: (untyped) -> Integer
43
53
 
@@ -1,13 +1,16 @@
1
1
  # Generated from lib/paper_trail_diff/historical_snapshot_store.rb with RBS::Inline
2
2
 
3
3
  module PaperTrailDiff
4
- # Reconstructs and caches immutable historical snapshots for one adapter configuration.
4
+ # Reconstructs and caches immutable historical snapshots for one adapter
5
+ # configuration. It keeps the histories batches prepare, by root version;
6
+ # one prepared for a single root goes back to the caller, who passes it to
7
+ # every read for that root.
5
8
  class HistoricalSnapshotStore
6
9
  # : (tree: AssociationTree, traversal: AssociationTraversal, normalizer: SnapshotNormalizer, preparer: untyped) -> void
7
10
  def initialize: (tree: AssociationTree, traversal: AssociationTraversal, normalizer: SnapshotNormalizer, preparer: untyped) -> void
8
11
 
9
- # : (untyped, Array[untyped], ?start_at: untyped, ?end_at: untyped) -> void
10
- def prepare: (untyped, Array[untyped], ?start_at: untyped, ?end_at: untyped) -> void
12
+ # : (untyped, Array[untyped], ?start_at: untyped, ?end_at: untyped) -> PreparedHistory?
13
+ def prepare: (untyped, Array[untyped], ?start_at: untyped, ?end_at: untyped) -> PreparedHistory?
11
14
 
12
15
  # : (Array[untyped], Array[untyped], ?start_at: untyped, ?end_at: untyped) -> void
13
16
  def prepare_batch: (Array[untyped], Array[untyped], ?start_at: untyped, ?end_at: untyped) -> void
@@ -18,37 +21,29 @@ module PaperTrailDiff
18
21
  # : (Array[untyped], Array[untyped], ?start_at: untyped, ?end_at: untyped) -> void
19
22
  def prepare_deleted_batch: (Array[untyped], Array[untyped], ?start_at: untyped, ?end_at: untyped) -> void
20
23
 
21
- # : (untyped, untyped) -> RecordSnapshot?
22
- def call: (untyped, untyped) -> RecordSnapshot?
24
+ # `history` is the one `prepare` returned for this root, if any.
25
+ # : (untyped, untyped, ?history: PreparedHistory?) -> RecordSnapshot?
26
+ def call: (untyped, untyped, ?history: PreparedHistory?) -> RecordSnapshot?
23
27
 
24
- # : (untyped, untyped) -> RecordSnapshot?
25
- def uncached: (untyped, untyped) -> RecordSnapshot?
28
+ # : (untyped, untyped, ?history: PreparedHistory?) -> RecordSnapshot?
29
+ def uncached: (untyped, untyped, ?history: PreparedHistory?) -> RecordSnapshot?
26
30
 
27
- # : (untyped, untyped, tree: AssociationTree, normalizer: SnapshotNormalizer) -> RecordSnapshot?
28
- def custom: (untyped, untyped, tree: AssociationTree, normalizer: SnapshotNormalizer) -> RecordSnapshot?
31
+ # : (untyped, untyped, tree: AssociationTree, normalizer: SnapshotNormalizer, ?history: PreparedHistory?) -> RecordSnapshot?
32
+ def custom: (untyped, untyped, tree: AssociationTree, normalizer: SnapshotNormalizer, ?history: PreparedHistory?) -> RecordSnapshot?
29
33
 
30
- # : (untyped, habtm_version: untyped) -> untyped
31
- def association_reader: (untyped, habtm_version: untyped) -> untyped
32
-
33
- # : () -> PreparedActivityIndex?
34
- def activity_index: () -> PreparedActivityIndex?
35
-
36
- # : (untyped) -> [Hash[untyped, untyped], Hash[untyped, untyped]]?
37
- def record_transition: (untyped) -> [ Hash[untyped, untyped], Hash[untyped, untyped] ]?
38
-
39
- # : (untyped, ?direct: bool) -> [bool, untyped]
40
- def record_after: (untyped, ?direct: bool) -> [ bool, untyped ]
34
+ # : (untyped, habtm_version: untyped, ?history: PreparedHistory?) -> untyped
35
+ def association_reader: (untyped, habtm_version: untyped, ?history: PreparedHistory?) -> untyped
41
36
 
42
37
  private
43
38
 
44
39
  @live_graph_collector: LiveGraphCollector
45
40
 
41
+ @live_roots: Hash[identity, untyped]
42
+
46
43
  @normalizer: SnapshotNormalizer
47
44
 
48
45
  @prepared_histories: Hash[Array[untyped], PreparedHistory]
49
46
 
50
- @prepared_history: PreparedHistory?
51
-
52
47
  @prepared_snapshotter: PreparedSnapshotBuilder
53
48
 
54
49
  @preparer: untyped
@@ -59,6 +54,10 @@ module PaperTrailDiff
59
54
 
60
55
  @tree: AssociationTree
61
56
 
57
+ # A batch's history for the version wins over the one a caller passes.
58
+ # : (untyped, PreparedHistory?) -> PreparedHistory?
59
+ def history_for: (untyped, PreparedHistory?) -> PreparedHistory?
60
+
62
61
  # : (untyped) -> Array[untyped]
63
62
  def context_key: (untyped) -> Array[untyped]
64
63
 
@@ -68,14 +67,20 @@ module PaperTrailDiff
68
67
  # : (Array[untyped], Array[untyped], ?live_records: Array[untyped], ?start_at: untyped, ?end_at: untyped) -> void
69
68
  def register_batch: (Array[untyped], Array[untyped], ?live_records: Array[untyped], ?start_at: untyped, ?end_at: untyped) -> void
70
69
 
71
- # : (untyped, untyped, tree: AssociationTree, normalizer: SnapshotNormalizer) -> RecordSnapshot?
72
- def snapshot_from_version: (untyped, untyped, tree: AssociationTree, normalizer: SnapshotNormalizer) -> RecordSnapshot?
70
+ # : (untyped, untyped, tree: AssociationTree, normalizer: SnapshotNormalizer, history: PreparedHistory?) -> RecordSnapshot?
71
+ def snapshot_from_version: (untyped, untyped, tree: AssociationTree, normalizer: SnapshotNormalizer, history: PreparedHistory?) -> RecordSnapshot?
72
+
73
+ # : (untyped, untyped, tree: AssociationTree, normalizer: SnapshotNormalizer, history: PreparedHistory?) -> RecordSnapshot?
74
+ def snapshot_from_live_root: (untyped, untyped, tree: AssociationTree, normalizer: SnapshotNormalizer, history: PreparedHistory?) -> RecordSnapshot?
73
75
 
74
- # : (untyped, untyped, tree: AssociationTree, normalizer: SnapshotNormalizer) -> RecordSnapshot?
75
- def snapshot_from_live_root: (untyped, untyped, tree: AssociationTree, normalizer: SnapshotNormalizer) -> RecordSnapshot?
76
+ # Rebuilding a version's associations writes them onto the record, so each
77
+ # snapshot gets its own copy of a batch's loaded row, built from the row's
78
+ # stored values without a query.
79
+ # : (untyped) -> untyped
80
+ def live_root: (untyped) -> untyped
76
81
 
77
- # : (untyped, untyped, tree: AssociationTree, normalizer: SnapshotNormalizer, habtm_version: untyped) -> RecordSnapshot?
78
- def normalize: (untyped, untyped, tree: AssociationTree, normalizer: SnapshotNormalizer, habtm_version: untyped) -> RecordSnapshot?
82
+ # : (untyped, untyped, tree: AssociationTree, normalizer: SnapshotNormalizer, habtm_version: untyped, history: PreparedHistory?) -> RecordSnapshot?
83
+ def normalize: (untyped, untyped, tree: AssociationTree, normalizer: SnapshotNormalizer, habtm_version: untyped, history: PreparedHistory?) -> RecordSnapshot?
79
84
 
80
85
  # : (untyped, untyped) -> Array[untyped]
81
86
  def snapshot_key: (untyped, untyped) -> Array[untyped]
@@ -39,21 +39,6 @@ module PaperTrailDiff
39
39
  # : () -> untyped
40
40
  def active_record_preloader: () -> untyped
41
41
 
42
- # The preloader applies a limit or offset to all owners' records at once,
43
- # not to each owner's, so such an association is loaded per record. A
44
- # has_one is no exception. Through a part with a limit, an offset or a
45
- # has_one cut, the preloader keeps what the part alone would load, while
46
- # the through's own query keeps the part's conditions only.
47
- # : (untyped, untyped) -> bool
48
- def batch_safe?: (untyped, untyped) -> bool
49
-
50
- # : (untyped) -> bool
51
- def cut_part?: (untyped) -> bool
52
-
53
- # Every part a through passes, at any depth.
54
- # : (untyped) -> Array[untyped]
55
- def through_parts: (untyped) -> Array[untyped]
56
-
57
42
  # : (Array[untyped], untyped) -> Array[untyped]
58
43
  def load_individually: (Array[untyped], untyped) -> Array[untyped]
59
44
 
@@ -43,6 +43,7 @@ module PaperTrailDiff
43
43
  # Returns the changed paths, or an empty hash when the pair is not two
44
44
  # structures this can look inside. An empty result therefore means "nothing
45
45
  # to report at this depth", and the caller still has the whole-value change.
46
+ # Two arrays at the top are one membership change, at the empty path.
46
47
  # : () -> nested_changes
47
48
  def call: () -> nested_changes
48
49
 
@@ -52,14 +53,16 @@ module PaperTrailDiff
52
53
 
53
54
  @to_value: untyped
54
55
 
55
- # Both sides have to be readable as a Hash for a nested answer to mean
56
- # anything. A column that held text on one side and JSON on the other
57
- # changed wholesale, and saying so is the accurate report.
58
- # : () -> [Hash[untyped, untyped]?, Hash[untyped, untyped]?]
59
- def structures: () -> [ Hash[untyped, untyped]?, Hash[untyped, untyped]? ]
56
+ # Both sides have to be readable as the same kind of structure for a
57
+ # nested answer to mean anything. A column that held text on one side and
58
+ # JSON on the other changed wholesale, and saying so is the accurate report.
59
+ # : () -> [untyped, untyped]
60
+ def structures: () -> [ untyped, untyped ]
60
61
 
61
- # : (untyped) -> Hash[untyped, untyped]?
62
- def structure: (untyped) -> Hash[untyped, untyped]?
62
+ # A string is read as JSON; anything else, or JSON that is neither an
63
+ # object nor an array, is left for #call to decline.
64
+ # : (untyped) -> untyped
65
+ def structure: (untyped) -> untyped
63
66
 
64
67
  # : (Hash[untyped, untyped], Hash[untyped, untyped], Array[String], nested_changes) -> void
65
68
  def walk: (Hash[untyped, untyped], Hash[untyped, untyped], Array[String], nested_changes) -> void
@@ -6,11 +6,10 @@ module PaperTrailDiff
6
6
  # the only place allowed to know about both PaperTrail and the pure engine.
7
7
  # Reconstruction logic lives in the collaborators it wires together.
8
8
  class PaperTrailAdapter
9
- # The only thing a wall-clock window can close on besides a later version.
10
- CLOSE_ON_CURRENT: ::Symbol
11
-
12
- # : (associations: Array[String | Symbol], ignore: ignore_option, ?reload_live_endpoints: bool, ?allow_expensive: bool) -> void
13
- def initialize: (associations: Array[String | Symbol], ignore: ignore_option, ?reload_live_endpoints: bool, ?allow_expensive: bool) -> void
9
+ # `recorded_changes:` reads what each activity boundary's version recorded.
10
+ # `allow_approximate:` accepts association paths read with PT-AT.
11
+ # : (associations: association_option, ignore: ignore_option, ?reload_live_endpoints: bool, ?recorded_changes: bool, ?allow_approximate: bool) -> void
12
+ def initialize: (associations: association_option, ignore: ignore_option, ?reload_live_endpoints: bool, ?recorded_changes: bool, ?allow_approximate: bool) -> void
14
13
 
15
14
  # : (untyped, untyped) -> Diff
16
15
  def compare: (untyped, untyped) -> Diff
@@ -19,47 +18,62 @@ module PaperTrailDiff
19
18
  # : (Array[comparison_input]) -> comparison_results
20
19
  def compare_many: (Array[comparison_input]) -> comparison_results
21
20
 
22
- # : (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped, ?close_on: Symbol?) -> Array[Step]
23
- def timeline: (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped, ?close_on: Symbol?) -> Array[Step]
21
+ # : (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped) -> Array[Step]
22
+ def timeline: (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped) -> Array[Step]
24
23
 
25
- # : (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool, ?group: Symbol?) -> Array[ActivityStep]
26
- def activity_timeline: (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool, ?group: Symbol?) -> Array[ActivityStep]
24
+ # : (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped, ?snapshots: bool, ?group: Symbol?) -> Array[ActivityStep]
25
+ def activity_timeline: (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped, ?snapshots: bool, ?group: Symbol?) -> Array[ActivityStep]
27
26
 
28
- # : (untyped, from: untyped, to: untyped, within: untyped, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool, ?group: Symbol?) -> Analysis
29
- def analyze: (untyped, from: untyped, to: untyped, within: untyped, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool, ?group: Symbol?) -> Analysis
27
+ # : (untyped, from: untyped, to: untyped, within: untyped, ?activity: bool, ?version_scope: untyped, ?snapshots: bool, ?group: Symbol?) -> Analysis
28
+ def analyze: (untyped, from: untyped, to: untyped, within: untyped, ?activity: bool, ?version_scope: untyped, ?snapshots: bool, ?group: Symbol?) -> Analysis
30
29
 
31
30
  # Analyzes many roots over one shared range, preparing their history once.
32
- # : (Array[untyped], within: untyped, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool, ?group: Symbol?) -> Hash[identity, Analysis]
33
- def analyze_many: (Array[untyped], within: untyped, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool, ?group: Symbol?) -> Hash[identity, Analysis]
31
+ # : (Array[untyped], within: untyped, ?activity: bool, ?version_scope: untyped, ?snapshots: bool, ?group: Symbol?) -> Hash[identity, Analysis]
32
+ def analyze_many: (Array[untyped], within: untyped, ?activity: bool, ?version_scope: untyped, ?snapshots: bool, ?group: Symbol?) -> Hash[identity, Analysis]
34
33
 
35
34
  # Selects the roots from a relation before running the ordinary batch, so a
36
35
  # caller reporting on a population does not have to rediscover which of its
37
36
  # members changed. The roots the relation could not reach come back named
38
37
  # rather than dropped -- see `PaperTrailDiff.analyze_scope`.
39
- # : (untyped, limit: Integer?, within: untyped, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool, ?group: Symbol?, ?historical_filter: untyped, ?max_filter_versions: Integer, ?include_deleted: bool) -> ScopedAnalysis
40
- def analyze_scope: (untyped, limit: Integer?, within: untyped, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool, ?group: Symbol?, ?historical_filter: untyped, ?max_filter_versions: Integer, ?include_deleted: bool) -> ScopedAnalysis
38
+ # : (untyped, limit: Integer?, within: untyped, ?activity: bool, ?version_scope: untyped, ?snapshots: bool, ?group: Symbol?, ?historical_filter: untyped, ?max_filter_versions: Integer, ?include_deleted: bool) -> ScopedAnalysis
39
+ def analyze_scope: (untyped, limit: Integer?, within: untyped, ?activity: bool, ?version_scope: untyped, ?snapshots: bool, ?group: Symbol?, ?historical_filter: untyped, ?max_filter_versions: Integer, ?include_deleted: bool) -> ScopedAnalysis
41
40
 
42
41
  private
43
42
 
44
- # Selecting by activity reads association history, so it must be available
45
- # before the first selection query rather than once analysis starts.
46
- # : (untyped, bool) -> void
47
- def check_scope: (untyped, bool) -> void
43
+ # : (bool, bool, Symbol?) -> ActivityView
44
+ def activity_view: (bool, bool, Symbol?) -> ActivityView
45
+
46
+ # : (untyped) -> Hash[Symbol, untyped]
47
+ def model_payload: (untyped) -> Hash[Symbol, untyped]
48
+
49
+ # : (untyped, from: untyped, to: untyped, within: untyped, activity: bool, version_scope: untyped, view: ActivityView) -> Analysis
50
+ def analyze_record: (untyped, from: untyped, to: untyped, within: untyped, activity: bool, version_scope: untyped, view: ActivityView) -> Analysis
51
+
52
+ # : (Array[untyped], within: untyped, activity: bool, version_scope: untyped, view: ActivityView) -> Hash[identity, Analysis]
53
+ def analyze_batch: (Array[untyped], within: untyped, activity: bool, version_scope: untyped, view: ActivityView) -> Hash[identity, Analysis]
54
+
55
+ # Analysis reads association history, so a request it would refuse is
56
+ # refused before the first selection query rather than once analysis starts.
57
+ # : (untyped) -> void
58
+ def check_scope: (untyped) -> void
59
+
60
+ # The endpoints of the hash comparisons. Anything else is left for the batch to refuse.
61
+ # : (untyped) -> Array[untyped]
62
+ def comparison_endpoints: (untyped) -> Array[untyped]
48
63
 
49
64
  # : (Array[comparison_input], preparer: untyped) -> ComparisonBatch
50
65
  def comparison_batch: (Array[comparison_input], preparer: untyped) -> ComparisonBatch
51
66
 
67
+ # Refused before the current records load, rather than once analysis starts.
52
68
  # : (Array[untyped]) -> Hash[identity, untyped]
53
69
  def load_batch_endpoints: (Array[untyped]) -> Hash[identity, untyped]
54
70
 
55
- # : (untyped, historical: bool) -> void
56
- def prepare_batch_model: (untyped, historical: bool) -> void
57
-
58
- @batch_safety: BatchSafety
59
-
60
71
  # : (untyped, Array[Array[String]], Hash[Symbol, untyped]) -> Hash[Array[String], Analysis?]
61
72
  def analyze_deleted: (untyped, Array[Array[String]], Hash[Symbol, untyped]) -> Hash[Array[String], Analysis?]
62
73
 
74
+ # : (untyped, limit: Integer?, within: untyped, activity: bool, version_scope: untyped, historical_filter: untyped, max_filter_versions: Integer, include_deleted: bool, view: ActivityView) -> ScopedAnalysisBuilder
75
+ def scoped_builder: (untyped, limit: Integer?, within: untyped, activity: bool, version_scope: untyped, historical_filter: untyped, max_filter_versions: Integer, include_deleted: bool, view: ActivityView) -> ScopedAnalysisBuilder
76
+
63
77
  @activity_snapshotter: ActivitySnapshotProvider
64
78
 
65
79
  @association_tree: AssociationTree
@@ -74,6 +88,8 @@ module PaperTrailDiff
74
88
 
75
89
  @normalizer: SnapshotNormalizer
76
90
 
91
+ @recorded: IgnorePolicy?
92
+
77
93
  @snapshot_pool: SnapshotPool
78
94
 
79
95
  @timeline_snapshotter: TimelineSnapshotProvider
@@ -82,24 +98,19 @@ module PaperTrailDiff
82
98
 
83
99
  @traversal_preparer: TraversalPreparer
84
100
 
85
- # : (untyped, from: untyped, to: untyped, within: untyped, version_scope: untyped, live_endpoint: untyped, ?snapshots: bool, ?group: Symbol?) -> Analysis
86
- def analyze_activity: (untyped, from: untyped, to: untyped, within: untyped, version_scope: untyped, live_endpoint: untyped, ?snapshots: bool, ?group: Symbol?) -> Analysis
87
-
88
- # Association membership is resolved by timestamp, so endpoints sharing one
89
- # cannot be told apart and any association change between them is invisible.
90
- # The result may still be correct -- nothing associated may have changed --
91
- # and the gem cannot tell which, since not seeing the change is the symptom.
92
- # So it reports the condition and leaves the judgement to the application.
101
+ # The result may still be correct -- nothing the path reaches may have
102
+ # changed -- and the gem cannot tell which, since not seeing the change is
103
+ # the symptom. So it reports the condition and leaves the judgement to the
104
+ # application.
93
105
  # : (untyped, untyped) -> void
94
106
  def notify_ambiguous_association_boundary: (untyped, untyped) -> void
95
107
 
96
- # A window with nothing recorded after its last change ends at the live
97
- # record, which holds the state that change produced -- whether the window
98
- # ended a moment ago or long before. `close_on: :current` asked for this
99
- # before it was the default and is still accepted. It names what ends a
100
- # wall-clock window, so it is meaningless for explicit endpoints.
101
- # : (Symbol?, untyped) -> bool
102
- def close_on_current?: (Symbol?, untyped) -> bool
108
+ # Loaded history orders two versions that share a timestamp by id, but
109
+ # PT-AT places association changes by timestamp alone, so only a path it
110
+ # reads can lose a change between them. A request the preparer refuses
111
+ # raises here, before anything is reported.
112
+ # : (untyped, untyped) -> bool
113
+ def ambiguous_association_boundary?: (untyped, untyped) -> bool
103
114
 
104
115
  # With neither a window nor endpoints, a range is the record's whole
105
116
  # history through its current saved state; a missing endpoint takes that
@@ -107,26 +118,30 @@ module PaperTrailDiff
107
118
  # : (untyped, untyped, untyped, untyped) -> [untyped, untyped]
108
119
  def default_range: (untyped, untyped, untyped, untyped) -> [ untyped, untyped ]
109
120
 
121
+ # A window with nothing recorded after its last change ends at the live
122
+ # record, which holds the state that change produced -- whether the window
123
+ # ended a moment ago or long before. Explicit endpoints name their own end.
110
124
  # Only a saved row has current state to close on. A destroyed root's own
111
125
  # destroy version already terminates its history, and a reified or unsaved
112
126
  # instance stands for a state that is not in the table.
113
- # : (untyped, Symbol?, untyped) -> untyped
114
- def live_endpoint_for: (untyped, Symbol?, untyped) -> untyped
127
+ # : (untyped, untyped) -> untyped
128
+ def live_endpoint_for: (untyped, untyped) -> untyped
115
129
 
116
130
  # : () -> void
117
131
  def build_snapshotters: () -> void
118
132
 
119
- # : (bool, within: untyped, snapshots: bool, group: Symbol?) -> BatchedRootAnalyzer
120
- def batched_root_analyzer: (bool, within: untyped, snapshots: bool, group: Symbol?) -> BatchedRootAnalyzer
133
+ # : (bool, within: untyped, view: ActivityView) -> BatchedRootAnalyzer
134
+ def batched_root_analyzer: (bool, within: untyped, view: ActivityView) -> BatchedRootAnalyzer
121
135
 
122
136
  # : () -> HistoricalSnapshotStore
123
137
  def build_historical_store: () -> HistoricalSnapshotStore
124
138
 
125
- # : () -> ActivitySnapshotProvider
126
- def build_activity_snapshotter: () -> ActivitySnapshotProvider
139
+ # Refreshes one root's snapshots, reading with the history prepared for it.
140
+ # : (PreparedActivitySnapshots) -> BranchSnapshotRefresher
141
+ def branch_refresher: (PreparedActivitySnapshots) -> BranchSnapshotRefresher
127
142
 
128
- # : (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped, ?live_endpoint: untyped, ?snapshots: bool, ?group: Symbol?) -> ActivityTimelineBuilder
129
- def activity_builder: (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped, ?live_endpoint: untyped, ?snapshots: bool, ?group: Symbol?) -> ActivityTimelineBuilder
143
+ # : (untyped, from: untyped, to: untyped, within: untyped, version_scope: untyped, live_endpoint: untyped, view: ActivityView) -> ActivityTimelineBuilder
144
+ def activity_builder: (untyped, from: untyped, to: untyped, within: untyped, version_scope: untyped, live_endpoint: untyped, view: ActivityView) -> ActivityTimelineBuilder
130
145
 
131
146
  # : (untyped) -> RecordSnapshot?
132
147
  def snapshot_for_endpoint: (untyped) -> RecordSnapshot?
@@ -134,11 +149,8 @@ module PaperTrailDiff
134
149
  # : (untyped) -> RecordSnapshot?
135
150
  def historical_snapshot: (untyped) -> RecordSnapshot?
136
151
 
137
- # : (untyped) -> RecordSnapshot?
138
- def uncached_historical_snapshot: (untyped) -> RecordSnapshot?
139
-
140
- # : (untyped, untyped) -> RecordSnapshot?
141
- def snapshot_at: (untyped, untyped) -> RecordSnapshot?
152
+ # : (untyped, untyped, ?history: PreparedHistory?) -> RecordSnapshot?
153
+ def snapshot_at: (untyped, untyped, ?history: PreparedHistory?) -> RecordSnapshot?
142
154
 
143
155
  # : (untyped) -> RecordSnapshot
144
156
  def live_snapshot: (untyped) -> RecordSnapshot
@@ -1,7 +1,8 @@
1
1
  # Generated from lib/paper_trail_diff/preloaded_endpoint_batch_loader.rb with RBS::Inline
2
2
 
3
3
  module PaperTrailDiff
4
- # Validates and reuses caller-owned live records without issuing association queries.
4
+ # Validates and reuses caller-owned live records, reading again only the
5
+ # associations a preload of many records cannot have loaded correctly.
5
6
  class PreloadedEndpointBatchLoader
6
7
  # : (tree: AssociationTree, traversal: AssociationTraversal) -> void
7
8
  def initialize: (tree: AssociationTree, traversal: AssociationTraversal) -> void
@@ -20,5 +21,12 @@ module PaperTrailDiff
20
21
 
21
22
  # : (untyped, AssociationTree, String, untyped) -> void
22
23
  def validate_association: (untyped, AssociationTree, String, untyped) -> void
24
+
25
+ # Preloading many records applies a limit or offset to all of them
26
+ # together, so what a caller preloaded cannot be trusted: one record keeps
27
+ # another's share, or none. Such an association is read again for each
28
+ # record, as reloading reads it.
29
+ # : (untyped) -> void
30
+ def read_alone: (untyped) -> void
23
31
  end
24
32
  end
@@ -2,9 +2,16 @@
2
2
 
3
3
  module PaperTrailDiff
4
4
  # Shares association event discovery across every root in a prepared graph.
5
+ #
6
+ # The candidates are the records the prepared snapshots can hold: those
7
+ # recorded under an owner from the start onward, and those under it now. A
8
+ # key changed without a version is recorded only by the record's next
9
+ # version, or by the current row, either of which can come after the range,
10
+ # and the snapshots read it from there. ActivityTreeFilter leaves out the
11
+ # events of a candidate that was outside the tree throughout.
5
12
  class PreparedActivityIndex
6
- # : (PreparedRecordIndex, Array[untyped], start_at: untyped, end_at: untyped) -> void
7
- def initialize: (PreparedRecordIndex, Array[untyped], start_at: untyped, end_at: untyped) -> void
13
+ # : (PreparedRecordIndex, Array[untyped], start_at: untyped) -> void
14
+ def initialize: (PreparedRecordIndex, Array[untyped], start_at: untyped) -> void
8
15
 
9
16
  # : (untyped, Array[untyped]) -> void
10
17
  def register: (untyped, Array[untyped]) -> void
@@ -32,8 +39,8 @@ module PaperTrailDiff
32
39
  # : (untyped, Array[untyped], untyped, ActivityRange) -> Array[untyped]
33
40
  def child_ids: (untyped, Array[untyped], untyped, ActivityRange) -> Array[untyped]
34
41
 
35
- # The `belongs_to` targets each owner pointed at in the range: at its start
36
- # and after each change inside it, plus the live row at a current end.
42
+ # The `belongs_to` targets each owner pointed at from the range's start
43
+ # onward, plus the live row.
37
44
  # : (untyped, Array[untyped], untyped, ActivityRange) -> Array[ActivityTargetCandidateLoader::Row]
38
45
  def target_rows: (untyped, Array[untyped], untyped, ActivityRange) -> Array[ActivityTargetCandidateLoader::Row]
39
46
 
@@ -74,9 +74,19 @@ module PaperTrailDiff
74
74
  # : (Hash[Symbol, untyped], untyped) -> Array[untyped]
75
75
  def child_ids_for: (Hash[Symbol, untyped], untyped) -> Array[untyped]
76
76
 
77
+ # PT-AT records a checkpoint's membership as it is when the checkpoint is
78
+ # saved, so a tag attached earlier in the checkpoint's own transaction is a
79
+ # member there, unlike other associations, which a version reads as they
80
+ # were before its transaction. A member created in that transaction has no
81
+ # earlier state, so it is read as it was created, from its creation on.
82
+ # The checkpoint's membership also stands for earlier points, since the
83
+ # previous root version; the member did not exist at those yet.
77
84
  # : (untyped, untyped, untyped, untyped, bool) -> Array[untyped]?
78
85
  def habtm_records: (untyped, untyped, untyped, untyped, bool) -> Array[untyped]?
79
86
 
87
+ # : (untyped, untyped, untyped, bool) -> untyped
88
+ def habtm_member: (untyped, untyped, untyped, bool) -> untyped
89
+
80
90
  # A has_many through reads its parts unranked, as its query does. Its own
81
91
  # scope applies to each row, and a ranked read then keeps a record reached
82
92
  # twice as one member.