clickwrap 0.2.0 → 0.3.0

data/lib/clickwrap/services/validate_policy_references.rb

@@ -15,7 +15,6 @@ module Clickwrap
         Clickwrap.policies.each do |policy|
           validate_documents!(policy)
           retention_class = validate_retention_class!(policy)
-          validate_request_evidence_retention!(policy, retention_class)
           validate_host_calculations!(policy, retention_class)
           validate_authority_adapter!(policy)
           validate_ip_geolocation_resolver!(policy)
@@ -105,20 +104,13 @@ module Clickwrap
           )
       end
 
-      def validate_request_evidence_retention!(policy, retention_class)
-        RequestEvidencePolicy::FIELD_CATEGORIES.each do |category|
-          setting = policy.request_evidence.setting_for(category)
-          next unless setting.record?
-          next if setting.delete_after || setting.retain_until || retention_class.rule_for(category)
-
-          raise DefinitionError,
-                "Policy #{policy.key} records #{category}, but neither that policy nor retention " \
-                "class #{retention_class.key} says when to dispose of it. Add " \
-                "`delete_after:`/`retain_until:` to the policy or the matching plain-English " \
-                "request-evidence rule to the retention class."
-        end
-      end
-
+      # There is deliberately no disposal check here any more. A recorded
+      # category with no clock anywhere — not on the policy, not in its
+      # retention class, not in the initializer — means it keeps pace with the
+      # evidence it corroborates, which is what the core event does by default
+      # too. What still fails below is a rule that names a calculation nobody
+      # registered: a deadline waiting on a typo never arrives, and that is a
+      # different thing from a deliberate absence of one.
       def validate_host_calculations!(policy, retention_class)
         referenced = retention_class.rules.values.filter_map do |rule|
           rule.host_event_name&.to_sym

data/lib/clickwrap/version.rb

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

data/lib/clickwrap/vocabulary.rb

@@ -160,6 +160,33 @@ module Clickwrap
       accuracy_radius_in_kilometers
     ].freeze
 
+    # The three coarse fields `config.record_request_evidence_by_default = true`
+    # turns on. Coarse means administrative area, not a point: a country, a
+    # region, and a city are what a provider can estimate from an address with
+    # any confidence at all. Everything finer — a postal code, coordinates, a
+    # timezone, a metro code — stays its own separately named decision, because
+    # a switch that reads "record request evidence" should not hand somebody
+    # coordinates they never asked for.
+    COARSE_IP_GEOLOCATION_DATA_FIELDS = %w[country region city].freeze
+
+    # The purpose Clickwrap records when a host enables request evidence
+    # without writing a purpose of their own. It is the gem's own sentence, not
+    # a reviewed host decision, and the privacy inventory says which of the two
+    # it is looking at. It exists because the alternative — refusing to boot
+    # until somebody writes a sentence — was pushing integrators to record
+    # nothing at all, and no corroboration is worse evidence than corroboration
+    # collected under the gem's stated purpose.
+    DEFAULT_REQUEST_EVIDENCE_PURPOSE =
+      "Corroborate who performed each recorded act, from where, on what client — to defend " \
+      "the recorded agreement itself."
+
+    # The reason recorded when a host keeps request evidence indefinitely
+    # without writing their own. Same posture as the purpose above: the
+    # declaration is still recorded and still readable years later; only the
+    # obligation to phrase it yourself is gone.
+    DEFAULT_REASON_FOR_KEEPING_REQUEST_EVIDENCE_INDEFINITELY =
+      "Corroboration lives as long as the evidence it corroborates"
+
     # Provenance that travels with any stored IP-geolocation result. A policy
     # cannot keep provider-derived coordinates while stripping the uncertainty
     # needed to interpret them.

data/lib/generators/clickwrap/install_generator.rb

@@ -28,9 +28,13 @@ module Clickwrap
     # spelling of the off-by-default posture. It disappears after generation;
     # it is deliberately not a runtime concept. There is no
     # `record_network_context`, `record_everything`, `full_evidence`, or
-    # regulation-named mode switch anywhere in this gem, because a flag that
-    # enables a whole category of personal data is the thing this gem exists not
-    # to do, and no flag can make a legal determination on a host's behalf.
+    # regulation-named mode switch anywhere in this gem, because a flag whose
+    # name hides what it collects is the thing this gem exists not to ship, and
+    # no flag can make a legal determination on a host's behalf. The runtime's
+    # one grouped switch, `config.record_request_evidence_by_default`, is not
+    # one of those: it names its three fields and can never grow a fourth. The
+    # installer still asks about them one at a time, because a purpose the host
+    # wrote beats the honest default the gem would otherwise record.
     class InstallGenerator < Rails::Generators::Base
       include ActiveRecord::Generators::Migration
 

data/lib/generators/clickwrap/templates/initializer.rb.erb

@@ -28,8 +28,11 @@
 #
 # There is deliberately no `maximum_evidence`, `full_evidence`, `legal_proof`,
 # or regulation-named mode setting. No runtime flag can make a legal
-# determination for you, and an option that turns on a category of personal data
-# as a side effect of something else is exactly what this gem exists not to do.
+# determination for you, and an option whose name does not say what it collects
+# is exactly what this gem exists not to ship. The one grouped switch that does
+# exist, `config.record_request_evidence_by_default`, names its own contents:
+# an IP address, a browser user agent, and a coarse country/region/city
+# estimate — nothing finer, ever.
 <%- if recipe -%>
 #
 # This file was scaffolded with `--request-evidence-recipe=<%= recipe %>`. The
