clickwrap 0.1.1 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4f6304579666eb5ab8765fd22bb279e897ae328b166fe7f6d3ae5addcc61b61a
-  data.tar.gz: 67be7cf559b23e5f85b14a37f0d72a343015ba2ac69d717b0951ef9e026d1199
+  metadata.gz: be18f8fc09eee066b71a234a134440010c6cf2beb82987b4bbe3636dde2f9133
+  data.tar.gz: a2c66a9be09cf999de30d890c4338e084146414cadbe0747022a3aedc8a4ef5f
 SHA512:
-  metadata.gz: b382d32b2a7c4dbccb05a2700b06b334255016c0c6bd8883e20ee1129030e47fc68959dcfc5aeebddd73ba517b68da927ec460bbb64ca52e7f82188d6ebe450a
-  data.tar.gz: 4b98d8d3d68a1d35d4497c1ebf6091de0fc2699ea382884495657f207b4f428b34a596d2adc7a1e95abf951e14287d1d0ab38a49e2bce4f9f2c06cfc5966e598
+  metadata.gz: 891f939a6b827915a5d2703ecf98b0ed9b9e761d3689a1117e8ba3df6ae0450c50a3f9d53edd0cbf844e996a7be447b080070b6ab2d916409b5d1ecfdc851ddc
+  data.tar.gz: 2387391b3d960d05dcdc783221bb5653de21406ecd0173b8fbafa1dc17d716549044a22bc719740892553b8a9c66beb8b42417c61e9bc7f585d569849fa43d9d

data/CHANGELOG.md

@@ -6,6 +6,55 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.1] - 2026-08-19
+
+### Added — request evidence can keep pace with the evidence it corroborates
+
+- **`keep_recorded_{ip_addresses,browser_user_agents,ip_geolocation}_indefinitely!(because:)`.**
+  By-default request evidence used to demand a deletion clock, which — after
+  0.2.0 flipped core evidence to keep-indefinitely — scheduled the
+  corroboration (IP, user agent, geolocation) to expire before the agreement
+  it corroborates. The third option now exists and must be said out loud with
+  a reason, like every escape hatch here. Declaring both a clock and
+  keep-indefinitely is refused as opposite decisions.
+
+### Documentation
+
+- The request-evidence README section now argues FOR recording: IP + user
+  agent + geolocation are what cement a recorded act to a person when the
+  dispute is "that wasn't me", and the recommended posture is on-by-default
+  with the purpose written down. The discipline is unchanged — no silent
+  enablement, per-field decisions, encryption, reviewed proxy provenance.
+
+## [0.2.0] - 2026-08-19
+
+### Changed — evidence is kept indefinitely by default
+
+- **The default retention posture is now indefinite.** A policy that never
+  says `retain_with` runs under a new built-in retention class,
+  `evidence_kept_indefinitely`: no deletion clock on the core event, none on
+  any request evidence. Previously such a policy refused to boot. The
+  direction is deliberate: keeping is reversible — a reviewed disposition can
+  always run later — while deletion is not, and the day contractual evidence
+  matters is usually years past every convenient schedule. Deletion is the
+  explicit, reviewed opt-in it always was: declare a class with clocks and
+  name it on the policy.
+- **A retention class may keep the core event forever.** New DSL verb
+  `retain_core_event_indefinitely` says the default out loud; omitting the
+  core-event rule now means the same thing instead of raising. Snapshots
+  record `{"indefinite" => true}`, the privacy inventory reports
+  `{"kind" => "indefinite"}`, events under such a class freeze no deadline,
+  and the retention planner never lists them as due — on any horizon.
+- **Registries can carry built-in seeds.** `Registry#clear` (every reload)
+  now returns a seeded registry to its built-ins instead of to nothing, which
+  is what keeps the default retention class alive across `to_prepare`.
+
+### Documentation
+
+- The README installs from rubygems.org (`gem "clickwrap"`), documents the
+  new retention default, and shows HTML pages and runtime `resolver:` sources
+  for legal documents alongside Markdown.
+
 ## [0.1.1] - 2026-08-19
 
 ### Fixed — the composed sentence in a language that declines its articles

data/README.md

