paper_trail_diff 0.14.0 → 0.15.0

data/sig/generated/paper_trail_diff/activity_event.rbs

@@ -7,19 +7,26 @@ module PaperTrailDiff
 
     attr_reader branches: Array[String]?
 
-    # : (version: untyped, branches: Array[String]?) -> void
-    def initialize: (version: untyped, branches: Array[String]?) -> void
+    # : (version: untyped, branches: Array[String]?, ?join: bool) -> void
+    def initialize: (version: untyped, branches: Array[String]?, ?join: bool) -> void
 
     # : () -> bool
     def root?: () -> bool
+
+    # Whether the version is of a through's join row, which links the root to
+    # a target without being one.
+    # : () -> bool
+    def join?: () -> bool
+
+    @join: bool
   end
 
   # Accumulates each version once while retaining every selected root branch.
   class ActivityEventRegistry
     def initialize: () -> untyped
 
-    # : (Array[untyped], ?branch: String?) -> void
-    def add: (Array[untyped], ?branch: String?) -> void
+    # : (Array[untyped], ?branch: String?, ?join: bool) -> void
+    def add: (Array[untyped], ?branch: String?, ?join: bool) -> void
 
     # : () -> Array[ActivityEvent]
     def to_a: () -> Array[ActivityEvent]
@@ -34,6 +41,20 @@ module PaperTrailDiff
 
   # Resolves the branch union that PT-AT exposes atomically for one transaction.
   class ActivityTransactionGroups
+    # A range ending at a version ends at the state before that version's
+    # transaction: PT-AT rebuilds its associations without the changes saved
+    # alongside it. A descendant version from that transaction, such as the
+    # child update behind a `touch: true` parent version, is therefore past the
+    # end. Kept, it would open a step whose change the closing state cannot
+    # show, and that change would be reported nowhere. A range ending at a time
+    # has no transaction to stop before.
+    # : (Array[ActivityEvent], untyped) -> Array[ActivityEvent]
+    def self.before_closing: (Array[ActivityEvent], untyped) -> Array[ActivityEvent]
+
+    # A version without a transaction shares one with nothing.
+    # : (untyped) -> Array[untyped]?
+    def self.transaction_key: (untyped) -> Array[untyped]?
+
     # : (Array[ActivityEvent]) -> void
     def initialize: (Array[ActivityEvent]) -> void
 

data/sig/generated/paper_trail_diff/activity_history.rbs

@@ -24,14 +24,19 @@ module PaperTrailDiff
 
   # Builds activity steps while retaining root snapshots for combined analysis.
   class ActivityHistoryBuilder
-    # : (Array[untyped], Array[ActivityEvent], untyped, ?current: untyped, ?include_step: untyped, ?snapshots: bool) -> void
-    def initialize: (Array[untyped], Array[ActivityEvent], untyped, ?current: untyped, ?include_step: untyped, ?snapshots: bool) -> void
+    # `closing` is the snapshot after the last event when the range closes on
+    # the current record. Any other range ends at a root event, or at events
+    # after a window whose steps are not reported, so nothing reads it.
+    # : (Array[untyped], Array[ActivityEvent], untyped, view: ActivityView, ?current: untyped, ?include_step: untyped, ?closing: RecordSnapshot?) -> void
+    def initialize: (Array[untyped], Array[ActivityEvent], untyped, view: ActivityView, ?current: untyped, ?include_step: untyped, ?closing: RecordSnapshot?) -> void
 
     # : () -> ActivityHistory
     def call: () -> ActivityHistory
 
     private
 
+    @closing: RecordSnapshot?
+
     @current: untyped
 
     @events: Array[ActivityEvent]
@@ -40,6 +45,8 @@ module PaperTrailDiff
 
     @include_step: untyped
 
+    @passed_reported: bool
+
     @previous_boundary: ActivityBoundary?
 
     @previous_event: ActivityEvent?
@@ -52,20 +59,28 @@ module PaperTrailDiff
 
     @selected_last_snapshot: RecordSnapshot?
 
-    @snapshots: bool
-
     @snapshotter: untyped
 
     @steps: Array[ActivityStep]
 
+    @view: ActivityView
+
     # : () -> void
     def reset: () -> void
 
+    # : () -> ActivityTreeFilter
+    def filter: () -> ActivityTreeFilter
+
     # : () -> ActivitySnapshotSequence
     def sequence: () -> ActivitySnapshotSequence
 
