paper_trail_diff 0.12.0 → 0.13.0

data/sig/generated/paper_trail_diff/scoped_root_selection.rbs

@@ -25,6 +25,8 @@ module PaperTrailDiff
   # window. `where(status: 'published')` selects what is published now, which is
   # not the same set as what was published while the window was open.
   class ScopedRootSelection
+    PAGE_SIZE: ::Integer
+
     # A plain class rather than Data.define, which arrived in Ruby 3.2 while this
     # gem supports 3.1.
     class Result
@@ -36,20 +38,43 @@ module PaperTrailDiff
       def initialize: (records: Array[untyped], unreachable: Array[Array[String]]) -> void
     end
 
-    # : (untyped, time_range: TimeRange?, limit: Integer) -> void
-    def initialize: (untyped, time_range: TimeRange?, limit: Integer) -> void
+    # : (untyped, time_range: TimeRange?, limit: Integer, ?historical_filter: untyped, ?max_filter_versions: Integer) -> void
+    def initialize: (untyped, time_range: TimeRange?, limit: Integer, ?historical_filter: untyped, ?max_filter_versions: Integer) -> void
 
     # : () -> Result
     def call: () -> Result
 
     private
 
+    @historical_filter: untyped
+
     @limit: Integer
 
     @scope: untyped
 
     @time_range: TimeRange?
 
+    # Leaves the candidate set in the database. Plucking every root changed in
+    # the window would cost memory and a statement proportional to all activity
+    # in the window -- not to the relation or `limit:` -- so a report on one
+    # record could read every id in a busy table. A subquery keeps the work
+    # bounded by what the relation and the deletions actually contain.
+    # : () -> Result
+    def database_selection: () -> Result
+
+    # Comparing the two columns in SQL needs them to share a type: PostgreSQL
+    # rejects an integer key against a string item_id outright.
+    # : () -> bool
+    def comparable_keys?: () -> bool
+
+    # Changed in the window but without a row, found with an anti-join instead
+    # of comparing two plucked lists.
+    # : () -> Array[String]
+    def missing_ids: () -> Array[String]
+
+    # : () -> untyped
+    def window_versions: () -> untyped
+
     # Accepts a model class as readily as a relation: `Article` and
     # `Article.where(...)` both name a population, and `all` is what makes them
     # the same kind of thing.
@@ -70,10 +95,25 @@ module PaperTrailDiff
     # : (Array[String]) -> Array[String]
     def live_ids: (Array[String]) -> Array[String]
 
-    # Loading one past the limit is what turns an oversized page into an error
-    # rather than a silently truncated report.
-    # : (Array[String]) -> Array[untyped]
-    def selected_records: (Array[String]) -> Array[untyped]
+    # Deduplicate records rather than adding SQL DISTINCT: an otherwise valid
+    # relation may order by joined columns or select a PostgreSQL json column.
+    # Read bounded pages until the relation ends or too many unique roots appear.
+    # : (untyped) -> Array[untyped]
+    def selected_records: (untyped) -> Array[untyped]
+
+    # : (untyped, Integer) -> Array[untyped]
+    def record_page: (untyped, Integer) -> Array[untyped]
+
+    # Preserve explicit ordering: SQL Server rejects duplicate ORDER BY columns,
+    # even when the extra ordering would only have served as a tie-breaker.
+    # : () -> untyped
+    def ordered_scope: () -> untyped
+
+    # : (Integer) -> Integer
+    def page_limit: (Integer) -> Integer
+
+    # : (Integer) -> void
+    def reject_oversized!: (Integer) -> void
 
     # : (String) -> Array[String]
     def identity: (String) -> Array[String]

data/sig/generated/paper_trail_diff/snapshot.rbs

@@ -113,6 +113,10 @@ module PaperTrailDiff
     # : () -> RecordReference
     def reference: () -> RecordReference
 
