textus 0.29.0 → 0.35.1

data/lib/textus/dispatcher.rb

@@ -11,12 +11,13 @@ module Textus
       accept: Textus::Write::Accept,
       reject: Textus::Write::Reject,
       publish: Textus::Write::Publish,
-      refresh: Textus::Write::RefreshWorker,
-      refresh_all: Textus::Write::RefreshAll,
+      fetch: Textus::Write::FetchWorker,
+      fetch_all: Textus::Write::FetchAll,
+      retention_sweep: Textus::Write::RetentionSweep,
 
       # Read
       get: Textus::Read::Get,
-      get_or_refresh: Textus::Read::GetOrRefresh,
+      get_or_fetch: Textus::Read::GetOrFetch,
       list: Textus::Read::List,
       where: Textus::Read::Where,
       uid: Textus::Read::Uid,
@@ -33,6 +34,7 @@ module Textus
       validate_all: Textus::Read::ValidateAll,
       doctor: Textus::Read::Doctor,
       boot: Textus::Read::Boot,
+      retainable: Textus::Read::Retainable,
 
       # Maintenance
       migrate: Textus::Maintenance::Migrate,
@@ -45,5 +47,11 @@ module Textus
     def self.fetch(verb)
       VERBS.fetch(verb.to_sym) { raise UsageError.new("unknown verb: #{verb.inspect}") }
     end
+
+    # Single home for the uniform use-case invocation protocol (ADR 0023):
+    # look up the verb, construct on (container:, call:), and invoke #call.
+    def self.invoke(verb, container:, call:, args: [], kwargs: {})
+      fetch(verb).new(container: container, call: call).call(*args, **kwargs)
+    end
   end
 end

data/lib/textus/doctor/check/{refresh_locks.rb → fetch_locks.rb}

@@ -1,13 +1,13 @@
 module Textus
   module Doctor
     class Check
-      # Lists per-key refresh lock files under <root>/.locks/ whose
+      # Lists per-key fetch lock files under <root>/.locks/ whose
       # recorded PID is no longer running. These are forensic artifacts only:
-      # Refresh::Lock uses flock(2), which the kernel releases on process
+      # Fetch::Lock uses flock(2), which the kernel releases on process
       # death, so stale files do not block subsequent acquires. The check
       # exists to let users clean up clutter and notice unexpected accumulation
-      # (e.g. a refresh path that crashes repeatedly).
-      class RefreshLocks < Check
+      # (e.g. a fetch path that crashes repeatedly).
+      class FetchLocks < Check
         def call
           dir = File.join(root, ".locks")
           return [] unless File.directory?(dir)
@@ -23,11 +23,11 @@ module Textus
           return nil if pid_alive?(pid)
 
           {
-            "code" => "refresh_lock.stale",
+            "code" => "fetch_lock.stale",
             "level" => "info",
             "subject" => path,
-            "message" => "refresh lock file at #{path} records dead PID #{pid} " \
-                         "(does not block refresh; flock is kernel-released on exit)",
+            "message" => "fetch lock file at #{path} records dead PID #{pid} " \
+                         "(does not block fetch; flock is kernel-released on exit)",
             "fix" => "safe to delete: rm #{path}",
           }
         rescue Errno::ENOENT

data/lib/textus/doctor/check/proposal_targets.rb

@@ -0,0 +1,45 @@
+module Textus
+  module Doctor
+    class Check
+      # Flags pending proposals whose `proposal.target_key` cannot ever be
+      # accepted: it points at a non-canon zone or resolves to no declared
+      # entry (ADR 0035). Reads the live queue zone; silent when there is no
+      # queue zone. Warnings, not errors — they are stale junk, not store
+      # corruption (the accept gate already refuses them).
+      class ProposalTargets < Check
+        def call
+          queue = manifest.policy.queue_zone
+          return [] unless queue
+
+          dispatch(:list, zone: queue).filter_map { |row| issue_for(row["key"]) }
+        end
+
+        private
+
+        def issue_for(key)
+          target = dispatch(:get, key).meta&.dig("proposal", "target_key")
+          return nil if target.nil? # not a proposal entry — skip
+
+          zone = manifest.resolver.resolve(target).entry.zone
+          return nil if manifest.policy.declared_kind(zone.to_s) == :canon
+
+          {
+            "code" => "proposal.target_not_canon",
+            "level" => "warning",
+            "subject" => key,
+            "message" => "proposal '#{key}' targets '#{target}' in zone '#{zone}' (not canon); it can never be accepted",
+            "fix" => "delete the proposal, or repoint target_key at a canon zone",
+          }
+        rescue Textus::UnknownKey
+          {
+            "code" => "proposal.target_unresolved",
+            "level" => "warning",
+            "subject" => key,
+            "message" => "proposal '#{key}' targets '#{target}', which resolves to no declared entry",
+            "fix" => "delete the proposal, or fix target_key",
+          }
+        end
+      end
+    end
+  end
+end