@@ -72,6 +72,16 @@ Clickwrap.document :handbook,
   from: Rails.root.join("app/content/legal/handbook.pdf")
 ```
 
+Markdown is a convention here, not a requirement. `from:` takes HTML pages (`.html`/`.htm`), plain text, JSON, and PDF just as readily — the media type is inferred from the extension or named with `media_type:` — and an HTML source is sanitized at publish through the same safe-list every rendering passes (semantic tags survive; scripts, styles, and event handlers never become part of legal evidence). A page that only exists at runtime — an ERB view, a CMS entry — publishes through a `resolver:`, a callable that hands over the exact bytes at publish time:
+
+```ruby
+Clickwrap.document :terms,
+  version: "2026-08-15",
+  media_type: "text/html",
+  resolver: ->(definition) { ApplicationController.render(template: "legal/terms", layout: false) },
+  link: "/legal/terms"
+```
+
 #### Reading that front matter yourself: `Clickwrap::FrontMatter`
 
 Your own pages usually need the same two answers, and it is the same block, so use the same reader rather than writing a third one:
@@ -146,7 +156,7 @@ Add the gem and run the installer:
 
 ```ruby
 # Gemfile
-gem "clickwrap", github: "rameerez/clickwrap"
+gem "clickwrap"
 ```
 
 ```bash
@@ -319,6 +329,8 @@ other render.
 
 ## How it works
 
+Most Rails apps treat "user agreed" as `accepted_terms_at` plus a checkbox. That's enough until you have to answer: which exact text, which version, what the button said, whether the box started unchecked, and whether the action happened without that evidence.
+
 Most apps eventually accumulate an `accepted_terms_at` column, a `terms_version` string, a few hidden form fields, an `after_create` callback, and some IP columns. Each part looks reasonable alone. Together they produce partial writes, client-owned policy decisions, mutable history, and evidence only the original engineer can explain.
 
 `clickwrap` replaces that plumbing with one coherent primitive:
@@ -706,9 +718,43 @@ Golden fixtures make a verifier regression for any released receipt schema fail
 
 With the engine mounted, users can view and download their own receipts, and operator access is always host-authorized. Read the [receipts and verification guide](guides/receipts-and-verification.md) for exports, bundles, and what each verification tier does and doesn't establish.
 
-## Request evidence is off by default
+## Request evidence: record it — it's what cements the act to a person
 
-`clickwrap` always records its event ID, server time, capture channel, and policy version. It records **no** IP addresses, browser user-agents, or IP geolocation unless a policy names the field with a purpose and a retention rule:
+`clickwrap` always records its event ID, server time, capture channel, and policy version. That proves **what was offered and what came back**. But an agreement dispute is rarely about the words — it's "that wasn't me" — and the answer to that is request evidence: the IP address, the browser, and where in the world the request came from, bound into the same digest-linked record at the same instant. Years later, "this exact sentence was accepted from this address, on this client, from this city, at this second, in the transaction that created the account" is a different conversation from "the row says yes". **Our recommendation is to record IP + user agent + geolocation on every assent policy** — you already hold a purpose (defending the very agreement being made) and the evidence lives encrypted, in its own annex, deletable on its own schedule if your counsel ever decides so.
+
+What the gem refuses to do is turn it on *silently*. Every field is a separate named decision with a written purpose — there is deliberately no `maximum_evidence` switch — so the recommended posture is three explicit blocks in your initializer:
+
+```ruby
+# clickwrap-doc-test: syntax-only — the resolver needs trackdown installed
+Clickwrap.configure do |config|
+  config.record_ip_address_by_default = true
+  config.reason_for_recording_ip_addresses_by_default =
+    "Corroborate who performed each recorded act, to defend the agreement itself"
+  config.keep_recorded_ip_addresses_indefinitely!(
+    because: "Corroboration must live exactly as long as the evidence it corroborates")
+
+  config.record_browser_user_agent_by_default = true
+  config.reason_for_recording_browser_user_agents_by_default =
+    "Corroborate the client context of each recorded act"
+  config.keep_recorded_browser_user_agents_indefinitely!(
+    because: "Corroboration must live exactly as long as the evidence it corroborates")
+
+  config.record_ip_geolocation_country_by_default = true
+  config.record_ip_geolocation_region_by_default = true
+  config.record_ip_geolocation_city_by_default = true
+  config.reason_for_recording_ip_geolocation_by_default =
+    "Corroborate where each recorded act was performed from"
+  config.keep_recorded_ip_geolocation_indefinitely!(
+    because: "Corroboration must live exactly as long as the evidence it corroborates")
+  config.ip_geolocation_resolver = Clickwrap::IpGeolocation::TrackdownResolver.new
+
+  config.review_default_request_evidence_configuration_on = Date.new(2027, 8, 1)
+end
+```
+
+(`keep_recorded_..._indefinitely!` matches the retention default since 0.2.0 — evidence keeps until deletion is an explicit reviewed act. A corroboration that expires before the agreement it corroborates is a scheduled weakening of the record; if your counsel wants a clock instead, `delete_recorded_..._after` is the same one-line decision in the other direction.)
+
+A single regulated surface can also name a field per policy instead of by default:
 
 ```ruby
 Clickwrap.policy :regulated_authorization do
@@ -752,13 +798,17 @@ The [request evidence guide](guides/request-evidence.md) covers every field, the
 
 ## Retention, deletion, and legal holds
 
-Every policy chooses an application-defined retention class:
+**By default, evidence is kept indefinitely.** A policy that never says `retain_with` runs under the built-in `evidence_kept_indefinitely` class: no deletion clock on the core event, none on any request evidence. The direction is deliberate — keeping is reversible (a reviewed disposition can always run later), deletion is not, and the day contractual evidence matters is usually years past every convenient schedule. Deletion is the explicit, opt-in decision:
 
 ```ruby
 Clickwrap.retention :ordinary_agreement_evidence do
