paper_trail_diff 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 808e6dba6570e96679cb5b355b774e8afcd3b6bf81c38c1a0b0fc088d6f9f416
-  data.tar.gz: 5978755e10f821777aadc86b6f4d79728a827cf48c1ba3e95c89a6f627eaea6e
+  metadata.gz: 4d60569584c3d30bd35c62c1f0f699fd8859545d81f873c926dfdd8268aed3df
+  data.tar.gz: 4961a77099927fff3476641b0409cb234e1f398e9b84e9cb3cc9e11b2d580064
 SHA512:
-  metadata.gz: '048b927dd9d8274675ae60692ad705ed586c9d31ed6f4c11a581521d86ff8621dedda7daf33a4e4c90223b31a42bc60184c6f376ed4b1363a3cfcb5a2b2ab65a'
-  data.tar.gz: 559ea7552ce0133864a3e55df66097fdbbee3315febf9d04cd7485e0caa14e9deb34625b48ecb660f00cd452ec00b4e12d1180689c88a2b2464e59e71182abb5
+  metadata.gz: 2cf13bffaca3d199b2332b0e3d1c7c7c00ef7c6f82a4c9e5a75c51f376889ff57c60e1bfab1f578a7122e972698318d2720bce5f8da2755abea50aebf6e7083e
+  data.tar.gz: a071cd71f7fb766105eda1e018991ed8030885822da23382404797984b265818c0012378aea5912a507fb7bc24e9294331201b0cf1918860df3d9613476d580d

data/CHANGELOG.md

@@ -3,6 +3,53 @@
 All notable changes to this project will be documented in this file. The
 project follows [Semantic Versioning](https://semver.org/).
 
+## [0.3.0] - 2026-08-10
+
+### Added
+
+- Add `within:` time-range selection to checkpoint timelines, activity
+  timelines, and combined analysis, with inclusive/exclusive end handling and
+  explicit errors when a final mutation cannot be reconstructed.
+- Add `compare_many` for collection reports, with batched current-root loading,
+  bounded live-association preloading, cross-root prepared history, immutable
+  identity-keyed results, and scale-invariant query regression coverage.
+- Add opt-in reuse of fully preloaded current endpoints and namespaced
+  ActiveSupport runtime instrumentation without automatic logging, including
+  end-to-end activity-timeline duration and step counts.
+
+### Changed
+
+- Teach timeline filtering through the shared `Step#empty?` protocol in the
+  README and quickstart examples.
+- Reuse the live graph loaded by `compare_many` while preparing historical
+  association state, and defer root version loading until an edge needs it.
+- Reuse collection identity positions and adjacent transition hints so activity
+  steps compare only the changed member, and resolve direct nested collection
+  owners by foreign key instead of scanning every parent snapshot.
+- Reuse prepared predecessor and successor scalar states for isolated activity
+  updates instead of reifying and deserializing each PaperTrail event again.
+- Preserve both sides of nested collection membership moves by using the
+  general comparator when one event changes multiple parent snapshots.
+- Preserve per-owner `limit`, `offset`, and owner-dependent association scopes
+  in `compare_many` while retaining batched preloading for safe branches.
+- Replace lifetime association-identity materialization with an indexed start-state
+  checkpoint plus post-boundary activity and current members.
+- Bound historical activity-child candidates at the selected end so membership
+  changes after the range cannot introduce unrelated empty timeline steps.
+- Decode compatible prepared scalar version payloads without constructing an
+  intermediate Active Record object, with reification fallback for unsafe schemas.
+- Reuse internally owned frozen collection arrays instead of defensively copying
+  them a second time during immutable activity reconstruction.
+- Replace pre-existing versions-relation ordering when selecting a time range's
+  immediate trailing reconstruction boundary.
+- Limit automatic CI to pull requests and `main` pushes, and cancel superseded
+  runs for the same pull request or ref.
+
+### Fixed
+
+- Supply TZInfo's timezone database to the test bundle so zoned-time coverage
+  runs on Windows as well as systems with a native zoneinfo database.
+
 ## [0.2.0] - 2026-08-09
 
 ### Added

data/QUICKSTART.md

@@ -118,17 +118,42 @@ steps.map do |step|
 end
 # => [["Draft", "Published"], ["Published", "Final"]]
 
-visible_steps = steps.reject { |step| step.diff.empty? }
+visible_steps = steps.reject(&:empty?)
 ```
 
 Empty steps remain in the timeline. Filter them only when the application's
 display does not need every version boundary.
 
+### Select mutations by time
+
+Use `within:` when the application has a reporting window rather than saved
+endpoint versions:
+
+<!-- executable:quickstart-time-range -->
+```ruby
+window = draft_version.created_at...final_version.created_at
+ranged_steps = PaperTrailDiff.timeline(article, within: window)
+
+ranged_steps.map do |step|
+  change = step.diff.attributes["title"]
+  [change.from, change.to]
+end
+# => [["Draft", "Published"], ["Published", "Final"]]
+```
+
+The half-open range selects the mutations recorded by `draft_version` and
+`published_version`. The excluded `final_version` is still used as the trailing
+boundary needed to reveal the last selected mutation. PaperTrail versions are
+pre-change snapshots, so a range containing mutations must have a later root
+version. The gem raises `PaperTrailDiff::IncompleteTimeRangeError` instead of
+assuming that the current record is the missing endpoint.
+
 ## 6. Choose the right API
 
 | Need | Call |
 | --- | --- |
 | Net difference between two endpoints | `compare` |
+| Net differences for many current records | `compare_many` |
 | One step per root-record version | `timeline` |
 | Steps for root and selected child versions | `activity_timeline` |
 | Net diff and timelines from one history pass | `analyze` |
@@ -228,7 +253,7 @@ steps = PaperTrailDiff.activity_timeline(
   associations: ["comments"]
 )
 
-steps.reject { |step| step.diff.empty? }.each do |step|
+steps.reject(&:empty?).each do |step|
   boundary = step.to_boundary
   puts "#{boundary.item_type} ##{boundary.item_id}"
 end
@@ -237,10 +262,27 @@ end
 Use a later transaction-backed root checkpoint instead of `to: current` when
 the result must remain reproducible after the database changes again.
 
+For a historical reporting window, replace `from:` and `to:` with `within:`:
+
+```ruby
+steps = PaperTrailDiff.activity_timeline(
+  article,
+  within: report_start...report_end,
+  associations: ["comments"]
+)
+```
+
+This selects versioned comment activity directly, even if the article had no
+mutation during the window. Take a root checkpoint after `report_end`; it gives
+the gem the historical context needed to expose the final child mutation.
+
 ## 9. Common surprises
 
 - PaperTrail stores pre-change snapshots. The current record is not represented
   by `versions.last`; pass the record explicitly when current state is wanted.
+- A `within:` window containing mutations needs a later root checkpoint. The
+  trailing version is reconstruction context and may appear as a step's ending
+  boundary even though its own mutation is outside the window.
 - `ignore:` replaces the default list. Include `updated_at` yourself when using
   a custom list and you still want it ignored.
 - Historical associations require PT-AT to be installed, loaded, migrated, and

data/README.md

@@ -82,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
@@ -133,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
@@ -177,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
 
@@ -204,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
@@ -224,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`.
 

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