textus 0.30.0 → 0.38.0

data/lib/textus/mcp/tools.rb

@@ -1,129 +1,14 @@
 module Textus
   module MCP
-    # Dispatch table for MCP tool names → implementations. Each implementation
-    # receives (session:, store:, args:) and returns a JSON-encodable value.
-    # Tool errors are wrapped in ToolError; ContractDrift / CursorExpired
-    # propagate verbatim so the server can map them to JSON-RPC codes.
+    # Thin delegator kept for name stability (ADR 0039). The dispatch table
+    # and JSON schemas are now DERIVED from per-verb contracts by MCP::Catalog;
+    # this module only forwards.
     module Tools
       module_function
 
       def call(name, session:, store:, args:)
-        impl = REGISTRY[name] or raise ToolError.new("unknown tool: #{name}")
-        impl.call(session, store, args || {})
-      rescue ContractDrift, CursorExpired
-        raise
-      rescue Textus::Error => e
-        raise ToolError.new("#{name}: #{e.message}")
+        Catalog.call(name, session: session, store: store, args: args || {})
       end
-
-      def ops_for(session, store)
-        store.as(session.role)
-      end
-
-      REGISTRY = {
-        "boot" => ->(_s, store, _a) { store.boot },
-
-        "find" => lambda do |s, store, args|
-          ops_for(s, store).list(zone: args["zone"], prefix: args["prefix"])
-        end,
-
-        "read" => lambda do |s, store, args|
-          key = args.fetch("key") { raise ToolError.new("read: missing key") }
-          env = ops_for(s, store).get(key)
-          env.to_h_for_wire
-        end,
-
-        "tick" => lambda do |s, store, args|
-          since = (args["since"] || s.cursor).to_i
-          ops_for(s, store).pulse(since: since)
-        end,
-
-        "write" => lambda do |s, store, args|
-          key = args.fetch("key") { raise ToolError.new("write: missing key") }
-          env = ops_for(s, store).put(
-            key,
-            meta: args["meta"] || {},
-            body: args["body"],
-            content: args["content"],
-            if_etag: args["if_etag"],
-          )
-          { "uid" => env.uid, "etag" => env.etag }
-        end,
-
-        "propose" => lambda do |s, store, args|
-          raise ToolError.new("propose: session has no propose_zone") unless s.propose_zone
-
-          rel = args.fetch("key") { raise ToolError.new("propose: missing key") }
-          target = "#{s.propose_zone}.#{rel}"
-          env = ops_for(s, store).put(
-            target,
-            meta: args["meta"] || {},
-            body: args["body"],
-            content: args["content"],
-          )
-          { "uid" => env.uid, "etag" => env.etag, "key" => target }
-        end,
-
-        "refresh" => lambda do |s, store, args|
-          key = args.fetch("key") { raise ToolError.new("refresh: missing key") }
-          outcome = ops_for(s, store).refresh(key)
-          { "outcome" => outcome.class.name.split("::").last.downcase }
-        end,
-
-        "refresh_stale" => lambda do |s, store, args|
-          ops_for(s, store).refresh_all(zone: args["zone"], prefix: args["prefix"])
-        end,
-
-        "schema" => lambda do |_s, store, args|
-          family = args.fetch("family") { raise ToolError.new("schema: missing family") }
-          store.schemas.fetch(family)
-        end,
-
-        "rules" => lambda do |_s, store, args|
-          key = args.fetch("key") { raise ToolError.new("rules: missing key") }
-          set = store.manifest.rules.for(key)
-          {
-            "refresh" => set.refresh&.to_h,
-            "promote" => set.respond_to?(:promote) ? set.promote&.to_h : nil,
-          }.compact
-        end,
-
-        "key_mv_prefix" => lambda do |s, store, args|
-          ops_for(s, store).key_mv_prefix(
-            from_prefix: args.fetch("from_prefix") { raise ToolError.new("key_mv_prefix: missing from_prefix") },
-            to_prefix: args.fetch("to_prefix") { raise ToolError.new("key_mv_prefix: missing to_prefix") },
-            dry_run: args["dry_run"] || false,
-          ).to_h
-        end,
-
-        "key_delete_prefix" => lambda do |s, store, args|
-          ops_for(s, store).key_delete_prefix(
-            prefix: args.fetch("prefix") { raise ToolError.new("key_delete_prefix: missing prefix") },
-            dry_run: args["dry_run"] || false,
-          ).to_h
-        end,
-
-        "zone_mv" => lambda do |s, store, args|
-          ops_for(s, store).zone_mv(
-            from: args.fetch("from") { raise ToolError.new("zone_mv: missing from") },
-            to: args.fetch("to") { raise ToolError.new("zone_mv: missing to") },
-            dry_run: args["dry_run"] || false,
-          ).to_h
-        end,
-
-        "rule_lint" => lambda do |s, store, args|
-          ops_for(s, store).rule_lint(
-            candidate_yaml: args.fetch("candidate_yaml") { raise ToolError.new("rule_lint: missing candidate_yaml") },
-          ).to_h
-        end,
-
-        "migrate" => lambda do |s, store, args|
-          ops_for(s, store).migrate(
-            plan_yaml: args.fetch("plan_yaml") { raise ToolError.new("migrate: missing plan_yaml") },
-            dry_run: args["dry_run"] || false,
-          ).to_h
-        end,
-      }.freeze
     end
   end
 end