@@ -251,10 +254,12 @@ Clickwrap.configure do |config|
   # proof that anyone was physically anywhere.
 <%- if records_any_request_evidence? -%>
   #
-  # You enabled some of these during install. The generator required an explicit
-  # purpose and deletion period before writing this file; review both below. The
-  # annex table itself came with `--with-request-evidence`, which this install
-  # added for you.
+  # You enabled some of these during install, and the installer asked for an
+  # explicit purpose and deletion period before writing this file; review both
+  # below. The gem itself would have accepted the fields without them and
+  # recorded its own stated purpose instead — the installer asks because a
+  # sentence your team wrote is worth more than one the gem supplied. The annex
+  # table came with `--with-request-evidence`, which this install added for you.
 <%- else -%>
   #
   # Everything here is off, which is the safe default — and the annex table was
@@ -272,12 +277,15 @@ Clickwrap.configure do |config|
 
   # --- Request evidence: why, how long, and how it is protected ---------------
   #
-  # An enabled field with a blank purpose or no deletion rule is a configuration
-  # error at boot, not a warning. "We turned it on and never decided why" is the
-  # failure mode these settings exist to prevent. There is no keep-forever
-  # default anywhere in this gem, and deleting a value removes the encrypted
-  # annex entry and appends a disposition event — the historical agreement,
-  # declaration, or authorization stays intact and verifiable without it.
+  # Both of these are optional, and the installer wrote yours because you gave
+  # them. A field enabled with no purpose records the one Clickwrap states, and
+  # the privacy inventory marks it as the gem's sentence rather than yours; a
+  # field with no deletion period keeps pace with the evidence it corroborates.
+  # What is refused is a purpose that is still scaffolding text, and a deletion
+  # period set alongside `keep_recorded_..._indefinitely!` for the same field.
+  # Deleting a value removes the encrypted annex entry and appends a disposition
+  # event — the historical agreement, declaration, or authorization stays intact
+  # and verifiable without it.
 
 <%- if record_ip_addresses? -%>
   config.reason_for_recording_ip_addresses_by_default =
@@ -301,10 +309,10 @@ Clickwrap.configure do |config|
   config.review_default_request_evidence_configuration_on = <%= review_date_literal %>
 <%- else -%>
   # Nothing above is enabled, so there is nothing to give a purpose or a
-  # deletion period to. Enabling a field is never one line — the gem refuses an
-  # enabled field with no recorded purpose and no deletion rule — and it wants a
-  # review date so the decision gets looked at again by a person instead of
-  # outliving its reason:
+  # deletion period to. Turning the ordinary three on later is one line —
+  # `config.record_request_evidence_by_default = true` — and these are the
+  # settings that upgrade it into a record your own team reviewed, plus a date
+  # so the decision gets looked at again instead of outliving its reason:
   #
   # config.reason_for_recording_ip_addresses_by_default = "Investigate disputed submissions"
   # config.delete_recorded_ip_addresses_after = 90.days
@@ -359,7 +367,9 @@ Clickwrap.configure do |config|
     Clickwrap.trusted_proxy_configuration_digest_for_rails_application
 <%- else -%>
   # A digest of the effective trusted-proxy rules, stored beside any recorded
-  # address. Nothing here records one, so there is nothing to stamp:
+  # address. Nothing here records one, so there is nothing to stamp. Set it if
+  # you enable IP recording later: it is not required, but without it every
+  # recorded address carries a blank where its collection context should be.
   #
   # config.trusted_proxy_configuration_digest =
   #   Clickwrap.trusted_proxy_configuration_digest_for_rails_application
@@ -368,8 +378,9 @@ Clickwrap.configure do |config|
 <%- if any_ip_geolocation_field? -%>
   # DECISION — you enabled IP-geolocation fields and explicitly selected this
   # resolver. Make its gem and data source available in every environment:
-  # Clickwrap refuses to boot with fields it has nothing to resolve, rather than
-  # recording blanks that later read as "no result".
+  # Clickwrap refuses to boot with fields nothing can resolve — no resolver here
+  # and no trackdown in the bundle — rather than recording blanks that later
+  # read as "no result".
   #
   # Only the fields authorized above are stored, never the whole result object,
   # and every stored value keeps the provider, source, estimated state,
@@ -378,11 +389,18 @@ Clickwrap.configure do |config|
   # needed to read them.
   config.ip_geolocation_resolver = <%= ip_geolocation_resolver_class_name %>.new
 <%- else -%>
-  # Required before any IP-geolocation field can be enabled, here or in a
-  # policy. The official optional resolver requires trackdown >= 0.4 so the
-  # provider that actually answered and per-request source trust are preserved:
+  # Something has to resolve an IP-geolocation field before it can be enabled,
+  # here or in a policy. Bundling trackdown is enough — Clickwrap uses the
+  # official adapter for you when you have not named a resolver of your own,
+  # and the privacy inventory reports it as the gem's choice rather than yours.
+  # It requires trackdown >= 0.4 so the provider that actually answered and
+  # per-request source trust are preserved:
   #
   #   bundle add trackdown --version ">= 0.4"
+  #
+  # Name it explicitly to pick a different provider, or when you are wiring
+  # Trackdown's per-request CDN trust:
+  #
   #   config.ip_geolocation_resolver = Clickwrap::IpGeolocation::TrackdownResolver.new
 <%- end -%>
 

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: clickwrap
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - rameerez
 bindir: exe
 cert_chain: []
-date: 2026-08-19 00:00:00.000000000 Z
+date: 2026-08-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: actionpack