textus 0.30.0 → 0.35.1

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/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

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

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

@@ -1,48 +1,59 @@
+# frozen_string_literal: true
+
 module Textus
   module Domain
     module Policy
       module Predicates
+        # Predicate: the entry's effective frontmatter satisfies the schema
+        # bound to the target key. For accept, the frontmatter lives under
+        # envelope.meta["frontmatter"]; for a direct put it is envelope.meta.
         class SchemaValid
           attr_reader :reason
 
-          def name
-            "schema_valid"
+          def initialize(schemas:)
+            @schemas = schemas
           end
 
-          def call(entry:, schemas:, manifest:) # rubocop:disable Metrics/PerceivedComplexity, Metrics/CyclomaticComplexity
-            return true if entry.nil? || manifest.nil? || schemas.nil?
+          def name = "schema_valid"
+
+          def call(eval)
+            manifest = eval.manifest
+            return true if eval.envelope.nil? || manifest.nil? || @schemas.nil?
 
-            target_key = entry.meta&.dig("proposal", "target_key")
+            target_key = eval.target
             return true unless target_key
 
             mentry = manifest.resolver.resolve(target_key).entry
             schema_ref = mentry&.schema
             return true unless schema_ref
 
-            schema = schemas.fetch_or_nil(schema_ref)
+            schema = @schemas.fetch_or_nil(schema_ref)
             return true unless schema
 
-            frontmatter = entry.meta&.dig("frontmatter") || {}
+            frontmatter =
+              eval.envelope.meta&.dig("frontmatter") || eval.envelope.meta || {}
             begin
               schema.validate!(frontmatter)
+              true
             rescue Textus::SchemaViolation => e
-              @reason = e.message.dup
-              d = e.details
-              if d.is_a?(Hash)
-                if d["missing"]
-                  @reason = "missing required fields: #{Array(d["missing"]).join(", ")}"
-                elsif d["field"]
-                  @reason = "field '#{d["field"]}': #{d["reason"]}"
-                end
-              end
-              return false
+              @reason = humanize(e)
+              false
             end
-
-            true
           rescue StandardError => e
             @reason = "schema validation error: #{e.message}"
             false
           end
+
+          private
+
+          def humanize(err)
+            d = err.details
+            return err.message.dup unless d.is_a?(Hash)
+            return "missing required fields: #{Array(d["missing"]).join(", ")}" if d["missing"]
+            return "field '#{d["field"]}': #{d["reason"]}" if d["field"]
+
+            err.message.dup
+          end
         end
       end
     end

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

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Textus
+  module Domain
+    module Policy
+      module Predicates
+        # Predicate: a proposal may only target a `canon` zone (ADR 0035). Runs
+        # on the `accept` floor, where Evaluation#target is the proposal's
+        # resolved target_key. Refuses promotion into workspace/derived/
+        # quarantine/queue — the queue→canon path is the only coherent one.
+        # No bespoke #error; failures accumulate into GuardFailed (ADR 0031).
+        class TargetIsCanon
+          attr_reader :reason
+
+          def name = "target_is_canon"
+
+          def call(eval)
+            zone = eval.manifest.resolver.resolve(eval.target).entry.zone
+            kind = eval.manifest.policy.declared_kind(zone.to_s)
+            return true if kind == :canon
+
+            @reason = "proposal target '#{eval.target}' is in zone '#{zone}' " \
+                      "(kind: #{kind || "none"}); proposals may only target a canon zone"
+            false
+          rescue Textus::UnknownKey
+            @reason = "proposal target '#{eval.target}' resolves to no declared entry"
+            false
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Textus
+  module Domain
+    module Policy
+      module Predicates
+        # Predicate #0 of every write guard. Wraps the post-0.31.0 capability
+        # topology gate (role.can ⊇ verb_for(zone.kind)). On failure, #error
+        # raises the capability-shaped WriteForbidden so the topology refusal
+        # — textus's signature product feature — is unchanged.
+        class ZoneWritableBy
+          attr_reader :reason
+
+          def name = "zone_writable_by"
+
+          def call(eval)
+            manifest = eval.manifest
+            @mentry = manifest.resolver.resolve(eval.target).entry
+            return true if manifest.policy.permission_for(@mentry.zone.to_s).allows_write?(eval.actor)
+
+            @verb    = manifest.policy.verb_for_zone(@mentry.zone) # capability the kind requires
+            @holders = manifest.policy.roles_with_capability(@verb)
+            @reason  = "zone '#{@mentry.zone}' needs capability '#{@verb}'; '#{eval.actor}' lacks it"
+            false
+          end
+
+          # Matches the capability-shaped WriteForbidden landed by ADR 0030
+          # Task 3:
+          #   WriteForbidden.new(key, zone, verb:, holders:)
+          #   → "writing '<k>' (zone '<z>') needs capability '<verb>'",
+          #     hint: "held by: <holders>; pass --as=<role>".
+          def error(_eval)
+            Textus::WriteForbidden.new(@mentry.key, @mentry.zone, verb: @verb, holders: @holders)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/textus/domain/staleness/intake_check.rb

@@ -15,7 +15,7 @@ module Textus
         def rows_for(mentry)
           return [] unless mentry.is_a?(Textus::Manifest::Entry::Intake)
 
-          ttl = @manifest.rules.for(mentry.key).refresh&.ttl_seconds
+          ttl = @manifest.rules.for(mentry.key).fetch&.ttl_seconds
           return [] unless ttl
 
           path = Textus::Key::Path.resolve(@manifest.data, mentry)
@@ -26,17 +26,17 @@ module Textus
         private
 
         def ttl_reason(mentry, path, ttl)
-          return "never refreshed" unless @file_stat.exists?(path)
+          return "never fetched" unless @file_stat.exists?(path)
 
-          last_str = last_refreshed_of(mentry, path)
-          return "never refreshed (no last_refreshed_at)" if last_str.nil?
+          last_str = last_fetched_of(mentry, path)
+          return "never fetched (no last_fetched_at)" if last_str.nil?
 
           last = parse_time(last_str)
           "ttl exceeded (#{ttl}s)" if last.nil? || (@clock.now - last) > ttl
         end
 
-        def last_refreshed_of(mentry, path)
-          Entry.for_format(mentry.format).parse(@file_stat.read(path), path: path)["_meta"]["last_refreshed_at"]
+        def last_fetched_of(mentry, path)
+          Entry.for_format(mentry.format).parse(@file_stat.read(path), path: path)["_meta"]["last_fetched_at"]
         end
 
         def parse_time(str)

data/lib/textus/envelope.rb

@@ -55,10 +55,10 @@ module Textus
       freshness.stale == true
     end
 
-    def refreshing?
+    def fetching?
       return false if freshness.nil?
 
-      freshness.refreshing == true
+      freshness.fetching == true
     end
   end
 end