-  retain_core_event_for 6.years
-  delete_recorded_ip_address_after 90.days
-  delete_recorded_browser_user_agent_after 90.days
+  retain_core_event_indefinitely          # the default, said out loud
+  delete_recorded_ip_address_after 6.years
+  delete_recorded_browser_user_agent_after 6.years
+end
+
+Clickwrap.retention :short_lived_marketing_evidence do
+  retain_core_event_for 6.years           # a reviewed deletion schedule, opt-in
 end
 ```
 

data/lib/clickwrap/configuration.rb

@@ -228,10 +228,14 @@ module Clickwrap
       @encrypt_recorded_ip_geolocation = true
 
       # nil means "every policy that enables the field must supply its own
-      # rule". There is no keep-forever default anywhere in this gem.
+      # rule" — or, for by-default recording, that the host has said
+      # `keep_recorded_..._indefinitely!(because: "…")` out loud. Keeping
+      # forever is never silent: it is either the per-policy retention class's
+      # explicit business, or a named, reasoned sentence in the initializer.
       @delete_recorded_ip_addresses_after = nil
       @delete_recorded_browser_user_agents_after = nil
       @delete_recorded_ip_geolocation_after = nil
+      @keep_recorded_request_evidence_indefinitely = {}
 
       # Rails' request.remote_ip is the conventional reader. The host remains
       # responsible for configuring and testing trusted proxies correctly:
@@ -895,13 +899,22 @@ module Clickwrap
                 "application's reviewed, present-tense reason, or turn that default off."
         end
 
-        next unless delete_after.nil?
+        if delete_after.present? && keeps_recorded_request_evidence_indefinitely?(category)
+          raise ConfigurationError,
+                "Clickwrap is told both to delete recorded #{category} after " \
+                "#{delete_after.inspect} and to keep it indefinitely. Those are opposite " \
+                "decisions — keep exactly one."
+        end
+
+        next if delete_after.present? || keeps_recorded_request_evidence_indefinitely?(category)
 
         raise ConfigurationError,
-              "Clickwrap is set to record #{category} for every policy by default, but " \
-              "`delete_recorded_#{plural_for(category)}_after` is nil, so nothing would ever " \
-              "delete it. Set a reviewed period, or turn the default off and let each policy " \
-              "choose its own retention rule."
+              "Clickwrap is set to record #{category} for every policy by default, but nothing " \
+              "says how long to keep it. Either set a reviewed period with " \
+              "`delete_recorded_#{plural_for(category)}_after`, or keep it as long as the " \
+              "evidence it corroborates with " \
+              "`keep_recorded_#{plural_for(category)}_indefinitely!(because: \"…\")` — or turn " \
+              "the default off and let each policy choose its own retention rule."
       end
     end
 
