textus 0.29.0 → 0.35.1

data/lib/textus/manifest/capabilities.rb

@@ -0,0 +1,29 @@
+module Textus
+  class Manifest
+    # Resolves a manifest's `roles:` block (or the absence of one) into a
+    # capability map: { role_name => [verbs] }. Verbs are a subset of the
+    # closed capability set (Schema::CAPABILITIES). See ADR 0030.
+    module Capabilities
+      # Fallback role set for a manifest that omits `roles:` entirely. Agent
+      # is intentionally minimal here (`propose` only) — narrower than the
+      # `textus init` scaffold, which declares `agent: [propose, keep]` so the
+      # default `notebook` workspace is writable. A roles-less manifest that
+      # declares a `kind: workspace` zone is therefore rejected at load (no
+      # `keep`-holder); declare `roles:` to opt into a workspace lane (ADR 0033).
+      DEFAULT_MAPPING = {
+        "human" => %w[author propose].freeze,
+        "agent" => %w[propose].freeze,
+        "automation" => %w[fetch build].freeze,
+      }.freeze
+
+      # Returns { role_name => [verbs] }. When `roles:` is declared we use
+      # exactly that; defaults are *not* layered in (declaring roles is an
+      # opt-in to a fully user-defined vocabulary).
+      def self.resolve(raw_roles)
+        return DEFAULT_MAPPING if raw_roles.nil?
+
+        raw_roles.to_h { |r| [r["name"], Array(r["can"]).freeze] }.freeze
+      end
+    end
+  end
+end

data/lib/textus/manifest/data.rb

@@ -1,17 +1,19 @@
 require_relative "schema"
-require_relative "role_kinds"
+require_relative "capabilities"
 
 module Textus
   class Manifest
     # Immutable, parsed view of a manifest YAML document.
     #
-    # Holds raw structural data (zones, entries, audit_config, role_mapping)
+    # Holds raw structural data (zones, entries, audit_config, role_caps)
     # but no behaviour beyond accessors. Behaviour (zone authority, key
     # resolution, rules) lives on Manifest::Policy / Resolver / Rules.
     class Data
       AUDIT_DEFAULTS = { max_size: 10_485_760, keep: 5 }.freeze
 
-      attr_reader :raw, :root, :entries, :zones, :zone_readers, :audit_config, :role_mapping, :policy
+      attr_reader :raw, :root, :entries, :declared_zone_kinds,
+                  :zone_descs, :zone_owners,
+                  :audit_config, :role_caps, :policy
 
       def self.validate_key!(key)
         raise UsageError.new("empty key") if key.nil? || key.empty?
@@ -33,13 +35,19 @@ module Textus
       def initialize(raw:, root:)
         @raw = raw
         @root = root
-        @zones = Array(raw["zones"]).to_h { |z| [z["name"], Array(z["write_policy"])] }
-        @zone_readers = Array(raw["zones"]).to_h do |z|
-          rp = z["read_policy"]
-          [z["name"], rp.nil? ? :all : Array(rp)]
+        # Write authority is derived from capabilities × zone-kind (ADR 0030),
+        # not a per-zone writer list. "Which zones are declared" lives in the
+        # one kind-keyed map below (declared_zone_kinds); membership checks by
+        # read-side callers (boot, maintenance/zone_mv) use its keyset (ADR 0034).
+        @declared_zone_kinds = Array(raw["zones"]).to_h do |z|
+          [z["name"], z["kind"]&.to_sym]
         end
+        @zone_descs  = Array(raw["zones"]).to_h { |z| [z["name"], z["desc"]] }
+        # Only zones that actually declare an owner — keep nil-tombstones out so a
+        # future `zone_owners.key?(name)` means "owner declared", not "zone exists".
+        @zone_owners = Array(raw["zones"]).to_h { |z| [z["name"], z["owner"]] }.compact
         @audit_config = build_audit_config(raw)
-        @role_mapping = RoleKinds.resolve(raw["roles"])
+        @role_caps = Capabilities.resolve(raw["roles"])
         # Policy is constructed before entries because Entry validators
         # call `entry.in_generator_zone?(policy)` and similar helpers
         # that take Policy as an argument.

data/lib/textus/manifest/entry/base.rb

@@ -23,8 +23,8 @@ module Textus
           raise UsageError.new("entry '#{@key}': #{e.message}")
         end
 