-    # : (ActivityEvent, RecordSnapshot?) -> void
-    def consume: (ActivityEvent, RecordSnapshot?) -> void
+    # A left-out event bounds nothing. A reported step it would have opened
+    # still moves the reported range's end past it, to the next boundary.
+    # : (ActivityEvent, RecordSnapshot?, bool) -> void
+    def consume: (ActivityEvent, RecordSnapshot?, bool) -> void
+
+    # : (ActivityEvent) -> void
+    def pass: (ActivityEvent) -> void
 
     # : (RecordSnapshot?) -> void
     def capture_first: (RecordSnapshot?) -> void

data/sig/generated/paper_trail_diff/activity_range.rbs

@@ -13,8 +13,9 @@ module PaperTrailDiff
     # : (untyped) -> bool
     def include?: (untyped) -> bool
 
-    # Narrows an Active Record version relation by timestamp. Exact tie-breaking
-    # remains in #include? so this works for integer, UUID, and custom version IDs.
+    # Narrows an Active Record version relation by timestamp, and to the
+    # start's transaction. Exact tie-breaking remains in #include? so this
+    # works for integer, UUID, and custom version IDs.
     # : (untyped) -> untyped
     def scope: (untyped) -> untyped
 
@@ -33,10 +34,16 @@ module PaperTrailDiff
 
     @end_key: Array[untyped]?
 
+    @opening_transaction: Array[untyped]?
+
     @start_key: Array[untyped]?
 
     @start_time: untyped
 
+    # A range starting at a version starts before that version's transaction,
+    # where PT-AT reads its associations. A version saved earlier in it, such
+    # as the child update behind a `touch: true` parent version, is a change
+    # inside the range.
     # : (untyped, Array[untyped]) -> bool
     def after_start?: (untyped, Array[untyped]) -> bool
 

data/sig/generated/paper_trail_diff/activity_snapshot_sequence.rbs

@@ -1,13 +1,44 @@
 # Generated from lib/paper_trail_diff/activity_snapshot_sequence.rb with RBS::Inline
 
 module PaperTrailDiff
-  # Optional full/partial snapshot operations consumed by the activity sequence.
+  # Prepares the snapshot store for an activity build, one root at a time.
+  # Before that, it reads the live record a range closes on.
   class ActivitySnapshotProvider
-    # : (snapshotter: untyped, refresher: untyped, preparer: untyped, ?activity_index: untyped) -> void
-    def initialize: (snapshotter: untyped, refresher: untyped, preparer: untyped, ?activity_index: untyped) -> void
+    # `snapshotter` reads a full snapshot with a given history, and `refresher`
+    # builds the incremental refresher for one root's snapshots.
+    # : (store: HistoricalSnapshotStore, snapshotter: untyped, refresher: untyped) -> void
+    def initialize: (store: HistoricalSnapshotStore, snapshotter: untyped, refresher: untyped) -> void
+
+    # Roots a batch prepared together share its history, so consecutive ones
+    # share these snapshots too, and the caches their refresher builds. They
+    # are the same for any root with that history, so reusing them depends on
+    # nothing but the history.
+    # : (untyped, Array[untyped], ?start_at: untyped, ?end_at: untyped) -> PreparedActivitySnapshots
+    def prepare: (untyped, Array[untyped], ?start_at: untyped, ?end_at: untyped) -> PreparedActivitySnapshots
 
-    # : (untyped, Array[untyped], ?start_at: untyped, ?end_at: untyped) -> void
-    def prepare: (untyped, Array[untyped], ?start_at: untyped, ?end_at: untyped) -> void
+    # : (untyped, untyped) -> RecordSnapshot?
+    def call: (untyped, untyped) -> RecordSnapshot?
+
+    @last: PreparedActivitySnapshots?
+
+    @refresher: untyped
+
+    @snapshotter: untyped
+
+    @store: HistoricalSnapshotStore
+  end
+
+  # One root's full and incremental snapshots during an activity build. Each
+  # read passes along the history prepared for this root, so none depends on
+  # which root was prepared last.
+  class PreparedActivitySnapshots
+    attr_reader history: PreparedHistory?
+
+    # : (PreparedHistory?, store: HistoricalSnapshotStore, snapshotter: untyped, refresher: untyped) -> void
+    def initialize: (PreparedHistory?, store: HistoricalSnapshotStore, snapshotter: untyped, refresher: untyped) -> void
+
+    # : () -> PreparedActivityIndex?
+    def activity_index: () -> PreparedActivityIndex?
 
     # : (untyped, untyped) -> RecordSnapshot?
     def call: (untyped, untyped) -> RecordSnapshot?
