clickwrap 0.3.3 → 0.3.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4e284e0a7a0474b4dc4d3031424074d45c06dfb3f4432d78a3c64c2ec9ca77ba
-  data.tar.gz: 1b09f1436d6f8b18bcfb7f39b4f4f33e311438bb79a020a6b9f47c777cdada15
+  metadata.gz: 6a3a937701ee11dbf64dc080a8299fb1130210c6776b8693f79e8ed8d42a3fd8
+  data.tar.gz: 52aec9d2d61684846076dbf8250530c73246da207533cfcc032855004b5a8680
 SHA512:
-  metadata.gz: 1778cebf0236280efaab60e63ec3f6591742e12188c27c152923d6ee58ad1eb04bc71c74b14f1b606ed93ea3212d8f307fc31e284db0a595235f20848311907e
-  data.tar.gz: 653515517233ee6b0d94245098c0d5dff6bd48cf3c708183b86158c9147a579aeac9ab345d5b52eda9ac7d53fc8f291feedfc2e286291da26a38fe123cf88f0e
+  metadata.gz: 170382234eebd4e10dea7d3248d8e829d0db40f764441ad264335d0b73dcb5806b71cf03078a1ed582053ff3e5b971d7f8b8309e56df0845f77f38c63346cc52
+  data.tar.gz: 7be06ef7af2f171fbcde39759f19dd81096307e095e60944df357c2aba58f8614b17c1335e8efa26a78fbb459aafb3a36baef4b479ac0513fdb66fc55420d6c0

data/CHANGELOG.md

@@ -6,6 +6,49 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.4] - 2026-10-24
+
+### Added — ask whether the Terms in force were agreed, under any policy
+
+- **`user.clickwraps.agreed_to_current_version_of?(:terms)`.** An invoicing
+  app on the fleet records the Terms agreement under two policies, signup and
+  re-acceptance, and had to write this query itself, because `current_for?`
+  reads one policy and `agreed_to?` ignores versions. The predicate is true
+  when a satisfied agreement to that statement, under any policy, recorded
+  the version in force now of each document the statement binds. A version
+  with a later `effective_at` counts only from that time. Until then, the
+  agreement to the version in force still counts. No agreement is false, and
+  so is an agreement under a policy that is no longer declared. It takes the
+  `subject:`, `tenant:` and `acting_for:` keywords of `agreed_to?`, with the
+  same defaults.
+
+  ```ruby
+  requires_clickwrap :current_terms,
+                     unless: -> { current_user.clickwraps.agreed_to_current_version_of?(:terms) }
+  ```
+
+### Fixed — tenant evidence re-asks when the shared document moves on
+
+- **`require_current_version: true` never re-asked evidence recorded in a
+  tenant that was offered the shared document.** The presenter offers a
+  tenant its own document and falls back to the shared one. The staleness
+  check looked only for the tenant's own document, found none, and answered
+  "current" whatever version was in force. The check now resolves the
+  document the way the presenter does, so a new shared version re-asks that
+  evidence. Evidence against a tenant's own document is unchanged.
+
+### Changed
+
+- The "is this version current?" rule moved from a private method of
+  `Clickwrap::Verification` to `StatementState#document_key_with_unseen_current_version`.
+  `require_current_version: true` and the new predicate call the same method,
+  so they cannot disagree.
+- The rule reads version ids only, through `Clickwrap::DocumentVersionsInForce`,
+  and never loads document bytes. The predicate looks up each document once
+  per call, however many policies recorded the agreement.
+  `Document#current_version` and this lookup share one scope,
+  `DocumentVersion.presentable_newest_first`.
+
 ## [0.3.3] - 2026-08-31
 
 ### Fixed — the actor class survives a reload

data/README.md