data/lib/textus/doctor/check/rule_ambiguity.rb

@@ -2,11 +2,11 @@ module Textus
   module Doctor
     class Check
       # Flags entries whose key is matched by two or more rule blocks of the
-      # SAME specificity in the same slot (refresh / handler_allowlist /
-      # promote). Ties are non-deterministic in the parser's pick step, so
+      # SAME specificity in the same slot (fetch / handler_allowlist /
+      # guard). Ties are non-deterministic in the parser's pick step, so
       # they're a configuration smell — surface them.
       class RuleAmbiguity < Check
-        SLOTS = %i[refresh handler_allowlist promote].freeze
+        SLOTS = %i[fetch handler_allowlist guard].freeze
 
         def call
           out = []

data/lib/textus/doctor/check.rb

@@ -28,11 +28,14 @@ module Textus
       def manifest = @container.manifest
       def rpc      = @container.rpc
 
-      # Dispatch a verb through the static Dispatcher table.
-      def dispatch(verb, *, **)
-        klass = Textus::Dispatcher.fetch(verb)
-        call_value = Textus::Call.build(role: Textus::Role::DEFAULT)
-        klass.new(container: @container, call: call_value).call(*, **)
+      # Dispatch a verb through the single use-case invocation seam (ADR 0026).
+      def dispatch(verb, *args, **kwargs)
+        Textus::Dispatcher.invoke(
+          verb,
+          container: @container,
+          call: Textus::Call.build(role: Textus::Role::DEFAULT),
+          args: args, kwargs: kwargs
+        )
       end
     end
   end

data/lib/textus/doctor.rb

@@ -23,7 +23,8 @@ module Textus
       Check::SchemaViolations,
       Check::RuleAmbiguity,
       Check::HandlerAllowlist,
-      Check::RefreshLocks,
+      Check::FetchLocks,
+      Check::ProposalTargets,
     ].freeze
 
     ALL_CHECKS = CHECKS.map(&:name_key).freeze

data/lib/textus/domain/action.rb

@@ -1,9 +1,9 @@
 module Textus
   module Domain
     module Action
-      Return       = Data.define
-      RefreshSync  = Data.define
-      RefreshTimed = Data.define(:budget_ms)
+      Return = Data.define
+      FetchSync  = Data.define
+      FetchTimed = Data.define(:budget_ms)
     end
   end
 end

data/lib/textus/domain/duration.rb

@@ -0,0 +1,22 @@
+module Textus
+  module Domain
+    # Parses a duration value into whole seconds. Accepts a bare integer (or
+    # integer-string) of seconds, or `<n><unit>` with unit s/m/h/d. Returns
+    # nil for nil or any unparseable value.
+    module Duration
+      UNIT_SECONDS = { "s" => 1, "m" => 60, "h" => 3600, "d" => 86_400 }.freeze
+
+      def self.seconds(value)
+        return nil if value.nil?
+
+        str = value.to_s.strip
+        return str.to_i if str.match?(/\A\d+\z/)
+
+        m = str.match(/\A(\d+)\s*([smhd])\z/)
+        return nil unless m
+
+        m[1].to_i * UNIT_SECONDS.fetch(m[2])
+      end
+    end
+  end
+end

data/lib/textus/domain/freshness/evaluator.rb

@@ -9,15 +9,15 @@ module Textus
         def call(policy, envelope, now:)
           return Verdict.fresh if policy.ttl_seconds.nil?
 
-          last_str = envelope&.meta&.dig("last_refreshed_at")
-          return Verdict.stale("never refreshed") if last_str.nil?
+          last_str = envelope&.meta&.dig("last_fetched_at")
+          return Verdict.stale("never fetched") if last_str.nil?
 
           last = begin
             Time.parse(last_str.to_s)
           rescue ArgumentError, TypeError
             nil
           end