@@ -18,16 +49,24 @@ module PaperTrailDiff
     # : (untyped, untyped, RecordSnapshot?, event: ActivityEvent) -> RecordSnapshot?
     def advance_root: (untyped, untyped, RecordSnapshot?, event: ActivityEvent) -> RecordSnapshot?
 
-    # : () -> PreparedActivityIndex?
-    def activity_index: () -> PreparedActivityIndex?
+    # The branches a refresh rebuilds, with this root's history.
+    # : (untyped, untyped, tree: AssociationTree, normalizer: SnapshotNormalizer) -> RecordSnapshot?
+    def custom: (untyped, untyped, tree: AssociationTree, normalizer: SnapshotNormalizer) -> RecordSnapshot?
 
-    @activity_index: untyped
+    # : (untyped, habtm_version: untyped) -> untyped
+    def association_reader: (untyped, habtm_version: untyped) -> untyped
 
-    @preparer: untyped
+    # : (untyped) -> [Hash[untyped, untyped], Hash[untyped, untyped]]?
+    def record_transition: (untyped) -> [ Hash[untyped, untyped], Hash[untyped, untyped] ]?
+
+    # : (untyped, ?direct: bool) -> [bool, untyped]
+    def record_after: (untyped, ?direct: bool) -> [ bool, untyped ]
 
     @refresher: untyped
 
     @snapshotter: untyped
+
+    @store: HistoricalSnapshotStore
   end
 
   # Builds chronological snapshots, refreshing only branches affected by prior events.

data/sig/generated/paper_trail_diff/activity_timeline_builder.rbs

@@ -1,17 +1,22 @@
 # Generated from lib/paper_trail_diff/activity_timeline_builder.rb with RBS::Inline
 
 module PaperTrailDiff
-  # Compares adjacent root and selected-descendant activity boundaries.
+  # Compares adjacent root and selected-descendant activity boundaries, between
+  # explicit endpoints or over a wall-clock window. Both replay the range's
+  # events into steps the same way, and close on the live row the same way.
+  # They differ in what they report and what closes them: explicit endpoints
+  # report every step between them and close on the endpoint asked for; a
+  # window reports only the events inside it, and closes on a final destroy,
+  # or on the live row when nothing recorded follows it.
   class ActivityTimelineBuilder
-    include ActivityGrouping
-
-    # : (untyped, range: TimelineRange, tree: AssociationTree, snapshotter: untyped, snapshots: bool, group: Symbol?) -> void
-    def initialize: (untyped, range: TimelineRange, tree: AssociationTree, snapshotter: untyped, snapshots: bool, group: Symbol?) -> void
+    # : (untyped, range: TimelineRange, tree: AssociationTree, snapshotter: untyped, view: ActivityView) -> void
+    def initialize: (untyped, range: TimelineRange, tree: AssociationTree, snapshotter: untyped, view: ActivityView) -> void
 
     # : () -> Array[ActivityStep]
     def build: () -> Array[ActivityStep]
 
-    # Builds all three version-bounded views from one activity snapshot pass.
+    # Builds the endpoint diff, the root timeline, and the activity from one
+    # activity snapshot pass.
     # : () -> Analysis
     def analyze: () -> Analysis
 
@@ -21,14 +26,14 @@ module PaperTrailDiff
 
     @record: untyped
 
-    @snapshots: bool
-
     @snapshotter: untyped
 
     @to: untyped
 
     @tree: AssociationTree
 
+    @view: ActivityView
+
     # : () -> Array[ActivityStep]
     def no_steps: () -> Array[ActivityStep]
 
@@ -40,6 +45,10 @@ module PaperTrailDiff
     # : () -> Array[ActivityStep]
     def build_between_versions: () -> Array[ActivityStep]
 
+    # Activity from the first to the last of the root versions.
+    # : (Array[untyped]) -> ActivityHistory
+    def version_history: (Array[untyped]) -> ActivityHistory
+
     # : () -> Array[ActivityStep]
     def build_to_current: () -> Array[ActivityStep]
 
@@ -48,14 +57,22 @@ module PaperTrailDiff
 
     # The explicit live endpoint and a batch's live closing endpoint use the
     # same selected plan. A version filter can close earlier, on its successor.