@@ -569,6 +569,7 @@ The actor proxy is the everyday API:
 ```ruby
 user.clickwraps.current_for?(:signup)
 user.clickwraps.agreed_to?(:terms)
+user.clickwraps.agreed_to_current_version_of?(:terms)
 user.clickwraps.consented_to?(:product_updates)
 user.clickwraps.declared?(:independent_contractor, subject: scheme)
 user.clickwraps.authorized?(:withdrawal, subject: withdrawal)
@@ -623,6 +624,17 @@ Publish a new version and `current_for?` flips to `false` for everyone who accep
 bin/rails clickwrap:reacceptance:plan POLICY=current_terms
 ```
 
+`current_for?(:current_terms)` reads only the evidence recorded under `:current_terms`. A person who signed up an hour ago agreed to the Terms in force under `:signup`, and has nothing under `:current_terms` yet. A gate on that policy alone sends them back to accept the same text again. Ask across every policy that records the agreement instead:
+
+```ruby
+class DashboardController < ApplicationController
+  requires_clickwrap :current_terms,
+                     unless: -> { current_user.clickwraps.agreed_to_current_version_of?(:terms) }
+end
+```
+
+`agreed_to_current_version_of?` applies the rule `require_current_version: true` applies. A version published with a later `effective_at` counts only from that time, so the gate starts on the effective date and not on the deploy that gives notice. Until then, the agreement to the version in force still counts. It takes the `subject:`, `tenant:` and `acting_for:` keywords of `agreed_to?`, with the same defaults. Like `agreed_to?`, it reads the current-state projection; `Clickwrap.verify` is the call that rechecks the evidence itself.
+
 ## Consent that can actually be withdrawn
 
 Consent is purpose-specific, initially unselected, and separate from Terms:
@@ -1015,6 +1027,8 @@ class ApplicationController < ActionController::Base
 end
 ```
 
+A person who accepted the Terms in force at signup did so under `:signup`, not under `:current_terms`. Let them through as [Reacceptance when documents change](#reacceptance-when-documents-change) shows.
+
 Publish the new version and every signed-in user gets redirected to the acceptance screen on their next request — and sent back to wherever they were going the moment they accept. Preview the blast radius before you activate it:
 
 ```bash

data/guides/consent-and-lifecycle.md

@@ -256,6 +256,7 @@ way past — it is the shape of the code.
 user.clickwraps.current_for?(:signup)
 user.clickwraps.required_for?(:current_terms)
 user.clickwraps.agreed_to?(:terms)
+user.clickwraps.agreed_to_current_version_of?(:terms)   # under any policy
 user.clickwraps.acknowledged?(:privacy_notice)
 user.clickwraps.consented_to?(:product_updates)
 user.clickwraps.declared?(:independent_contractor, subject: scheme)

data/lib/clickwrap/actor_proxy.rb

@@ -34,6 +34,37 @@ module Clickwrap
       satisfied?("agreement", statement_key, subject: subject, tenant: tenant, acting_for: acting_for)
     end
 
+    # Whether the actor agreed to the version in force now of each document
+    # this statement binds, under ANY policy that records the statement.
+    #
+    # Neither neighbour answers this. `agreed_to?` reads the newest agreement
+    # and ignores versions. `current_for?` checks versions inside one policy
+    # only. A signup form and a re-acceptance screen usually record the same
+    # `agree_to :terms` under two policies, so a person who signed up an hour
+    # ago has the version in force under `:signup` and nothing under
+    # `:current_terms`. A gate on `current_for?(:current_terms)` alone sends
+    # that person back to accept the same text again.
+    #
+    # "In force" is the rule `require_current_version: true` applies: a version
+    # with a later `effective_at` counts only from that time, and until then
+    # the acceptance of the version it replaces still counts. An agreement that
+    # no longer stands does not count. No agreement at all is false.
+    #
+    # The scope keywords mean what they mean on `agreed_to?`, and so do their
+    # defaults: no subject, no tenant, not acting for anyone. That default is
+    # where a `tenant_is :not_applicable` policy records its evidence.
+    def agreed_to_current_version_of?(statement_key, subject: nil, tenant: nil, acting_for: nil)
+      # Each policy that recorded the agreement usually binds the same
+      # documents, so their versions in force are looked up once per call.
+      versions_in_force = DocumentVersionsInForce.new
+
+      states(subject: subject, tenant: tenant, acting_for: acting_for)
+        .for_statement(statement_key)
+        .where(kind: "agreement")
+        .order(effective_at: :desc)
+        .any? { |state| state.satisfies? && agreed_to_current_versions?(state, versions_in_force) }
+    end
+
     def acknowledged?(statement_key, subject: nil, tenant: nil, acting_for: nil)
       satisfied?("acknowledgment", statement_key, subject: subject, tenant: tenant, acting_for: acting_for)
     end
