textus 0.30.0 → 0.38.0

data/lib/textus/schema/tools.rb

@@ -49,7 +49,7 @@ module Textus
           end
         raise UsageError.new("schema migrate needs --rename=OLD:NEW or schema.evolution.migrate_from") if renames.empty?
 
-        authority = accept_authority_for(store)
+        authority = accept_role_for(store)
         ops = store.as(authority)
         touched = []
         store.manifest.resolver.enumerate.each do |row|
@@ -87,13 +87,13 @@ module Textus
         raise UsageError.new("schema not found: #{name}")
       end
 
-      def self.accept_authority_for(store)
-        authority = store.manifest.policy.roles_with_kind(:accept_authority).first
+      def self.accept_role_for(store)
+        authority = store.manifest.policy.roles_with_capability("author").first
         return authority if authority
 
         raise UsageError.new(
-          "schema migrate requires a role with kind :accept_authority in the manifest; " \
-          "none declared (add e.g. `- { name: owner, kind: accept_authority }` to roles:)",
+          "schema migrate requires a role holding the 'author' capability; " \
+          "none declared (add e.g. `- { name: owner, can: [author] }` to roles:)",
         )
       end
     end

data/lib/textus/session.rb

@@ -0,0 +1,24 @@
+module Textus
+  # The agent session: per-connection (MCP), per-process (CLI), or per-loop
+  # (Ruby) orientation state — the audit cursor plus the manifest etag and
+  # propose_zone captured at boot. Immutable Data value; advance_cursor
+  # returns a new instance. ADR 0036.
+  Session = Data.define(:role, :cursor, :propose_zone, :manifest_etag) do
+    def advance_cursor(new_cursor) = with(cursor: new_cursor)
+
+    def check_etag!(observed_etag)
+      return if observed_etag == manifest_etag
+
+      raise Textus::MCP::ContractDrift.new(
+        "manifest changed (was #{short_etag(manifest_etag)}, now #{short_etag(observed_etag)}); re-run boot",
+      )
+    end
+
+    private
+
+    # First 8 hex chars after the "sha256:" prefix — a stable short id for
+    # the drift diagnostic. Tolerates non-prefixed values (delete_prefix is
+    # a no-op when the prefix is absent).
+    def short_etag(etag) = etag.to_s.delete_prefix("sha256:")[0, 8]
+  end
+end

data/lib/textus/store.rb

@@ -50,6 +50,17 @@ module Textus
       @container ||= Textus::Container.from_store(self)
     end
 
+    # Build an agent Session oriented at the current cursor/manifest — the
+    # Ruby equivalent of an MCP `initialize`. ADR 0036.
+    def session(role:)
+      Textus::Session.new(
+        role: role,
+        cursor: audit_log.latest_seq,
+        propose_zone: manifest.policy.propose_zone_for(role),
+        manifest_etag: file_store.etag(File.join(root, "manifest.yaml")),
+      )
+    end
+
     def as(role, dry_run: false, correlation_id: nil)
       RoleScope.new(container: container, role: role, dry_run: dry_run, correlation_id: correlation_id)
     end

data/lib/textus/version.rb

@@ -1,4 +1,4 @@
 module Textus
-  VERSION = "0.30.0"
+  VERSION = "0.38.0"
   PROTOCOL = "textus/3"
 end

data/lib/textus/write/accept.rb

@@ -1,37 +1,30 @@
-require_relative "authority_gate"
-
 module Textus
   module Write
     class Accept
-      include AuthorityGate
-
       def initialize(container:, call:)
-        @container    = container
-        @call         = call
-        @manifest     = container.manifest
-        @schemas      = container.schemas
-        @events       = container.events
+        @container = container
+        @call      = call
+        @manifest  = container.manifest
+        @schemas   = container.schemas
+        @events    = container.events
       end
 
       def call(pending_key)
-        assert_accept_authority!("accept")
-
-        env = Textus::Read::Get.new(
-          container: @container, call: @call,
-        ).call(pending_key)
+        env = Textus::Read::Get.new(container: @container, call: @call).call(pending_key)
         proposal = env.meta["proposal"] or raise ProposalError.new("entry has no proposal block: #{pending_key}")
         target = proposal["target_key"] or raise ProposalError.new("proposal missing target_key")
         action = proposal["action"] || "put"
 