-    # : () -> [RootVersionPlan, Array[ActivityEvent], ActivityHistory, RecordSnapshot?, ActivityBoundary?]
-    def current_history: () -> [ RootVersionPlan, Array[ActivityEvent], ActivityHistory, RecordSnapshot?, ActivityBoundary? ]
+    # : () -> [RootVersionPlan, ActivityHistory, RecordSnapshot?, ActivityBoundary?]
+    def current_history: () -> [ RootVersionPlan, ActivityHistory, RecordSnapshot?, ActivityBoundary? ]
+
+    # Events up to the instant the current record was read. A range that a
+    # version filter closes earlier ends at that version, with no snapshot.
+    # : (RootVersionPlan, RecordSnapshot?, untyped) -> ActivityHistory
+    def history_until: (RootVersionPlan, RecordSnapshot?, untyped) -> ActivityHistory
 
-    # Without a closing boundary nothing reads the events or the closing pair,
-    # so their mutations cannot change an answer.
+    # Without a closing boundary nothing reads the closing pair, so its
+    # mutations cannot change an answer.
     # mutant:disable
-    # : (RootVersionPlan) -> [RootVersionPlan, Array[ActivityEvent], ActivityHistory, RecordSnapshot?, ActivityBoundary?]
-    def empty_history: (RootVersionPlan) -> [ RootVersionPlan, Array[ActivityEvent], ActivityHistory, RecordSnapshot?, ActivityBoundary? ]
+    # : (RootVersionPlan) -> [RootVersionPlan, ActivityHistory, RecordSnapshot?, ActivityBoundary?]
+    def empty_history: (RootVersionPlan) -> [ RootVersionPlan, ActivityHistory, RecordSnapshot?, ActivityBoundary? ]
+
+    # : (untyped) -> ActivityBoundary
+    def current_boundary: (untyped) -> ActivityBoundary
 
     # : () -> [RecordSnapshot?, untyped]
     def capture_current: () -> [ RecordSnapshot?, untyped ]
@@ -63,33 +80,120 @@ module PaperTrailDiff
     # : () -> void
     def validate_current_range!: () -> void
 
-    # : (Array[untyped], ?range_start: untyped, ?range_end: untyped) -> Array[ActivityEvent]
-    def collect_events: (Array[untyped], ?range_start: untyped, ?range_end: untyped) -> Array[ActivityEvent]
-
-    # : (Array[untyped], ?end_at: untyped) -> void
-    def prepare_history: (Array[untyped], ?end_at: untyped) -> void
-
     # Appends the transition into an explicit closing boundary, which is either
     # a requested current record or the absence a final root destroy leaves.
-    # Either follows the root versions, which are themselves events.
-    # : (ActivityHistory, Array[ActivityEvent], ActivityBoundary?, RecordSnapshot?) -> Array[ActivityStep]
-    def activity_steps: (ActivityHistory, Array[ActivityEvent], ActivityBoundary?, RecordSnapshot?) -> Array[ActivityStep]
+    # Either follows the root versions, which are themselves events, so the
+    # last boundary the history kept opens it.
+    # : (ActivityHistory, ActivityBoundary?, RecordSnapshot?) -> Array[ActivityStep]
+    def activity_steps: (ActivityHistory, ActivityBoundary?, RecordSnapshot?) -> Array[ActivityStep]
 
     # A destroyed root has no later version, but its own event states that
     # nothing follows it, so the removal can still close the timeline.
     # : (Array[untyped]) -> ActivityBoundary?
     def destroyed_boundary: (Array[untyped]) -> ActivityBoundary?
 
-    # : (Array[untyped], Array[ActivityEvent], ?current: untyped) -> ActivityHistory
-    def event_history: (Array[untyped], Array[ActivityEvent], ?current: untyped) -> ActivityHistory
-
     # Only the activity view gains the closing removal. The endpoint diff and
     # the root timeline keep their `compare` and `timeline` semantics, under
     # which the state at a destroy version is the state before the deletion.
-    # : (RootVersionPlan, Array[ActivityEvent], ActivityHistory) -> Analysis
-    def build_analysis: (RootVersionPlan, Array[ActivityEvent], ActivityHistory) -> Analysis
+    # : (RootVersionPlan, ActivityHistory) -> Analysis
+    def build_analysis: (RootVersionPlan, ActivityHistory) -> Analysis
 