-        def in_generator_zone?(policy) = policy.zone_kinds(@zone).include?(:generator)
-        def in_proposal_zone?(policy)  = policy.zone_kinds(@zone).include?(:proposer)
+        def in_generator_zone?(policy) = policy.derived_zone?(@zone)
+        def in_proposal_zone?(policy)  = policy.queue_zone?(@zone)
 
         def nested?  = false
         def derived? = false

data/lib/textus/manifest/policy.rb

@@ -2,46 +2,89 @@ module Textus
   class Manifest
     # Authority over zones and roles derived from a Manifest::Data snapshot.
     # Encapsulates the lookups previously living on Manifest itself
-    # (zone_writers, zone_kinds, permission_for, role_kind, roles_with_kind).
+    # (zone_writers, permission_for). Write authority is derived from
+    # capabilities × zone-kind (ADR 0030): each zone-kind requires one verb
+    # (Schema::KIND_REQUIRES_VERB) and a role may write a zone iff its caps
+    # include that verb (verb_for_zone, roles_with_capability). Derived /
+    # proposal-queue status is authoritative via the declared-kind family
+    # (declared_kind, derived_zone?, queue_zone?, queue_zone).
     class Policy
       def initialize(data)
         @data = data
-        @zone_kinds_cache = {}
       end
 
-      def zone_writers(zone_name)
-        @data.zones[zone_name] or raise UsageError.new("undeclared zone '#{zone_name}'")
+      # The capability a zone's kind requires to be written, or nil if the
+      # zone declares no kind. declared_kind returns a Symbol; the table is
+      # keyed by String.
+      def verb_for_zone(zone_name)
+        kind = declared_kind(zone_name)
+        kind && Schema::KIND_REQUIRES_VERB[kind.to_s]
+      end
+
+      # Names of roles whose declared caps include `verb`.
+      def roles_with_capability(verb)
+        @data.role_caps.select { |_name, caps| caps.include?(verb) }.keys
       end
 
-      def zone_readers
-        @data.zone_readers
+      # The conventional automated proposer: a role that can propose but is not
+      # the author-anchor (so it resolves to `agent`, not `human`, under the
+      # default mapping). Falls back to the first proposer, then nil.
+      def proposer_role
+        proposers = roles_with_capability("propose")
+        (proposers - roles_with_capability("author")).first || proposers.first
+      end
+
+      # The roles authorized to write `zone_name`: those holding the verb its
+      # kind requires. Raises on an undeclared zone.
+      def zone_writers(zone_name)
+        raise UsageError.new("undeclared zone '#{zone_name}'") unless @data.declared_zone_kinds.key?(zone_name)
+
+        roles_with_capability(verb_for_zone(zone_name))
       end
 
       def permission_for(zone_name)
         Textus::Domain::Permission.new(
           zone: zone_name,
-          write_policy: zone_writers(zone_name),
-          read_policy: @data.zone_readers[zone_name] || :all,
+          writers: zone_writers(zone_name),
         )
       end
 
-      def zone_kinds(zone_name)
-        @zone_kinds_cache[zone_name] ||= zone_writers(zone_name).each_with_object(Set.new) do |w, acc|
-          k = role_kind(w)
-          acc << k if k
-        end.freeze
+      # The kind declared on a zone in the manifest, or nil if undeclared.
+      def declared_kind(zone_name)
+        @data.declared_zone_kinds[zone_name]
       end
 
-      def role_mapping
-        @data.role_mapping
+      # Zone names declaring `kind` (a Symbol), in manifest order. Lets callers
+      # (boot) name a kind's live zone instance(s) instead of hardcoding names.
+      def zones_of_kind(kind)
+        @data.declared_zone_kinds.select { |_name, k| k == kind }.keys
       end
 
-      def role_kind(name)
-        @data.role_mapping[name]
+      # The single zone declaring `kind: queue`, or nil. Schema guarantees <=1.
+      def queue_zone
+        @data.declared_zone_kinds.key(:queue)
       end
 
-      def roles_with_kind(kind)
-        @data.role_mapping.each_with_object([]) { |(name, k), acc| acc << name if k == kind }
+      # A zone is derived iff it declares kind: derived.
+      def derived_zone?(zone_name)
+        declared_kind(zone_name) == :derived
+      end
+
+      # A zone is a proposal queue iff it declares kind: queue.
+      def queue_zone?(zone_name)
+        declared_kind(zone_name) == :queue
+      end
+
+      # The zone a proposer role writes proposals into: the single zone that
+      # declares kind: queue, when the role can write it. Returns nil if there
+      # is no queue zone or the role cannot write it.
+      def propose_zone_for(role)
+        return nil if role.nil?
+
+        q = queue_zone
+        return nil unless q && zone_writers(q).include?(role)
+
+        q
       end
     end
   end