+    # A copy holding a different state for one association.
+    # : (String, AssociationSnapshot) -> RecordSnapshot
+    def with_association: (String, AssociationSnapshot) -> RecordSnapshot
+
     # : () -> Hash[Symbol, untyped]
     def to_h: () -> Hash[Symbol, untyped]
 

data/sig/generated/paper_trail_diff/snapshot_normalizer.rbs

@@ -37,8 +37,15 @@ module PaperTrailDiff
     # : (untyped, tree: AssociationTree, path: String) -> snapshot_attributes
     def attributes_for: (untyped, tree: AssociationTree, path: String) -> snapshot_attributes
 
+    # Same exclusions as AR normalization, applied to an already typed state.
+    # : (PreparedRecordState, tree: AssociationTree, path: String, ?incoming: untyped, ?associations: snapshot_associations) -> RecordSnapshot
+    def from_state: (PreparedRecordState, tree: AssociationTree, path: String, ?incoming: untyped, ?associations: snapshot_associations) -> RecordSnapshot
+
     private
 
+    # : (String, RecordSnapshot) -> RecordSnapshot
+    def pool_state: (String, RecordSnapshot) -> RecordSnapshot
+
     @excluded_attributes: Hash[Array[untyped], Array[String]]
 
     @ignore_policy: IgnorePolicy
@@ -66,6 +73,12 @@ module PaperTrailDiff
     # : (untyped, Array[untyped], String) -> Array[String]
     def build_excluded_attributes: (untyped, Array[untyped], String) -> Array[String]
 
+    # `has_paper_trail skip:` columns are never written to a version, so history
+    # holds only their defaults. Compared with a live row they would report a
+    # change nobody recorded.
+    # : (untyped) -> Array[String]
+    def skipped_columns: (untyped) -> Array[String]
+
     # : (Array[untyped]) -> Array[String]
     def relationship_columns: (Array[untyped]) -> Array[String]
 

data/sig/generated/paper_trail_diff/step.rbs

@@ -22,7 +22,13 @@ module PaperTrailDiff
     # : () -> bool
     def empty?: () -> bool
 
-    # : () -> Hash[Symbol, untyped]
-    def to_h: () -> Hash[Symbol, untyped]
+    # The root event whose change this step reports.
+    # : () -> ActivityBoundary
+    def source_boundary: () -> ActivityBoundary
+
+    # The same shape as `ActivityStep#to_h`, so a consumer reads both step
+    # types alike; each boundary carries its own `version_id`.
+    # : (?metadata: bool) -> Hash[Symbol, untyped]
+    def to_h: (?metadata: bool) -> Hash[Symbol, untyped]
   end
 end

data/sig/generated/paper_trail_diff/stored_time_precision.rbs

@@ -0,0 +1,36 @@
+# Generated from lib/paper_trail_diff/stored_time_precision.rb with RBS::Inline
+
+module PaperTrailDiff
+  # Matches time values to the precision PaperTrail actually stored.
+  #
+  # PaperTrail's JSON serializer, and a `json` or `jsonb` object column, write
+  # times through ActiveSupport's JSON encoder, which keeps only
+  # `ActiveSupport::JSON::Encoding.time_precision` fractional digits
+  # (milliseconds by default). The live row keeps the database's precision, so
+  # comparing the two would report every timestamp as changed even though
+  # nothing was edited. Truncating every side to the stored precision is
+  # idempotent, so values that came from history are unaffected and only the
+  # digits history could never have held are dropped.
+  module StoredTimePrecision
+    NANOSECOND_DIGITS: ::Integer
+
+    JSON_COLUMN_TYPES: untyped
+
+    # Fractional digits a model's history keeps for times, or nil when the
+    # history is stored losslessly.
+    # : (untyped) -> Integer?
+    def self?.digits: (untyped) -> Integer?
+
+    # : (Hash[untyped, untyped], Integer?) -> Hash[untyped, untyped]
+    def self?.apply: (Hash[untyped, untyped], Integer?) -> Hash[untyped, untyped]
+
+    # : (untyped, Integer) -> untyped
+    def self?.truncate: (untyped, Integer) -> untyped
+
+    # : (untyped) -> bool
+    def self?.json_history?: (untyped) -> bool
+
+    # : () -> bool
+    def self?.json_serializer?: () -> bool
+  end
+end

