paper_trail_diff 0.7.0 → 0.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 33b445f893d6d95faf0ad22b72d35e8b248f3c00240e537898cac2d067ece043
-  data.tar.gz: 57ee0b8fc242825852726933a9aa332cd309c38d2af21724a41c4bfcfbf2bd41
+  metadata.gz: a84116670d1dd65a6cf569a266ccc8587a9eab4e65d38cf84df485c26d33d9dc
+  data.tar.gz: 2c8ddb0fd1b2203e644f3c50ed24da33ed25cb4c4240665eab85368cd4534f22
 SHA512:
-  metadata.gz: bbbdea8be4b4300705da0f915dbe3b61ede862817fa27c44f0371c8454f9995f20b16120acc43cf0272f8fdecfdef4fa5fce160642812805a2c636f6f6acf9a0
-  data.tar.gz: e6f9a063c376a1214b1deacbd0ea15e325e82a1cccecd86d3d747268471bac0b20585249a4dcb1f039730f39bb019cc35a7e12a2e0bbfb963d4cc856acd6d2ef
+  metadata.gz: 3e32ecbedd636456388129cc664cf688b0aa909d5c05b45124eb1a6bd82dabbffa96557fe5efc946e93fe459234d3c4c5ce9af11f39228ddab55228f5a53e2f9
+  data.tar.gz: 1b29680ab942334fd98ce5cc0a4f2bc823fd180b258282e8be2c07ba784c9c3b5aa9edc76e0e118fec3baabcfbc94344c208aef116702874c0eb4dd226cddcac

data/CHANGELOG.md