data/lib/textus/manifest/rules.rb

@@ -1,8 +1,8 @@
 module Textus
   class Manifest
     class Rules
-      RuleSet = ::Data.define(:refresh, :handler_allowlist, :promote, :retention)
-      EMPTY_SET = RuleSet.new(refresh: nil, handler_allowlist: nil, promote: nil, retention: nil)
+      RuleSet = ::Data.define(:fetch, :handler_allowlist, :guard, :retention)
+      EMPTY_SET = RuleSet.new(fetch: nil, handler_allowlist: nil, guard: nil, retention: nil)
 
       def self.parse(raw)
         new(Array(raw).map { |b| Block.new(b) })
@@ -15,16 +15,16 @@ module Textus
       attr_reader :blocks
 
       def for(key)
-        slots = { refresh: [], handler_allowlist: [], promote: [], retention: [] }
+        slots = { fetch: [], handler_allowlist: [], guard: [], retention: [] }
         @blocks.each do |b|
           next unless Textus::Domain::Policy::Matcher.matches?(b.match, key)
 
           slots.each_key { |slot| slots[slot] << b if b.public_send(slot) }
         end
         RuleSet.new(
-          refresh: pick(slots[:refresh], :refresh, key),
+          fetch: pick(slots[:fetch], :fetch, key),
           handler_allowlist: pick(slots[:handler_allowlist], :handler_allowlist, key),
-          promote: pick(slots[:promote], :promote, key),
+          guard: pick(slots[:guard], :guard, key),
           retention: pick(slots[:retention], :retention, key),
         )
       end
@@ -44,22 +44,22 @@ module Textus
       end
 
       class Block
-        attr_reader :match, :refresh, :handler_allowlist, :promote, :retention
+        attr_reader :match, :fetch, :handler_allowlist, :guard, :retention
 
         def initialize(raw)
           @match = raw["match"] or raise Textus::UsageError.new("rule block missing match:")
-          @refresh = parse_refresh(raw["refresh"])
+          @fetch = parse_fetch(raw["fetch"])
           @handler_allowlist = parse_handler_allowlist(raw["intake_handler_allowlist"])
-          @promote = parse_promotion(raw["promotion"])
-          @retention = raw["retention"] # reserved — passthrough only
+          @guard = parse_guard(raw["guard"])
+          @retention = parse_retention(raw["retention"])
         end
 
         private
 
-        def parse_refresh(h)
+        def parse_fetch(h)
           return nil if h.nil?
 
