paper_trail_diff 0.1.0 → 0.3.0

data/README.md

@@ -12,6 +12,8 @@ available when
 
 Ruby 3.1 or newer and PaperTrail 16 or 17 are supported.
 
+New to the gem? Start with the copyable [Quickstart](QUICKSTART.md).
+
 ## Installation
 
 Add the gem to your bundle:
@@ -80,6 +82,95 @@ association caches and in-memory edits are not compared. Use a database
 transaction with an appropriate isolation level when several live association
 queries must represent one atomic application snapshot.
 
+For collection-level reports, use `compare_many` to reload current roots and
+preload each explicitly selected live association path across the batch. Each
+entry has the same endpoints and options as `compare`; results are returned in
+input order as a frozen hash keyed by `[item_type, item_id]` strings:
+
+```ruby
+diffs = PaperTrailDiff.compare_many(
+  [
+    { from: first_versions.fetch(order_a.id), to: order_a },
+    { from: first_versions.fetch(order_b.id), to: order_b }
+  ],
+  associations: [:line_items],
+  ignore: []
+)
+
+diffs.fetch(["Order", order_a.id.to_s]) # => PaperTrailDiff::Diff
+```
+
+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
+their per-endpoint behavior and all historical reconstruction retains the same
+PaperTrail Association Tracking requirements as `compare`. Live collection
+scopes with per-owner semantics, such as `limit`, `offset`, or an owner
+argument, are loaded per root; other selected branches remain batched. Callers
+should still use an appropriate database transaction when all live queries
+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:
+
+```ruby
+orders = Order.where(id: ids).preload(line_items: :product).to_a
+
+diffs = PaperTrailDiff.compare_many(
+  orders.map do |order|
+    { from: first_versions.fetch(order.id), to: order }
+  end,
+  associations: ["line_items.product"],
+  reload_live_endpoints: false
+)
+```
+
+With `reload_live_endpoints: false`, scalar values and association targets come
+from the supplied instances. Every requested association path must already be
+loaded; otherwise `PaperTrailDiff::UnloadedAssociationError` is raised before
+normalization instead of silently issuing an N+1 query. The caller is
+responsible for the consistency and freshness of that in-memory graph.
+
+### Runtime performance diagnostics
+
+The gem never prints or logs automatically. It emits these
+`ActiveSupport::Notifications` events so applications can choose their logger
+and formatting:
+
+- `compare.paper_trail_diff`
+- `compare_many.paper_trail_diff`
+- `activity_timeline.paper_trail_diff`
+- `load_live_endpoints.paper_trail_diff`
+- `prepare_history.paper_trail_diff`
+
+```ruby
+ActiveSupport::Notifications.subscribe(/\.paper_trail_diff\z/) do |name, start, finish, _id, payload|
+  Rails.logger.debug(
+    event: name,
+    duration_ms: ((finish - start) * 1_000).round(1),
+    **payload
+  )
+end
+```
+
+The payloads contain counts, model names, association paths, and reload mode,
+not endpoint objects or record attributes. The activity-timeline event wraps
+the complete call and includes `step_count`, so its notification duration is
+the user-visible runtime. To inspect the exact SQL generated by one report,
+scope a standard `sql.active_record` subscriber around it:
+
+```ruby
+callback = proc do |_name, _start, _finish, _id, payload|
+  Rails.logger.debug(payload[:sql]) unless payload[:cached] || payload[:name] == "SCHEMA"
+end
+
+ActiveSupport::Notifications.subscribed(callback, "sql.active_record") do
+  PaperTrailDiff.compare_many(comparisons, associations: [:line_items])
+end
+```
+
 ## Build a root-checkpoint timeline
 
 `timeline` accepts two version objects from the supplied record's history. The
