paper_trail_diff 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fac7dbbad6368383d2b73f4c5acbdcabb1599da6c096a5c8363327a8602a1298
-  data.tar.gz: 7657cc9ae4b3e8f7d9f1026ac06fb93b6571ba7258bca66183b84053bb8469c0
+  metadata.gz: a4d3c1e15ef20c4e3d05f5c0442d7e55cd0eb811a15766d2119a3cf35b2e729c
+  data.tar.gz: 4cc8dceb10e7aa71f1feb7d9fcc3917040bec4b2cc69641b4b3817d6761aad94
 SHA512:
-  metadata.gz: adadf85c15151889247d0791ffc944731c781c6dc3f4d23b4a04fa046e489b74f2a6501a16fb53386e6c80c3fae4d6c583d4b91db198bfbe8919a3a19eaf1a4e
-  data.tar.gz: 2a3bf4422b73c513981b519d04f0c556574f75ebc08963fab606f872c2428acac2455869675318ae75d8f71bddeb208e952642eeafedae7131b4745b5f36f534
+  metadata.gz: 3887a515ee90f1c14b890a21d4a91b4892f4097b74c9ec27f136fd8476f01cd285c0a310a03b0c528e709cdca299bca2e243522844d09a86d272c043e48879b1
+  data.tar.gz: a1390db78cc31cbf20420fd18b536ad8cd826de4927943cbdddc08b7a31f9dad5f81acee77db97059f044ad435bd3170e54f8ef2ccd5c68f3e256bfa5d848642

data/CHANGELOG.md