data/sig/generated/paper_trail_diff/support.rbs

@@ -43,6 +43,13 @@ module PaperTrailDiff
     # : (untyped) -> bool
     def self?.versioned?: (untyped) -> bool
 
+    # `versions.item_id` is often a string column -- PaperTrail's setup for UUID
+    # keys -- while the model's own key is an integer. An id read from history
+    # is cast to the key's type, or the same record read once from history and
+    # once from its live row would count as two.
+    # : (untyped, untyped) -> untyped
+    def self?.record_id: (untyped, untyped) -> untyped
+
     # : (untyped) -> bool
     def self?.sequential_id?: (untyped) -> bool
 

data/sig/generated/paper_trail_diff/time_activity_timeline_builder.rbs

@@ -29,6 +29,9 @@ module PaperTrailDiff
     # : () -> [ActivityHistory, RootVersionPlan, ActivityStep?, RecordSnapshot?, untyped]
     def history_and_versions: () -> [ ActivityHistory, RootVersionPlan, ActivityStep?, RecordSnapshot?, untyped ]
 
+    # : () -> void
+    def reject_live_habtm!: () -> void
+
     # : (RootVersionPlan, untyped) -> [ActivityHistory, RootVersionPlan, ActivityStep?, RecordSnapshot?, untyped]
     def history_for: (RootVersionPlan, untyped) -> [ ActivityHistory, RootVersionPlan, ActivityStep?, RecordSnapshot?, untyped ]
 
@@ -40,8 +43,10 @@ module PaperTrailDiff
     # : (Array[untyped], untyped) -> Array[ActivityEvent]
     def events_through: (Array[untyped], untyped) -> Array[ActivityEvent]
 
-    # : (Array[untyped], Array[ActivityEvent]) -> ActivityHistory
-    def build_history: (Array[untyped], Array[ActivityEvent]) -> ActivityHistory
+    # Events after the last root version read the root from the live record
+    # when the window closes on it, as an explicit `to: record` range does.
+    # : (Array[untyped], Array[ActivityEvent], ?current: untyped) -> ActivityHistory
+    def build_history: (Array[untyped], Array[ActivityEvent], ?current: untyped) -> ActivityHistory
 
     # : (ActivityHistory, ActivityStep?) -> Array[ActivityStep]
     def activity_steps: (ActivityHistory, ActivityStep?) -> Array[ActivityStep]

data/sig/generated/paper_trail_diff/time_range.rbs

@@ -22,10 +22,19 @@ module PaperTrailDiff
     # : (untyped) -> untyped
     def trailing_scope: (untyped) -> untyped
 
+    # Each item's earliest version after the range, keyed by item id. One row
+    # per item comes back from a NOT EXISTS rather than a window function, so
+    # the query stays portable; a timestamp tie keeps the lower id.
+    # : (untyped) -> Hash[String, untyped]
+    def first_trailing_versions: (untyped) -> Hash[String, untyped]
+
     private
 
     @exclude_end: bool
 
+    # : (untyped) -> untyped
+    def after_end: (untyped) -> untyped
+
     # : () -> Range[Time]
     def query_range: () -> Range[Time]
 

data/sig/generated/paper_trail_diff/time_version_range.rbs

@@ -6,9 +6,6 @@ module PaperTrailDiff
     # : (untyped, time_range: TimeRange, ?version_scope: untyped, ?live_endpoint: untyped) -> void
     def initialize: (untyped, time_range: TimeRange, ?version_scope: untyped, ?live_endpoint: untyped) -> void
 
