textus 0.30.0 → 0.38.0

data/lib/textus/cli.rb

@@ -90,8 +90,8 @@ module Textus
           textus get KEY
           textus put KEY --stdin [--fetch=NAME] --as=ROLE
           textus freshness [--prefix=KEY] [--zone=Z]
-          textus refresh KEY
-          textus refresh stale [--prefix=KEY] [--zone=Z]
+          textus fetch KEY
+          textus fetch stale [--prefix=KEY] [--zone=Z]
           textus audit [--key=K] [--zone=Z] [--role=R] [--verb=V] [--since=X] [--correlation-id=ID] [--limit=N]
           textus blame KEY [--limit=N]
           textus doctor

data/lib/textus/container.rb

@@ -3,7 +3,7 @@ module Textus
   # ReadCaps/WriteCaps/HookCaps trio from 0.26.x. Built once per Store.
   Container = Data.define(
     :manifest, :file_store, :schemas, :root,
-    :audit_log, :events, :rpc, :authorizer
+    :audit_log, :events, :rpc
   )
 
   class Container
@@ -16,7 +16,6 @@ module Textus
         audit_log: store.audit_log,
         events: store.events,
         rpc: store.rpc,
-        authorizer: Textus::Domain::Authorizer.new(manifest: store.manifest),
       )
     end
   end

data/lib/textus/contract.rb

@@ -0,0 +1,106 @@
+module Textus
+  # Declarative, co-located interface contract for a verb. One source of truth
+  # for the agent-facing summary, the argument schema, which transports expose
+  # the verb, and how the return value is shaped for the wire. CLI/Ruby/MCP and
+  # boot project from this; the MCP catalog is fully derived from it (ADR 0039).
+  module Contract
+    # One argument of a verb. `positional: true` means it is passed to the
+    # use-case as a positional (e.g. `get(key)`); otherwise as a keyword.
+    # `session_default` names a zero-arg method on `Textus::Session` (Symbol)
+    # that supplies the value when the wire arg is absent; `nil` means no default.
+    Arg = Data.define(:name, :type, :required, :positional, :session_default, :description)
+
+    JSON_TYPES = {
+      String => "string", Integer => "integer", Hash => "object",
+      Array => "array", :boolean => "boolean"
+    }.freeze
+
+    def self.json_type(type)
+      JSON_TYPES.fetch(type) { raise ArgumentError.new("no JSON type mapping for #{type.inspect}") }
+    end
+
+    Spec = Data.define(:verb, :summary, :args, :surfaces, :response) do
+      def mcp? = surfaces.include?(:mcp)
+
+      def required_args = args.select(&:required)
+
+      # JSON-Schema object for MCP tools/list inputSchema.
+      # Outer keys (:type, :properties, :required) are symbols; inner property
+      # keys are strings — matches the MCP/JSON wire shape expected by clients.
+      def input_schema
+        props = args.to_h do |a|
+          h = { "type" => Contract.json_type(a.type) }
+          h["description"] = a.description if a.description
+          [a.name.to_s, h]
+        end
+        { type: "object", properties: props, required: required_args.map { |a| a.name.to_s } }
+      end
+    end
+
+    # Mixed onto a use-case class via `extend`. Calls accumulate into ivars,
+    # frozen into a Spec on first read of `.contract`.
+    module DSL
+      def verb(name = nil)
+        if name
+          raise "contract already built; declare verb before reading .contract" if defined?(@__contract) && @__contract
+
+          @__verb = name
+        else
+          @__verb
+        end
+      end
+
+      def summary(text = nil)
+        if text
+          raise "contract already built; declare summary before reading .contract" if defined?(@__contract) && @__contract
+
+          @__summary = text
+        else
+          @__summary
+        end
+      end
+
+      def surfaces(*list)
+        if list.empty?
+          @__surfaces ||= []
+        else
+          raise "contract already built; declare surfaces before reading .contract" if defined?(@__contract) && @__contract
+
+          @__surfaces = list
+        end
+      end
+
+      def arg(name, type, required: false, positional: false, session_default: nil, description: nil)
+        raise "contract already built; declare args before reading .contract" if defined?(@__contract) && @__contract
+
+        (@__args ||= []) << Arg.new(
+          name: name, type: type, required: required,
+          positional: positional, session_default: session_default, description: description
+        )
+      end
+
+      def response(&blk)
+        @__response = blk if blk
+        @__response || ->(v) { v }
+      end
+
+      def contract?
+        !@__verb.nil?
+      end
+
+      # rubocop:disable Naming/MemoizedInstanceVariableName
+      # @__contract uses double-underscore to match the other accumulator ivars
+      # (@__verb, @__args, etc.) and avoid name collision with user-defined `@contract`.
+      def contract
+        @__contract ||= Spec.new(
+          verb: @__verb,
+          summary: @__summary,
+          args: (@__args || []).freeze,
+          surfaces: (@__surfaces || []).freeze,
+          response: response,
+        )
+      end
+      # rubocop:enable Naming/MemoizedInstanceVariableName
+    end
+  end
+end