data/lib/textus/ports/audit_log.rb

@@ -10,7 +10,7 @@ module Textus
 
       def initialize(root, max_size: DEFAULT_MAX_SIZE, keep: DEFAULT_KEEP)
         @root     = root
-        @path     = File.join(root, "audit.log")
+        @path     = Textus::Layout.audit_log(root)
         @max_size = max_size
         @keep     = keep
       end
@@ -54,6 +54,7 @@ module Textus
       end
 
       def append(role:, verb:, key:, etag_before:, etag_after:, extras: nil)
+        FileUtils.mkdir_p(File.dirname(@path))
         File.open(@path, File::WRONLY | File::APPEND | File::CREAT, 0o644) do |f|
           f.flock(File::LOCK_EX)
           next_seq = current_max_seq_unlocked + 1
@@ -81,6 +82,14 @@ module Textus
 
       private
 
+      def rotated(n)
+        File.join(Textus::Layout.audit_dir(@root), "audit.log.#{n}")
+      end
+
+      def rotated_meta(n)
+        File.join(Textus::Layout.audit_dir(@root), "audit.log.#{n}.meta.json")
+      end
+
       # Caller holds the flock. Returns the highest seq across the active log,
       # OR the most-recent rotated file's max_seq if the active log is empty.
       def current_max_seq_unlocked
@@ -113,7 +122,7 @@ module Textus
       end
 
       def read_meta(n)
-        path = File.join(@root, "audit.log.#{n}.meta.json")
+        path = rotated_meta(n)
         return nil unless File.exist?(path)
 
         JSON.parse(File.read(path))
@@ -151,25 +160,18 @@ module Textus
         meta = { "min_seq" => min_seq, "max_seq" => max_seq, "rotated_at" => Time.now.utc.iso8601 }
 
         # Drop the file that would be shifted past @keep.
-        oldest      = File.join(@root, "audit.log.#{@keep}")
-        oldest_meta = File.join(@root, "audit.log.#{@keep}.meta.json")
-        FileUtils.rm_f(oldest)
-        FileUtils.rm_f(oldest_meta)
+        FileUtils.rm_f(rotated(@keep))
+        FileUtils.rm_f(rotated_meta(@keep))
 
         # Shift .N → .(N+1) for N = keep-1 down to 1.
         (@keep - 1).downto(1) do |n|