-    # : (?context_required: bool) -> Array[untyped]
-    def select: (?context_required: bool) -> Array[untyped]
-
     # : (?context_required: bool) -> RootVersionPlan
     def select_plan: (?context_required: bool) -> RootVersionPlan
 
@@ -22,9 +19,6 @@ module PaperTrailDiff
 
     @version_scope: untyped
 
-    # : () -> untyped
-    def versions_relation: () -> untyped
-
     # : (untyped) -> untyped
     def trailing_version: (untyped) -> untyped
 

data/sig/generated/paper_trail_diff/timeline_builder.rbs

@@ -3,8 +3,8 @@
 module PaperTrailDiff
   # Selects and compares a chronological slice of a record's version history.
   class TimelineBuilder
-    # : (untyped, from: untyped, to: untyped, snapshotter: untyped, ?within: untyped, ?versions: Array[untyped]?, ?version_scope: untyped, ?plan: RootVersionPlan?, ?live_endpoint: untyped) -> void
-    def initialize: (untyped, from: untyped, to: untyped, snapshotter: untyped, ?within: untyped, ?versions: Array[untyped]?, ?version_scope: untyped, ?plan: RootVersionPlan?, ?live_endpoint: untyped) -> void
+    # : (untyped, from: untyped, to: untyped, snapshotter: untyped, ?within: untyped, ?version_scope: untyped, ?plan: RootVersionPlan?, ?live_endpoint: untyped) -> void
+    def initialize: (untyped, from: untyped, to: untyped, snapshotter: untyped, ?within: untyped, ?version_scope: untyped, ?plan: RootVersionPlan?, ?live_endpoint: untyped) -> void
 
     # : () -> Array[Step]
     def build: () -> Array[Step]

data/sig/generated/paper_trail_diff/timeline_range.rbs

@@ -5,16 +5,20 @@ module PaperTrailDiff
   class TimelineRange
     BOUNDARY_SYMBOLS: untyped
 
+    # `:last` once named the last version, whose recorded state is the one
+    # *before* the latest change, so a range ending there silently dropped it.
+    LAST_REMOVED: ::String
+
     attr_reader from: untyped
 
     attr_reader to: untyped
 
     attr_reader time_range: TimeRange?
 
-    # : (untyped, from: untyped, to: untyped, within: untyped, ?versions: Array[untyped]?, ?version_scope: untyped, ?plan: RootVersionPlan?, ?live_endpoint: untyped) -> void
-    def initialize: (untyped, from: untyped, to: untyped, within: untyped, ?versions: Array[untyped]?, ?version_scope: untyped, ?plan: RootVersionPlan?, ?live_endpoint: untyped) -> void
+    # : (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped, ?plan: RootVersionPlan?, ?live_endpoint: untyped) -> void
+    def initialize: (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped, ?plan: RootVersionPlan?, ?live_endpoint: untyped) -> void
 
-    # A record with no versions has no first or last boundary to resolve, which
+    # A record with no versions has no first boundary to resolve, which
     # is an empty history rather than a bad request.
     # : () -> bool
     def unresolved?: () -> bool
@@ -26,9 +30,6 @@ module PaperTrailDiff
     # : (?context_required: bool) -> RootVersionPlan
     def select_plan: (?context_required: bool) -> RootVersionPlan
 
-    # : (?context_required: bool) -> Array[untyped]
-    def select: (?context_required: bool) -> Array[untyped]
-
     # : () -> bool
     def time?: () -> bool
 
@@ -56,15 +57,13 @@ module PaperTrailDiff
 
     @version_scope: untyped
 
-    @versions: Array[untyped]?
-
-    # : () -> Array[untyped]
-    def empty_versions: () -> Array[untyped]
+    # : () -> RootVersionPlan
+    def explicit_plan: () -> RootVersionPlan
 
     # : (untyped) -> bool
     def symbolic?: (untyped) -> bool
 