-    # : () -> TimeActivityTimelineBuilder
-    def time_builder: () -> TimeActivityTimelineBuilder
+    # : () -> Array[ActivityStep]
+    def window_steps: () -> Array[ActivityStep]
+
+    # : () -> Analysis
+    def analyze_window: () -> Analysis
+
+    # A window with a closing step ends at what closed it: the live row, or
+    # nothing after a destroy, where no live row is read. One that ends before
+    # a later event ends at the state that event found.
+    # : (ActivityHistory, ActivityStep?, RecordSnapshot?) -> RecordSnapshot?
+    def window_final_snapshot: (ActivityHistory, ActivityStep?, RecordSnapshot?) -> RecordSnapshot?
+
+    # : () -> [ActivityHistory, RootVersionPlan, ActivityStep?, RecordSnapshot?, untyped]
+    def window_history: () -> [ ActivityHistory, RootVersionPlan, ActivityStep?, RecordSnapshot?, untyped ]
+
+    # Nothing reads a window's closing step, live snapshot, or capture time
+    # when it reported nothing, so mutations of those cannot change an answer.
+    # mutant:disable
+    # : (RootVersionPlan) -> [ActivityHistory, RootVersionPlan, ActivityStep?, RecordSnapshot?, untyped]
+    def empty_window: (RootVersionPlan) -> [ ActivityHistory, RootVersionPlan, ActivityStep?, RecordSnapshot?, untyped ]
+
+    # A window with no selected event reports nothing. Any other has a
+    # boundary after its last one: the plan refuses a window that has no later
+    # version, ends on no destroy, and does not close on the live row.
+    # : (RootVersionPlan, untyped) -> [ActivityHistory, RootVersionPlan, ActivityStep?, RecordSnapshot?, untyped]
+    def window_replay: (RootVersionPlan, untyped) -> [ ActivityHistory, RootVersionPlan, ActivityStep?, RecordSnapshot?, untyped ]
+
+    # One live read serves both the closing activity step and the endpoint the
+    # analysis reports, which would otherwise reconstruct the graph twice.
+    # : (RootVersionPlan) -> RecordSnapshot?
+    def window_live_snapshot: (RootVersionPlan) -> RecordSnapshot?
+
+    # Root versions inside the window that the plan does not report are context
+    # rather than mutations: the version appended to reveal the last selected
+    # change, and anything a filter excluded but the replay still walks. Neither
+    # may be counted as a selected mutation. Descendant events are not filtered,
+    # so window membership is the whole test for them.
+    # : (Array[ActivityEvent], RootVersionPlan) -> Array[ActivityEvent]
+    def selected_events: (Array[ActivityEvent], RootVersionPlan) -> Array[ActivityEvent]
+
+    # A window either closes on the absence its final destruction leaves, or on
+    # current state when it reaches past everything recorded. Both are boundaries
+    # no version can supply.
+    #
+    # Everything recorded means on every requested path, not only the root's
+    # own versions. When an association changed after the window, its last
+    # step already ends at that change, at the state the window left; closing
+    # on current state would add the later change to a window it was not in.
+    # : (ActivityHistory, ActivityEvent, RootVersionPlan, untyped, RecordSnapshot?, Array[ActivityEvent]) -> ActivityStep?
+    def window_closing: (ActivityHistory, ActivityEvent, RootVersionPlan, untyped, RecordSnapshot?, Array[ActivityEvent]) -> ActivityStep?
+
+    # : (ActivityHistory, ActivityEvent) -> ActivityStep
+    def window_destroyed_step: (ActivityHistory, ActivityEvent) -> ActivityStep
+
+    # The last boundary reached is where current state is compared from, which
+    # is the final event rather than the final root version once descendants
+    # have moved since it. A selected event is a boundary the history kept.
+    # : (ActivityHistory, untyped, untyped, RecordSnapshot?) -> ActivityStep
+    def window_current_step: (ActivityHistory, untyped, untyped, RecordSnapshot?) -> ActivityStep
+
+    # : (ActivityEvent) -> bool
+    def terminal_destroy?: (ActivityEvent) -> bool
+
+    # : () -> void
+    def reject_live_habtm!: () -> void
+
+    # : () -> Array[String]?
+    def root_recorded: () -> Array[String]?
+
+    # A window prepares from its start, explicit endpoints from their first
+    # version.
+    # : (Array[untyped], ?end_at: untyped) -> untyped
+    def prepare_history: (Array[untyped], ?end_at: untyped) -> untyped
+
+    # A window collects from its start, explicit endpoints from their first
+    # version. Explicit endpoints also stop before the rest of the closing
+    # version's transaction (see ActivityTransactionGroups.before_closing); a
+    # window keeps every event it collected and reports only those inside it.
+    # : (Array[untyped], untyped, range_end: untyped) -> Array[ActivityEvent]
+    def collect_events: (Array[untyped], untyped, range_end: untyped) -> Array[ActivityEvent]
+
+    # Events after the last root version read the root from the live record
+    # when the range closes on it. Explicit endpoints report every step, as
+    # their range includes every version.
+    # : (Array[untyped], Array[ActivityEvent], untyped, ?current: untyped, ?closing: RecordSnapshot?) -> ActivityHistory
+    def replay: (Array[untyped], Array[ActivityEvent], untyped, ?current: untyped, ?closing: RecordSnapshot?) -> ActivityHistory
+
+    # The step from the last boundary the history reached to one that closes
+    # the range.
+    # : (ActivityHistory, ActivityBoundary, ActivityBoundary, RecordSnapshot?) -> ActivityStep
+    def step_from_last: (ActivityHistory, ActivityBoundary, ActivityBoundary, RecordSnapshot?) -> ActivityStep
+
+    # : (Array[ActivityStep]) -> Array[ActivityStep]
+    def present: (Array[ActivityStep]) -> Array[ActivityStep]
+
+    # : (RootVersionPlan, ActivityHistory, final: RecordSnapshot?, steps: Array[ActivityStep], ?closing_snapshot: RecordSnapshot?, ?captured_at: untyped) -> Analysis
+    def analysis: (RootVersionPlan, ActivityHistory, final: RecordSnapshot?, steps: Array[ActivityStep], ?closing_snapshot: RecordSnapshot?, ?captured_at: untyped) -> Analysis
   end
 end