-          src      = File.join(@root, "audit.log.#{n}")
-          dst      = File.join(@root, "audit.log.#{n + 1}")
-          File.rename(src, dst) if File.exist?(src)
-
-          src_meta = File.join(@root, "audit.log.#{n}.meta.json")
-          dst_meta = File.join(@root, "audit.log.#{n + 1}.meta.json")
-          File.rename(src_meta, dst_meta) if File.exist?(src_meta)
+          File.rename(rotated(n), rotated(n + 1)) if File.exist?(rotated(n))
+          File.rename(rotated_meta(n), rotated_meta(n + 1)) if File.exist?(rotated_meta(n))
         end
 
         # Active log → .1
-        File.rename(@path, File.join(@root, "audit.log.1"))
-        File.write(File.join(@root, "audit.log.1.meta.json"), JSON.generate(meta) + "\n")
+        File.rename(@path, rotated(1))
+        File.write(rotated_meta(1), JSON.generate(meta) + "\n")
         # Next append will create a fresh audit.log via File::CREAT.
       end
 

data/lib/textus/ports/audit_subscriber.rb

@@ -33,7 +33,7 @@ module Textus
         extras["target_key"]  = kwargs[:target_key]  if kwargs.key?(:target_key)
         extras["pending_key"] = kwargs[:pending_key] if kwargs.key?(:pending_key)
         @audit_log.append(
-          role: "runner", verb: "event_error", key: key,
+          role: "automation", verb: "event_error", key: key,
           etag_before: nil, etag_after: nil, extras: extras
         )
       end

data/lib/textus/ports/build_lock.rb

@@ -5,7 +5,6 @@ require "time"
 module Textus
   module Ports
     class BuildLock
-      LOCK_FILENAME = ".build.lock"
       MAX_HOLDER_BYTES = 512
 
       def self.with(root:, &)
@@ -13,7 +12,7 @@ module Textus
       end
 
       def initialize(root:)
-        @path = File.join(root, LOCK_FILENAME)
+        @path = Textus::Layout.build_lock(root)
         @file = nil
       end
 

data/lib/textus/ports/{refresh → fetch}/detached.rb

@@ -1,6 +1,6 @@
 module Textus
   module Ports
-    module Refresh
+    module Fetch
       module Detached
         module_function
 
@@ -16,14 +16,14 @@ module Textus
             $stdout.reopen(File::NULL, "w")
             $stderr.reopen(File::NULL, "w")
 
-            lock = Textus::Ports::Refresh::Lock.new(root: store_root, key: key)
+            lock = Textus::Ports::Fetch::Lock.new(root: store_root, key: key)
             exit(0) unless lock.try_acquire
 
             begin
               store = Textus::Store.new(store_root)
-              store.as("runner").refresh(key)
+              store.as("automation").fetch(key)
             rescue StandardError
-              # Already logged via :refresh_failed; exit cleanly.
+              # Already logged via :fetch_failed; exit cleanly.
             ensure
               lock.release
               exit(0)

data/lib/textus/ports/{refresh → fetch}/lock.rb

@@ -2,12 +2,12 @@ require "fileutils"
 
 module Textus
   module Ports
-    module Refresh
+    module Fetch
       class Lock
         def initialize(root:, key:)
           @root = root
           @key  = key
-          @path = File.join(root, ".locks", "#{safe_key}.lock")
+          @path = File.join(Textus::Layout.locks(root), "#{safe_key}.lock")
           @file = nil
         end
 

data/lib/textus/projection.rb

@@ -8,7 +8,7 @@ module Textus
 
     # `reader` — a callable `->(key) { envelope_or_nil }`. Caller picks
     #   semantics: pure read (`ops.get`) for materialization paths;
-    #   `ops.get_or_refresh` if you want refresh-on-stale.
+    #   `ops.get_or_fetch` if you want fetch-on-stale.
     # `lister` — a callable `->(prefix:) { [ { "key" => ... }, ... ] }`.
     # `rpc` — a `Hooks::RpcRegistry` used to dispatch `transform_rows` callables.
     # `transform_context` — capability object handed to transform reducers as `caps:`.