@@ -913,6 +926,16 @@ module Clickwrap
       end
     end
 
+    def declare_indefinite_request_evidence!(category, because)
+      if because.to_s.strip.empty?
+        raise ConfigurationError,
+              "keep_recorded_#{plural_for(category)}_indefinitely! needs a `because:` " \
+              "explaining the reviewed decision."
+      end
+
+      @keep_recorded_request_evidence_indefinitely[category] = because
+    end
+
     def validate_trusted_proxy_configuration!
       records_ip_derived_evidence =
         record_ip_address_by_default || enabled_default_ip_geolocation_fields.any?
@@ -1098,6 +1121,32 @@ module Clickwrap
     # The deliberate, named escape hatch referenced by `ensure_encryption_choice`.
     # It exists so that turning encryption off is a sentence a reviewer can find
     # in a diff, with the host's own reason attached, rather than a `false`.
+    # The named escape hatch for by-default request evidence with no deletion
+    # clock: request evidence exists to corroborate evidence that (since 0.2.0)
+    # keeps indefinitely by default, and a corroboration that expires before
+    # the thing it corroborates is a scheduled weakening of the record. Same
+    # rule as every escape hatch here: keeping forever must be a sentence a
+    # reviewer can find in a diff, with the host's own reason attached.
+    def keep_recorded_ip_addresses_indefinitely!(because:)
+      declare_indefinite_request_evidence!(:ip_address, because)
+    end
+
+    def keep_recorded_browser_user_agents_indefinitely!(because:)
+      declare_indefinite_request_evidence!(:browser_user_agent, because)
+    end
+
+    def keep_recorded_ip_geolocation_indefinitely!(because:)
+      declare_indefinite_request_evidence!(:ip_geolocation, because)
+    end
+
+    def keeps_recorded_request_evidence_indefinitely?(category)
+      @keep_recorded_request_evidence_indefinitely.key?(category.to_sym)
+    end
+
+    def reason_for_keeping_recorded_request_evidence_indefinitely(category)
+      @keep_recorded_request_evidence_indefinitely[category.to_sym]
+    end
+
     def deliberately_store_request_evidence_unencrypted!(because:)
       if because.to_s.strip.empty?
         raise ConfigurationError,

data/lib/clickwrap/dsl/retention_builder.rb

@@ -27,6 +27,13 @@ module Clickwrap
         assign_rule!(:core_event, duration:)
       end
 
+      # The default, said out loud. Omitting the core-event rule means the same
+      # thing, but a retention class somebody will read in review is better off
+      # carrying the decision in words.
+      def retain_core_event_indefinitely
+        assign_rule!(:core_event, indefinite: true)
+      end
+
       # For obligations a duration cannot express — "five years, or three years
       # after this contract is liquidated, whichever is later". The named
       # calculation is registered by the host on the configuration object, and
@@ -62,11 +69,26 @@ module Clickwrap
         assign_rule!(:ip_geolocation, host_event_name:)
       end
 
+      # Keeping the annex as long as the core event it corroborates, said in
+      # the retention class itself. A corroboration that expires before the
+      # evidence it corroborates is a scheduled weakening of the record.
+      def keep_recorded_ip_address_indefinitely
+        assign_rule!(:ip_address, indefinite: true)
+      end
+
+      def keep_recorded_browser_user_agent_indefinitely
+        assign_rule!(:browser_user_agent, indefinite: true)
+      end
+
+      def keep_recorded_ip_geolocation_indefinitely
+        assign_rule!(:ip_geolocation, indefinite: true)
+      end
+
       def compile = RetentionClass.new(key: @key, rules: @rules)
 
       private
 
-      def assign_rule!(part, duration: nil, host_event_name: nil)
+      def assign_rule!(part, duration: nil, host_event_name: nil, indefinite: false)
         if @rules.key?(part)
           raise DefinitionError,
                 "Retention class #{@key} declares #{part} more than once. Keep one reviewed " \
@@ -74,7 +96,7 @@ module Clickwrap
                 "deletion deadline."
         end
 