data/sig/generated/paper_trail_diff/activity_tree_filter.rbs

@@ -0,0 +1,73 @@
+# Generated from lib/paper_trail_diff/activity_tree_filter.rb with RBS::Inline
+
+module PaperTrailDiff
+  # Leaves out the events of records that were outside the root's tree.
+  #
+  # A record found in the tree at one time in a range brings every version it
+  # saved in the range, including those it saved while it belonged elsewhere:
+  # a comment edited on another article before it moved to this one, or after
+  # it left a scope. Such a version changes nothing the root shows. As a
+  # boundary it would open a step of its own, and inside a transaction, where
+  # a change surfaces one event late, that step would take the credit for the
+  # root's own change.
+  #
+  # PT-AT reads associations as they were before a transaction, so a record
+  # is judged by two snapshots: the one at its transaction's first event, and
+  # the one after its last, which is the next event's or what the range
+  # closes on. A record in neither was outside the tree throughout.
+  #
+  # The root's own events are always kept, and so are the versions of a
+  # through's join rows, which a snapshot does not hold, and an event whose
+  # step is not reported, which only bounds one that is.
+  class ActivityTreeFilter
+    # `closing` is the snapshot after the last event: the current record's,
+    # or nil when nothing follows, as after the root's destruction.
+    # : (Array[ActivityEvent], reported: untyped, closing: RecordSnapshot?) -> void
+    def initialize: (Array[ActivityEvent], reported: untyped, closing: RecordSnapshot?) -> void
+
+    # Yields each event of the sequence with its snapshot, and whether to keep
+    # it, in order.
+    # : (untyped) { (ActivityEvent, RecordSnapshot?, bool) -> void } -> void
+    def call: (untyped) { (ActivityEvent, RecordSnapshot?, bool) -> void } -> void
+
+    private
+
+    @closing: RecordSnapshot?
+
+    @ends: Array[Integer]
+
+    @reported: untyped
+
+    @starts: Array[Integer]
+
+    @types: Hash[String, Array[String?]]
+
+    # : (ActivityEvent, Integer, Array[[ActivityEvent, RecordSnapshot?]]) -> bool
+    def keep?: (ActivityEvent, Integer, Array[[ ActivityEvent, RecordSnapshot? ]]) -> bool
+
+    # : (ActivityEvent) -> bool
+    def reported?: (ActivityEvent) -> bool
+
+    # Where each event's transaction starts, and the position just past its
+    # last event. Two transactions can interleave, so a transaction's events
+    # need not be adjacent.
+    # : (Array[ActivityEvent]) -> [Array[Integer], Array[Integer]]
+    def spans: (Array[ActivityEvent]) -> [ Array[Integer], Array[Integer] ]
+
+    # A version saved outside a transaction is a transaction of its own,
+    # keyed by its position.
+    # : (Array[ActivityEvent]) -> Array[Array[untyped] | Integer]
+    def transaction_keys: (Array[ActivityEvent]) -> Array[Array[untyped] | Integer]
+
+    # : (RecordSnapshot?, ActivityEvent) -> bool
+    def holds?: (RecordSnapshot?, ActivityEvent) -> bool
+
+    # : (AssociationSnapshot, Array[String?], untyped) -> bool
+    def contains?: (AssociationSnapshot, Array[String?], untyped) -> bool
+
+    # A version names its record's base class, and a snapshot the record's
+    # own class, which may be any subclass of it.
+    # : (String) -> Array[String?]
+    def types: (String) -> Array[String?]
+  end
+end