-        evaluate_promotion!(env, target)
+        guard.for(:accept, target).check!(
+          Textus::Domain::Policy::Evaluation.new(
+            actor: @call.role, transition: :accept, origin: pending_key,
+            target: target, envelope: env, manifest: @manifest
+          ),
+        )
 
         case action
         when "put"
-          # Nested proposal "frontmatter" — the meta to write to the accepted
-          # target. Not related to the removed intake-handler legacy bridge.
-          target_meta = env.meta["frontmatter"] || {}
-          target_body = env.body
-          put_op.call(target, meta: target_meta, body: target_body)
+          put_op.call(target, meta: env.meta["frontmatter"] || {}, body: env.body)
         when "delete"
           delete_op.call(target)
         else
@@ -39,48 +32,19 @@ module Textus
         end
 
         delete_op.call(pending_key)
-
-        @events.publish(:proposal_accepted,
-                        ctx: hook_context,
-                        key: pending_key,
-                        target_key: target)
-
+        @events.publish(:proposal_accepted, ctx: hook_context, key: pending_key, target_key: target)
         { "protocol" => PROTOCOL, "accepted" => pending_key, "target_key" => target, "action" => action }
       end
 
       private
 
-      def hook_context
-        @hook_context ||= Textus::Hooks::Context.for(container: @container, call: @call)
-      end
-
-      def put_op
-        @put_op ||= Textus::Write::Put.new(
-          container: @container, call: @call,
-        )
+      def guard
+        @guard ||= Textus::Domain::Policy::GuardFactory.new(manifest: @manifest, schemas: @schemas)
       end
 
-      def delete_op
-        @delete_op ||= Textus::Write::Delete.new(
-          container: @container, call: @call,
-        )
-      end
-
-      def evaluate_promotion!(env, target_key)
-        rules = @manifest.rules.for(target_key)
-        promote = rules.promote
-        return if promote.nil? || promote.requires.empty?
-
-        policy = Textus::Domain::Policy::Promotion.from_names(promote.requires)
-        result = policy.evaluate(
-          entry: env, schemas: @schemas, manifest: @manifest, role: @call.role,
-        )
-        return if result.ok?
-
-        raise ProposalError.new(
-          "promotion gate failed: #{result.reasons.join("; ")}",
-        )
-      end
+      def hook_context = @hook_context ||= Textus::Hooks::Context.for(container: @container, call: @call)
+      def put_op       = @put_op ||= Textus::Write::Put.new(container: @container, call: @call)
+      def delete_op    = @delete_op ||= Textus::Write::Delete.new(container: @container, call: @call)
     end
   end
 end

data/lib/textus/write/delete.rb

@@ -5,7 +5,6 @@ module Textus
         @container    = container
         @call         = call
         @manifest     = container.manifest
-        @authorizer   = container.authorizer
         @events       = container.events
       end
 
@@ -13,7 +12,7 @@ module Textus
         Textus::Manifest::Data.validate_key!(key)
         mentry = @manifest.resolver.resolve(key).entry
 
-        @authorizer.authorize_write!(mentry, role: @call.role)
+        guard_for(:delete, key, if_etag: if_etag).check!(eval_for(:delete, target_key: key))
 
         writer.delete(key, mentry: mentry, if_etag: if_etag)
 
@@ -28,6 +27,19 @@ module Textus
 
       private
 
+      def guard_for(transition, key, if_etag: nil)
+        Textus::Domain::Policy::GuardFactory.new(
+          manifest: @manifest, schemas: @container.schemas, extra: { if_etag: if_etag },
+        ).for(transition, key)
+      end
+
+      def eval_for(transition, target_key:, envelope: nil)
+        Textus::Domain::Policy::Evaluation.new(
+          actor: @call.role, transition: transition, origin: nil,
+          target: target_key, envelope: envelope, manifest: @manifest
+        )
+      end
+
       def hook_context
         @hook_context ||= Textus::Hooks::Context.for(container: @container, call: @call)
       end

data/lib/textus/write/{refresh_all.rb → fetch_all.rb}

@@ -1,28 +1,36 @@
 module Textus
   module Write