-        @rules[part] = RetentionClass::Rule.new(part:, duration:, host_event_name:)
+        @rules[part] = RetentionClass::Rule.new(part:, duration:, host_event_name:, indefinite:)
       end
 
       def method_missing(name, *_arguments, **_options)

data/lib/clickwrap/models/event.rb

@@ -557,7 +557,9 @@ module Clickwrap
       return if retain_core_event_until.present? || retention_rule_name.present?
 
       rule = Clickwrap.retention_class!(retention_class_key).rule_for(:core_event)
-      return if rule.nil?
+      # An indefinite rule freezes nothing: no deadline, no named calculation.
+      # The blank schedule plus the class key IS the recorded decision.
+      return if rule.nil? || rule.indefinite?
 
       if rule.duration?
         self.retain_core_event_until = recorded_at_by_server + rule.duration

data/lib/clickwrap/policy.rb

@@ -29,7 +29,10 @@ module Clickwrap
                    authority_rule: nil, options: {})
       @key = key.to_s
       @statements = statements.freeze
-      @retention_class_key = retention_class_key&.to_s
+      # A policy that never says `retain_with` keeps its evidence indefinitely
+      # under the built-in class — the reversible default. Deletion clocks are
+      # the reviewed opt-in, declared with `Clickwrap.retention` and named here.
+      @retention_class_key = (retention_class_key || DEFAULT_RETENTION_CLASS_KEY).to_s
       @request_evidence = request_evidence || RequestEvidencePolicy.new(policy_key: @key)
       @persist_presentations_for = persist_presentations_for
       @persist_presentations_because = persist_presentations_because
@@ -238,12 +241,10 @@ module Clickwrap
     end
 
     def validate_retention!
-      return if retention_class_key
-
-      raise DefinitionError,
-            "Policy #{key} has no retention class. Add `retain_with :some_class` and define " \
-            "that class with `Clickwrap.retention`. Clickwrap will not default your evidence " \
-            "to forever, and it will not pick a period for you."
+      # Always present: the initializer defaults a silent policy to the
+      # built-in evidence_kept_indefinitely class. Kept as a method so the
+      # validation order below still reads as the full checklist.
+      raise DefinitionError, "Policy #{key} has no retention class." if retention_class_key.blank?
     end
 
     def validate_persisted_presentations!

data/lib/clickwrap/privacy.rb

@@ -220,6 +220,7 @@ module Clickwrap
       # difference between "not due yet" and "nothing can ever say when".
       def describe_rule(rule)
         return nil if rule.nil?