-    # Resolving `:first` and `:last` here keeps callers from depending on the
+    # Resolving `:first` here keeps callers from depending on the
     # order PaperTrail happens to give its versions association, which a caller
     # is also free to reorder.
     # : (untyped) -> untyped
@@ -73,9 +72,6 @@ module PaperTrailDiff
     # : () -> untyped
     def ordered_versions: () -> untyped
 
-    # : () -> untyped
-    def versions_relation: () -> untyped
-
     # : (untyped) -> TimeRange?
     def build_time_range: (untyped) -> TimeRange?
 

data/sig/generated/paper_trail_diff/timeline_snapshot_provider.rbs

@@ -21,6 +21,8 @@ module PaperTrailDiff
 
     @live_snapshotter: untyped
 
+    @snapshots: Hash[Array[untyped], RecordSnapshot?]
+
     @store: HistoricalSnapshotStore
   end
 end

data/sig/generated/paper_trail_diff/version_boundary.rbs

@@ -0,0 +1,23 @@
+# Generated from lib/paper_trail_diff/version_boundary.rb with RBS::Inline
+
+module PaperTrailDiff
+  # Places one version relative to another on the recorded timeline.
+  module VersionBoundary
+    # Whether `candidate` was recorded at or after `boundary`. Versions sharing
+    # a timestamp are ordered by id, which reflects insertion order only for
+    # sequential ids in one version table; any other tie cannot be ordered, and
+    # guessing would place a change on an arbitrary side of the boundary. A
+    # bare instant has no position among same-time versions, so it keeps them.
+    # : (untyped, untyped) -> bool
+    def self?.at_or_after?: (untyped, untyped) -> bool
+
+    # : (untyped) -> bool
+    def self?.version_record?: (untyped) -> bool
+
+    # : (untyped, untyped) -> bool
+    def self?.same_version?: (untyped, untyped) -> bool
+
+    # : (untyped, untyped) -> bool
+    def self?.orderable_tie?: (untyped, untyped) -> bool
+  end
+end

data/sig/generated/paper_trail_diff/version_query.rbs

@@ -0,0 +1,15 @@
+# Generated from lib/paper_trail_diff/version_query.rb with RBS::Inline
+
+module PaperTrailDiff
+  # Arel conditions shared by the version queries that need one row per item.
+  module VersionQuery
+    # Keeps each item's earliest version among those the block also accepts:
+    # no other version of the same item that the block accepts is earlier. A
+    # correlated NOT EXISTS stays portable where window functions are not.
+    # : (untyped) ?{ (untyped) -> untyped } -> untyped
+    def self?.no_earlier_version: (untyped) ?{ (untyped) -> untyped } -> untyped
+
+    # : (untyped, untyped) ?{ (untyped) -> untyped } -> untyped
+    def self?.earlier_version: (untyped, untyped) ?{ (untyped) -> untyped } -> untyped
+  end
+end

data/sig/generated/paper_trail_diff/version_range.rbs

@@ -6,18 +6,15 @@ module PaperTrailDiff
     # : (untyped, from: untyped, to: untyped, ?version_scope: untyped) -> void
     def initialize: (untyped, from: untyped, to: untyped, ?version_scope: untyped) -> void
 
-    # Same selection as `select`, but keeping the step pairs a filter implies.
+    # Keep both reconstruction boundaries and the step pairs a filter implies.
     # : () -> RootVersionPlan
     def select_plan_for_range: () -> RootVersionPlan
 
     # : () -> untyped
     def validated_relation: () -> untyped
 
-    # : () -> Array[untyped]
-    def select: () -> Array[untyped]
-
-    # : () -> Array[untyped]
-    def select_through_latest: () -> Array[untyped]
+    # : (untyped) -> RootVersionPlan
+    def select_plan_through_current: (untyped) -> RootVersionPlan
 
     private
 
@@ -29,14 +26,8 @@ module PaperTrailDiff
 
     @version_scope: untyped
 