data/lib/textus/read/audit.rb

@@ -3,7 +3,7 @@ require "time"
 
 module Textus
   module Read
-    # Queries .textus/audit.log. Filters: key, zone, role, verb, since,
+    # Queries .textus/.run/audit/audit.log. Filters: key, zone, role, verb, since,
     # correlation_id, limit. Reads the log file as JSON-Lines (legacy TSV
     # rows produce nil and are skipped).
     class Audit
@@ -33,7 +33,7 @@ module Textus
       def initialize(container:, call: nil) # rubocop:disable Lint/UnusedMethodArgument
         @manifest  = container.manifest
         @root      = container.root
-        @log_path  = File.join(container.root, "audit.log")
+        @log_path  = Textus::Layout.audit_log(container.root)
         @audit_log = container.audit_log
       end
 
@@ -84,7 +84,7 @@ module Textus
       end
 
       def all_log_files
-        rotated = Dir.glob(File.join(@root, "audit.log.*"))
+        rotated = Dir.glob(File.join(Textus::Layout.audit_dir(@root), "audit.log.*"))
                      .reject { |p| p.end_with?(".meta.json") }
                      .sort_by { |p| -p.scan(/\d+$/).first.to_i } # .5 .4 .3 .2 .1 → oldest first
         active = File.exist?(@log_path) ? [@log_path] : []

data/lib/textus/read/boot.rb

@@ -5,6 +5,12 @@ module Textus
     # (container:, call:) entry point that Dispatcher::VERBS resolves to.
     # Boot is role-independent, so `call` is not consulted.
     class Boot
+      extend Textus::Contract::DSL
+
+      verb     :boot
+      summary  "Return the orientation contract: zones, entries, schemas, write_flows, agent_quickstart."
+      surfaces :cli, :ruby, :mcp
+
       def initialize(container:, call:)
         @container = container
         @call      = call

data/lib/textus/read/freshness.rb

@@ -3,8 +3,8 @@ require "time"
 module Textus
   module Read
     # Per-entry freshness report. Walks every entry declared in the manifest,
-    # consults `rules_for(key)` for a refresh rule, and reports the
-    # current status. Status is one of :fresh, :stale, :never_refreshed, or
+    # consults `rules_for(key)` for a fetch rule, and reports the
+    # current status. Status is one of :fresh, :stale, :never_fetched, or
     # :no_policy.
     class Freshness
       def initialize(container:, call:, evaluator: Textus::Domain::Freshness::Evaluator)
@@ -16,7 +16,7 @@ module Textus
         @cache      = {}
       end
 
-      # Returns the soonest `next_due_at` across all entries with a refresh
+      # Returns the soonest `next_due_at` across all entries with a fetch
       # policy, as an ISO-8601 string, or nil if none.
       def soonest_due(prefix: nil, zone: nil)
         times = call(prefix: prefix, zone: zone)
@@ -43,17 +43,17 @@ module Textus
 
       def row_for(mentry)
         set = @manifest.rules.for(mentry.key)
-        refresh = set.refresh
+        fetch = set.fetch
         envelope = safe_get(mentry.key)
-        last = envelope&.meta&.dig("last_refreshed_at")
+        last = envelope&.meta&.dig("last_fetched_at")
 
-        return base_row(mentry, last).merge(status: :no_policy) if refresh.nil?
+        return base_row(mentry, last).merge(status: :no_policy) if fetch.nil?
 
-        fp = refresh.to_freshness_policy
+        fp = fetch.to_freshness_policy
         cache_key = [mentry.key, last]
         verdict = (@cache[cache_key] ||= @evaluator.call(fp, envelope, now: @call.now))
         status = if verdict.fresh? then :fresh
-                 elsif last.nil?   then :never_refreshed
+                 elsif last.nil?   then :never_fetched
                  else                   :stale
                  end
 
