clickwrap 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 98648fe84ac49eb6e6f0aa31206529051b15a13317c28ea8405d1b78f49b6668
-  data.tar.gz: f3dd9f393dcd3b0ced96de1fa320608e631962c8531edd2365110d7825c88d85
+  metadata.gz: 601c5b3f678c4b70f6a9b5466230a445f41bbb6c944a3479ce60ef252f189768
+  data.tar.gz: 8137ed6901d3b33f93b18d1300ecf548eec2bb5e90cb59410d7614060e80d73d
 SHA512:
-  metadata.gz: 5d5ccebc49daf312d199a0d0eede813f80966dadb04654ea49345d408b4708b520208e3dd5018dba99eacb815c93ac735fd562691f5a0ddbb88acb725ea86221
-  data.tar.gz: dcdcd70b597f09f91ccf43efed3f7ebd55e1389275e9701598e015e47a759089ed8003933e17c56fbe643cbcf26df69399eca1472c3be9ba06585e3f2ffdaddc
+  metadata.gz: 6313bfced4a79586e71d32ee58c4e216a6a7f96b1e0910fb066f877bc3c0465fb0408bcf1d5690f630472f92584f27209ed87a1c686bae20dae1116b2fd654cc
+  data.tar.gz: c950b0d74657b7b9965b00a7cd6274bbe62ce5fb827e20a6d076980a4b168f19a215fc3f3900a817422cc036e57698f7ef5ae77fbcdc76a7f41793421889dd66

data/CHANGELOG.md