+        return { "kind" => "indefinite" } if rule.indefinite?
         return { "kind" => "duration", "seconds" => rule.duration.to_i } if rule.duration?
 
         {

data/lib/clickwrap/registry.rb

@@ -9,11 +9,18 @@ module Clickwrap
   # loading the declaration files again. Seeing the same key twice inside one
   # load is therefore always ambiguous and is refused instead of letting file
   # order silently decide which policy governs a production action.
+  #
+  # A registry may carry a seed: built-in entries that are its floor rather
+  # than its contents. Clearing re-runs the seed, so a reload returns to the
+  # built-ins, never to nothing — which is what lets a gem-shipped default
+  # (the indefinite retention class) survive every `to_prepare`.
   class Registry
-    def initialize(kind)
+    def initialize(kind, &seed)
       @kind = kind
       @entries = {}
       @mutex = Mutex.new
+      @seed = seed
+      @seed&.call(self)
     end
 
     attr_reader :kind
@@ -47,7 +54,12 @@ module Clickwrap
     def size = @entries.size
     def empty? = @entries.empty?
     def each(&) = @entries.each_value(&)
-    def clear = @mutex.synchronize { @entries.clear }
+
+    def clear
+      @mutex.synchronize { @entries.clear }
+      @seed&.call(self)
+      self
+    end
 
     include Enumerable
   end

data/lib/clickwrap/request_evidence_extractor.rb

@@ -483,10 +483,14 @@ module Clickwrap
 
     # --- Retention ------------------------------------------------------------
 
-    # Every recorded field leaves here with a disposal rule: a date, or the name
-    # of a host rule that will produce one. There is no keep-forever default
-    # anywhere in this gem, and a recorded field with neither is a configuration
-    # bug caught before the row is written rather than a row nobody ever deletes.
+    # Every recorded field leaves here with a disposal answer: a date, the name
+    # of a host rule that will produce one, or the explicit reviewed decision
+    # to keep it as long as the evidence it corroborates. Keeping forever is
+    # never a silent default — it is a named declaration in the retention class
+    # (`keep_recorded_..._indefinitely`) or the initializer
+    # (`keep_recorded_..._indefinitely!(because: "…")`) — and a recorded field
+    # with no answer at all is a configuration bug caught before the row is
+    # written rather than a row nobody ever decided about.
     #
     # `retain_until` names a host calculation instead of a duration because real
     # record-keeping schedules are not always durations — "five years, or three
@@ -500,6 +504,14 @@ module Clickwrap
       return { "#{category}_delete_after": now + class_rule.duration } if class_rule&.duration?
       return { "#{category}_retain_until_rule": class_rule.host_event_name.to_s } if class_rule&.host_event?
 
+      # Indefinite — declared in the class or application-wide — stamps
+      # nothing: the blank schedule plus the recorded declaration IS the
+      # disposal answer, exactly like an indefinite core event.
+      if class_rule&.indefinite? ||
+         Clickwrap.config.keeps_recorded_request_evidence_indefinitely?(category)
+        return {}
+      end
+
       raise ConfigurationError, missing_retention_message(category)
     end
 
@@ -510,11 +522,13 @@ module Clickwrap
     end
 
     def missing_retention_message(category)
-      "Clickwrap is about to record #{category} for policy #{policy_key} and nothing says when " \
-        "to delete it. Give the policy a rule — `delete_after:` with a reviewed period, or " \
-        "`retain_until:` naming a host retention calculation — or add a #{category} rule to " \
-        "retention class #{policy.retention_class_key.inspect}. Clickwrap has no keep-forever " \
-        "default and will not choose a period for you."
+      "Clickwrap is about to record #{category} for policy #{policy_key} and nothing says what " \
+        "should ever happen to it. Give the policy a rule — `delete_after:` with a reviewed " \
+        "period, or `retain_until:` naming a host retention calculation — add a #{category} " \
+        "rule (or `keep_recorded_#{category}_indefinitely`) to retention class " \
+        "#{policy.retention_class_key.inspect}, or answer it application-wide with " \
+        "`keep_recorded_..._indefinitely!(because: \"…\")`. Keeping forever is never silent, " \
+        "and Clickwrap will not choose for you."
     end
 
     # --- Failing closed -------------------------------------------------------

data/lib/clickwrap/request_evidence_policy.rb

@@ -205,12 +205,15 @@ module Clickwrap
               "as a data-collection purpose."
       end
 
-      if setting.delete_after.nil? && setting.retain_until.nil? && retention_class_key.nil?
+      if setting.delete_after.nil? && setting.retain_until.nil? && retention_class_key.nil? &&
+         !Clickwrap.config.keeps_recorded_request_evidence_indefinitely?(category)
         raise DefinitionError,
-              "Policy #{policy_key} records #{category} but never says when to delete it. " \
-              "Give it `delete_after:` with a duration, or `retain_until:` naming a host event " \
-              "rule, or attach a retention class with a rule for this category. Clickwrap has " \
-              "no keep-forever default."
+              "Policy #{policy_key} records #{category} but nothing says what should ever " \
+              "happen to it. Give it `delete_after:` with a duration, or `retain_until:` " \
+              "naming a host event rule, attach a retention class with a rule for this " \
+              "category, or answer it application-wide with " \
+              "`keep_recorded_..._indefinitely!(because: \"…\")`. Keeping forever is never " \
+              "silent, and Clickwrap will not choose for you."
       end
 
       return unless setting.delete_after && setting.delete_after.to_i <= 0

data/lib/clickwrap/retention/planner.rb

@@ -131,6 +131,15 @@ module Clickwrap
 
           rule = retention_class.rule_for(:core_event)
           return Eligibility.new(rule: nil, unresolved_reason: "No core-event rule is defined.") if rule.nil?
+          if rule.indefinite?
+            # Never due, by design — the reason names the decision, not a gap.
+            # (Scopes skip indefinite classes, so this branch is the answer for
+            # anyone asking about one event directly, and a guard for the
+            # applier's re-check.)
+            return Eligibility.new(rule: "indefinite",
+                                   unresolved_reason: "This event's retention class keeps the core " \
+                                                      "event indefinitely; it is never due.")
+          end
           return resolve_host_event(rule.host_event_name, event) if rule.host_event?
 
           Eligibility.new(eligible_at: event.recorded_at_by_server + rule.duration,
@@ -249,7 +258,7 @@ module Clickwrap
 
         Clickwrap.retention_classes.each do |retention_class|
           rule = retention_class.rule_for(:core_event)
-          next if rule.nil?
+          next if rule.nil? || rule.indefinite?
 
           unscheduled = base_events.where(retain_core_event_until: nil, retention_class_key: retention_class.key)
 

data/lib/clickwrap/retention_class.rb

@@ -5,14 +5,19 @@ module Clickwrap
   # kept, and what triggers the clock.
   #
   #   Clickwrap.retention :ordinary_agreement_evidence do
-  #     retain_core_event_for 6.years
-  #     delete_recorded_ip_address_after 90.days
-  #     delete_recorded_browser_user_agent_after 90.days
-  #     delete_recorded_ip_geolocation_after 90.days
+  #     retain_core_event_indefinitely
+  #     delete_recorded_ip_address_after 6.years
+  #     delete_recorded_browser_user_agent_after 6.years
   #   end
   #
-  # Clickwrap does not choose these periods and cannot tell you whether yours
-  # are right. What it does is make a reviewed decision executable and
+  # The default — for any part not given a rule, the core event included — is
+  # to keep the evidence indefinitely. That direction is deliberate: keeping is
+  # reversible (a reviewed disposition can always run later) while deletion is
+  # not, and the day contractual evidence matters is usually years away.
+  # Deletion is therefore the explicit, reviewed act, never a default.
+  #
+  # Clickwrap does not choose deletion periods and cannot tell you whether
+  # yours are right. What it does is make a reviewed decision executable and
   # auditable, keep the core event's schedule separate from the optional
   # personal request evidence, and delegate event-based or "later of" rules to
   # a named host calculation. The host owns that calculation because a fixed
@@ -21,19 +26,24 @@ module Clickwrap
   class RetentionClass
     PARTS = %i[core_event ip_address browser_user_agent ip_geolocation].freeze
 
-    # A rule is either a duration from the event's server-recorded time, or the
-    # name of a host-registered calculation that may depend on domain state and
-    # may not be resolvable yet.
-    Rule = Data.define(:part, :duration, :host_event_name) do
-      def initialize(part:, duration: nil, host_event_name: nil)
+    # A rule is a duration from the event's server-recorded time, the name of a
+    # host-registered calculation that may depend on domain state and may not
+    # be resolvable yet — or the explicit decision to keep the part forever.
+    Rule = Data.define(:part, :duration, :host_event_name, :indefinite) do
+      def initialize(part:, duration: nil, host_event_name: nil, indefinite: false)
         super
       end
 
       def duration? = !duration.nil?
       def host_event? = !host_event_name.nil?
+      def indefinite? = indefinite
 
       def to_snapshot
-        { "duration_seconds" => duration&.to_i, "host_event" => host_event_name&.to_s }.compact
+        {
+          "duration_seconds" => duration&.to_i,
+          "host_event" => host_event_name&.to_s,
+          "indefinite" => (true if indefinite)
+        }.compact
       end
     end
 
@@ -41,6 +51,12 @@ module Clickwrap
 
     def initialize(key:, rules:)
       @key = key.to_s
+      # A part with no declared rule is kept indefinitely. For the core event
+      # that default is made explicit here, so every consumer — the planner,
+      # the privacy inventory, the snapshot on a plan — sees a reviewed answer
+      # ("indefinite") rather than a silence it must interpret.
+      rules = rules.dup
+      rules[:core_event] ||= Rule.new(part: :core_event, indefinite: true)
       @rules = rules.freeze
 
       validate!
@@ -67,10 +83,11 @@ module Clickwrap
       end
 
       rules.each_value do |rule|
-        if rule.duration? == rule.host_event?
+        if [rule.duration?, rule.host_event?, rule.indefinite?].count(true) != 1
           raise DefinitionError,
                 "Retention class #{key} must give #{rule.part} exactly one schedule: a " \
-                "duration or a named host calculation, not both or neither."
+                "duration, a named host calculation, or indefinite — never a combination " \
+                "and never none."
         end
 
         if rule.host_event? && rule.host_event_name.to_s.strip.empty?
@@ -85,13 +102,6 @@ module Clickwrap
               "Retention class #{key} keeps #{rule.part} for #{rule.duration.inspect}, which is " \
               "not a period."
       end
-
-      return if rules.key?(:core_event)
-
-      raise DefinitionError,
-            "Retention class #{key} never says how long to keep the core event. Use " \
-            "`retain_core_event_for 6.years` or `retain_core_event_until :your_host_event`. " \
-            "Clickwrap has no forever default, and it will not pick a period for you."
     end
   end
 end

data/lib/clickwrap/services/validate_policy_references.rb

@@ -110,15 +110,32 @@ module Clickwrap
           setting = policy.request_evidence.setting_for(category)
           next unless setting.record?
           next if setting.delete_after || setting.retain_until || retention_class.rule_for(category)
+          # The application-wide answer counts too: recording enabled in the
+          # initializer carries its disposal decision in the same place —
+          # either a global clock or the explicit, reasoned keep-indefinitely.
+          next if config_answers_disposal_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."
+                "Policy #{policy.key} records #{category}, but nothing says when to dispose of " \
+                "it. Add `delete_after:`/`retain_until:` to the policy, a plain-English " \
+                "request-evidence rule (or `keep_recorded_#{category}_indefinitely`) to " \
+                "retention class #{retention_class.key}, or answer it application-wide in the " \
+                "initializer with `delete_recorded_..._after` or " \
+                "`keep_recorded_..._indefinitely!(because: \"…\")`."
         end
       end
 
+      def config_answers_disposal_for?(category)
+        clock =
+          case category.to_sym
+          when :ip_address then Clickwrap.config.delete_recorded_ip_addresses_after
+          when :browser_user_agent then Clickwrap.config.delete_recorded_browser_user_agents_after
+          else Clickwrap.config.delete_recorded_ip_geolocation_after
+          end
+
+        clock.present? || Clickwrap.config.keeps_recorded_request_evidence_indefinitely?(category)
+      end
+
       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.1.1"
+  VERSION = "0.2.1"
 
   # The canonical schema version for receipts, event digests, and presentation
   # manifests. This is deliberately independent of VERSION: gem releases may

data/lib/clickwrap.rb

@@ -58,6 +58,10 @@ require_relative "clickwrap/engine" if defined?(Rails::Engine)
 # long you must keep anything. Those belong to the application and its counsel,
 # and no configuration flag here can stand in for them.
 module Clickwrap
+  # The retention class every policy gets unless it names its own with
+  # `retain_with`: evidence kept indefinitely, deletion always an explicit,
+  # reviewed act. Keeping is reversible; deleting is not.
+  DEFAULT_RETENTION_CLASS_KEY = "evidence_kept_indefinitely"
   DOCUMENT_OPTIONS = %i[
     version locale media_type effective_at tenant from content resolver renderer link
   ].freeze
@@ -109,7 +113,19 @@ module Clickwrap
 
     def documents = @documents ||= Registry.new(:document)
     def policies = @policies ||= Registry.new(:policy)
-    def retention_classes = @retention_classes ||= Registry.new(:retention_class)
+
+    # The registry is seeded with one built-in class: evidence kept
+    # indefinitely, nothing scheduled for deletion. It exists so a policy that
+    # never says `retain_with` has a real, inspectable retention class instead
+    # of a hole — keeping is the reversible default; deletion is the reviewed
+    # opt-in. A host wanting deletion clocks declares its own class and names
+    # it on the policy. The seed survives every reload (see Registry#clear).
+    def retention_classes
+      @retention_classes ||= Registry.new(:retention_class) do |registry|
+        registry.register(DEFAULT_RETENTION_CLASS_KEY,
+                          RetentionClass.new(key: DEFAULT_RETENTION_CLASS_KEY, rules: {}))
+      end
+    end
 
     # Declares one immutable document version. Declaring it does not publish it:
     # `bin/rails clickwrap:publish` reads the bytes once, digests them, and

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: clickwrap
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.1
 platform: ruby
 authors:
 - rameerez