@@ -3,6 +3,26 @@
 All notable changes to this project will be documented in this file. The
 project follows [Semantic Versioning](https://semver.org/).
 
+## [0.5.0] - 2026-08-11
+
+### Added
+
+- Add `analyze_many`, which analyzes many roots over one shared `within:` window,
+  or over each root's whole history when the window is omitted, selecting their
+  versions and preparing their history once for the batch. Query cost is flat in
+  the number of roots for the endpoint diff and checkpoint timeline; descendant
+  event discovery under `activity: true` remains per-root. A root with no
+  versions in range returns an empty `Analysis`, and roots are supplied as live
+  records so a root deleted inside the window cannot be included.
+- Accept `:first` and `:last` as `compare_many` endpoints, resolved against the
+  record the pair's other endpoint names, in two queries per model class rather
+  than one lookup per root. A root with no recorded history compares as an empty
+  `Diff`, and an unanchored `{ from: :first, to: :last }` raises.
+- Accept `reload_live_endpoints:` on `activity_timeline`, which reads live state
+  whenever `to:` is a current record but previously had no way to reuse an
+  already-preloaded graph. `timeline` and `analyze` are bounded by versions and
+  never read live state, so the option is deliberately absent there.
+
 ## [0.4.0] - 2026-08-11
 
 ### Added

data/README.md

@@ -213,6 +213,21 @@ diffs = PaperTrailDiff.compare_many(
 diffs.fetch(["Order", orders.first.id.to_s]) # => PaperTrailDiff::Diff
 ```
 
+Endpoints may also be given as `:first` or `:last`, resolved against the record
+the pair's other endpoint names. That replaces the lookup above entirely, and
+resolves every root in two queries per model class rather than one per root:
+
+```ruby
+diffs = PaperTrailDiff.compare_many(
+  orders.map { |order| { from: :first, to: order } },
+  associations: [:line_items]
+)
+```
+
+A symbol carries no identity of its own, so `{ from: :first, to: :last }` raises
+rather than guessing. A root with no recorded history resolves to an empty
+`Diff`, matching how the timeline APIs answer the same question.
+
 Root identities must be unique within one call. Historical reconstruction for
 ordinary versioned, unscoped association paths is also prepared across the
 collection. Paths that require the existing point-in-time PT-AT fallback retain
@@ -225,8 +240,10 @@ must observe one atomic snapshot.
 
 ### Reuse already-preloaded current endpoints
 
-`compare` and `compare_many` reload current endpoints by default. A caller that
-already owns a consistent, fully preloaded graph may opt out:
+`compare`, `compare_many`, and `activity_timeline(..., to: record)` reload
+current endpoints by default. A caller that already owns a consistent, fully
+preloaded graph may opt out. The option has no effect on `timeline` or
+`analyze`, which are bounded by versions and never read live state:
 
 ```ruby
 orders = Order.where(id: order_ids).preload(line_items: :product).to_a
@@ -285,6 +302,43 @@ ActiveSupport::Notifications.subscribed(callback, "sql.active_record") do
 end
 ```
 
+## Analyze many records over one window
+
+`analyze_many` answers "what changed for these records during this period" for a
+whole collection, selecting every root's versions and preparing their selected
+association history once for the batch:
+
+```ruby
+results = PaperTrailDiff.analyze_many(
+  Order.where(status: "open").to_a,
+  within: Time.zone.parse("2026-08-01")...Time.zone.parse("2026-09-01"),
+  associations: [:line_items]
+)
+
+results.fetch(["Order", order.id.to_s]).diff      # net change across the window
+results.fetch(["Order", order.id.to_s]).timeline  # its checkpoint steps
+```
+
+Results are a frozen hash keyed by `[item_type, item_id]` strings, and each
+value is the same `Analysis` that `analyze` returns for one record. A root with
+no versions inside the window gets an empty `Analysis` rather than raising, so a
+listing page needs no special case. Root identities must be unique.
+
+Omit `within:` to analyze each root's whole recorded history instead, which is
+the batched equivalent of `analyze(record, from: :first, to: :last)`. Explicit
+version endpoints are not accepted, because a single pair cannot mean the same
+thing for every root.
+
+Query cost is flat in the number of roots for the diff and timeline views:
+selecting versions and preparing history are both shared across the batch. On a
+twenty-root batch that is 7 queries against 120 for the same work done one
+record at a time. Passing `activity: true` also works and returns the same
+results, but discovering descendant events is inherently per-root, so that view
+batches far less.
+
+Roots are supplied as live records, so a root deleted inside the window cannot
+be included; use `activity_timeline` for a history that ends in a deletion.
+
 ## Build a root-checkpoint timeline
 
 `timeline` accepts two version objects from the supplied record's history, or

data/lib/paper_trail_diff/analysis_batch.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # Builds one Analysis per root over a shared range, selecting every root's
+  # 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) -> void
+    def initialize(records, time_range:, live_loader:, history_preparer:, analyzer:)
+      @records = records
+      @time_range = time_range
+      @live_loader = live_loader
+      @history_preparer = history_preparer
+      @analyzer = analyzer
+    end
+
+    #: () -> Hash[identity, Analysis]
+    def call
+      records = validated_records
+      selected = BatchedRootVersions.new(records, time_range: @time_range).call
+      prepare(records, selected)
+      records.to_h do |record|
+        key = Endpoint.identity(record)
+        [Support.immutable_copy(key), analysis_for(record, selected.fetch(key, []))]
+      end.freeze
+    end
+
+    private
+
+    # @rbs @records: Array[untyped]
+    # @rbs @time_range: TimeRange?
+    # @rbs @live_loader: untyped
+    # @rbs @history_preparer: untyped
+    # @rbs @analyzer: untyped
+
+    #: () -> Array[untyped]
+    def validated_records
+      raise ConfigurationError, 'records: must be an array' unless @records.is_a?(Array)
+
+      @records.each { |record| Endpoint.validate!(record) }
+      identities = @records.map { |record| Endpoint.identity(record) }
+      return @records if identities.uniq.length == identities.length
+
+      raise ConfigurationError, 'records: identities must be unique'
+    end
+
+    # Association history is prepared per model class across every selected root
+    # version, which is the work that would otherwise repeat for each record.
+    # 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], Array[untyped]]) -> void
+    def prepare(records, selected)
+      loaded = @live_loader.call(records)
+      records.group_by(&:class).each_value do |grouped|
+        versions = grouped.flat_map { |record| selected.fetch(Endpoint.identity(record), []) }
+        next if versions.empty?
+
+        roots = grouped.map { |record| loaded.fetch(Endpoint.identity(record), record) }
+        @history_preparer.call(roots, versions)
+      end
+    end
+
+    # A root with no versions in range has nothing to report, which is an empty
+    # result rather than a failed request.
+    #: (untyped, Array[untyped]) -> Analysis
+    def analysis_for(record, versions)
+      return Analysis.empty if versions.empty?
+
+      @analyzer.call(record, versions)
+    end
+  end
+end

data/lib/paper_trail_diff/batch_boundary_resolver.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # Resolves `:first` and `:last` endpoints for a whole batch in two queries per
+  # model class. Left to the caller this is a per-root lookup, which reintroduces
+  # exactly the queries a batched comparison exists to remove.
+  class BatchBoundaryResolver
+    BOUNDARIES = %i[first last].freeze
+
+    class << self
+      #: (untyped) -> bool
+      def symbolic?(endpoint)
+        endpoint.is_a?(Symbol)
+      end
+    end
+
+    #: (Array[[untyped, untyped]]) -> void
+    def initialize(pairs)
+      @pairs = pairs
+    end
+
+    # Returns the pairs with every resolvable symbol replaced. A symbol that
+    # names history the record does not have is left in place, so the caller can
+    # decide what an absent history means rather than being handed nil.
+    #: () -> Array[[untyped, untyped]]
+    def call
+      return @pairs unless @pairs.flatten(1).any? { |endpoint| symbolic?(endpoint) }
+
+      index = boundary_index
+      @pairs.map do |from, to|
+        [resolve(from, to, index), resolve(to, from, index)]
+      end
+    end
+
+    private
+
+    # @rbs @pairs: Array[[untyped, untyped]]
+
+    #: (untyped) -> bool
+    def symbolic?(endpoint)
+      self.class.symbolic?(endpoint)
+    end
+
+    #: (untyped, untyped, Hash[Array[String], Hash[Symbol, untyped]]) -> untyped
+    def resolve(endpoint, other, index)
+      return endpoint unless symbolic?(endpoint)
+
+      unless BOUNDARIES.include?(endpoint)
+        raise ConfigurationError,
+              "unsupported boundary: #{endpoint.inspect}; use :first, :last, a version, or a record"
+      end
+
+      identity = anchor_identity(other)
+      unless identity
+        raise ConfigurationError,
+              'a :first or :last endpoint needs the other endpoint to name a record'
+      end
+
+      index.dig(identity, endpoint) || endpoint
+    end
+
+    # A symbol carries no identity of its own, so the pair's other endpoint has
+    # to say which record is meant.
+    #: (untyped) -> Array[String]?
+    def anchor_identity(endpoint)
+      return if endpoint.nil? || symbolic?(endpoint)
+
+      Endpoint.identity(endpoint)
+    rescue InvalidEndpointError
+      nil
+    end
+
+    #: () -> Hash[Array[String], Hash[Symbol, untyped]]
+    def boundary_index
+      index = {} #: Hash[Array[String], Hash[Symbol, untyped]]
+      anchors.group_by { |model_class, _id| model_class }.each do |model_class, entries|
+        add_model_boundaries(index, model_class, entries.map { |_klass, id| id }.uniq)
+      end
+      index
+    end
+
+    #: () -> Array[[untyped, untyped]]
+    def anchors
+      @pairs.flatten(1).filter_map { |endpoint| anchor(endpoint) }.uniq
+    end
+
+    #: (untyped) -> [untyped, untyped]?
+    def anchor(endpoint)
+      return if endpoint.nil? || symbolic?(endpoint)
+
+      if Endpoint.version?(endpoint)
+        [Endpoint.model_class(endpoint), endpoint.item_id]
+      elsif Endpoint.record?(endpoint)
+        [endpoint.class, endpoint.id]
+      end
+    rescue InvalidEndpointError
+      nil
+    end
+
+    #: (Hash[Array[String], Hash[Symbol, untyped]], untyped, Array[untyped]) -> void
+    def add_model_boundaries(index, model_class, ids)
+      first_ids, last_ids, versions = boundary_versions(model_class, ids)
+      ids.each do |id|
+        index[identity_key(model_class, id)] = {
+          first: versions[boundary_key(first_ids, id)],
+          last: versions[boundary_key(last_ids, id)]
+        }
+      end
+    end
+
+    # Two grouped queries name each root's outermost versions, and one more
+    # loads them, whatever the size of the batch.
+    #: (untyped, Array[untyped]) -> [Hash[untyped, untyped], Hash[untyped, untyped], Hash[untyped, untyped]]
+    def boundary_versions(model_class, ids)
+      version_class = model_class.paper_trail.version_class
+      scope = version_class.where(item_type: model_class.base_class.name.to_s, item_id: ids)
+      first_ids = scope.group(:item_id).minimum(:id)
+      last_ids = scope.group(:item_id).maximum(:id)
+      loaded = version_class.where(id: (first_ids.values + last_ids.values).uniq).index_by(&:id)
+      [first_ids, last_ids, loaded]
+    end
+
+    # Grouped keys come back with whatever type the column uses, so match on the
+    # string form rather than assuming integers.
+    #: (Hash[untyped, untyped], untyped) -> untyped
+    def boundary_key(grouped, id)
+      key = grouped.keys.find { |candidate| candidate.to_s == id.to_s }
+      grouped[key]
+    end
+
+    #: (untyped, untyped) -> Array[String]
+    def identity_key(model_class, id)
+      [model_class.base_class.name.to_s, id.to_s]
+    end
+  end
+end

data/lib/paper_trail_diff/batched_root_analyzer.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # Builds one root's Analysis inside a batch, from versions the batch already
+  # selected and history it already prepared.
+  class BatchedRootAnalyzer
+    #: (tree: AssociationTree, timeline_snapshotter: untyped, activity_snapshotter: untyped, preparer: untyped, activity: bool) -> void
+    def initialize(tree:, timeline_snapshotter:, activity_snapshotter:, preparer:, activity:)
+      @tree = tree
+      @timeline_snapshotter = timeline_snapshotter
+      @activity_snapshotter = activity_snapshotter
+      @preparer = preparer
+      @activity = activity
+    end
+
+    #: (untyped, Array[untyped]) -> Analysis
+    def call(record, versions)
+      @preparer.call(record.class, historical: true)
+      return activity_analysis(record, versions) if @activity
+
+      TimelineBuilder.new(
+        record,
+        from: versions.first,
+        to: versions.last,
+        within: nil,
+        versions: versions,
+        snapshotter: @timeline_snapshotter
+      ).analyze
+    end
+
+    private
+
+    # @rbs @tree: AssociationTree
+    # @rbs @timeline_snapshotter: untyped
+    # @rbs @activity_snapshotter: untyped
+    # @rbs @preparer: untyped
+    # @rbs @activity: bool
+
+    #: (untyped, Array[untyped]) -> Analysis
+    def activity_analysis(record, versions)
+      range = TimelineRange.new(
+        record, from: versions.first, to: versions.last, within: nil, versions: versions
+      )
+      ActivityTimelineBuilder.new(
+        record, range: range, tree: @tree, snapshotter: @activity_snapshotter
+      ).analyze
+    end
+  end
+end

data/lib/paper_trail_diff/batched_root_versions.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # Selects each root's versions for a batched range in a fixed number of
+  # queries. Only the range forms that mean the same thing for every root are
+  # supported: a shared wall-clock window, or each root's own whole history.
+  class BatchedRootVersions
+    #: (Array[untyped], time_range: TimeRange?) -> void
+    def initialize(records, time_range:)
+      @records = records
+      @time_range = time_range
+    end
+
+    # Returns root versions per record identity, in chronological order.
+    #: () -> Hash[Array[String], Array[untyped]]
+    def call
+      return {} if @records.empty?
+
+      selected = {} #: Hash[Array[String], Array[untyped]]
+      @records.group_by(&:class).each do |model_class, records|
+        select_model(model_class, records, selected)
+      end
+      selected
+    end
+
+    private
+
+    # @rbs @records: Array[untyped]
+    # @rbs @time_range: TimeRange?
+
+    #: (untyped, Array[untyped], Hash[Array[String], Array[untyped]]) -> void
+    def select_model(model_class, records, selected)
+      ids = records.map(&:id)
+      range = @time_range
+      grouped = grouped_versions(model_class, ids, range)
+      empty = {} #: Hash[String, untyped]
+      trailing = range ? trailing_versions(model_class, ids, range) : empty
+      records.each do |record|
+        key = identity(model_class, record.id)
+        selected[key] = versions_for(grouped.fetch(record.id.to_s, []), trailing[record.id.to_s])
+      end
+    end
+
+    # The window's own versions plus, when it has one, the later version needed
+    # to reveal the last mutation inside it. A window closing on the root's own
+    # destruction needs no later version, because none can exist.
+    #: (Array[untyped], untyped) -> Array[untyped]
+    def versions_for(in_range, trailing)
+      return in_range if @time_range.nil?
+      return in_range.freeze if in_range.empty?
+      return in_range.freeze if trailing.nil? && terminal_destroy?(in_range)
+
+      unless trailing
+        raise IncompleteTimeRangeError,
+              'time range requires a later root version to reconstruct its final change'
+      end
+
+      (in_range + [trailing]).freeze
+    end
+
+    #: (Array[untyped]) -> bool
+    def terminal_destroy?(versions)
+      versions.last&.event.to_s == 'destroy'
+    end
+
+    #: (untyped, Array[untyped], TimeRange?) -> Hash[String, Array[untyped]]
+    def grouped_versions(model_class, ids, range)
+      scope = base_scope(model_class, ids)
+      scope = range.scope(scope) if range
+      ordered(scope).group_by { |version| version.item_id.to_s }
+    end
+
+    # One row per root: the earliest version after the window, found without a
+    # window function so the query stays portable.
+    #: (untyped, Array[untyped], TimeRange) -> Hash[String, untyped]
+    def trailing_versions(model_class, ids, range)
+      table = model_class.paper_trail.version_class.arel_table
+      relation = range.trailing_scope(base_scope(model_class, ids))
+      ordered(relation.where(no_earlier_trailing(table, range)))
+        .to_h { |version| [version.item_id.to_s, version] }
+    end
+
+    #: (untyped, TimeRange) -> untyped
+    def no_earlier_trailing(table, range)
+      arel = Object.const_get(:Arel) #: untyped
+      later = table.alias('paper_trail_diff_later_roots')
+      arel.const_get(:SelectManager).new
+          .from(later)
+          .project(arel.sql('1'))
+          .where(preceding(table, later, range))
+          .exists
+          .not
+    end
+
+    # Mirrors the window's own end handling, so a version sitting exactly on an
+    # inclusive boundary stays inside the window instead of masking the trailing
+    # version that follows it.
+    #: (untyped, untyped, TimeRange) -> untyped
+    def preceding(table, later, range)
+      same_item = later[:item_type].eq(table[:item_type])
+                                   .and(later[:item_id].eq(table[:item_id]))
+      same_item.and(after_window(later, range)).and(later[:created_at].lt(table[:created_at]))
+    end
+
+    #: (untyped, TimeRange) -> untyped
+    def after_window(later, range)
+      return later[:created_at].gteq(range.end_time) if range.exclude_end?
+
+      later[:created_at].gt(range.end_time)
+    end
+
+    #: (untyped, Array[untyped]) -> untyped
+    def base_scope(model_class, ids)
+      model_class.paper_trail.version_class.where(
+        item_type: model_class.base_class.name.to_s,
+        item_id: ids
+      )
+    end
+
+    #: (untyped) -> Array[untyped]
+    def ordered(relation)
+      relation.reorder(created_at: :asc, id: :asc).to_a
+    end
+
+    #: (untyped, untyped) -> Array[String]
+    def identity(model_class, id)
+      [model_class.base_class.name.to_s, id.to_s]
+    end
+  end
+end

data/lib/paper_trail_diff/comparison_batch.rb

@@ -23,18 +23,10 @@ module PaperTrailDiff
 
     #: () -> comparison_results
     def call
-      pairs = comparison_pairs
-      pairs.each { |from, to| Endpoint.validate_pair!(from, to) }
-      ensure_unique_identities!(pairs)
-      prepare_endpoint_classes!(pairs)
-      live_records = load_live_records(pairs.flatten)
-      prepare_historical_batches!(pairs, live_records)
-      live_snapshots = normalize_live_records(live_records)
-
-      pairs.to_h do |from, to|
-        identity = Support.immutable_copy(Endpoint.identity(from))
-        [identity, compare(from, to, live_snapshots)]
-      end.freeze
+      resolved = BatchBoundaryResolver.new(comparison_pairs).call
+      pairs = resolved.reject { |pair| pair.any? { |endpoint| symbolic?(endpoint) } }
+      ensure_unique_identities!(resolved)
+      results(resolved, prepared_live_snapshots(pairs)).freeze
     end
 
     private
@@ -46,6 +38,38 @@ module PaperTrailDiff
     # @rbs @historical_snapshotter: untyped
     # @rbs @live_normalizer: untyped
 
+    #: (Array[[untyped, untyped]]) -> Hash[identity, RecordSnapshot]
+    def prepared_live_snapshots(pairs)
+      pairs.each { |from, to| Endpoint.validate_pair!(from, to) }
+      prepare_endpoint_classes!(pairs)
+      live_records = load_live_records(pairs.flatten)
+      prepare_historical_batches!(pairs, live_records)
+      normalize_live_records(live_records)
+    end
+
+    #: (untyped) -> bool
+    def symbolic?(endpoint)
+      BatchBoundaryResolver.symbolic?(endpoint)
+    end
+
+    # A boundary symbol that stayed unresolved means the root has no recorded
+    # history. An absent history is an empty result rather than a failed
+    # request, matching how the timeline APIs answer the same question.
+    #: (Array[[untyped, untyped]], Hash[identity, RecordSnapshot]) -> comparison_results
+    def results(resolved, live_snapshots)
+      resolved.to_h do |from, to|
+        identity = Support.immutable_copy(entry_identity(from, to))
+        next [identity, Diff.new] if symbolic?(from) || symbolic?(to)
+
+        [identity, compare(from, to, live_snapshots)]
+      end
+    end
+
+    #: (untyped, untyped) -> identity
+    def entry_identity(from, to)
+      Endpoint.identity(symbolic?(from) ? to : from)
+    end
+
     #: (untyped, untyped, Hash[identity, RecordSnapshot]) -> Diff
     def compare(from, to, live_snapshots)
       Engine.compare(snapshot(from, live_snapshots), snapshot(to, live_snapshots))
@@ -125,7 +149,7 @@ module PaperTrailDiff
 
     #: (Array[[untyped, untyped]]) -> void
     def ensure_unique_identities!(pairs)
-      identities = pairs.map { |from, _to| Endpoint.identity(from) }
+      identities = pairs.map { |from, to| entry_identity(from, to) }
       return if identities.uniq.length == identities.length
 
       raise ConfigurationError, 'comparisons: root identities must be unique'

data/lib/paper_trail_diff/historical_snapshot_store.rb

@@ -24,6 +24,8 @@ module PaperTrailDiff
       end_at: root_versions.last.created_at
     )
       return if @tree.empty?
+      # A batched preparation already covers these roots.
+      return if root_versions.any? { |v| @prepared_histories.key?(context_key(v)) }
 
       @prepared_history = PreparedHistoryLoader.new(
         record,
@@ -35,7 +37,6 @@ module PaperTrailDiff
       ).call
     end
 
-    # Prepares selected history for several roots of the same model class.
     #: (Array[untyped], Array[untyped]) -> void
     def prepare_batch(records, root_versions)
       return if @tree.empty? || records.empty? || root_versions.empty?
@@ -50,12 +51,7 @@ module PaperTrailDiff
       key = snapshot_key(root_endpoint, context_endpoint)
       return @snapshots[key] if @snapshots.key?(key)
 
-      @snapshots[key] = custom(
-        root_endpoint,
-        context_endpoint,
-        tree: @tree,
-        normalizer: @normalizer
-      )
+      @snapshots[key] = uncached(root_endpoint, context_endpoint)
     end
 
     #: (untyped, untyped) -> RecordSnapshot?