@@ -6,6 +6,73 @@ 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
+
+- **Per-key sentence fragments.** Spanish cannot say "acepto %{documents}" for
+  every document — the article agrees with the noun ("los Términos", "la
+  Política"). The composer now looks up
+  `clickwrap.sentence.fragments.<kind>.<key>` before falling back to the
+  per-kind template, and the gem ships Spanish defaults for its standard keys.
+  An application adds its own in its locale files; no DSL change.
+- **One opening capital.** Fragment templates are written lowercase for the
+  middle of a sentence; the composer capitalizes exactly one letter — the
+  first — once, at build time, so the signed manifest and the rendered HTML
+  can never disagree. The Spanish signup now reads
+  "Acepto los Términos y Condiciones y doy por recibida la Política de
+  Privacidad." instead of "Acepto Términos y Condiciones y He recibido
+  Política de Privacidad."
+- **One voice, composed or itemized.** The Spanish composed acknowledgment now
+  says "doy por recibida" — the same words as the itemized default statement —
+  instead of the flatter "he recibido". The same act reads the same way in
+  either rendering. (Still never "he leído": the evidence records an
+  affirmative act on an offered notice, not that anyone read it. A host that
+  wants the first-person read-declaration owns that wording via its locale
+  files — see the next fix.)
+- **Host locale overrides actually win now.** The engine appended its locale
+  files to `app.config.i18n.load_path` on top of Rails's automatic engine
+  locale loading. Railties paths are unshifted ahead of that list, so the
+  appended copy landed AFTER the host's own locale files — and every host
+  override of a gem key silently lost to the gem's default. The manual append
+  is gone; Rails::Engine's own `:add_locales` ordering (gem first, host last)
+  is the contract, and a test now pins it.
+- **Checkbox optical alignment.** The box was mathematically centred on the
+  first line and still read as floating high: Latin text carries its mass
+  between cap-height and baseline, below the line box's midpoint. The offset
+  gains an optical eighth of an em, calibrated against rendered screenshots.
+
+## [0.1.0] - 2026-08-19
+
 ### Changed — the signup clickwrap is one line
 
 - **`form.clickwrap` renders ONE checkbox carrying ONE sentence** whenever every

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/app/assets/stylesheets/clickwrap.css

@@ -88,14 +88,18 @@
 .clickwrap-statement__checkbox,
 .clickwrap-statement__radio {
   /* Sized in em so the box matches the sentence it belongs to instead of
-     towering over small text, and optically centered against the FIRST line
-     of the label: (line-height minus box) halved. Flex `baseline` cannot do
-     this — a checkbox aligns its bottom edge to the baseline and ends up
-     floating high. The rem fallback covers engines without the lh unit. */
+     towering over small text, and aligned against the FIRST line of the
+     label: (line-height minus box) halved, plus an optical eighth of an em.
+     The mathematical centre is not the visual one — Latin text carries its
+     mass between cap-height and baseline, below the line box's midpoint, so
+     a box centred by arithmetic reads as floating high (calibrated against
+     rendered screenshots at 400%). Flex `baseline` is still worse: a
+     checkbox aligns its bottom edge to the baseline and floats higher. The
+     em fallback covers engines without the lh unit. */
   width: 1em;
   height: 1em;
-  margin: 0.2em 0 0;
-  margin-top: calc((1lh - 1em) / 2);
+  margin: 0.325em 0 0;
+  margin-top: calc((1lh - 1em) / 2 + 0.125em);
   flex: 0 0 auto;
   accent-color: var(--clickwrap-focus);
 }

data/config/locales/es.yml

@@ -22,13 +22,29 @@ es:
       acknowledgment:
         privacy_notice: "Doy por recibida la Política de Privacidad."
 
-    # La frase de una sola línea. En español el artículo concuerda con el
-    # documento ("los Términos", "la Política"), y solo la aplicación sabe qué
-    # documento nombra, así que el artículo vive en la etiqueta del enlace y no
-    # en estas plantillas — por eso `documents_joiner` es " y " y no " y el ".
+    # La frase de una sola línea. Las plantillas se escriben en minúscula y
+    # PARA EL MEDIO de la frase ("… y he recibido …"): la mayúscula inicial la
+    # pone el compositor, una sola vez, al primer fragmento.
+    #
+    # En español el artículo concuerda con el documento ("los Términos", "la
+    # Política"), así que cada clave estándar lleva su propia plantilla bajo
+    # `fragments`, con el artículo correcto. Una aplicación con documentos
+    # propios añade aquí los suyos (p. ej.
+    # `fragments.agreement.contrato_marco: "acepto el %{documents}"`); sin
+    # plantilla propia se usa la genérica, que es neutra y correcta aunque
+    # menos idiomática.
     sentence:
-      agreement: "Acepto %{documents}"
-      acknowledgment: "He recibido %{documents}"
+      fragments:
+        agreement:
+          terms: "acepto los %{documents}"
+        acknowledgment:
+          # La misma voz que la declaración detallada ("Doy por recibida la
+          # Política de Privacidad."): el mismo acto debe leerse igual
+          # compuesto que detallado. Nunca "he leído": la evidencia registra
+          # un acto afirmativo sobre un aviso ofrecido, no que alguien leyera.
+          privacy_notice: "doy por recibida la %{documents}"
+      agreement: "acepto %{documents}"
+      acknowledgment: "he recibido %{documents}"
       documents_joiner: " y "
       joiner: " y "
       terminator: "."

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/engine.rb

@@ -124,12 +124,15 @@ module Clickwrap
       end
     end
 
-    # Ship the gem's locale files. Host locale files with the same keys override
-    # these automatically (I18n's load order puts the app last), which is how a
-    # host rewords a statement without forking a view.
-    initializer "clickwrap.locales" do |app|
-      app.config.i18n.load_path += Dir[root.join("config", "locales", "**", "*.{rb,yml}").to_s]
-    end
+    # The gem's locale files ship through Rails::Engine's own :add_locales
+    # (every engine's `config/locales` is picked up automatically) — and NOT
+    # through a manual `app.config.i18n.load_path +=` on top of it. The manual
+    # append is not merely redundant: railties paths are UNSHIFTED before
+    # everything in `load_path`, so an appended copy of these files lands
+    # AFTER the host's own locales and quietly overrides them. Load order is
+    # the whole contract here — gem first, host last — because a host rewords
+    # a statement by shipping the same key in its own locale file, and the
+    # host's counsel must always get the last word.
 
     initializer "clickwrap.assets" do |app|
       app.config.assets.paths << root.join("app/assets/stylesheets") if app.config.respond_to?(:assets)

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/presenter.rb

@@ -383,6 +383,12 @@ module Clickwrap
 
     def build_combined(composable, fragments, connectives)
       control = composable.first
+      # Fragment templates are written for the middle of a sentence ("he
+      # recibido la …"), because every fragment but the first sits there. The
+      # sentence's opening capital is applied here, once, so the signed
+      # manifest text and the rendered HTML can never disagree about it.
+      fragments = [fragments.first.with(prefix: fragments.first.prefix.sub(/\A\p{Ll}/, &:upcase))] +
+                  fragments[1..]
 
       Combined.new(
         sentence: fragments.map(&:to_text).join(connectives[:joiner]) + connectives[:terminator],
@@ -433,7 +439,14 @@ module Clickwrap
     end
 
     def sentence_fragment(statement, connectives)
-      template = sentence_text(statement.kind)
+      # A language that needs to agree with its nouns — an article, a gendered
+      # participle — cannot say "acepto %{documents}" for every document. A
+      # per-key template carries those words for THIS document
+      # (clickwrap.sentence.fragments.agreement.terms: "acepto los
+      # %{documents}"); the per-kind template stays the fallback for keys
+      # nobody translated specifically.
+      template = sentence_text("fragments.#{statement.kind}.#{statement.key}") ||
+                 sentence_text(statement.kind)
       return nil if template.nil?
 
       prefix, suffix = template.split(DOCUMENTS_PLACEHOLDER, 2)

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.0"
+  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.0
+  version: 0.2.0
 platform: ruby
 authors:
 - rameerez