data/sig/generated/paper_trail_diff/activity_version_collector.rbs

@@ -6,6 +6,8 @@ module PaperTrailDiff
     # : (untyped, root_versions: Array[untyped], tree: AssociationTree, ?range_start: untyped, ?range_end: untyped, ?prepared: PreparedActivityIndex?) -> void
     def initialize: (untyped, root_versions: Array[untyped], tree: AssociationTree, ?range_start: untyped, ?range_end: untyped, ?prepared: PreparedActivityIndex?) -> void
 
+    # A tie between version tables, or between ids that do not count up,
+    # raises rather than building a timeline in an arbitrary order.
     # : () -> Array[ActivityEvent]
     def call: () -> Array[ActivityEvent]
 

data/sig/generated/paper_trail_diff/activity_view.rbs

@@ -0,0 +1,42 @@
+# Generated from lib/paper_trail_diff/activity_view.rb with RBS::Inline
+
+module PaperTrailDiff
+  # How a request presents its activity steps: whether they keep their
+  # snapshots, whether a transaction's steps merge into one, and which of
+  # their versions' recorded changes they carry. Built and checked once per
+  # request, and read the same way by both activity builders, or the same
+  # history would read differently depending on how it was asked for.
+  class ActivityView
+    # Options only an activity view uses are refused without one.
+    # : (activity: bool, snapshots: bool, group: Symbol?, recorded: IgnorePolicy?) -> ActivityView
+    def self.build: (activity: bool, snapshots: bool, group: Symbol?, recorded: IgnorePolicy?) -> ActivityView
+
+    # : (?snapshots: bool, ?group: Symbol?, ?recorded: IgnorePolicy?) -> void
+    def initialize: (?snapshots: bool, ?group: Symbol?, ?recorded: IgnorePolicy?) -> void
+
+    # Merging a group compares its outer states, so the snapshots must survive
+    # the build even when the caller did not ask to keep them.
+    # : () -> bool
+    def retain?: () -> bool
+
+    # The attributes a boundary's version recorded, when they were asked for.
+    # : (root: bool) -> Array[String]?
+    def recorded_attributes: (root: bool) -> Array[String]?
+
+    # Applied last, to finished steps, so grouping sees the same timeline the
+    # caller would otherwise have received.
+    # : (Array[ActivityStep]) -> Array[ActivityStep]
+    def present: (Array[ActivityStep]) -> Array[ActivityStep]
+
+    private
+
+    @group: Symbol?
+
+    @recorded: IgnorePolicy?
+
+    @snapshots: bool
+
+    # : () -> bool
+    def grouping?: () -> bool
+  end
+end

data/sig/generated/paper_trail_diff/analysis.rbs

@@ -14,7 +14,9 @@ module PaperTrailDiff
     attr_reader to_snapshot: RecordSnapshot?
 
     # The result for a record whose requested history contains no versions,
-    # which is an empty history rather than a failed request.
+    # which is an empty history rather than a failed request. Its snapshots
+    # are nil because no state was read, not because the record was absent:
+    # reading one would rebuild the whole graph, per record in a batch.
     # : () -> Analysis
     def self.empty: () -> Analysis
 