data/lib/textus/cursor_store.rb

@@ -0,0 +1,24 @@
+require "fileutils"
+
+module Textus
+  # Per-role cursor cache under <root>/.run/state/cursor.<role>. A convenience so
+  # `textus pulse` (no --since) means "since I last looked". Gitignored;
+  # losing it just re-emits recent deltas, never corrupts the store. ADR 0036/0038.
+  class CursorStore
+    def initialize(root:, role:)
+      @path = Textus::Layout.cursor(root, role)
+    end
+
+    def read
+      Integer(File.read(@path).strip)
+    rescue Errno::ENOENT, ArgumentError
+      0
+    end
+
+    def write(seq)
+      FileUtils.mkdir_p(File.dirname(@path))
+      File.write(@path, seq.to_s)
+      seq
+    end
+  end
+end

data/lib/textus/dispatcher.rb

@@ -6,18 +6,19 @@ module Textus
     VERBS = {
       # Write
       put: Textus::Write::Put,
+      propose: Textus::Write::Propose,
       delete: Textus::Write::Delete,
       mv: Textus::Write::Mv,
       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,
@@ -30,11 +31,12 @@ module Textus
       pulse: Textus::Read::Pulse,
       policy_explain: Textus::Read::PolicyExplain,
       published: Textus::Read::Published,
-      schema_envelope: Textus::Read::SchemaEnvelope,
+      schema: Textus::Read::SchemaEnvelope,
       validate_all: Textus::Read::ValidateAll,
       doctor: Textus::Read::Doctor,
       boot: Textus::Read::Boot,
       retainable: Textus::Read::Retainable,
+      rules: Textus::Read::Rules,
 
       # Maintenance
       migrate: Textus::Maintenance::Migrate,

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

@@ -3,7 +3,7 @@ module Textus
     class Check
       class AuditLog < Check
         def call
-          path = File.join(root, "audit.log")
+          path = Textus::Layout.audit_log(root)
           Textus::Ports::AuditLog.new(root).verify_integrity.map do |v|
             {
               "code" => "audit.parse_error",

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

@@ -1,15 +1,15 @@
 module Textus
   module Doctor
     class Check
-      # Lists per-key refresh lock files under <root>/.locks/ whose
+      # Lists per-key fetch lock files under <root>/.run/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")
+          dir = Textus::Layout.locks(root)
           return [] unless File.directory?(dir)
 
           Dir.glob(File.join(dir, "*.lock")).filter_map { |path| inspect_lock(path) }
@@ -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.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,15 @@
+# frozen_string_literal: true
+
+module Textus
+  module Domain
+    module Policy
+      # Immutable context handed to every predicate. `manifest` 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, :manifest
+      )
+    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