-    class RefreshAll
+    class FetchAll
+      extend Textus::Contract::DSL
+
+      verb     :fetch_all
+      summary  "Fetch all stale quarantine entries, optionally scoped by zone/prefix."
+      surfaces :cli, :ruby, :mcp
+      arg :prefix, String
+      arg :zone,   String
+
       def initialize(container:, call:)
         @container    = container
         @call         = call
       end
 
       def call(prefix: nil, zone: nil)
-        worker = Textus::Write::RefreshWorker.new(
+        worker = Textus::Write::FetchWorker.new(
           container: @container, call: @call,
         )
 
         stale_rows = Textus::Read::Stale.new(container: @container, call: @call).call(prefix: prefix, zone: zone)
-        refreshed = []
+        fetched = []
         failed = []
         skipped = []
 
         stale_rows.each do |row|
           key = row["key"] || row[:key]
           reason = row["reason"] || row[:reason]
-          if reason.to_s.match?(/ttl exceeded|never refreshed/)
+          if reason.to_s.match?(/ttl exceeded|never fetched/)
             begin
               worker.run(key)
-              refreshed << key
+              fetched << key
             rescue Textus::Error => e
               failed << { "key" => key, "error" => e.message }
             end
@@ -34,7 +42,7 @@ module Textus
         {
           "protocol" => Textus::PROTOCOL,
           "ok" => failed.empty?,
-          "refreshed" => refreshed,
+          "fetched" => fetched,
           "failed" => failed,
           "skipped" => skipped,
         }

data/lib/textus/write/{refresh_orchestrator.rb → fetch_orchestrator.rb}

@@ -1,8 +1,8 @@
 module Textus
   module Write
-    class RefreshOrchestrator
-      # Collaborator (not a Dispatcher verb): constructed directly by RefreshWorker /
-      # GetOrRefresh, which pass their derived hook_context in. That's why this takes
+    class FetchOrchestrator
+      # Collaborator (not a Dispatcher verb): constructed directly by FetchWorker /
+      # GetOrFetch, which pass their derived hook_context in. That's why this takes
       # hook_context: explicitly while verb use cases derive their own.
       def initialize(worker:, store_root:, events:, hook_context: nil, detached_spawner: nil)
         @worker       = worker
@@ -14,9 +14,9 @@ module Textus
 
       def execute(action, key:)
         case action
-        when Textus::Domain::Action::Return       then Textus::Domain::Outcome::Skipped.new
-        when Textus::Domain::Action::RefreshSync  then run_sync(key)
-        when Textus::Domain::Action::RefreshTimed then run_timed(action.budget_ms, key)
+        when Textus::Domain::Action::Return then Textus::Domain::Outcome::Skipped.new
+        when Textus::Domain::Action::FetchSync  then run_sync(key)
+        when Textus::Domain::Action::FetchTimed then run_timed(action.budget_ms, key)
         else raise ArgumentError.new("unknown action: #{action.inspect}")
         end
       end
@@ -25,13 +25,13 @@ module Textus
 
       def run_sync(key)
         envelope = @worker.run(key)
-        Textus::Domain::Outcome::Refreshed.new(envelope: envelope)
+        Textus::Domain::Outcome::Fetched.new(envelope: envelope)
       rescue Textus::Error => e
         Textus::Domain::Outcome::Failed.new(error: e)
       end
 
       def run_timed(budget_ms, key)
-        return run_timed_with_fork(budget_ms, key) if Textus::Ports::Refresh::Detached.supported?
+        return run_timed_with_fork(budget_ms, key) if Textus::Ports::Fetch::Detached.supported?
 
         run_timed_cooperative(budget_ms, key)
       end
@@ -49,7 +49,7 @@ module Textus
           thread.kill
           return Textus::Domain::Outcome::Failed.new(
             error: Textus::UsageError.new(
-              "refresh exceeded budget #{budget_ms}ms (no fork available — cooperative cancel)",
+              "fetch exceeded budget #{budget_ms}ms (no fork available — cooperative cancel)",
             ),
           )
         end
@@ -57,7 +57,7 @@ module Textus
         if result.is_a?(Textus::Error)
           Textus::Domain::Outcome::Failed.new(error: result)
         else
-          Textus::Domain::Outcome::Refreshed.new(envelope: result)
+          Textus::Domain::Outcome::Fetched.new(envelope: result)
         end
       end
 
@@ -77,25 +77,25 @@ module Textus
           # Single-flight: if a sibling process / earlier fork holds the
           # per-leaf lock, don't fork another worker — they're already
           # doing this work.
-          probe = Textus::Ports::Refresh::Lock.new(root: @store_root, key: key)
+          probe = Textus::Ports::Fetch::Lock.new(root: @store_root, key: key)
           return Textus::Domain::Outcome::Detached.new unless probe.try_acquire
 
           probe.release
 
           payload = { key: key, started_at: Time.now.utc.iso8601, budget_ms: budget_ms }
           payload[:ctx] = @hook_context if @hook_context
-          @events.publish(:refresh_backgrounded, **payload)
+          @events.publish(:fetch_backgrounded, **payload)
           @detached_spawner.call(store_root: @store_root, key: key)
           Textus::Domain::Outcome::Detached.new
         elsif result.is_a?(Textus::Error)
           Textus::Domain::Outcome::Failed.new(error: result)
         else
-          Textus::Domain::Outcome::Refreshed.new(envelope: result)
+          Textus::Domain::Outcome::Fetched.new(envelope: result)
         end
       end
 
       def default_spawner
-        Textus::Ports::Refresh::Detached.method(:spawn)
+        Textus::Ports::Fetch::Detached.method(:spawn)
       end
     end
   end

data/lib/textus/write/{refresh_worker.rb → fetch_worker.rb}

@@ -2,20 +2,28 @@ require "timeout"
 
 module Textus
   module Write
-    class RefreshWorker
+    class FetchWorker
+      extend Textus::Contract::DSL
+
+      verb     :fetch
+      summary  "Run a fetch action for one quarantine entry."
+      surfaces :cli, :ruby, :mcp
+      arg :key, String, required: true, positional: true
+      response { |outcome| { "outcome" => outcome.class.name.split("::").last.downcase } }
+
       FETCH_TIMEOUT_SECONDS = IntakeFetch::FETCH_TIMEOUT_SECONDS
 
       def initialize(container:, call:)
         @container    = container
         @call         = call
         @manifest     = container.manifest
+        @schemas      = container.schemas
         @events       = container.events
         @rpc          = container.rpc
-        @authorizer   = container.authorizer
       end
 
       # call(key) is the primary entry; run is kept as an alias for
-      # Orchestrator and RefreshAll which call worker.run(key).
+      # Orchestrator and FetchAll which call worker.run(key).
       def call(key)
         run(key)
       end
@@ -63,11 +71,11 @@ module Textus
 
       def fetch_timeout_for(key)
         rule = @manifest.rules.for(key)
-        rule&.refresh&.fetch_timeout_seconds || FETCH_TIMEOUT_SECONDS
+        rule&.fetch&.fetch_timeout_seconds || FETCH_TIMEOUT_SECONDS
       end
 
       def fetch_with_events(key, mentry, remaining)
-        @events.publish(:refresh_started, ctx: hook_context, key: key, mode: :sync)
+        @events.publish(:fetch_started, ctx: hook_context, key: key, mode: :sync)
         call_intake(key, mentry, remaining)
       end
 
@@ -80,23 +88,30 @@ module Textus
                       args: { trigger_key: key, leaf_segments: remaining || [] })
         end
       rescue Timeout::Error