@@ -105,6 +136,18 @@ module Clickwrap
       )
     end
 
+    # The documents come from the statement as its policy declares it now,
+    # exactly as `require_current_version` reads them. Evidence under a policy
+    # that is no longer declared has nothing to check against, and "cannot
+    # check" is never "yes".
+    def agreed_to_current_versions?(state, versions_in_force)
+      statement = Clickwrap.policies[state.policy_key]&.statement(state.statement_key)
+      return false unless statement
+
+      state.document_key_with_unseen_current_version(statement.document_keys,
+                                                     versions_in_force: versions_in_force).nil?
+    end
+
     def satisfied?(kind, statement_key, subject:, tenant:, acting_for:)
       state = state_for(kind, statement_key, subject: subject, tenant: tenant, acting_for: acting_for)
       !state.nil? && state.satisfies?

data/lib/clickwrap/document_versions_in_force.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Clickwrap
+  # The id of the version in force of each document: the version
+  # `Document#current_version` returns, for one locale at one moment.
+  #
+  # A re-acceptance gate asks this on every protected write, once for each
+  # policy that recorded the agreement. Those policies usually bind the same
+  # documents, so each document is looked up once and the answer is kept for
+  # the life of this object. The lookup reads ids only, because a version row
+  # also holds the document's bytes and this question needs none of them.
+  #
+  # A tenant's own document wins over the shared one, as the presenter chooses
+  # them. Evidence recorded in a tenant that was offered the shared document
+  # is therefore compared with the shared document's version in force.
+  class DocumentVersionsInForce
+    def initialize(locale: I18n.locale, at: Clickwrap.now)
+      @locale = locale
+      @at = at
+      @ids = {}
+    end
+
+    # nil when the document is not published or has no version in force.
+    def id_for(document_key, tenant_key: nil)
+      key = [document_key.to_s, tenant_key.presence]
+      return @ids[key] if @ids.key?(key)
+
+      @ids[key] = look_up(*key)
+    end
+
+    private
+
+    def look_up(document_key, tenant_key)
+      document_id = document_id_for(document_key, tenant_key)
+      return nil unless document_id
+
+      DocumentVersion.where(document_id: document_id).presentable_newest_first(@at, @locale).pick(:id)
+    end
+
+    def document_id_for(document_key, tenant_key)
+      ids = Document.where(document_key: document_key, tenant_key: [tenant_key, nil].uniq)
+                    .pluck(:tenant_key, :id)
+                    .to_h
+
+      ids.fetch(tenant_key) { ids[nil] }
+    end
+  end
+end

data/lib/clickwrap/models/document.rb

@@ -28,13 +28,7 @@ module Clickwrap
     # always writes an `effective_at`, so no NULL reaches this comparison and
     # PostgreSQL and SQLite agree about which document the server offered.
     def current_version(locale: I18n.locale, at: Clickwrap.now)
-      versions
-        .published
-        .effective_at_or_before(at)
-        .not_retired_at(at)
-        .for_locale(locale)
-        .order(effective_at: :desc, published_at: :desc, created_at: :desc)
-        .first
+      versions.presentable_newest_first(at, locale).first
     end
 
     def version(label, locale: I18n.locale)

data/lib/clickwrap/models/document_version.rb

@@ -34,6 +34,17 @@ module Clickwrap
     scope :effective_at_or_before, ->(moment) { where(effective_at: ..moment).or(where(effective_at: nil)) }
     scope :not_retired_at, ->(moment) { where(retired_at: nil).or(where(retired_at: moment...)) }
 