@@ -3,6 +3,27 @@
 All notable changes to this project will be documented in this file. The
 project follows [Semantic Versioning](https://semver.org/).
 
+## [0.7.1] - 2026-08-11
+
+### Fixed
+
+- Load each current endpoint once per call instead of once per request for it,
+  so `close_on: :current` no longer costs a live read per root and
+  `analyze_many` keeps the flat query cost it exists for. A twenty-root batch
+  closing on current state issued 43 queries against the 3 a closed window
+  needs. Every root in one result now also reflects the same instant rather
+  than whenever its turn came.
+
+### Changed
+
+- Name the way out in `IncompleteTimeRangeError`: the message now points at
+  `close_on: :current` and at narrowing the window. Its previous advice — add a
+  checkpoint after the window — cannot be followed by a report about the
+  present, which is the case that raises it most.
+- Correct the `reload_live_endpoints:` documentation, which claimed `timeline`
+  and `analyze` never read live state. They do under `close_on: :current`, and
+  they do not accept the option.
+
 ## [0.7.0] - 2026-08-11
 
 ### Added

data/README.md

@@ -242,8 +242,13 @@ must observe one atomic snapshot.
 
 `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:
+preloaded graph may opt out. Each endpoint is loaded once per call, so a batch
+that resolves every root up front and then reads one of them again pays
+nothing the second time, and every root in one result reflects the same instant.
+
+The option is not accepted by `timeline`, `analyze`, or `analyze_many`. Those
+are bounded by versions and read live state only under
+[`close_on: :current`](#reporting-up-to-now), which always reloads:
 
 ```ruby
 orders = Order.where(id: order_ids).preload(line_items: :product).to_a

data/lib/paper_trail_diff/live_endpoint_provider.rb

@@ -23,18 +23,37 @@ module PaperTrailDiff
                 else
                   PreloadedEndpointBatchLoader.new(tree: tree, traversal: traversal)
                 end
+      @loaded = {} #: Hash[identity, untyped]
     end
 
+    # Loads each endpoint at most once for the life of this provider, which is
+    # one public call. A batch that resolves every root up front and then asks
+    # again for one of them costs nothing the second time, and every root in the
+    # result reflects the same instant rather than whenever its turn came.
     #: (Array[untyped]) -> Hash[identity, untyped]
     def call(records)
-      Instrumentation.instrument('load_live_endpoints', payload(records)) do
-        @loader.call(records)
+      missing = records.reject { |record| @loaded.key?(Endpoint.identity(record)) }
+      return known(records) if missing.empty?
+
+      loaded = Instrumentation.instrument('load_live_endpoints', payload(missing)) do
+        @loader.call(missing)
       end
+      @loaded.merge!(loaded)
+      known(records)
     end
 
     private
 
     # @rbs @loader: untyped
+    # @rbs @loaded: Hash[identity, untyped]
+
+    #: (Array[untyped]) -> Hash[identity, untyped]
+    def known(records)
+      records.to_h do |record|
+        identity = Endpoint.identity(record)
+        [identity, @loaded.fetch(identity)]
+      end
+    end
 
     #: (Array[untyped]) -> Hash[Symbol, untyped]
     def payload(records)

data/lib/paper_trail_diff/root_version_selection.rb

@@ -11,7 +11,12 @@ module PaperTrailDiff
   # Both the single-record and the batched selectors resolve this here, because
   # the rule is subtle enough that two copies of it would drift apart.
   class RootVersionSelection
-    INCOMPLETE = 'time range requires a later root version to reconstruct its final change'
+    # An error is a specification, so it names the way out as well as the wall.
+    # A window ending at the present can never gain a later version, which makes
+    # "write a checkpoint afterwards" impossible advice on its own.
+    INCOMPLETE = 'time range requires a later root version to reconstruct its ' \
+                 'final change: pass close_on: :current to end at current state, ' \
+                 'or narrow the window to end before the last recorded version'
 
     #: (in_range: Array[untyped], selected: Array[untyped], after_range: untyped, windowed: bool, ?context_required: bool, ?filtered: bool, ?live_endpoint: untyped) -> void
     def initialize( # rubocop:disable Metrics/ParameterLists

data/lib/paper_trail_diff/time_activity_timeline_builder.rb

@@ -187,7 +187,9 @@ module PaperTrailDiff
       return true if terminal_destroy?(selected.last)
       return true if plan.closing_record
 
-      message = 'time range requires a later activity boundary to reconstruct its final change'
+      message = 'time range requires a later activity boundary to reconstruct its ' \
+                'final change: pass close_on: :current to end at current state, ' \
+                'or narrow the window to end before the last recorded boundary'
       raise IncompleteTimeRangeError, message
     end
 

data/lib/paper_trail_diff/version.rb

@@ -2,5 +2,5 @@
 # rbs_inline: enabled
 
 module PaperTrailDiff
-  VERSION = '0.7.0'
+  VERSION = '0.7.1'
 end

data/sig/generated/paper_trail_diff/live_endpoint_provider.rbs

@@ -10,13 +10,22 @@ module PaperTrailDiff
     # : (tree: AssociationTree, traversal: AssociationTraversal, reload: bool) -> void
     def initialize: (tree: AssociationTree, traversal: AssociationTraversal, reload: bool) -> void
 
+    # Loads each endpoint at most once for the life of this provider, which is
+    # one public call. A batch that resolves every root up front and then asks
+    # again for one of them costs nothing the second time, and every root in the
+    # result reflects the same instant rather than whenever its turn came.
     # : (Array[untyped]) -> Hash[identity, untyped]
     def call: (Array[untyped]) -> Hash[identity, untyped]
 
     private
 
+    @loaded: Hash[identity, untyped]
+
     @loader: untyped
 
+    # : (Array[untyped]) -> Hash[identity, untyped]
+    def known: (Array[untyped]) -> Hash[identity, untyped]
+
     # : (Array[untyped]) -> Hash[Symbol, untyped]
     def payload: (Array[untyped]) -> Hash[Symbol, untyped]
   end

data/sig/generated/paper_trail_diff/root_version_selection.rbs

@@ -10,6 +10,9 @@ module PaperTrailDiff
   # Both the single-record and the batched selectors resolve this here, because
   # the rule is subtle enough that two copies of it would drift apart.
   class RootVersionSelection
+    # An error is a specification, so it names the way out as well as the wall.
+    # A window ending at the present can never gain a later version, which makes
+    # "write a checkpoint afterwards" impossible advice on its own.
     INCOMPLETE: ::String
 
     # : (in_range: Array[untyped], selected: Array[untyped], after_range: untyped, windowed: bool, ?context_required: bool, ?filtered: bool, ?live_endpoint: untyped) -> void

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: paper_trail_diff
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.7.1
 platform: ruby
 authors:
 - Alex Williams
@@ -200,11 +200,11 @@ licenses:
 metadata:
   allowed_push_host: https://rubygems.org
   bug_tracker_uri: https://github.com/aheathwilliams/paper_trail_diff/issues
-  changelog_uri: https://github.com/aheathwilliams/paper_trail_diff/blob/v0.7.0/CHANGELOG.md
-  documentation_uri: https://github.com/aheathwilliams/paper_trail_diff/blob/v0.7.0/README.md
+  changelog_uri: https://github.com/aheathwilliams/paper_trail_diff/blob/v0.7.1/CHANGELOG.md
+  documentation_uri: https://github.com/aheathwilliams/paper_trail_diff/blob/v0.7.1/README.md
   homepage_uri: https://github.com/aheathwilliams/paper_trail_diff
   rubygems_mfa_required: 'true'
-  source_code_uri: https://github.com/aheathwilliams/paper_trail_diff/tree/v0.7.0
+  source_code_uri: https://github.com/aheathwilliams/paper_trail_diff/tree/v0.7.1
 rdoc_options: []
 require_paths:
 - lib