-    # : () -> untyped
-    def versions_relation: () -> untyped
-
-    # : (untyped, ?through: untyped) -> Array[untyped]
-    def select_relation: (untyped, ?through: untyped) -> Array[untyped]
-
-    # : (untyped, ?through: untyped) -> RootVersionPlan
-    def select_plan: (untyped, ?through: untyped) -> RootVersionPlan
+    # : (untyped, ?through: untyped, ?live_endpoint: untyped) -> RootVersionPlan
+    def select_plan: (untyped, ?through: untyped, ?live_endpoint: untyped) -> RootVersionPlan
 
     # : (Array[untyped]) -> Array[untyped]
     def ordered: (Array[untyped]) -> Array[untyped]

data/sig/generated/paper_trail_diff.rbs

@@ -13,42 +13,39 @@ module PaperTrailDiff
   def self.compare: (untyped, untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?reload_live_endpoints: bool) -> Diff
 
   # Compares many independent endpoint pairs while batching current-record loading.
-  # : (Array[comparison_input], ?associations: Array[String | Symbol], ?ignore: ignore_option, ?reload_live_endpoints: bool) -> comparison_results
-  def self.compare_many: (Array[comparison_input], ?associations: Array[String | Symbol], ?ignore: ignore_option, ?reload_live_endpoints: bool) -> comparison_results
+  # : (Array[comparison_input], ?associations: Array[String | Symbol], ?ignore: ignore_option, ?reload_live_endpoints: bool, ?allow_expensive: bool) -> comparison_results
+  def self.compare_many: (Array[comparison_input], ?associations: Array[String | Symbol], ?ignore: ignore_option, ?reload_live_endpoints: bool, ?allow_expensive: bool) -> comparison_results
 
-  # Compares every adjacent reconstructed state in an inclusive version range.
+  # Compares every adjacent reconstructed state in an inclusive version range,
+  # by default the record's whole history through its current state.
   # : (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?version_scope: untyped, ?close_on: Symbol?) -> Array[Step]
   def self.timeline: (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?version_scope: untyped, ?close_on: Symbol?) -> Array[Step]
 
   # Compares adjacent root and selected-descendant activity boundaries.
-  # `reload_live_endpoints:` applies only when `to:` is a current record; the
-  # other range forms never read live state.
-  # : (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?reload_live_endpoints: bool, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool) -> Array[ActivityStep]
-  def self.activity_timeline: (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?reload_live_endpoints: bool, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool) -> Array[ActivityStep]
+  # `reload_live_endpoints:` applies whenever the range ends at the current
+  # record: an explicit `to:` record, the default range, or a window with no
+  # later version.
+  # : (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?reload_live_endpoints: bool, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool, ?group: Symbol?) -> Array[ActivityStep]
+  def self.activity_timeline: (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?reload_live_endpoints: bool, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool, ?group: Symbol?) -> Array[ActivityStep]
 
   # Builds an endpoint diff and root-checkpoint timeline while normalizing each version once.
   # : (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool, ?group: Symbol?) -> Analysis
   def self.analyze: (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool, ?group: Symbol?) -> Analysis
 
-  # Analyzes many roots over one shared time window, preparing their selected
-  # history once for the batch instead of once per record. Roots with no
-  # versions in the window return an empty `Analysis`.
-  #
-  # Pass `records` to analyze a list you assembled, which returns a Hash keyed
-  # by identity. Pass `scope:` with a `limit:` to have the roots selected for
-  # you from a relation, which returns a `ScopedAnalysis` -- the same Hash,
-  # plus the roots the relation could not reach. See `analyze_scope` for why
-  # that second collection exists.
-  # : (?Array[untyped]?, ?scope: untyped, ?limit: Integer?, ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?) -> (Hash[identity, Analysis] | ScopedAnalysis)
-  def self.analyze_many: (?Array[untyped]?, ?scope: untyped, ?limit: Integer?, ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?) -> (Hash[identity, Analysis] | ScopedAnalysis)
+  # Analyzes an array of records over one shared range, preparing their
+  # selected history once for the batch instead of once per record, and
+  # returns a frozen Hash keyed by identity. Roots with nothing to report in
+  # the window return an empty `Analysis`. To let a relation choose the
+  # records, use `analyze_scope`.
+  # : (Array[untyped], ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool, ?group: Symbol?, ?allow_expensive: bool) -> Hash[identity, Analysis]
+  def self.analyze_many: (Array[untyped], ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool, ?group: Symbol?, ?allow_expensive: bool) -> Hash[identity, Analysis]
 
   # Analyzes every root the relation reaches whose history moved inside the
