textus 0.30.0 → 0.35.1

data/lib/textus/errors.rb

@@ -90,39 +90,21 @@ module Textus
   end
 
   class WriteForbidden < Error
-    def initialize(k, z, writers: nil)
-      writers_str =
-        if writers && !writers.empty?
-          writers.join(", ")
+    def initialize(k, z, verb: nil, holders: nil)
+      holders_str =
+        if holders && !holders.empty?
+          holders.join(", ")
         else
-          "the role(s) listed in the manifest 'write_policy:'"
+          "no declared role"
         end
       details = { "key" => k, "zone" => z }
-      details["writers"] = writers if writers
+      details["verb"] = verb if verb
+      details["holders"] = holders if holders
       super(
         "write_forbidden",
-        "zone '#{z}' is not agent-writable for key '#{k}'",
+        "writing '#{k}' (zone '#{z}') needs capability '#{verb}'",
         details: details,
-        hint: "this zone is writable by #{writers_str}; pass --as=<role>",
-      )
-    end
-  end
-
-  class ReadForbidden < Error
-    def initialize(k, z, readers: nil)
-      readers_str =
-        if readers && !readers.empty?
-          readers.join(", ")
-        else
-          "the role(s) listed in the manifest 'read_policy:'"
-        end
-      details = { "key" => k, "zone" => z }
-      details["readers"] = readers if readers
-      super(
-        "read_forbidden",
-        "zone '#{z}' is not readable by role for key '#{k}'",
-        details: details,
-        hint: "this zone is readable by #{readers_str}; pass --as=<role>",
+        hint: "held by: #{holders_str}; pass --as=<role>",
       )
     end
   end
@@ -163,7 +145,7 @@ module Textus
         "invalid_role",
         message || "role '#{r}' is not declared in any zone",
         details: { "role" => r },
-        hint: message ? nil : "valid roles are declared in .textus/manifest.yaml under zones[].write_policy",
+        hint: message ? nil : "valid roles are declared in .textus/manifest.yaml under roles: (each with a can: list)",
       )
     end
   end
@@ -204,6 +186,21 @@ module Textus
     def initialize(m) = super("proposal_error", m)
   end
 