@@ -69,7 +69,7 @@ module Textus
         {
           key: mentry.key,
           zone: mentry.zone,
-          last_refreshed_at: last,
+          last_fetched_at: last,
           age_seconds: last ? (@call.now - Time.parse(last)).to_i : nil,
         }
       end

data/lib/textus/read/get.rb

@@ -1,11 +1,19 @@
 module Textus
   module Read
     # Pure read: returns the on-disk envelope annotated with a freshness
-    # verdict. Never triggers refresh; never invokes the orchestrator.
+    # verdict. Never triggers fetch; never invokes the orchestrator.
     #
-    # For interactive reads that want refresh-on-stale, use
-    # `Read::GetOrRefresh`, which composes this with the orchestrator.
+    # For interactive reads that want fetch-on-stale, use
+    # `Read::GetOrFetch`, which composes this with the orchestrator.
     class Get
+      extend Textus::Contract::DSL
+
+      verb     :get
+      summary  "Read one entry. Returns the envelope (uid, etag, _meta, body, freshness)."
+      surfaces :cli, :ruby, :mcp
+      arg :key, String, required: true, positional: true
+      response(&:to_h_for_wire)
+
       def initialize(container:, call:, evaluator: Textus::Domain::Freshness::Evaluator)
         @container  = container
         @call       = call
@@ -19,16 +27,16 @@ module Textus
         return nil if envelope.nil?
 
         policy_set = @manifest.rules.for(key)
-        refresh_policy = policy_set.refresh
-        return annotate_fresh(envelope) if refresh_policy.nil?
+        fetch_policy = policy_set.fetch
+        return annotate_fresh(envelope) if fetch_policy.nil?
 
-        policy = refresh_policy.to_freshness_policy
+        policy = fetch_policy.to_freshness_policy
         verdict = @evaluator.call(policy, envelope, now: @call.now)
 
         envelope.with(freshness: Textus::Domain::Freshness.build(
           stale: verdict.stale?,
           reason: verdict.reason,
-          refreshing: false,
+          fetching: false,
         ))
       end
 
@@ -58,7 +66,7 @@ module Textus
 
       def annotate_fresh(envelope)
         envelope.with(freshness: Textus::Domain::Freshness.build(
-          stale: false, reason: nil, refreshing: false,
+          stale: false, reason: nil, fetching: false,
         ))
       end
     end

data/lib/textus/read/{get_or_refresh.rb → get_or_fetch.rb}

@@ -1,6 +1,6 @@
 module Textus
   module Read
-    # Composes pure `Read::Get` with the refresh orchestrator: runs Get
+    # Composes pure `Read::Get` with the fetch orchestrator: runs Get
     # to obtain the envelope and freshness verdict, then if the verdict
     # is stale and the rule's `on_stale` policy demands action, hands
     # off to the orchestrator. Use for interactive reads where the
@@ -8,7 +8,7 @@ module Textus
     #
     # Pure reads (build, projection, schema tooling) should use
     # `Read::Get` directly; it has no orchestrator dependency.
-    class GetOrRefresh
+    class GetOrFetch
       def initialize(container:, call:, get: nil, orchestrator: nil)
         @container    = container
         @call         = call
@@ -24,10 +24,10 @@ module Textus
       end
 
       def build_orchestrator