-        @events.publish(:refresh_failed, ctx: hook_context, key: key,
-                                         error_class: "Timeout::Error",
-                                         error_message: "intake '#{mentry.handler}' exceeded #{timeout}s")
+        @events.publish(:fetch_failed, ctx: hook_context, key: key,
+                                       error_class: "Timeout::Error",
+                                       error_message: "intake '#{mentry.handler}' exceeded #{timeout}s")
         raise UsageError.new("intake '#{mentry.handler}' exceeded #{timeout}s timeout")
       rescue Textus::Error => e
-        @events.publish(:refresh_failed, ctx: hook_context, key: key, error_class: e.class.name,
-                                         error_message: e.message)
+        @events.publish(:fetch_failed, ctx: hook_context, key: key, error_class: e.class.name,
+                                       error_message: e.message)
         raise
       rescue StandardError => e
-        @events.publish(:refresh_failed, ctx: hook_context, key: key, error_class: e.class.name,
-                                         error_message: e.message)
+        @events.publish(:fetch_failed, ctx: hook_context, key: key, error_class: e.class.name,
+                                       error_message: e.message)
         raise UsageError.new("intake '#{mentry.handler}' raised: #{e.class}: #{e.message}")
       end
 
       def persist_and_notify(key, mentry, result, before_etag)
         normalized = self.class.normalize_action_result(result, format: mentry.format)