@@ -95,11 +186,22 @@ steps = PaperTrailDiff.timeline(
 
 steps.first.from_version # the original PaperTrail version
 steps.first.to_version   # the next PaperTrail version
+steps.first.from_boundary # immutable presentation metadata
+steps.first.to_boundary
 steps.first.diff         # a PaperTrailDiff::Diff
+steps.first.empty?        # delegates to the diff
 steps.first.to_h
 # => { from_version_id: 2, to_version_id: 3, diff: { ... } }
 ```
 
+Both timeline types expose `from_boundary`, `to_boundary`, `diff`, and
+`empty?`. A historical boundary has `event`, `whodunnit`, `record`,
+`recorded_at`, `version?`, and `current?` readers. Checkpoint `Step` objects
+also retain their original `from_version` and `to_version` for callers that
+need custom PaperTrail metadata. Existing `Step#to_h` and
+`ActivityBoundary#to_h` shapes remain unchanged; use the readers for the new
+metadata.
+
 Every version boundary remains in the result, even when its diff is empty after
 ignored fields are removed. Equal boundaries return a frozen empty array.
 
@@ -120,7 +222,7 @@ steps = PaperTrailDiff.activity_timeline(
   associations: ["comments.replies", :author]
 )
 
-steps.reject { |step| step.diff.empty? }
+steps.reject(&:empty?)
 ```
 
 Pass the record explicitly as `to:` to include current state without creating a
@@ -164,9 +266,55 @@ intermediate events without transaction-backed owner checkpoints. Historical
 HABTM activity and `compare(version, article, associations: [:tags])` remain
 supported where the historical endpoint has usable PT-AT metadata.
 
-Both timeline APIs preserve empty boundaries. A display may filter
-`step.diff.empty?`, while audit-oriented callers can retain every recorded
-boundary.
+Both timeline APIs preserve empty boundaries. A display may use
+`steps.reject(&:empty?)`, while audit-oriented callers can retain every
+recorded boundary.
+
+## Select mutations by time
+
+`timeline`, `activity_timeline`, and `analyze` also accept a finite time range
+through `within:` instead of explicit `from:` and `to:` versions. Half-open
+ranges are recommended for adjacent reporting windows:
+
+```ruby
+window = Time.zone.parse("2026-08-01")...Time.zone.parse("2026-09-01")
+
+steps = PaperTrailDiff.timeline(article, within: window)
+
+activity_steps = PaperTrailDiff.activity_timeline(
+  article,
+  within: window,
+  associations: ["comments.replies", :author]
+)
+
+analysis = PaperTrailDiff.analyze(
+  article,
+  within: window,
+  associations: ["comments.replies"],
+  activity: true
+)
+```
+
+The range selects mutations by the timestamp of their source PaperTrail
+version. Ruby's inclusive (`..`) and exclusive (`...`) end semantics are
+honored. A returned step's `to_boundary` may be after the range: because a
+PaperTrail version is a pre-change snapshot, the gem needs one later root
+version to reveal the final selected mutation. That version is reconstruction
+context, not an additional selected mutation.
+
+If the window contains a relevant mutation but no later root version exists,
+the call raises `PaperTrailDiff::IncompleteTimeRangeError`. Create a root
+checkpoint after the reporting window before running historical analysis. The
+gem does not silently substitute current database state. A root-only window
+with no selected mutation returns a frozen empty timeline.
+
+Time ranges and explicit `from:`/`to:` endpoints are mutually exclusive.
+Malformed, open-ended, or reversed ranges raise
+`PaperTrailDiff::InvalidTimeRangeError`. With `activity_timeline`, selected
+descendant versions are included even when no root mutation occurred inside
+the window; the later root checkpoint is still required so PT-AT can
+reconstruct the enclosing graph and determine whether descendant activity is
+present. The ordinary `timeline` remains a root-only checkpoint timeline.
 
 ## Build an endpoint and timeline together
 
@@ -191,8 +339,9 @@ analysis.activity_timeline
 ```
 
 Without `activity: true`, `analysis.activity_timeline` is `nil` and no activity
-work is performed. `analyze` remains version-bounded; use the standalone
-`activity_timeline(..., to: article)` API for an explicit current endpoint.
+work is performed. `analyze` accepts explicit historical versions or
+`within:`, but not a current-record endpoint; use the standalone
+`activity_timeline(..., to: article)` API when the final boundary must be live.
 
 `timeline`, `activity_timeline`, and both forms of `analyze` prepare the selected
 historical range once. The loader walks only the explicit association paths and
@@ -211,20 +360,49 @@ and other unsupported shapes fall back to the ordinary PT-AT point reifier on
 a per-reflection basis. This hybrid path preserves existing reconstruction
 behavior while avoiding repeated association queries for supported paths.
 
-Activity event discovery is bounded to the selected range. Prepared scalar
-state also retains later successor versions for selected identities because a
-PaperTrail version is a pre-change snapshot and may be the only correct state
-for an earlier boundary. Memory therefore scales with relevant selected
-history, not only with the number of returned steps. Keep requested paths and
-ranges intentional. For large histories, applications should give the database
-a matching composite index. A typical PaperTrail installation can add one
-without making it a requirement of this gem:
+For supported collection events, adjacent snapshots share an immutable
+identity-position index and carry a one-step transition hint. Diffing therefore
+visits only the changed member instead of hashing the whole collection again.
+Prepared scalar history also exposes the predecessor and successor attributes
+for isolated update events, allowing activity reconstruction to update the
+immutable snapshot directly instead of reifying and deserializing the same
+PaperTrail event again. Compatible scalar payloads are decoded into prepared
+state without first constructing a disposable Active Record object. Encrypted,
+schema-mismatched, missing, ambiguous, or identity-changing states fall back to
+the ordinary event reifier.
+For a direct nested `has_many` such as `comments.replies`, the child's foreign
+key also locates its parent snapshot directly rather than walking every
+comment. Membership changes and ambiguous or unsupported relationship shapes
+retain the general comparator and traversal fallback.
+
+Activity event loading is bounded to the selected range. Association identity
+discovery retains one indexed checkpoint for members present at the starting
+boundary, then considers later association activity and current members; it no
+longer materializes every pre-range association row. Prepared scalar state also
+retains later successor versions for selected identities because a PaperTrail
+version is a pre-change snapshot and may be the only correct state for an
+earlier boundary. Memory therefore scales with relevant selected history, not
+only with the number of returned steps. Keep requested paths and ranges
+intentional. An activity timeline must also emit a diff for every selected
+event. Repeated events within one wide collection still copy the frozen records
+array when producing each immutable snapshot, so they can do pointer-copying
+work proportional to the number of events times the collection width even when
+SQL and Ruby-level comparison work stay linear. Bound or paginate unusually
+wide activity ranges in latency-sensitive requests.
+
+For large histories, applications should give the database a matching
+composite index. A typical PaperTrail installation can add one without making
+it a requirement of this gem:
 
 ```ruby
 add_index :versions, %i[item_type item_id created_at id],
           name: "index_versions_on_item_and_timeline"
 ```
 
+This index is especially useful for repeated `within:` queries because root
+selection is constrained by `item_type`, `item_id`, and `created_at`, then
+ordered deterministically by timestamp and version ID.
+
 PT-AT's normal index beginning with `foreign_key_name`, `foreign_key_id`, and
 `foreign_type` should also be retained on `version_associations`.
 
@@ -323,6 +501,61 @@ database state. Unknown names and unsupported macros raise explicit
 Malformed public options raise `PaperTrailDiff::ConfigurationError`, also under
 that base error.
 
+## Traverse result trees
+
+The nested tree remains the canonical, lossless result. For renderers,
+counters, exports, and notifications, `Diff#each_change` provides a
+deterministic depth-first stream of semantic changes:
+
+<!-- executable:readme-traversal-changes -->
+```ruby
+diff.each_change do |entry|
+  entry.kind              # :attribute_changed, :record_added, ...
+  entry.association_path  # ["comments", "replies"]
+  entry.record_path       # frozen RecordReference objects
+  entry.association_kind  # :has_many, :belongs_to, ...
+  entry.attribute         # "body" for an attribute entry
+  entry.value             # ValueChange, RecordChange, or RecordSnapshot
+end
+
+counts = diff.each_change.map(&:kind).tally
+```
+
+`record_changed` entries are emitted before that record's attribute and nested
+association changes, allowing an application to count both changed records and
+changed fields. Singular relationship operations are classified separately as
+`relationship_added`, `relationship_removed`, or `relationship_replaced`.
+Root create/delete transitions remain `record_presence_changed`.
+
+Added, removed, and replaced records carry complete bounded snapshots. Use
+`each_entry` when a renderer also needs that nested state without writing a
+second snapshot walker:
+
+<!-- executable:readme-traversal-entries -->
+```ruby
+diff.each_entry do |entry|
+  next unless entry.included_state?
+
+  entry.kind     # :record_included, :attribute_included, :association_included
+  entry.state    # :before or :after
+  entry.context  # :included_state
+end
+```
+
+An included record is historical context, not evidence that the nested record
+changed independently. `each_change` therefore omits included-state entries.
+Both methods return an `Enumerator` when no block is supplied and return the
+diff when called with a block. Entries and their paths are immutable and have
+deterministic `to_h` output. The root location uses empty association and record
+paths; descendant `record_path` values contain only the explicitly traversed
+descendant identities.
+
+Traversal is path-preserving and does not deduplicate. If the same record is
+reachable through two selected paths, it appears at both locations so the
+consumer can choose whether path identity or record identity controls counting.
+Walking a result never performs database access and never discovers additional
+associations.
+
 ## Discover and diagnose associations
 
 Configuration UIs can use bounded public reflection instead of duplicating the
@@ -392,6 +625,7 @@ The public result types are:
 - `PaperTrailDiff::ActivityBoundary`
 - `PaperTrailDiff::Analysis`
 - `PaperTrailDiff::ValueChange`
+- `PaperTrailDiff::TraversalEntry`
 - `PaperTrailDiff::RecordReference`
 - `PaperTrailDiff::RecordSnapshot`
 - `PaperTrailDiff::RecordChange`
@@ -404,11 +638,13 @@ The public result types are:
 They expose readers, are frozen after construction, and provide deterministic
 `to_h` output. Structural hash keys are symbols; attribute and association
 names are strings. Attribute values retain their Ruby types. `RecordChange#record`
-is a `RecordReference` with `type` and `id` readers. `Step` itself is frozen but
-intentionally retains the original, potentially mutable PaperTrail version
-objects for metadata access; `Step#to_h` emits only their IDs. `ActivityStep`
-instead retains only immutable boundary metadata and serializes as
-`{ from: ..., to: ..., diff: ... }`.
+is a `RecordReference` with `type` and `id` readers. `TraversalEntry#record` and
+`#association` return the final components of their corresponding paths. `Step`
+itself is frozen but intentionally retains the original, potentially mutable
+PaperTrail version objects for metadata access; its new boundary readers provide
+an immutable presentation interface, while `Step#to_h` continues to emit only
+version IDs. `ActivityStep` retains only immutable boundary metadata and
+serializes as `{ from: ..., to: ..., diff: ... }`.
 
 ## Historical correctness and limitations
 
@@ -459,6 +695,9 @@ mise exec -- act push -j quality --matrix ruby:4.0 --matrix paper_trail:17
 
 The default Rake task runs core specs without PT-AT loaded, association specs in
 a separate process, RuboCop, generated-signature verification, and Steep.
+Selected Ruby blocks in this README and the quickstart are executed in those
+same isolated test sessions; the `<!-- executable:... -->` marker opts a block
+into the appropriate stateful session.
 Inline `#:` annotations in `lib/` generate the committed RBS files under
 `sig/generated/`.
 

data/lib/paper_trail_diff/activity_boundary.rb

@@ -9,6 +9,9 @@ module PaperTrailDiff
     attr_reader :item_type #: String
     attr_reader :item_id #: untyped
     attr_reader :recorded_at #: untyped
+    attr_reader :event #: String?
+    attr_reader :whodunnit #: untyped
+    attr_reader :record #: RecordReference
 
     class << self
       #: (untyped) -> ActivityBoundary
@@ -18,7 +21,9 @@ module PaperTrailDiff
           version_id: version.id,
           item_type: version.item_type,
           item_id: version.item_id,
-          recorded_at: version.created_at
+          recorded_at: version.created_at,
+          event: version.event,
+          whodunnit: version.whodunnit
         )
       end
 