+    # The versions a policy may present at `moment` in `locale`, the one to
+    # present first. `Document#current_version` and
+    # `DocumentVersionsInForce` both read this scope, so they cannot disagree.
+    scope :presentable_newest_first, lambda { |moment, locale|
+      published
+        .effective_at_or_before(moment)
+        .not_retired_at(moment)
+        .for_locale(locale)
+        .order(effective_at: :desc, published_at: :desc, created_at: :desc)
+    }
+
     # Publishing freezes content. Editing a published version is refused here
     # rather than in a code review, because the whole promise of this table is
     # that its rows do not change.

data/lib/clickwrap/models/statement_state.rb

@@ -86,6 +86,26 @@ module Clickwrap
       true
     end
 
+    # The first of these documents whose version in force now is not one this
+    # state recorded, or nil when this state recorded each of them. "In force"
+    # is `Document#current_version` for the request's locale, with this
+    # state's tenant document first and the shared document after it, as the
+    # presenter offered them. So a version published with a later
+    # `effective_at` changes nothing before that time, and a document with no
+    # version in force changes nothing either. `require_current_version: true`
+    # and `agreed_to_current_version_of?` both ask this method, so a gate and
+    # a predicate never disagree about which version is current. Pass one
+    # `versions_in_force` to several states to look each document up once.
+    def document_key_with_unseen_current_version(document_keys, versions_in_force: DocumentVersionsInForce.new)
+      recorded = Array(document_version_ids).map(&:to_s)
+
+      Array(document_keys).find do |document_key|
+        current_id = versions_in_force.id_for(document_key, tenant_key: tenant_key)
+
+        current_id && !recorded.include?(current_id.to_s)
+      end
+    end
+
     # Why it does not, as one of the stable error symbols applications branch
     # on. Never an English string: an authorization decision should not depend
     # on parsing a message.

data/lib/clickwrap/verification.rb

@@ -218,7 +218,7 @@ module Clickwrap
         end
 
         if statement.requires_current_version?
-          stale = stale_document?(statement, state)
+          stale = state.document_key_with_unseen_current_version(statement.document_keys)
 
           if stale
             return Result.failure(:unseen_document_version,
@@ -482,23 +482,6 @@ module Clickwrap
         value = statement.subject_fingerprint_with.call(subject)
         value.nil? ? nil : Digest.digest(value.to_s)
       end
-
-      # Returns the document key whose current published version is newer than
-      # the one this evidence was captured against, or nil when everything the
-      # statement requires is still current.
-      def stale_document?(statement, state)
-        recorded = Array(state.document_version_ids).map(&:to_s)
-
-        statement.document_keys.find do |document_key|
-          document = ::Clickwrap::Document.find_by(
-            document_key: document_key,
-            tenant_key: state.tenant_key.presence
-          )
-          current = document&.current_version(locale: I18n.locale)
-
-          current && !recorded.include?(current.id.to_s)
-        end
-      end
     end
   end
 end

data/lib/clickwrap/version.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Clickwrap
-  VERSION = "0.3.3"
+  VERSION = "0.3.4"
 
   # The canonical schema version for receipts, event digests, and presentation
   # manifests. This is deliberately independent of VERSION: gem releases may

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: clickwrap
 version: !ruby/object:Gem::Version
-  version: 0.3.3
+  version: 0.3.4
 platform: ruby
 authors:
 - rameerez
 bindir: exe
 cert_chain: []
-date: 2026-08-31 00:00:00.000000000 Z
+date: 2026-10-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: actionpack
@@ -217,6 +217,7 @@ files:
 - lib/clickwrap/document_renderer.rb
 - lib/clickwrap/document_renderers/markdown.rb
 - lib/clickwrap/document_renderers/markdown_rails.rb
+- lib/clickwrap/document_versions_in_force.rb
 - lib/clickwrap/dsl/policy_builder.rb
 - lib/clickwrap/dsl/retention_builder.rb
 - lib/clickwrap/durable_commit_callback.rb