-          return Verdict.stale("unparseable last_refreshed_at: #{last_str.inspect}") if last.nil?
+          return Verdict.stale("unparseable last_fetched_at: #{last_str.inspect}") if last.nil?
 
           age = now - last
           return Verdict.fresh if age <= policy.ttl_seconds

data/lib/textus/domain/freshness/policy.rb

@@ -7,8 +7,8 @@ module Textus
 
           case on_stale
           when :warn       then Action::Return.new
-          when :sync       then Action::RefreshSync.new
-          when :timed_sync then Action::RefreshTimed.new(budget_ms: sync_budget_ms)
+          when :sync       then Action::FetchSync.new
+          when :timed_sync then Action::FetchTimed.new(budget_ms: sync_budget_ms)
           else                  Action::Return.new
           end
         end

data/lib/textus/domain/freshness.rb

@@ -8,19 +8,19 @@ module Textus
     #
     # Note on wire format: `#to_h_for_wire` is intentionally narrower than the
     # full field set. It emits the legacy keys ("stale", "stale_reason",
-    # "refreshing", and "refresh_error" when present) so the CLI JSON wire
+    # "fetching", and "fetch_error" when present) so the CLI JSON wire
     # stays byte-identical with textus/3. The gem-side fields `checked_at`
     # and `ttl_remaining_ms` are NOT emitted on the wire in this phase.
     Freshness = Data.define(
-      :stale, :refreshing, :reason, :refresh_error, :checked_at, :ttl_remaining_ms
+      :stale, :fetching, :reason, :fetch_error, :checked_at, :ttl_remaining_ms
     ) do