+  class GuardFailed < Error
+    def initialize(failed)
+      # failed: [[predicate_name, reason], ...]
+      rows = failed.map { |name, reason| { "predicate" => name, "reason" => reason } }
+      names = failed.map(&:first)
+      super(
+        "guard_failed",
+        "guard refused crossing: #{failed.map { |n, r| "#{n} (#{r})" }.join("; ")}",
+        details: { "failed" => rows },
+        hint: "run 'textus policy explain <key> --output=json' to see the full guard; " \
+              "unmet: #{names.join(", ")}",
+      )
+    end
+  end
+
   class FlagRenamed < Error
     def initialize(old_flag, new_flag)
       super(

data/lib/textus/hooks/event_bus.rb

@@ -10,16 +10,16 @@ module Textus
       EVENTS = {
         entry_put: %i[ctx key envelope],
         entry_deleted: %i[ctx key],
-        entry_refreshed: %i[ctx key envelope change],
+        entry_fetched: %i[ctx key envelope change],
         entry_renamed: %i[ctx key from_key to_key envelope],
         build_completed: %i[ctx key envelope sources],
         proposal_accepted: %i[ctx key target_key],
         proposal_rejected: %i[ctx key target_key],
         file_published: %i[ctx key envelope source target],
         store_loaded: %i[ctx],
-        refresh_started: %i[ctx key mode],
-        refresh_failed: %i[ctx key error_class error_message],
-        refresh_backgrounded: %i[ctx key started_at budget_ms],
+        fetch_started: %i[ctx key mode],
+        fetch_failed: %i[ctx key error_class error_message],
+        fetch_backgrounded: %i[ctx key started_at budget_ms],
       }.freeze
 
       RPC_EVENTS = %i[resolve_intake transform_rows validate].freeze

data/lib/textus/init.rb

@@ -2,20 +2,25 @@ require "fileutils"
 
 module Textus
   module Init
-    ZONES = %w[identity working intake review output].freeze
+    ZONES = %w[knowledge notebook feeds proposals artifacts].freeze
 
     DEFAULT_MANIFEST = <<~YAML
       version: textus/3
+      roles:
+        - { name: human,      can: [author, propose] }
+        - { name: agent,      can: [propose, keep] }
+        - { name: automation, can: [fetch, build] }
       zones:
-        - { name: identity, kind: origin,     write_policy: [human],          read_policy: [all] }
-        - { name: working,  kind: origin,     write_policy: [human],          read_policy: [all] }
-        - { name: intake,   kind: quarantine, write_policy: [runner],         read_policy: [all] }
-        - { name: review,   kind: queue,      write_policy: [agent, human],   read_policy: [all] }
-        - { name: output,   kind: derived,    write_policy: [builder],        read_policy: [all] }
+        - { name: knowledge, kind: canon,     desc: "the maintained source of truth (identity.* lives here)" }
+        - { name: notebook,  kind: workspace, owner: agent, desc: "the agent's own durable working notes" }
+        - { name: feeds,     kind: quarantine, desc: "external inputs pulled in" }
+        - { name: proposals, kind: queue,     desc: "changes awaiting your accept" }
+        - { name: artifacts, kind: derived,   desc: "computed, shippable outputs" }
       entries:
-        - { key: identity.self, path: identity/self.md, zone: identity, schema: null, owner: human:self, kind: leaf }
-        - { key: working.notes, path: working/notes,    zone: working,  schema: null, owner: human:self, nested: true, kind: nested }
-        - { key: review.notes,  path: review/notes,     zone: review,   schema: null, owner: agent:self, nested: true, kind: nested }
+        - { key: knowledge.identity, path: knowledge/identity.md, zone: knowledge, schema: null, owner: human:self, kind: leaf }
+        - { key: knowledge.notes,    path: knowledge/notes,       zone: knowledge, schema: null, owner: human:self, nested: true, kind: nested }
+        - { key: notebook.notes,     path: notebook/notes,        zone: notebook,  schema: null, owner: agent:self, nested: true, kind: nested }
+        - { key: proposals.notes,    path: proposals/notes,       zone: proposals, schema: null, owner: agent:self, nested: true, kind: nested }
     YAML
 
     HOOKS_README = <<~MD
@@ -31,12 +36,12 @@ module Textus
       ```ruby
       Textus.hook do |reg|
         reg.on(:resolve_intake, :my_source) do |config:, args:, **|
-          { _meta: { "last_refreshed_at" => Time.now.utc.iso8601 }, body: "…" }
+          { _meta: { "last_fetched_at" => Time.now.utc.iso8601 }, body: "…" }
         end
 
         reg.on(:transform_rows, :my_source) { |rows:, **| rows.map { |r| r.merge(processed: true) } }
         reg.on(:validate,       :my_check)  { |caps:, **| [] }
-        reg.on(:entry_put,      :my_listener, keys: ["working.*"]) { |key:, envelope:, **| }
+        reg.on(:entry_put,      :my_listener, keys: ["knowledge.*"]) { |key:, envelope:, **| }
 
         # Run a side-effect every time textus writes a file to your repo:
         reg.on(:file_published, :notify) do |key:, target:, **|
@@ -51,25 +56,25 @@ module Textus
 
       ```yaml
       entries:
-        - key: intake.foo
+        - key: feeds.foo
           kind: intake
-          path: intake/foo.md
-          zone: intake
+          path: feeds/foo.md
+          zone: feeds
           intake:
             handler: my_source
 
       rules:
-        - match: intake.foo
-          refresh:
+        - match: feeds.foo
+          fetch:
             ttl: 10m
             on_stale: timed_sync   # warn | sync | timed_sync (default: warn)
       ```
 
       Events: :resolve_intake, :transform_rows, :validate (rpc — return value used)
-              :entry_put, :entry_deleted, :entry_refreshed, :entry_renamed,
+              :entry_put, :entry_deleted, :entry_fetched, :entry_renamed,
               :build_completed, :proposal_accepted, :proposal_rejected,
               :file_published, :store_loaded,
-              :refresh_started, :refresh_failed, :refresh_backgrounded (pub-sub — return discarded)
+              :fetch_started, :fetch_failed, :fetch_backgrounded (pub-sub — return discarded)
 
       See SPEC.md §5.10 for the full table.
     MD

data/lib/textus/maintenance/zone_mv.rb

@@ -15,7 +15,7 @@ module Textus
 
       def call(from:, to:, dry_run: false)
         raise UsageError.new("from and to required") if from.nil? || to.nil? || from.empty? || to.empty?
-        raise UsageError.new("zone '#{from}' not declared") unless @manifest.data.zones.key?(from)
+        raise UsageError.new("zone '#{from}' not declared") unless @manifest.data.declared_zone_kinds.key?(from)
 
         dest_dir = File.join(@root, "zones", to)
         raise UsageError.new("destination 'zones/#{to}' already exists") if File.exist?(dest_dir)

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,18 +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, :declared_zone_kinds,
-                  :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?
@@ -34,16 +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)]
-        end
+        # 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/policy.rb

@@ -2,28 +2,50 @@ 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, permission_for, role_kind, roles_with_kind). Derived /
+    # (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), not inferred
-    # from writers.
+    # (declared_kind, derived_zone?, queue_zone?, queue_zone).
     class Policy
       def initialize(data)
         @data = data
       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
+
+      # 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
 
-      def zone_readers
-        @data.zone_readers
+      # 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
 
@@ -32,6 +54,12 @@ module Textus
         @data.declared_zone_kinds[zone_name]
       end
 
+      # 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
+
       # The single zone declaring `kind: queue`, or nil. Schema guarantees <=1.
       def queue_zone
         @data.declared_zone_kinds.key(:queue)
@@ -47,18 +75,6 @@ module Textus
         declared_kind(zone_name) == :queue
       end
 
-      def role_mapping
-        @data.role_mapping
-      end
-
-      def role_kind(name)
-        @data.role_mapping[name]
-      end
-
-      def roles_with_kind(kind)
-        @data.role_mapping.each_with_object([]) { |(name, k), acc| acc << name if k == kind }
-      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.

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"])
+          @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,14 @@ 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")
-
-          Textus::Domain::Policy::Promote.new(requires: Array(h["requires"]))
+          h
         end
 
         def parse_retention(h)

data/lib/textus/manifest/schema.rb

@@ -2,15 +2,26 @@ 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 kind write_policy read_policy].freeze
-      ZONE_KINDS   = %w[origin quarantine queue derived].freeze
-      KIND_REQUIRES_ROLE_KIND = {
-        "derived" => "generator",
-        "queue" => "proposer",
-        "quarantine" => "runner",
+      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
@@ -18,11 +29,10 @@ module Textus
       ].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
-      RETENTION_KEYS  = %w[expire_after archive_after].freeze
+      RETENTION_KEYS = %w[expire_after archive_after].freeze
       AUDIT_KEYS = %w[max_size keep].freeze
 
       def self.validate!(raw)
@@ -34,7 +44,6 @@ 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
@@ -66,52 +75,37 @@ 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")
+          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["promotion"], PROMOTION_KEYS, "#{path}.promotion") if r["promotion"].is_a?(Hash)
           walk(r["retention"], RETENTION_KEYS, "#{path}.retention") if r["retention"].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(", ")})",
-            )
-          end
-        end
-      end
-
       def self.validate_roles!(roles)
         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
 
@@ -143,28 +137,24 @@ module Textus
         )
       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)
-        mapping = role_kind_mapping(raw)
-        Array(raw["zones"]).each do |z|
-          required = KIND_REQUIRES_ROLE_KIND[z["kind"]] or next
-          writers  = Array(z["write_policy"])
-          next if writers.any? { |w| mapping[w] == required }
+        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"]}' declares kind: #{z["kind"]} but no writer is a #{required} " \
-            "(writers: #{writers.join(", ")})",
+            "zone '#{z["name"]}' (#{z["kind"]}) at '$.zones[#{i}]' " \
+            "needs a role with capability '#{verb}'; none declared",
           )
         end
       end
-
-      # name => kind string, honouring an explicit roles: block or the default mapping.
-      def self.role_kind_mapping(raw)
-        if raw["roles"].nil?
-          RoleKinds::DEFAULT_MAPPING.transform_values(&:to_s)
-        else
-          Array(raw["roles"]).to_h { |r| [r["name"], r["kind"]] }
-        end
-      end
     end
   end
 end

data/lib/textus/manifest.rb

@@ -4,11 +4,11 @@ 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, declared_kind/derived_zone?/
   #     queue_zone?, permission_for, …)
-  #   * rules    — match-block rule engine (refresh, handler allowlist, promotion, …)
+  #   * rules    — match-block rule engine (fetch, handler allowlist, promotion, …)
   #
   # Use `manifest.data.entries`, `manifest.policy.declared_kind(z)`, etc.
   Manifest = Data.define(:data, :resolver, :policy, :rules)
@@ -18,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,7 +49,7 @@ module Textus
       end
 
       def handle_initialize(rid, _params)
-        proposer = @store.manifest.policy.roles_with_kind(:proposer).first
+        proposer = @store.manifest.policy.proposer_role
         propose_zone = @store.manifest.policy.propose_zone_for(proposer)
 
         @session = Session.new(