textus 0.18.0 → 0.20.2

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

@@ -0,0 +1,38 @@
+module Textus
+  class Manifest
+    class Entry
+      class Base < Entry
+        attr_reader :raw, :key, :path, :zone, :schema, :owner, :format, :manifest
+
+        # rubocop:disable Metrics/ParameterLists, Lint/MissingSuper
+        def initialize(manifest:, raw:, key:, path:, zone:, schema:, owner:, format:)
+          @manifest = manifest
+          @raw = raw
+          @key = key
+          @path = path
+          @zone = zone
+          @schema = schema
+          @owner = owner
+          @format = format
+        end
+        # rubocop:enable Metrics/ParameterLists, Lint/MissingSuper
+
+        def kind = self.class.name.split("::").last.downcase.to_sym
+
+        def zone_writers
+          @manifest.zone_writers(@zone)
+        rescue UsageError => e
+          raise UsageError.new("entry '#{@key}': #{e.message}")
+        end
+
+        def in_generator_zone? = @manifest.zone_kinds(@zone).include?(:generator)
+        def in_proposal_zone?  = @manifest.zone_kinds(@zone).include?(:proposer)
+
+        def nested?  = false
+        def derived? = false
+        def intake?  = false
+        def leaf?    = false
+      end
+    end
+  end
+end

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

@@ -0,0 +1,25 @@
+module Textus
+  class Manifest
+    class Entry
+      class Derived < Base
+        Projection = Data.define(:select, :pluck, :sort_by, :transform)
+        External   = Data.define(:sources, :runner)
+
+        attr_reader :source, :template, :inject_intro, :publish_to, :events
+
+        def initialize(source:, template: nil, inject_intro: false, publish_to: [], events: {}, **rest)
+          super(**rest)
+          @source = source
+          @template = template
+          @inject_intro = inject_intro
+          @publish_to = Array(publish_to)
+          @events = events || {}
+        end
+
+        def derived? = true
+        def projection? = @source.is_a?(Projection)
+        def external?   = @source.is_a?(External)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,19 @@
+module Textus
+  class Manifest
+    class Entry
+      class Intake < Base
+        attr_reader :handler, :config, :events, :publish_to
+
+        def initialize(handler:, config: {}, events: {}, **rest)
+          super(**rest)
+          @handler = handler
+          @config = config || {}
+          @events = events || {}
+          @publish_to = []
+        end
+
+        def intake? = true
+      end
+    end
+  end
+end

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

@@ -0,0 +1,16 @@
+module Textus
+  class Manifest
+    class Entry
+      class Leaf < Base
+        attr_reader :publish_to
+
+        def initialize(publish_to: [], **rest)
+          super(**rest)
+          @publish_to = Array(publish_to)
+        end
+
+        def leaf? = true
+      end
+    end
+  end
+end

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

@@ -0,0 +1,39 @@
+require_relative "validators/publish_each"
+
+module Textus
+  class Manifest
+    class Entry
+      class Nested < Base
+        PUBLISH_EACH_VARS   = Validators::PublishEach::KNOWN_VARS
+        PUBLISH_EACH_VAR_RE = Validators::PublishEach::VAR_RE
+
+        attr_reader :index_filename, :publish_each, :publish_to
+
+        def initialize(index_filename: nil, publish_each: nil, publish_to: [], **rest)
+          super(**rest)
+          @index_filename = index_filename
+          @publish_each = publish_each
+          @publish_to = Array(publish_to)
+        end
+
+        def nested? = true
+
+        def publish_target_for(full_key)
+          return nil if @publish_each.nil?
+
+          entry_segs = @key.split(".")
+          key_segs = full_key.split(".")
+          raise UsageError.new("key '#{full_key}' is not under entry '#{@key}'") unless key_segs[0, entry_segs.length] == entry_segs
+
+          remaining = key_segs[entry_segs.length..] || []
+          leaf = remaining.join("/")
+          basename = remaining.last || ""
+          ext = Textus::Entry.for_format(@format).extensions.first.to_s.sub(/^\./, "")
+
+          vars = { "leaf" => leaf, "basename" => basename, "key" => full_key, "ext" => ext }
+          @publish_each.gsub(PUBLISH_EACH_VAR_RE) { vars.fetch(::Regexp.last_match(1)) }
+        end
+      end
+    end
+  end
+end

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