@@ -34,16 +39,37 @@ module PaperTrailDiff
       end
     end
 
-    #: (kind: Symbol, version_id: untyped, item_type: untyped, item_id: untyped, recorded_at: untyped) -> void
-    def initialize(kind:, version_id:, item_type:, item_id:, recorded_at:)
+    #: (kind: Symbol, version_id: untyped, item_type: untyped, item_id: untyped, recorded_at: untyped, ?event: untyped, ?whodunnit: untyped) -> void
+    def initialize( # rubocop:disable Metrics/ParameterLists
+      kind:,
+      version_id:,
+      item_type:,
+      item_id:,
+      recorded_at:,
+      event: nil,
+      whodunnit: nil
+    )
       @kind = kind
       @version_id = Support.immutable_copy(version_id)
       @item_type = Support.immutable_copy(item_type.to_s)
       @item_id = Support.immutable_copy(item_id)
       @recorded_at = Support.immutable_copy(recorded_at)
+      @event = Support.immutable_copy(event&.to_s)
+      @whodunnit = Support.immutable_copy(whodunnit)
+      @record = RecordReference.new(type: @item_type, id: @item_id)
       freeze
     end
 
+    #: () -> bool
+    def version?
+      kind == :version
+    end
+
+    #: () -> bool
+    def current?
+      kind == :current
+    end
+
     #: () -> Hash[Symbol, untyped]
     def to_h
       {
@@ -70,6 +96,11 @@ module PaperTrailDiff
       freeze
     end
 
+    #: () -> bool
+    def empty?
+      diff.empty?
+    end
+
     #: () -> Hash[Symbol, untyped]
     def to_h
       {

data/lib/paper_trail_diff/activity_child_candidate_loader.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # Loads direct-child identities active at or after one activity boundary.
+  class ActivityChildCandidateLoader
+    #: (untyped, Array[untyped], untyped, ActivityRange) -> void
+    def initialize(parent_class, parent_ids, reflection, range)
+      @parent_class = parent_class
+      @parent_ids = parent_ids
+      @reflection = reflection
+      @range = range
+    end
+
+    #: () -> Array[untyped]
+    def call
+      historical_ids | current_ids
+    end
+
+    private
+
+    # @rbs @parent_class: untyped
+    # @rbs @parent_ids: Array[untyped]
+    # @rbs @reflection: untyped
+    # @rbs @range: ActivityRange
+
+    #: () -> Array[untyped]
+    def historical_ids
+      version_class = @parent_class.paper_trail.version_class
+      candidate_scope(version_class).call(historical_relation(version_class))
+                                    .distinct.pluck(version_class.arel_table[:item_id])
+    end
+
+    #: (untyped) -> untyped
+    def historical_relation(version_class)
+      @parent_class.paper_trail.version_association_class.joins(:version).where(
+        foreign_key_name: @reflection.foreign_key.to_s,
+        foreign_key_id: @parent_ids,
+        foreign_type: parent_types
+      ).where(version_class.table_name => { item_type: child_item_type })
+    end
+
+    #: (untyped) -> VersionAssociationCandidateScope
+    def candidate_scope(version_class)
+      VersionAssociationCandidateScope.new(
+        version_class,
+        @range.start_time,
+        end_at: @range.end_time
+      )
+    end
+
+    #: () -> Array[untyped]
+    def current_ids
+      return [] unless @range.current_end?
+
+      relation = @reflection.klass.base_class.unscoped.where(
+        @reflection.foreign_key => @parent_ids
+      )
+      relation = relation.where(@reflection.type => parent_types) if @reflection.options[:as]
+      relation.distinct.pluck(@reflection.klass.primary_key)
+    end
+
+    #: () -> String
+    def child_item_type
+      @reflection.klass.base_class.name
+    end
+
+    #: () -> Array[String?]
+    def parent_types
+      [nil, '', @parent_class.name.to_s, @parent_class.base_class.name.to_s].uniq
+    end
+  end
+end