-  # window, selecting them in a fixed number of queries rather than making the
-  # caller rediscover them.
+  # window. Joined duplicates are read in bounded pages and analyzed once.
   #
   # `limit:` is required and exceeding it raises. Selection moves into the gem
-  # here, so the bound on how much work a page can ask for has to move with
-  # it, and a truncated audit report is worse than a refused one.
+  # here. The relation's own limit/offset select the live page; this separate
+  # ceiling rejects too many unique roots rather than truncating that page.
   #
   # Returns a `ScopedAnalysis`, which destructures:
   #
@@ -57,7 +54,8 @@ module PaperTrailDiff
   #   )
   #
   # `unreachable` names roots that changed in the window but have no live row
-  # left. A relation's conditions are evaluated against the live table, so a
+  # left, independently of the live page's pagination and safety ceiling.
+  # A relation's conditions are evaluated against the live table, so a
   # destroyed root cannot be tested against them at all -- its history is
   # intact and the state it held at destruction may well have matched. Those
   # roots are reported rather than dropped so that a page auditing deletions
@@ -66,8 +64,14 @@ module PaperTrailDiff
   # Note also that a relation selects on current state, not on state during
   # the window: `where(status: 'published')` means published *now*, which is a
   # different set from what was published while the window was open.
-  # : (untyped, limit: Integer?, ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?) -> ScopedAnalysis
-  def self.analyze_scope: (untyped, limit: Integer?, ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?) -> ScopedAnalysis
+  # : (untyped, limit: Integer?, ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool, ?group: Symbol?, ?historical_filter: untyped, ?max_filter_versions: Integer, ?include_deleted: bool, ?allow_expensive: bool) -> ScopedAnalysis
+  def self.analyze_scope: (untyped, limit: Integer?, ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool, ?group: Symbol?, ?historical_filter: untyped, ?max_filter_versions: Integer, ?include_deleted: bool, ?allow_expensive: bool) -> ScopedAnalysis
+
+  # Recent root and selected-child activity through the current saved state.
+  # Historical windows remain explicit on analyze_scope; this entry point is
+  # deliberately named for a report through now rather than an as-of query.
+  # : (untyped, since: untyped, limit: Integer, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?snapshots: bool, ?group: Symbol?, ?include_deleted: bool, ?historical_filter: untyped, ?max_filter_versions: Integer, ?allow_expensive: bool) -> ScopedAnalysis
+  def self.report: (untyped, since: untyped, limit: Integer, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?snapshots: bool, ?group: Symbol?, ?include_deleted: bool, ?historical_filter: untyped, ?max_filter_versions: Integer, ?allow_expensive: bool) -> ScopedAnalysis
 
   # Returns the association macros this release can normalize.
   # : () -> Array[Symbol]
@@ -126,6 +130,8 @@ module PaperTrailDiff
 
   type comparison_results = Hash[identity, Diff]
 
+  type report_options = { within: untyped, activity: bool, version_scope: untyped, close_on: Symbol?, snapshots: bool, group: Symbol? }
+
   type ignore_option = Array[String | Symbol] | Hash[String | Symbol, untyped]
 
   type reference_key = :type | :id | "type" | "id"