@@ -23,6 +25,11 @@ module PaperTrailDiff
     # : (diff: Diff, timeline: Array[Step], ?activity_timeline: Array[ActivityStep]?, ?from_snapshot: RecordSnapshot?, ?to_snapshot: RecordSnapshot?) -> void
     def initialize: (diff: Diff, timeline: Array[Step], ?activity_timeline: Array[ActivityStep]?, ?from_snapshot: RecordSnapshot?, ?to_snapshot: RecordSnapshot?) -> void
 
+    # Every activity step's rows, in time order. Only the activity timeline says
+    # who made each change, so an analysis built without it has no rows to give.
+    # : () -> Array[ChangeRow]
+    def change_rows: () -> Array[ChangeRow]
+
     # Reconstructed endpoint states are opt-in, because they carry the whole
     # selected graph whether or not anything changed, which dwarfs the rest of
     # the payload for a wide graph.

data/sig/generated/paper_trail_diff/analysis_batch.rbs

@@ -5,8 +5,8 @@ module PaperTrailDiff
   # versions and preparing their association history once for the whole batch
   # rather than once per root.
   class AnalysisBatch
-    # : (Array[untyped], time_range: TimeRange?, live_loader: untyped, history_preparer: untyped, analyzer: untyped, ?version_scope: untyped, ?close_on_current: bool, ?context_required: bool) -> void
-    def initialize: (Array[untyped], time_range: TimeRange?, live_loader: untyped, history_preparer: untyped, analyzer: untyped, ?version_scope: untyped, ?close_on_current: bool, ?context_required: bool) -> void
+    # : (Array[untyped], time_range: TimeRange?, live_loader: untyped, history_preparer: untyped, analyzer: untyped, ?version_scope: untyped, ?context_required: bool) -> void
+    def initialize: (Array[untyped], time_range: TimeRange?, live_loader: untyped, history_preparer: untyped, analyzer: untyped, ?version_scope: untyped, ?context_required: bool) -> void
 
     # : () -> Hash[identity, Analysis]
     def call: () -> Hash[identity, Analysis]
@@ -15,8 +15,6 @@ module PaperTrailDiff
 
     @analyzer: untyped
 
-    @close_on_current: bool
-
     @context_required: bool
 
     @history_preparer: untyped
@@ -29,11 +27,6 @@ module PaperTrailDiff
 
     @version_scope: untyped
 
-    # A filter is a callable that narrows the version relation, so it is checked
-    # up front rather than failing partway through a batch.
-    # : (untyped) -> untyped
-    def validated_scope: (untyped) -> untyped
-
     # : () -> Array[untyped]
     def validated_records: () -> Array[untyped]
 
@@ -42,21 +35,21 @@ module PaperTrailDiff
     # The roots are preloaded first, because preparation reads their current
     # association state as a fallback and would otherwise walk it one root at a
     # time.
-    # : (Array[untyped], Hash[Array[String], RootVersionPlan], Hash[Array[String], untyped]) -> void
-    def prepare: (Array[untyped], Hash[Array[String], RootVersionPlan], Hash[Array[String], untyped]) -> void
+    # : (Array[untyped], Hash[Array[String], RootVersionPlan], Hash[Array[String], untyped], Hash[Array[String], TimeRange]) -> void
+    def prepare: (Array[untyped], Hash[Array[String], RootVersionPlan], Hash[Array[String], untyped], Hash[Array[String], TimeRange]) -> void
 
     # : (Array[untyped], Hash[Array[String], RootVersionPlan]) -> bool
     def closes_live?: (Array[untyped], Hash[Array[String], RootVersionPlan]) -> bool
 
     # A plan closing on the live record reads history up to now; the others
     # stop at the window, so a past window does not load everything since.
-    # : (Array[untyped], ?live: bool) -> Hash[Symbol, untyped]
-    def preparation_range: (Array[untyped], ?live: bool) -> Hash[Symbol, untyped]
+    # : (Array[untyped], Hash[Array[String], TimeRange], live: bool) -> Hash[Symbol, untyped]
+    def preparation_range: (Array[untyped], Hash[Array[String], TimeRange], live: bool) -> Hash[Symbol, untyped]
 
     # A root with no versions in range has nothing to report, which is an empty
     # result rather than a failed request -- unless an activity view closes it
     # on current state, where its descendants may still have moved.
-    # : (untyped, RootVersionPlan) -> Analysis
-    def analysis_for: (untyped, RootVersionPlan) -> Analysis
+    # : (untyped, RootVersionPlan, TimeRange?) -> Analysis
+    def analysis_for: (untyped, RootVersionPlan, TimeRange?) -> Analysis
   end
 end