-          Textus::Domain::Policy::Refresh.new(
+          Textus::Domain::Policy::Fetch.new(
             ttl: h["ttl"],
             on_stale: h["on_stale"] || "warn",
             sync_budget_ms: h["sync_budget_ms"],
@@ -73,12 +73,23 @@ module Textus
           Textus::Domain::Policy::HandlerAllowlist.new(handlers: arr)
         end
 
-        def parse_promotion(h)
+        # A guard: block is a map of transition => [predicate specs]. Predicate
+        # names are validated at GuardFactory build time via Predicates::Registry
+        # (ADR 0031); here we only assert the structural shape.
+        def parse_guard(h)
           return nil if h.nil?
+          raise Textus::BadManifest.new("guard: must be a map of transition => [predicates]") unless h.is_a?(Hash)
 
-          raise Textus::BadManifest.new("promotion: must be a hash with a 'requires:' array") unless h.is_a?(Hash) && h.key?("requires")
+          h
+        end
+
+        def parse_retention(h)
+          return nil if h.nil?
 
-          Textus::Domain::Policy::Promote.new(requires: Array(h["requires"]))
+          Textus::Domain::Policy::Retention.new(
+            expire_after: h["expire_after"],
+            archive_after: h["archive_after"],
+          )
         end
       end
     end

data/lib/textus/manifest/schema.rb

@@ -2,21 +2,38 @@ module Textus
   class Manifest
     module Schema
       ROOT_KEYS    = %w[version roles zones entries rules audit].freeze
-      ROLE_KEYS    = %w[name kind].freeze
-      ROLE_KINDS   = %w[accept_authority generator proposer runner].freeze
-      ZONE_KEYS    = %w[name write_policy read_policy].freeze
-      ENTRY_KEYS   = %w[
+      ROLE_KEYS    = %w[name can].freeze
+      ZONE_KEYS    = %w[name kind owner desc].freeze
+      # The closed coordination vocabulary (ADR 0028; completed at five in ADR
+      # 0033; unified here in ADR 0034). Each lane pairs a zone-kind with the
+      # single capability that authorizes originating bytes in it — a total
+      # bijection. This table is the ONE source of truth; the three legacy
+      # constants below are derived from it so a zone-kind and its required
+      # capability cannot drift. Key order is canon-first so the unknown-kind
+      # error message reads canon, workspace, quarantine, queue, derived.
+      LANES = {
+        "canon" => "author",
+        "workspace" => "keep",
+        "quarantine" => "fetch",
+        "queue" => "propose",
+        "derived" => "build",
+      }.freeze
+
+      ZONE_KINDS         = LANES.keys.freeze
+      CAPABILITIES       = LANES.values.freeze
+      KIND_REQUIRES_VERB = LANES
+      ENTRY_KEYS = %w[
         key path zone kind schema owner nested format
         compute template publish_to publish_each
         intake events inject_boot index_filename
       ].freeze
       COMPUTE_KEYS = %w[kind select pluck sort_by limit transform command sources].freeze
       INTAKE_KEYS  = %w[handler config].freeze
-      RULE_KEYS    = %w[match refresh intake_handler_allowlist promotion retention].freeze
-      REFRESH_KEYS = %w[ttl on_stale sync_budget_ms fetch_timeout_seconds].freeze
+      RULE_KEYS    = %w[match fetch intake_handler_allowlist guard retention].freeze
+      FETCH_KEYS = %w[ttl on_stale sync_budget_ms fetch_timeout_seconds].freeze
       FETCH_TIMEOUT_SECONDS_CEILING = 3600
-      PROMOTION_KEYS = %w[requires].freeze
-      AUDIT_KEYS     = %w[max_size keep].freeze
+      RETENTION_KEYS = %w[expire_after archive_after].freeze
+      AUDIT_KEYS = %w[max_size keep].freeze
 
       def self.validate!(raw)
         raise BadManifest.new("manifest must be a hash") unless raw.is_a?(Hash)
@@ -27,12 +44,21 @@ module Textus
         validate_entries!(raw["entries"])
         validate_rules!(raw["rules"])
         walk(raw["audit"], AUDIT_KEYS, "$.audit") if raw["audit"].is_a?(Hash)
-        validate_zone_writers_declared!(raw)
+        validate_single_queue!(raw)
+        validate_zone_kind_consistency!(raw)
       end
 
       def self.validate_zones!(zones)
         Array(zones).each_with_index do |z, i|
           walk(z, ZONE_KEYS, "$.zones[#{i}]")
+          if z["kind"].nil?
+            raise BadManifest.new("zone '#{z["name"]}' at '$.zones[#{i}]' must declare a kind (one of: #{ZONE_KINDS.join(", ")})")
+          end
+          next if ZONE_KINDS.include?(z["kind"])
+
+          raise BadManifest.new(
+            "unknown zone kind '#{z["kind"]}' at '$.zones[#{i}]' (known: #{ZONE_KINDS.join(", ")})",
+          )
         end
       end
 
@@ -49,27 +75,11 @@ module Textus
         Array(rules).each_with_index do |r, i|
           path = "$.rules[#{i}]"
           walk(r, RULE_KEYS, path)
-          if r["refresh"].is_a?(Hash)
-            walk(r["refresh"], REFRESH_KEYS, "#{path}.refresh")
-            validate_fetch_timeout!(r["refresh"]["fetch_timeout_seconds"], "#{path}.refresh.fetch_timeout_seconds")
-          end
-          walk(r["promotion"], PROMOTION_KEYS, "#{path}.promotion") if r["promotion"].is_a?(Hash)
-        end
-      end
-
-      def self.validate_zone_writers_declared!(raw)
-        return if raw["roles"].nil? # default mapping is permissive
-
-        declared = Array(raw["roles"]).map { |r| r["name"] }.compact.to_set
-        Array(raw["zones"]).each do |z|
-          Array(z["write_policy"]).each_with_index do |w, j|
-            next if declared.include?(w)
-
-            raise BadManifest.new(
-              "zone '#{z["name"]}' write_policy[#{j}] references undeclared role '#{w}' " \
-              "(declared roles: #{declared.to_a.join(", ")})",
-            )
+          if r["fetch"].is_a?(Hash)
+            walk(r["fetch"], FETCH_KEYS, "#{path}.fetch")
+            validate_fetch_timeout!(r["fetch"]["fetch_timeout_seconds"], "#{path}.fetch.fetch_timeout_seconds")
           end
+          walk(r["retention"], RETENTION_KEYS, "#{path}.retention") if r["retention"].is_a?(Hash)
         end
       end
 
@@ -77,23 +87,25 @@ module Textus
         return if roles.nil?
         raise BadManifest.new("roles: must be a list") unless roles.is_a?(Array)
 
-        accept_authority_count = 0
         roles.each_with_index do |r, i|
           path = "$.roles[#{i}]"
           walk(r, ROLE_KEYS, path)
           name = r["name"] or raise BadManifest.new("role at '#{path}' missing name")
-          kind = r["kind"] or raise BadManifest.new("role '#{name}' at '#{path}' missing kind")
-          unless ROLE_KINDS.include?(kind)
-            raise BadManifest.new("unknown role kind '#{kind}' at '#{path}' (known: #{ROLE_KINDS.join(", ")})")
-          end
+          Array(r["can"]).each do |verb|
+            next if CAPABILITIES.include?(verb)
 
-          accept_authority_count += 1 if kind == "accept_authority"
+            raise BadManifest.new(
+              "unknown capability '#{verb}' for role '#{name}' at '#{path}' " \
+              "(known: #{CAPABILITIES.join(", ")})",
+            )
+          end
         end
-        return unless accept_authority_count > 1
+
+        author_holders = roles.count { |r| Array(r["can"]).include?("author") }
+        return if author_holders <= 1
 
         raise BadManifest.new(
-          "manifest declares #{accept_authority_count} accept_authority roles; " \
-          "at most one accept_authority role is allowed",
+          "manifest declares #{author_holders} roles with the author capability; at most one is allowed",
         )
       end
 
@@ -115,6 +127,34 @@ module Textus
           raise BadManifest.new("unknown key '#{k}' at '#{path}'")
         end
       end
+
+      def self.validate_single_queue!(raw)
+        queues = Array(raw["zones"]).select { |z| z["kind"] == "queue" }.map { |z| z["name"] }
+        return if queues.size <= 1
+
+        raise BadManifest.new(
+          "at most one zone may declare kind: queue (found: #{queues.join(", ")})",
+        )
+      end
+
+      # Write authority is derived from capabilities (ADR 0030): a zone of a
+      # given kind can only be written by a role that holds the kind's required
+      # verb. Reject a manifest declaring a zone whose required verb is held by
+      # no role. Capabilities.resolve returns the defaults when `roles:` is nil,
+      # so the capability union is all four verbs and every kind is satisfied.
+      def self.validate_zone_kind_consistency!(raw)
+        held = Capabilities.resolve(raw["roles"]).values.flatten.uniq
+
+        Array(raw["zones"]).each_with_index do |z, i|
+          verb = KIND_REQUIRES_VERB[z["kind"]]
+          next if verb.nil? || held.include?(verb)
+
+          raise BadManifest.new(
+            "zone '#{z["name"]}' (#{z["kind"]}) at '$.zones[#{i}]' " \
+            "needs a role with capability '#{verb}'; none declared",
+          )
+        end
+      end
     end
   end
 end

data/lib/textus/manifest.rb

@@ -4,12 +4,13 @@ module Textus
   # Manifest is the composition record for a parsed manifest. It bundles
   # four collaborators:
   #
-  #   * data     — frozen value: raw, root, zones, entries, audit_config, role_mapping
+  #   * data     — frozen value: raw, root, zones, entries, audit_config, role_caps
   #   * resolver — resolves keys → entry + path
-  #   * policy   — zone/role authority (zone_writers, zone_kinds, permission_for, …)
-  #   * rules    — match-block rule engine (refresh, handler allowlist, promotion, …)
+  #   * policy   — zone/role authority (zone_writers, declared_kind/derived_zone?/
+  #     queue_zone?, permission_for, …)
+  #   * rules    — match-block rule engine (fetch, handler allowlist, promotion, …)
   #
-  # Use `manifest.data.entries`, `manifest.policy.zone_kinds(z)`, etc.
+  # Use `manifest.data.entries`, `manifest.policy.declared_kind(z)`, etc.
   Manifest = Data.define(:data, :resolver, :policy, :rules)
 end
 
@@ -17,7 +18,7 @@ require_relative "manifest/schema"
 require_relative "manifest/data"
 require_relative "manifest/policy"
 require_relative "manifest/resolver"
-require_relative "manifest/role_kinds"
+require_relative "manifest/capabilities"
 
 # Reopen Textus::Manifest (defined above as a Data.define) to attach
 # class-level loaders and helpers.

data/lib/textus/mcp/server.rb

@@ -49,16 +49,8 @@ module Textus
       end
 
       def handle_initialize(rid, _params)
-        proposer = @store.manifest.policy.roles_with_kind(:proposer).first
-        propose_zone = nil
-        if proposer
-          @store.manifest.data.zones.each do |zname, writers|
-            if writers.include?(proposer) && zname.include?("review")
-              propose_zone = zname
-              break
-            end
-          end
-        end
+        proposer = @store.manifest.policy.proposer_role
+        propose_zone = @store.manifest.policy.propose_zone_for(proposer)
 
         @session = Session.new(
           role: @role,

data/lib/textus/mcp/session.rb

@@ -1,29 +1,15 @@
 module Textus
   module MCP
-    # Per-connection state held by the server. Immutable; advance_cursor
-    # returns a new instance.
-    class Session
-      attr_reader :role, :cursor, :propose_zone, :manifest_etag
-
-      def initialize(role:, cursor:, propose_zone:, manifest_etag:)
-        @role = role
-        @cursor = cursor
-        @propose_zone = propose_zone
-        @manifest_etag = manifest_etag
-      end
-
-      def advance_cursor(new_cursor)
-        self.class.new(
-          role: @role, cursor: new_cursor,
-          propose_zone: @propose_zone, manifest_etag: @manifest_etag
-        )
-      end
+    # Per-connection state held by the server. Immutable Data value;
+    # advance_cursor returns a new instance via #with.
+    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
+        return if observed_etag == manifest_etag
 
         raise ContractDrift.new(
-          "manifest changed (was #{short_etag(@manifest_etag)}, now #{short_etag(observed_etag)}); re-run boot",
+          "manifest changed (was #{short_etag(manifest_etag)}, now #{short_etag(observed_etag)}); re-run boot",
         )
       end
 
@@ -32,9 +18,7 @@ module Textus
       # 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
+      def short_etag(etag) = etag.to_s.delete_prefix("sha256:")[0, 8]
     end
   end
 end

data/lib/textus/mcp/tool_schemas.rb

@@ -29,16 +29,16 @@ module Textus
                  "meta" => { "type" => "object" },
                  "body" => { "type" => "string" },
                }, %w[key meta]),
-          tool("refresh", "Run an intake refresh for one key. Returns the refresh Outcome.",
+          tool("fetch", "Run an intake fetch for one key. Returns the fetch Outcome.",
                { "key" => { "type" => "string" } }, ["key"]),
-          tool("refresh_stale", "Refresh all stale intake entries, optionally scoped by zone/prefix.",
+          tool("fetch_stale", "Fetch all stale intake entries, optionally scoped by zone/prefix.",
                {
                  "zone" => { "type" => "string" },
                  "prefix" => { "type" => "string" },
                }, []),
           tool("schema", "Return the schema (field shape) for an entry family.",
                { "family" => { "type" => "string" } }, ["family"]),
-          tool("rules", "Return effective rules for a key (refresh, promote, ...).",
+          tool("rules", "Return effective rules for a key (fetch, promote, ...).",
                { "key" => { "type" => "string" } }, ["key"]),
           tool("key_mv_prefix",
                "Bulk-rename every leaf key under from_prefix to to_prefix. Dry-run returns a Plan; apply with dry_run: false.",

data/lib/textus/mcp/tools.rb

@@ -64,14 +64,14 @@ module Textus
           { "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)
+        "fetch" => lambda do |s, store, args|
+          key = args.fetch("key") { raise ToolError.new("fetch: missing key") }
+          outcome = ops_for(s, store).fetch(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"])
+        "fetch_stale" => lambda do |s, store, args|
+          ops_for(s, store).fetch_all(zone: args["zone"], prefix: args["prefix"])
         end,
 
         "schema" => lambda do |_s, store, args|
@@ -83,8 +83,8 @@ module Textus
           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,
+            "fetch" => set.fetch&.to_h,
+            "guard" => set.guard,
           }.compact
         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/{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,7 +2,7 @@ require "fileutils"
 
 module Textus
   module Ports
-    module Refresh
+    module Fetch
       class Lock
         def initialize(root:, key:)
           @root = root