-        @authorizer.authorize_write!(mentry, role: @call.role)
+        Textus::Domain::Policy::GuardFactory.new(
+          manifest: @manifest, schemas: @schemas,
+        ).for(:fetch, key).check!(
+          Textus::Domain::Policy::Evaluation.new(
+            actor: @call.role, transition: :fetch, origin: nil,
+            target: key, envelope: nil, manifest: @manifest
+          ),
+        )
         envelope = writer.put(
           key,
           mentry: mentry,
@@ -105,7 +120,7 @@ module Textus
           ),
         )
         change = detect_change(before_etag, envelope)
-        @events.publish(:entry_refreshed, ctx: hook_context, key: key, envelope: envelope, change: change) unless change == :unchanged
+        @events.publish(:entry_fetched, ctx: hook_context, key: key, envelope: envelope, change: change) unless change == :unchanged
         envelope
       end
 

data/lib/textus/write/mv.rb

@@ -6,7 +6,6 @@ module Textus
         @call         = call
         @manifest     = container.manifest
         @events       = container.events
-        @authorizer   = container.authorizer
       end
 
       def call(old_key, new_key, dry_run: false)
@@ -38,8 +37,8 @@ module Textus
         raise UnknownKey.new(old_key) unless reader.exists?(old_key)
 
         validate_zone_and_format!(old_res.entry, new_res.entry)
-        @authorizer.authorize_write!(old_res.entry, role: @call.role)
-        @authorizer.authorize_write!(new_res.entry, role: @call.role)
+        guard_for(:mv, old_key).check!(eval_for(:mv, target_key: old_key))
+        guard_for(:mv, new_key).check!(eval_for(:mv, target_key: new_key))
         raise UsageError.new("mv: target '#{new_key}' already exists at #{new_res.path}") if reader.exists?(new_key)
 
         [old_res, new_res]
@@ -101,6 +100,19 @@ module Textus
         }
       end
 
+      def guard_for(transition, key, if_etag: nil)
+        Textus::Domain::Policy::GuardFactory.new(
+          manifest: @manifest, schemas: @container.schemas, extra: { if_etag: if_etag },
+        ).for(transition, key)
+      end
+
+      def eval_for(transition, target_key:, envelope: nil)
+        Textus::Domain::Policy::Evaluation.new(
+          actor: @call.role, transition: transition, origin: nil,
+          target: target_key, envelope: envelope, manifest: @manifest
+        )
+      end
+
       def writer
         @writer ||= Textus::Envelope::IO::Writer.from(container: @container, call: @call)
       end

data/lib/textus/write/propose.rb

@@ -0,0 +1,46 @@
+module Textus
+  module Write
+    # Queue a proposal: resolve the acting role's propose_zone, prefix the key,
+    # and write there via the Put verb. Was inlined in the MCP `propose` tool
+    # and the CLI propose verb; promoted to a first-class verb so all three
+    # transports share one implementation (ADR 0036, ADR 0039).
+    class Propose
+      extend Textus::Contract::DSL
+
+      verb     :propose
+      summary  "Write a proposal to the role's propose_zone. Auto-prefixes the key."
+      surfaces :cli, :ruby, :mcp
+      arg :key,     String, required: true, positional: true,
+                            description: "key relative to propose_zone, e.g. 'decisions.feature-x'"
+      arg :meta,    Hash,   required: true
+      arg :body,    String
+      arg :content, Hash
+      response { |env| { "uid" => env.uid, "etag" => env.etag, "key" => env.key } }
+
+      def initialize(container:, call:)
+        @container = container
+        @call      = call
+        @manifest  = container.manifest
+      end
+
+      # if_etag is intentionally absent: a proposal is always a fresh queue write.
+      def call(key, meta: nil, body: nil, content: nil)
+        zone = @manifest.policy.propose_zone_for(@call.role)
+        unless zone
+          raise Textus::Error.new(
+            "propose_forbidden",
+            "role '#{@call.role}' has no writable propose_zone",
+            details: { "role" => @call.role },
+            hint: "the manifest must define a queue zone and '#{@call.role}' must hold the 'propose' capability",
+          )
+        end
+
+        Textus::Dispatcher.invoke(
+          :put, container: @container, call: @call,
+                args: ["#{zone}.#{key}"],
+                kwargs: { meta: meta || {}, body: body, content: content }
+        )
+      end
+    end
+  end
+end