-      def self.build(stale:, refreshing: false, reason: nil, refresh_error: nil,
+      def self.build(stale:, fetching: false, reason: nil, fetch_error: nil,
                      checked_at: nil, ttl_remaining_ms: nil)
         new(
           stale: stale,
-          refreshing: refreshing,
+          fetching: fetching,
           reason: reason,
-          refresh_error: refresh_error,
+          fetch_error: fetch_error,
           checked_at: checked_at,
           ttl_remaining_ms: ttl_remaining_ms,
         )
@@ -30,9 +30,9 @@ module Textus
         h = {
           "stale" => stale,
           "stale_reason" => reason,
-          "refreshing" => refreshing,
+          "fetching" => fetching,
         }
-        h["refresh_error"] = refresh_error unless refresh_error.nil?
+        h["fetch_error"] = fetch_error unless fetch_error.nil?
         h
       end
     end

data/lib/textus/domain/outcome.rb

@@ -1,8 +1,8 @@
 module Textus
   module Domain
     module Outcome
-      Skipped   = Data.define
-      Refreshed = Data.define(:envelope)
+      Skipped = Data.define
+      Fetched = Data.define(:envelope)
       Detached  = Data.define
       Failed    = Data.define(:error)
     end

data/lib/textus/domain/permission.rb

@@ -1,15 +1,7 @@
 module Textus
   module Domain
-    Permission = Data.define(:zone, :write_policy, :read_policy) do
-      def allows_write?(role)
-        write_policy.include?(role.to_s)
-      end
-
-      def allows_read?(role)
-        return true if [:all, ["all"]].include?(read_policy)
-
-        read_policy.include?(role.to_s)
-      end
+    Permission = Data.define(:zone, :writers) do
+      def allows_write?(role) = writers.include?(role.to_s)
     end
   end
 end

data/lib/textus/domain/policy/base_guards.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Textus
+  module Domain
+    module Policy
+      # The CLOSED floor (ADR 0031 §4): predicate names every transition
+      # evaluates regardless of rules:. rules[].guard only ADDS to these.
+      module BaseGuards
+        # The minimal floor — only what the verb is meaningless without.
+        # schema_valid / etag_match / fresh_within are NOT here: they are
+        # composable-only, added per-key via rules[].guard (ADR 0031).
+        BASE = {
+          put: %w[zone_writable_by],
+          delete: %w[zone_writable_by],
+          mv: %w[zone_writable_by],
+          accept: %w[author_held target_is_canon],
+          reject: %w[author_held],
+          fetch: %w[zone_writable_by],
+        }.freeze
+
+        def self.for(transition) = BASE.fetch(transition, [])
+      end
+    end
+  end
+end

data/lib/textus/domain/policy/evaluation.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Textus
+  module Domain
+    module Policy
+      # Immutable context handed to every predicate. `snapshot` is the
+      # manifest (pure, no I/O); `envelope` is the entry under evaluation
+      # (nil when no bytes exist yet, e.g. a fresh put). `origin`/`target`
+      # are dotted keys; `transition` is the verb symbol.
+      Evaluation = Data.define(
+        :actor, :transition, :origin, :target, :envelope, :snapshot
+      ) do
+        def manifest = snapshot
+        def role     = actor
+      end
+    end
+  end
+end

data/lib/textus/domain/policy/{refresh.rb → fetch.rb}

@@ -1,7 +1,7 @@
 module Textus
   module Domain
     module Policy
-      class Refresh
+      class Fetch
         ALLOWED_ON_STALE = %i[warn sync timed_sync].freeze
 
         attr_reader :ttl, :on_stale, :sync_budget_ms, :fetch_timeout_seconds
@@ -21,21 +21,7 @@ module Textus
         end
 
         def ttl_seconds
-          return nil if @ttl.nil?
-
-          str = @ttl.to_s.strip
-          return str.to_i if str.match?(/\A\d+\z/)
-
-          m = str.match(/\A(\d+)\s*([smhd])\z/)
-          return nil unless m
-
-          n = m[1].to_i
-          case m[2]
-          when "s" then n
-          when "m" then n * 60
-          when "h" then n * 3600
-          when "d" then n * 86_400
-          end
+          Textus::Domain::Duration.seconds(@ttl)
         end
 
         def to_freshness_policy

data/lib/textus/domain/policy/guard.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Textus
+  module Domain
+    module Policy
+      # An ordered list of pure predicates over one Evaluation (ADR 0031).
+      # check! short-circuits on the first failing predicate that defines a
+      # bespoke #error (only zone_writable_by → WriteForbidden, the product's
+      # legible topology refusal); every other failure accumulates into
+      # GuardFailed naming the unmet predicate(s).
+      class Guard
+        attr_reader :predicates
+
+        def initialize(predicates)
+          @predicates = predicates
+        end
+
+        def check!(eval)
+          accumulated = []
+          @predicates.each do |pred|
+            next if pred.call(eval)
+            raise pred.error(eval) if pred.respond_to?(:error)
+
+            accumulated << [pred.name, pred.reason]
+          end
+          raise Textus::GuardFailed.new(accumulated) unless accumulated.empty?
+        end
+
+        def explain(eval)
+          @predicates.map { |p| [p.name, p.call(eval), p.reason] }
+        end
+      end
+    end
+  end
+end

data/lib/textus/domain/policy/guard_factory.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Textus
+  module Domain
+    module Policy
+      # Builds the effective Guard for (transition, key): base floor ++
+      # the predicates declared under rules[].guard[transition]. The single
+      # place the closed floor and the open ceiling are composed.
+      class GuardFactory
+        def initialize(manifest:, schemas:, extra: {})
+          @manifest = manifest
+          @schemas  = schemas
+          @extra    = extra # transient per-call params, e.g. { if_etag: "..." }
+        end
+
+        def for(transition, key)
+          specs = BaseGuards.for(transition) + composed(transition, key)
+          predicates = specs.map { |spec| build(spec) }.uniq(&:name)
+          Guard.new(predicates)
+        end
+
+        private
+
+        def composed(transition, key)
+          guard_map = @manifest.rules.for(key).guard
+          return [] if guard_map.nil?
+
+          Array(guard_map[transition.to_s])
+        end
+
+        def build(spec)
+          # etag_match takes a per-call param rather than a manifest one.
+          return Predicates::EtagMatch.new(if_etag: @extra[:if_etag]) if spec == "etag_match"
+
+          Predicates::Registry.build(spec, schemas: @schemas)
+        end
+      end
+    end
+  end
+end

data/lib/textus/domain/policy/predicates/author_held.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Textus
+  module Domain
+    module Policy
+      module Predicates
+        # Predicate: the acting role must hold the 'author' capability in the
+        # active manifest (ADR 0030 capability roles). Folds in the old
+        # Write::AuthorityGate so accept/reject and rules[].guard share one
+        # implementation. No bespoke #error — failures accumulate into
+        # GuardFailed (ADR 0031).
+        class AuthorHeld
+          attr_reader :reason
+
+          def name = "author_held"
+
+          def call(eval)
+            holders = eval.manifest.policy.roles_with_capability("author")
+            return true if holders.include?(eval.actor.to_s)
+
+            @reason =
+              if holders.empty?
+                "no role holds the 'author' capability; #{eval.transition} is disabled"
+              else
+                "role '#{eval.actor}' lacks the 'author' capability (held by: #{holders.join(", ")})"
+              end
+            false
+          end
+        end
+      end
+    end
+  end
+end

data/lib/textus/domain/policy/predicates/etag_match.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Textus
+  module Domain
+    module Policy
+      module Predicates
+        # Advisory pre-flight etag check for policy explain. The
+        # authoritative compare-and-write stays in Envelope::IO::Writer
+        # (atomic write-then-audit, ADR 0017). Passes when no if_etag is
+        # supplied (params[:if_etag] nil) — guard does not require it.
+        class EtagMatch
+          attr_reader :reason
+
+          def initialize(if_etag: nil)
+            @if_etag = if_etag
+          end
+
+          def name = "etag_match"
+
+          def call(eval)
+            return true if @if_etag.nil?
+            return true if eval.envelope.nil? # creating; Writer handles race
+            return true if eval.envelope.etag == @if_etag
+
+            @reason = "etag mismatch: wanted #{@if_etag}, have #{eval.envelope.etag}"
+            false
+          end
+        end
+      end
+    end
+  end
+end

data/lib/textus/domain/policy/predicates/fresh_within.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Textus
+  module Domain
+    module Policy
+      module Predicates
+        # Parameterized predicate: the entry must have been written within
+        # `duration` of now. Duration strings ("1h", "30m", "7d") parse via
+        # Domain::Duration.seconds. Passes when no envelope exists yet.
+        class FreshWithin
+          attr_reader :reason
+
+          def initialize(duration:, now: nil)
+            @seconds = Textus::Domain::Duration.seconds(duration)
+            @now = now
+          end
+
+          def name = "fresh_within"
+
+          def call(eval)
+            return true if eval.envelope.nil? || @seconds.nil?
+
+            written = written_at(eval.envelope)
+            return true if written.nil?
+
+            now = @now || Textus::Ports::Clock.now
+            return true if now - written <= @seconds
+
+            @reason = "entry older than #{@seconds}s (written #{written.iso8601})"
+            false
+          end
+
+          private
+
+          # Domain-pure: reads the stored write timestamp from the envelope's
+          # freshness (checked_at) or meta (last_fetched_at/generated_at) and
+          # parses the stored ISO-8601 string. Parsing a stored string is not
+          # I/O (allowed in domain, ADR 0024).
+          def written_at(envelope)
+            raw = envelope.freshness&.checked_at ||
+                  envelope.meta&.dig("last_fetched_at") ||
+                  envelope.meta&.dig("generated_at")
+            return raw if raw.is_a?(Time)
+            return nil if raw.nil?
+
+            begin
+              Time.parse(raw.to_s)
+            rescue StandardError
+              nil
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/textus/domain/policy/predicates/registry.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Textus
+  module Domain
+    module Policy
+      module Predicates
+        # The single source of truth for the predicate vocabulary
+        # (ADR 0031 §3). Replaces both Promote::KNOWN and Promotion::REGISTRY.
+        # Each entry is name => ->(params:, schemas:) { predicate }.
+        module Registry
+          ENTRIES = {
+            "zone_writable_by" => ->(**) { ZoneWritableBy.new },
+            "author_held" => ->(**) { AuthorHeld.new },
+            "target_is_canon" => ->(**) { TargetIsCanon.new },
+            "schema_valid" => ->(schemas:, **) { SchemaValid.new(schemas: schemas) },
+            "etag_match" => ->(params:, **) { EtagMatch.new(if_etag: params) },
+            "fresh_within" => ->(params:, **) { FreshWithin.new(duration: params) },
+          }.freeze
+
+          # Accepts either "name" or { "name" => params }.
+          def self.build(spec, schemas:)
+            name, params =
+              if spec.is_a?(Hash)
+                spec.first
+              else
+                [spec.to_s, nil]
+              end
+            ctor = ENTRIES[name.to_s] or raise Textus::UsageError.new(
+              "unknown guard predicate: '#{name}' (known: #{ENTRIES.keys.join(", ")})",
+            )
+            ctor.call(params: params, schemas: schemas)
+          end
+
+          def self.known = ENTRIES.keys
+        end
+      end
+    end
+  end
+end