-        worker = Textus::Write::RefreshWorker.new(
+        worker = Textus::Write::FetchWorker.new(
           container: @container, call: @call,
         )
-        Textus::Write::RefreshOrchestrator.new(
+        Textus::Write::FetchOrchestrator.new(
           worker: worker, store_root: @container.root, events: @container.events,
           hook_context: hook_context
         )
@@ -41,10 +41,10 @@ module Textus
         return envelope unless envelope.freshness&.stale
 
         policy_set = @manifest.rules.for(key)
-        refresh_policy = policy_set.refresh
-        return envelope if refresh_policy.nil?
+        fetch_policy = policy_set.fetch
+        return envelope if fetch_policy.nil?
 
-        policy = refresh_policy.to_freshness_policy
+        policy = fetch_policy.to_freshness_policy
         verdict = Textus::Domain::Freshness::Verdict.stale(envelope.freshness.reason)
         action = policy.decide(verdict)
         outcome = @orchestrator.execute(action, key: key)
@@ -52,15 +52,15 @@ module Textus
         case outcome
         when Textus::Domain::Outcome::Skipped
           envelope
-        when Textus::Domain::Outcome::Refreshed
+        when Textus::Domain::Outcome::Fetched
           outcome.envelope.with(
-            freshness: Textus::Domain::Freshness.build(stale: false, reason: nil, refreshing: false),
+            freshness: Textus::Domain::Freshness.build(stale: false, reason: nil, fetching: false),
           )
         when Textus::Domain::Outcome::Detached
-          envelope.with(freshness: envelope.freshness.with(refreshing: true))
+          envelope.with(freshness: envelope.freshness.with(fetching: true))
         when Textus::Domain::Outcome::Failed
           envelope.with(
-            freshness: envelope.freshness.with(refresh_error: outcome.error.message),
+            freshness: envelope.freshness.with(fetch_error: outcome.error.message),
           )
         end
       end

data/lib/textus/read/list.rb

@@ -1,6 +1,14 @@
 module Textus
   module Read
     class List
+      extend Textus::Contract::DSL
+
+      verb     :list
+      summary  "List keys filtered by zone and/or prefix."
+      surfaces :cli, :ruby, :mcp
+      arg :prefix, String
+      arg :zone,   String
+
       def initialize(container:, call: nil) # rubocop:disable Lint/UnusedMethodArgument
         @manifest = container.manifest
       end

data/lib/textus/read/policy_explain.rb

@@ -1,40 +1,44 @@
 module Textus
   module Read
     # For one key, surface every matching policy block along with the
-    # per-slot effective value (which loses ties win-by-specificity).
+    # per-slot effective value (which loses ties win-by-specificity) and the
+    # effective guard predicate names for every write transition (ADR 0031).
     class PolicyExplain
       def initialize(container:, call: nil) # rubocop:disable Lint/UnusedMethodArgument
         @manifest = container.manifest
+        @schemas  = container.schemas
       end
 
       def call(key:)
-        policies = @manifest.rules
-        matching = policies.explain(key)
-        winners  = policies.for(key)
+        matching = @manifest.rules.explain(key)
+        winners  = @manifest.rules.for(key)
+        factory  = Textus::Domain::Policy::GuardFactory.new(manifest: @manifest, schemas: @schemas)
 
         {
           key: key,
           matched_blocks: matching.map do |b|
             {
               match: b.match,
-              refresh: !b.refresh.nil?,
+              fetch: !b.fetch.nil?,
               handler_allowlist: !b.handler_allowlist.nil?,
-              promote: !b.promote.nil?,
+              guard: !b.guard.nil?,
               retention: !b.retention.nil?,
             }
           end,
           effective: {
-            refresh: winners.refresh && {
-              ttl_seconds: winners.refresh.ttl_seconds,
-              on_stale: winners.refresh.on_stale,
+            fetch: winners.fetch && {
+              ttl_seconds: winners.fetch.ttl_seconds,
+              on_stale: winners.fetch.on_stale,
             },
             handler_allowlist: winners.handler_allowlist&.handlers,
-            promotion: winners.promote && { requires: winners.promote.requires },
             retention: winners.retention && {
               expire_after: winners.retention.expire_after,
               archive_after: winners.retention.archive_after,
             },
           },
+          guards: Textus::Domain::Policy::BaseGuards::BASE.keys.to_h do |transition|
+            [transition, factory.for(transition, key).predicates.map(&:name)]
+          end,
         }
       end
     end

data/lib/textus/read/pulse.rb

@@ -7,6 +7,13 @@ module Textus
     # APIs; pulse is sugar with a stable envelope shape and a monotonic
     # cursor (seq).
     class Pulse
+      extend Textus::Contract::DSL
+
+      verb     :pulse
+      summary  "Delta since cursor — changed entries, stale, pending proposals, doctor summary."
+      surfaces :cli, :ruby, :mcp
+      arg :since, Integer, session_default: :cursor, description: "audit seq to diff from; defaults to the session cursor"
+
       def initialize(container:, call:)
         @container  = container
         @call       = call
@@ -49,11 +56,12 @@ module Textus
       end
 
       def review_keys
-        # List constructor takes only manifest:; returns hashes with string keys.
-        # Guard: zones is a Hash keyed by name string.
-        return [] unless @manifest.data.zones.key?("review")
+        # The single queue zone (kind: queue; schema guarantees ≤1), derived
+        # from the manifest rather than a hardcoded zone name (ADR 0034 / D1).
+        queue = @manifest.policy.queue_zone
+        return [] unless queue
 
-        rows = Read::List.new(container: @container).call(zone: "review")
+        rows = Read::List.new(container: @container).call(zone: queue)
         rows.map { |r| r.is_a?(Hash) ? (r["key"] || r[:key]) : r }
       end
 

data/lib/textus/read/rules.rb

@@ -0,0 +1,24 @@
+module Textus
+  module Read
+    # Effective rule set (fetch + guard) for a key. Was the inlined MCP
+    # `rules` tool; promoted to a first-class verb so MCP is a pure projection
+    # (ADR 0039).
+    class Rules
+      extend Textus::Contract::DSL
+
+      verb     :rules
+      summary  "Return effective rules for a key (fetch, guard, ...)."
+      surfaces :ruby, :mcp
+      arg :key, String, required: true, positional: true
+
+      def initialize(container:, call: nil) # rubocop:disable Lint/UnusedMethodArgument
+        @manifest = container.manifest
+      end
+
+      def call(key)
+        set = @manifest.rules.for(key)
+        { "fetch" => set.fetch&.to_h, "guard" => set.guard }.compact
+      end
+    end
+  end
+end

data/lib/textus/read/schema_envelope.rb

@@ -1,6 +1,13 @@
 module Textus
   module Read
     class SchemaEnvelope
+      extend Textus::Contract::DSL
+
+      verb     :schema
+      summary  "Return the schema (field shape) for an entry's family, by key."
+      surfaces :ruby, :mcp
+      arg :key, String, required: true, positional: true
+
       def initialize(container:, call: nil) # rubocop:disable Lint/UnusedMethodArgument
         @manifest = container.manifest
         @schemas  = container.schemas

data/lib/textus/read/validator.rb

@@ -54,7 +54,7 @@ module Textus
         last_writer = @audit_log.last_writer_for(key)
         return if last_writer.nil?
 
-        last_writer_is_authority = @manifest.policy.role_kind(last_writer) == :accept_authority
+        last_writer_is_authority = @manifest.policy.roles_with_capability("author").include?(last_writer)
 
         env.meta.each_key do |field|
           owner = schema.maintained_by(field)

data/lib/textus/role.rb

@@ -2,9 +2,13 @@ module Textus
   module Role
     PATTERN = /\A[a-z][a-z0-9_-]*\z/
     DEFAULT = "human".freeze
+    # The default acting identity for the MCP transport (ADR 0040): an agent
+    # over stdio proposes; it does not inherit the human's authority. CLI
+    # callers keep the `human` DEFAULT.
+    AGENT = "agent".freeze
 
-    def self.resolve(root:, flag: nil, env: ENV)
-      candidate = flag || env["TEXTUS_ROLE"] || read_file(root) || DEFAULT
+    def self.resolve(root:, flag: nil, env: ENV, default: DEFAULT)
+      candidate = flag || env["TEXTUS_ROLE"] || read_file(root) || default
       raise InvalidRole.new(candidate) unless candidate.match?(PATTERN)
 
       candidate