@@ -9,61 +9,88 @@ module Textus
           path = raw["path"] or raise UsageError.new("manifest entry '#{key}' missing path")
           zone = raw["zone"] or raise UsageError.new("manifest entry '#{key}' missing zone")
 
-          nested = raw["nested"] == true
-          compute, projection, generator = parse_compute(raw, key)
-          intake_handler, intake_config = parse_intake(raw["intake"])
-          format = resolve_format(raw, path, nested)
+          raw_kind = raw["kind"] or raise BadManifest.new("entry '#{key}' missing required `kind:` (leaf|nested|derived|intake)")
+          kind = raw_kind.to_sym
+          format = resolve_format(raw, path)
 
-          Textus::Manifest::Entry.new(
+          common = {
             manifest: manifest, raw: raw,
             key: key, path: path, zone: zone,
             schema: raw["schema"], owner: raw["owner"],
-            nested: nested,
-            template: raw["template"],
-            publish_to: Array(raw["publish_to"]),
+            format: format
+          }
+
+          case kind
+          when :leaf    then build_leaf(common, raw)
+          when :nested  then build_nested(common, raw)
+          when :derived then build_derived(common, raw, key)
+          when :intake  then build_intake(common, raw, key)
+          else raise BadManifest.new("entry '#{key}': unknown kind: #{kind.inspect}")
+          end
+        end
+
+        def self.build_leaf(common, raw)
+          Leaf.new(publish_to: raw["publish_to"], **common)
+        end
+
+        def self.build_nested(common, raw)
+          Nested.new(
+            index_filename: raw["index_filename"],
             publish_each: raw["publish_each"],
-            events: raw["events"] || {},
+            publish_to: raw["publish_to"],
+            **common,
+          )
+        end
+
+        def self.build_derived(common, raw, key)
+          source = parse_source(raw, key)
+          Derived.new(
+            source: source,
+            template: raw["template"],
             inject_intro: raw["inject_intro"] == true,
-            index_filename: raw["index_filename"],
-            format: format,
-            compute: compute, projection: projection, generator: generator,
-            intake_handler: intake_handler, intake_config: intake_config
+            publish_to: raw["publish_to"],
+            events: raw["events"] || {},
+            **common,
           )
         end
 
-        def self.parse_compute(raw, key)
-          src = raw["compute"]
-          return [nil, nil, nil] if src.nil?
+        def self.build_intake(common, raw, key)
+          intake = raw["intake"] || {}
+          handler = intake["handler"] || raw["intake_handler"] or
+            raise UsageError.new("intake entry '#{key}' missing handler")
+          config = intake["config"] || raw["intake_config"] || {}
+          Intake.new(handler: handler, config: config, events: raw["events"] || {}, **common)
+        end
+
+        def self.parse_source(raw, key)
+          compute = raw["compute"]
+          raise BadManifest.new("derived entry '#{key}' requires compute: { kind: projection|external } or template:") if compute.nil?
 
-          kind = src["kind"]
-          unless COMPUTE_KINDS.include?(kind)
+          unless COMPUTE_KINDS.include?(compute["kind"])
             raise BadManifest.new(
-              "entry '#{key}': compute.kind must be one of #{COMPUTE_KINDS.join(", ")} (got #{kind.inspect})",
+              "entry '#{key}': compute.kind must be one of #{COMPUTE_KINDS.join(", ")} (got #{compute["kind"].inspect})",
             )
           end
 
-          frozen = src.freeze
-          if kind == "projection"
-            [frozen, frozen, nil]
+          if compute["kind"] == "projection"
+            Derived::Projection.new(
+              select: compute["select"],
+              pluck: compute["pluck"],
+              sort_by: compute["sort_by"],
+              transform: compute["transform"],
+            )
           else
-            [frozen, nil, frozen]
+            Derived::External.new(sources: compute["sources"], runner: compute["runner"])
           end
         end
 
-        def self.parse_intake(src)
-          src ||= {}
-          [src["handler"], src["config"] || {}]
-        end
-
-        def self.resolve_format(raw, path, nested)
+        def self.resolve_format(raw, path)
           declared = raw["format"]
           ext = File.extname(path)
           inferred = Textus::Entry.infer_from_extension(ext)
 
           if declared.nil?
             return inferred if inferred
-            return "markdown" if ext == "" && nested
-            return "markdown" if ext == ""
 
             return "markdown"
           end

data/lib/textus/manifest/entry/validators/events.rb

@@ -4,8 +4,9 @@ module Textus
       module Validators
         module Events
           def self.call(entry)
-            pubsub_events = Textus::Hooks::Registry::EVENTS.select { |_, s| s[:mode] == :pubsub }.keys
-            entry.events.each_key do |evt|
+            pubsub_events = Textus::Hooks::Bus::EVENTS.select { |_, s| s[:mode] == :pubsub }.keys
+            events = entry.respond_to?(:events) ? entry.events : {}
+            events.each_key do |evt|
               next if pubsub_events.include?(evt.to_sym)
 
               raise UsageError.new(

data/lib/textus/manifest/entry/validators/format_matrix.rb

@@ -5,7 +5,7 @@ module Textus
         module FormatMatrix
           def self.call(entry)
             begin
-              Textus::Entry.for_format(entry.format).validate_path_extension(entry.path, entry.nested)
+              Textus::Entry.for_format(entry.format).validate_path_extension(entry.path, entry.nested?)
             rescue UsageError => e
               raise UsageError.new("entry '#{entry.key}': #{e.message}")
             end
@@ -14,8 +14,10 @@ module Textus
               raise UsageError.new("entry '#{entry.key}': text format must not declare a schema")
             end
 
-            return unless entry.in_generator_zone? && entry.template.nil? && entry.generator.nil? &&
-                          %w[markdown text].include?(entry.format) && !entry.nested
+            has_template = entry.respond_to?(:template) && !entry.template.nil?
+            is_external   = entry.derived? && entry.external?
+            return unless entry.in_generator_zone? && !has_template && !is_external &&
+                          %w[markdown text].include?(entry.format) && !entry.nested?
 
             raise UsageError.new("entry '#{entry.key}': derived #{entry.format} entries require a template")
           end

data/lib/textus/manifest/entry/validators/index_filename.rb

@@ -4,31 +4,32 @@ module Textus
       module Validators
         module IndexFilename
           def self.call(entry)
-            return if entry.index_filename.nil?
+            index_filename = entry.respond_to?(:index_filename) ? entry.index_filename : entry.raw["index_filename"]
+            return if index_filename.nil?
 
-            check_shape!(entry)
-            check_extension!(entry)
+            check_shape!(entry, index_filename)
+            check_extension!(entry, index_filename)
           end
 
-          def self.check_shape!(entry)
-            raise UsageError.new("entry '#{entry.key}': index_filename requires nested: true") unless entry.nested
+          def self.check_shape!(entry, index_filename)
+            raise UsageError.new("entry '#{entry.key}': index_filename requires nested: true") unless entry.nested?
 
-            unless entry.index_filename.is_a?(String) && !entry.index_filename.empty?
+            unless index_filename.is_a?(String) && !index_filename.empty?
               raise UsageError.new("entry '#{entry.key}': index_filename must be a non-empty string")
             end
 
-            return unless entry.index_filename.include?("/") || File.basename(entry.index_filename) != entry.index_filename
+            return unless index_filename.include?("/") || File.basename(index_filename) != index_filename
 
             raise UsageError.new("entry '#{entry.key}': index_filename must be a bare basename (no slashes)")
           end
 
-          def self.check_extension!(entry)
-            ext = File.extname(entry.index_filename)
+          def self.check_extension!(entry, index_filename)
+            ext = File.extname(index_filename)
             inferred = Textus::Entry.infer_from_extension(ext)
 
             if inferred.nil?
               raise UsageError.new(
-                "entry '#{entry.key}': index_filename #{entry.index_filename.inspect} has unknown extension #{ext.inspect}",
+                "entry '#{entry.key}': index_filename #{index_filename.inspect} has unknown extension #{ext.inspect}",
               )
             end
             return if inferred == entry.format

data/lib/textus/manifest/entry/validators/inject_intro.rb

@@ -4,10 +4,13 @@ module Textus
       module Validators
         module InjectIntro
           def self.call(entry)
-            return unless entry.inject_intro
+            inject_intro = entry.respond_to?(:inject_intro) ? entry.inject_intro : false
+            return unless inject_intro
 
             raise UsageError.new("entry '#{entry.key}': inject_intro: is only valid on derived entries") unless entry.in_generator_zone?
-            return unless entry.template.nil?
+
+            has_template = entry.respond_to?(:template) && !entry.template.nil?
+            return if has_template
 
             raise UsageError.new("entry '#{entry.key}': inject_intro: requires a template:")
           end

data/lib/textus/manifest/entry/validators/publish_each.rb

@@ -7,14 +7,17 @@ module Textus
           VAR_RE = /\{([a-z]+)\}/
           REQUIRED_DISCRIMINATOR_VARS = %w[leaf basename key].freeze
 
-          def self.call(entry)
-            return if entry.publish_each.nil?
+          def self.call(entry) # rubocop:disable Metrics/AbcSize
+            publish_each = entry.respond_to?(:publish_each) ? entry.publish_each : entry.raw["publish_each"]
+            return if publish_each.nil?
 
-            raise UsageError.new("entry '#{entry.key}': publish_each requires nested: true") unless entry.nested
-            raise UsageError.new("entry '#{entry.key}': publish_to and publish_each are mutually exclusive") unless entry.publish_to.empty?
-            raise UsageError.new("entry '#{entry.key}': publish_each must be a string") unless entry.publish_each.is_a?(String)
+            raise UsageError.new("entry '#{entry.key}': publish_each requires nested: true") unless entry.nested?
 
-            used_vars = entry.publish_each.scan(VAR_RE).flatten
+            publish_to = entry.respond_to?(:publish_to) ? entry.publish_to : Array(entry.raw["publish_to"])
+            raise UsageError.new("entry '#{entry.key}': publish_to and publish_each are mutually exclusive") unless publish_to.empty?
+            raise UsageError.new("entry '#{entry.key}': publish_each must be a string") unless publish_each.is_a?(String)
+
+            used_vars = publish_each.scan(VAR_RE).flatten
             unknown = used_vars - KNOWN_VARS
             unless unknown.empty?
               raise UsageError.new(

data/lib/textus/manifest/entry.rb

@@ -5,78 +5,6 @@ module Textus
       # constants on Entry. Canonical source is the PublishEach validator.
       PUBLISH_EACH_VARS = Validators::PublishEach::KNOWN_VARS
       PUBLISH_EACH_VAR_RE = Validators::PublishEach::VAR_RE
-
-      attr_reader :raw, :key, :path, :zone, :schema, :owner, :nested,
-                  :template, :publish_to, :publish_each,
-                  :events, :inject_intro, :index_filename, :format,
-                  :compute, :projection, :generator,
-                  :intake_handler, :intake_config
-
-      # rubocop:disable Metrics/ParameterLists
-      def initialize(manifest:, raw:, key:, path:, zone:, schema:, owner:, nested:,
-                     template:, publish_to:, publish_each:, events:, inject_intro:,
-                     index_filename:, format:, compute:, projection:, generator:,
-                     intake_handler:, intake_config:)
-        @manifest = manifest
-        @raw = raw
-        @key = key
-        @path = path
-        @zone = zone
-        @schema = schema
-        @owner = owner
-        @nested = nested
-        @template = template
-        @publish_to = publish_to
-        @publish_each = publish_each
-        @events = events
-        @inject_intro = inject_intro
-        @index_filename = index_filename
-        @format = format
-        @compute = compute
-        @projection = projection
-        @generator = generator
-        @intake_handler = intake_handler
-        @intake_config = intake_config
-      end
-      # rubocop:enable Metrics/ParameterLists
-
-      # Resolves the per-leaf target path (relative to repo root) for a full
-      # dotted key under this entry's prefix. Returns nil if this entry has no
-      # publish_each template.
-      def publish_target_for(full_key)
-        return nil if @publish_each.nil?
-
-        entry_segs = @key.split(".")
-        key_segs = full_key.split(".")
-        raise UsageError.new("key '#{full_key}' is not under entry '#{@key}'") unless key_segs[0, entry_segs.length] == entry_segs
-
-        remaining = key_segs[entry_segs.length..] || []
-        leaf = remaining.join("/")
-        basename = remaining.last || ""
-        ext = Textus::Entry.for_format(@format).extensions.first.to_s.sub(/^\./, "")
-
-        vars = { "leaf" => leaf, "basename" => basename, "key" => full_key, "ext" => ext }
-        @publish_each.gsub(PUBLISH_EACH_VAR_RE) { vars.fetch(::Regexp.last_match(1)) }
-      end
-
-      # Signal-based zone-kind predicates: derive the "kind" of a zone from its
-      # write_policy signals rather than its literal name, so detection keeps
-      # working when users rename the default zones.
-      def in_generator_zone?
-        zone_writers.include?("builder")
-      end
-
-      def in_proposal_zone?
-        zone_writers.include?("agent")
-      end
-
-      private
-
-      def zone_writers
-        @manifest.zone_writers(@zone)
-      rescue UsageError => e
-        raise UsageError.new("entry '#{@key}': #{e.message}")
-      end
     end
   end
 end

data/lib/textus/manifest/resolver.rb

@@ -0,0 +1,112 @@
+module Textus
+  class Manifest
+    class Resolver
+      Resolution = Data.define(:entry, :path, :remaining)
+
+      def initialize(manifest)
+        @manifest = manifest
+      end
+
+      def resolve(key)
+        @manifest.validate_key!(key)
+        segments = key.split(".")
+        candidates = @manifest.entries
+                              .map { |e| [e, e.key.split(".")] }
+                              .select { |(_, esegs)| esegs == segments[0, esegs.length] }
+                              .sort_by { |(_, esegs)| -esegs.length }
+        raise UnknownKey.new(key, suggestions: suggestions_for(key)) if candidates.empty?
+
+        entry, esegs = candidates.first
+        remaining = segments[esegs.length..]
+        build_resolution(entry, remaining, key)
+      end
+
+      def suggestions_for(key)
+        candidates = enumerate.map { |r| r[:key] }
+        candidates.concat(@manifest.entries.reject { |e| nested_entry?(e) }.map(&:key))
+        candidates.uniq!
+        Key::Distance.suggest(key, candidates, limit: 5)
+      rescue StandardError
+        []
+      end
+
+      def enumerate(prefix: nil)
+        out = @manifest.entries.flat_map { |entry| nested_entry?(entry) ? enumerate_nested(entry) : enumerate_leaf(entry) }
+        out.select! { |row| row[:key] == prefix || row[:key].start_with?("#{prefix}.") } if prefix
+        out.sort_by { |row| row[:key] }
+      end
+
+      private
+
+      # Returns true for entries that behave as nested (Nested subclass, or any
+      # entry with nested: true in the raw YAML — e.g. Intake entries covering
+      # a directory of leaf files).
+      def nested_entry?(entry)
+        entry.is_a?(Textus::Manifest::Entry::Nested) || entry.raw["nested"] == true
+      end
+
+      def build_resolution(entry, remaining, key)
+        if remaining.empty?
+          Resolution.new(entry: entry, path: resolve_leaf_path(entry), remaining: [])
+        else
+          raise UnknownKey.new(key, suggestions: suggestions_for(key)) unless nested_entry?(entry)
+
+          index_fn = entry.respond_to?(:index_filename) ? entry.index_filename : nil
+          path = if index_fn
+                   File.join(@manifest.root, "zones", entry.path, *remaining, index_fn)
+                 else
+                   primary_ext = Textus::Entry.for_format(entry.format).extensions.first
+                   File.join(@manifest.root, "zones", entry.path, *remaining) + primary_ext
+                 end
+          Resolution.new(entry: entry, path: path, remaining: remaining)
+        end
+      end
+
+      def enumerate_leaf(entry)
+        fp = resolve_leaf_path(entry)
+        File.exist?(fp) ? [{ key: entry.key, path: fp, manifest_entry: entry }] : []
+      end
+
+      def enumerate_nested(entry)
+        base = File.join(@manifest.root, "zones", entry.path)
+        return [] unless File.directory?(base)
+
+        entry_index_filename = entry.respond_to?(:index_filename) ? entry.index_filename : nil
+        glob_pattern = entry_index_filename ? "**/#{entry_index_filename}" : nested_glob(entry.format)
+        Dir.glob(File.join(base, glob_pattern)).filter_map { |path| nested_row_for(entry, base, path) }
+      end
+
+      def nested_row_for(entry, base, path)
+        rel = path.sub(%r{\A#{Regexp.escape(base)}/?}, "")
+        entry_if = entry.respond_to?(:index_filename) ? entry.index_filename : nil
+        stripped = entry_if ? File.dirname(rel) : rel.sub(/#{Regexp.escape(File.extname(rel))}\z/, "")
+        segs = stripped.split("/").reject { |s| s.empty? || s == "." }
+        return nil if segs.empty?
+
+        illegal = segs.find { |s| !valid_segment?(s) }
+        if illegal
+          warn("textus: skipping illegal key segment '#{illegal}' at #{path} — " \
+               "rename to match [a-z0-9][a-z0-9-]* (run 'textus doctor' for the full list)")
+          return nil
+        end
+
+        { key: (entry.key.split(".") + segs).join("."), path: path, manifest_entry: entry }
+      end
+
+      def valid_segment?(seg)
+        return false if seg.nil? || seg.empty?
+        return false if seg.length > Key::Grammar::MAX_SEGMENT_LEN
+
+        seg.match?(Key::Grammar::SEGMENT)
+      end
+
+      def resolve_leaf_path(entry)
+        Textus::Key::Path.resolve(@manifest, entry)
+      end
+
+      def nested_glob(format)
+        Textus::Entry.for_format(format).nested_glob
+      end
+    end
+  end
+end

data/lib/textus/manifest/role_kinds.rb

@@ -0,0 +1,21 @@
+module Textus
+  class Manifest
+    module RoleKinds
+      DEFAULT_MAPPING = {
+        "human" => :accept_authority,
+        "agent" => :proposer,
+        "builder" => :generator,
+        "runner" => :runner,
+      }.freeze
+
+      # Returns { role_name => kind_symbol }. 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"], r["kind"].to_sym] }.freeze
+      end
+    end
+  end
+end

data/lib/textus/manifest/schema.rb

@@ -1,10 +1,12 @@
 module Textus
   class Manifest
     module Schema
-      ROOT_KEYS    = %w[version zones entries rules].freeze
+      ROOT_KEYS    = %w[version roles zones entries rules].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[
-        key path zone schema owner nested format
+        key path zone kind schema owner nested format
         compute template publish_to publish_each
         intake events inject_intro index_filename
       ].freeze
@@ -19,6 +21,7 @@ module Textus
         raise BadManifest.new("manifest must be a hash") unless raw.is_a?(Hash)
 
         walk(raw, ROOT_KEYS, "$")
+        validate_roles!(raw["roles"])
         Array(raw["zones"]).each_with_index do |z, i|
           walk(z, ZONE_KEYS, "$.zones[#{i}]")
         end
@@ -37,6 +40,47 @@ module Textus
           end
           walk(r["promotion"], PROMOTION_KEYS, "#{path}.promotion") if r["promotion"].is_a?(Hash)
         end
+        validate_zone_writers_declared!(raw)
+      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
+
+          accept_authority_count += 1 if kind == "accept_authority"
+        end
+        return unless accept_authority_count > 1
+
+        raise BadManifest.new(
+          "manifest declares #{accept_authority_count} accept_authority roles; " \
+          "at most one accept_authority role is allowed",
+        )
       end
 
       def self.validate_fetch_timeout!(value, path)