data/lib/textus/write/put.rb

@@ -1,18 +1,29 @@
 module Textus
   module Write
     class Put
+      extend Textus::Contract::DSL
+
+      verb     :put
+      summary  "Create or update an entry. Schema-validated. Returns {uid, etag}."
+      surfaces :cli, :ruby, :mcp
+      arg :key,     String, required: true, positional: true
+      arg :meta,    Hash, required: true
+      arg :body,    String
+      arg :content, Hash
+      arg :if_etag, String
+      response { |env| { "uid" => env.uid, "etag" => env.etag } }
+
       def initialize(container:, call:)
         @container    = container
         @call         = call
         @manifest     = container.manifest
-        @authorizer   = container.authorizer
         @events       = container.events
       end
 
       def call(key, meta: nil, body: nil, content: nil, if_etag: nil)
         Textus::Manifest::Data.validate_key!(key)
         mentry = @manifest.resolver.resolve(key).entry
-        @authorizer.authorize_write!(mentry, role: @call.role)
+        guard_for(:put, key, if_etag: if_etag).check!(eval_for(:put, target_key: key))
 
         envelope = writer.put(
           key,
@@ -33,6 +44,19 @@ module Textus
 
       private
 
+      def guard_for(transition, key, if_etag: nil)
+        Textus::Domain::Policy::GuardFactory.new(
+          manifest: @manifest, schemas: @container.schemas, extra: { if_etag: if_etag },
+        ).for(transition, key)
+      end
+
+      def eval_for(transition, target_key:, envelope: nil)
+        Textus::Domain::Policy::Evaluation.new(
+          actor: @call.role, transition: transition, origin: nil,
+          target: target_key, envelope: envelope, manifest: @manifest
+        )
+      end
+
       def hook_context
         @hook_context ||= Textus::Hooks::Context.for(container: @container, call: @call)
       end

data/lib/textus/write/reject.rb

@@ -1,19 +1,21 @@
-require_relative "authority_gate"
-
 module Textus
   module Write
     class Reject
-      include AuthorityGate
-
       def initialize(container:, call:)
         @container    = container
         @call         = call
         @manifest     = container.manifest
+        @schemas      = container.schemas
         @events       = container.events
       end
 
       def call(pending_key)
-        assert_accept_authority!("reject")
+        guard.for(:reject, pending_key).check!(
+          Textus::Domain::Policy::Evaluation.new(
+            actor: @call.role, transition: :reject, origin: pending_key,
+            target: pending_key, envelope: nil, manifest: @manifest
+          ),
+        )
 
         mentry = @manifest.resolver.resolve(pending_key).entry
         unless mentry.in_proposal_zone?(@manifest.policy)
@@ -40,6 +42,10 @@ module Textus
 
       private
 
+      def guard
+        @guard ||= Textus::Domain::Policy::GuardFactory.new(manifest: @manifest, schemas: @schemas)
+      end
+
       def hook_context
         @hook_context ||= Textus::Hooks::Context.for(container: @container, call: @call)
       end

data/lib/textus.rb

@@ -20,6 +20,10 @@ loader.ignore(File.expand_path("textus/mcp/errors.rb", __dir__))
 loader.setup
 loader.eager_load
 
+# Derive CLI_VERBS after eager_load so all contract-declaring files are present
+# (boot.rb loads first alphabetically; Dispatcher contracts are declared later).
+Textus::Boot::CLI_VERBS = Textus::Boot.build_cli_verbs.freeze
+
 module Textus
   @hook_mutex  = Mutex.new
   @hook_blocks = []