clickwrap 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4f6304579666eb5ab8765fd22bb279e897ae328b166fe7f6d3ae5addcc61b61a
-  data.tar.gz: 67be7cf559b23e5f85b14a37f0d72a343015ba2ac69d717b0951ef9e026d1199
+  metadata.gz: 601c5b3f678c4b70f6a9b5466230a445f41bbb6c944a3479ce60ef252f189768
+  data.tar.gz: 8137ed6901d3b33f93b18d1300ecf548eec2bb5e90cb59410d7614060e80d73d
 SHA512:
-  metadata.gz: b382d32b2a7c4dbccb05a2700b06b334255016c0c6bd8883e20ee1129030e47fc68959dcfc5aeebddd73ba517b68da927ec460bbb64ca52e7f82188d6ebe450a
-  data.tar.gz: 4b98d8d3d68a1d35d4497c1ebf6091de0fc2699ea382884495657f207b4f428b34a596d2adc7a1e95abf951e14287d1d0ab38a49e2bce4f9f2c06cfc5966e598
+  metadata.gz: 6313bfced4a79586e71d32ee58c4e216a6a7f96b1e0910fb066f877bc3c0465fb0408bcf1d5690f630472f92584f27209ed87a1c686bae20dae1116b2fd654cc
+  data.tar.gz: c950b0d74657b7b9965b00a7cd6274bbe62ce5fb827e20a6d076980a4b168f19a215fc3f3900a817422cc036e57698f7ef5ae77fbcdc76a7f41793421889dd66

data/CHANGELOG.md

@@ -6,6 +6,35 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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:
@@ -752,13 +764,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/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
@@ -66,7 +73,7 @@ module Clickwrap
 
       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 +81,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/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/version.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Clickwrap
-  VERSION = "0.1.1"
+  VERSION = "0.2.0"
 
   # 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.0
 platform: ruby
 authors:
 - rameerez