textus 0.30.0 → 0.38.0

data/lib/textus/domain/policy/predicates/fresh_within.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Textus
+  module Domain
+    module Policy
+      module Predicates
+        # Parameterized predicate: the entry must have been written within
+        # `duration` of now. Duration strings ("1h", "30m", "7d") parse via
+        # Domain::Duration.seconds. Passes when no envelope exists yet.
+        class FreshWithin
+          attr_reader :reason
+
+          def initialize(duration:, now: nil)
+            @seconds = Textus::Domain::Duration.seconds(duration)
+            @now = now
+          end
+
+          def name = "fresh_within"
+
+          def call(eval)
+            return true if eval.envelope.nil? || @seconds.nil?
+
+            written = written_at(eval.envelope)
+            return true if written.nil?
+
+            now = @now || Textus::Ports::Clock.now
+            return true if now - written <= @seconds
+
+            @reason = "entry older than #{@seconds}s (written #{written.iso8601})"
+            false
+          end
+
+          private
+
+          # Domain-pure: reads the stored write timestamp from the envelope's
+          # freshness (checked_at) or meta (last_fetched_at/generated_at) and
+          # parses the stored ISO-8601 string. Parsing a stored string is not
+          # I/O (allowed in domain, ADR 0024).
+          def written_at(envelope)
+            raw = envelope.freshness&.checked_at ||
+                  envelope.meta&.dig("last_fetched_at") ||
+                  envelope.meta&.dig("generated_at")
+            return raw if raw.is_a?(Time)
+            return nil if raw.nil?
+
+            begin
+              Time.parse(raw.to_s)
+            rescue StandardError
+              nil
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/textus/domain/policy/predicates/registry.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Textus
+  module Domain
+    module Policy
+      module Predicates
+        # The single source of truth for the predicate vocabulary
+        # (ADR 0031 §3). Replaces both Promote::KNOWN and Promotion::REGISTRY.
+        # Each entry is name => ->(params:, schemas:) { predicate }.
+        module Registry
+          ENTRIES = {
+            "zone_writable_by" => ->(**) { ZoneWritableBy.new },
+            "author_held" => ->(**) { AuthorHeld.new },
+            "target_is_canon" => ->(**) { TargetIsCanon.new },
+            "schema_valid" => ->(schemas:, **) { SchemaValid.new(schemas: schemas) },
+            "etag_match" => ->(params:, **) { EtagMatch.new(if_etag: params) },
+            "fresh_within" => ->(params:, **) { FreshWithin.new(duration: params) },
+          }.freeze
+
+          # Accepts either "name" or { "name" => params }.
+          def self.build(spec, schemas:)
+            name, params =
+              if spec.is_a?(Hash)
+                spec.first
+              else
+                [spec.to_s, nil]
+              end
+            ctor = ENTRIES[name.to_s] or raise Textus::UsageError.new(
+              "unknown guard predicate: '#{name}' (known: #{ENTRIES.keys.join(", ")})",
+            )
+            ctor.call(params: params, schemas: schemas)
+          end
+
+          def self.known = ENTRIES.keys
+        end
+      end
+    end
+  end
+end

data/lib/textus/domain/policy/predicates/schema_valid.rb

@@ -1,48 +1,59 @@
+# frozen_string_literal: true
+
 module Textus
   module Domain
     module Policy
       module Predicates
+        # Predicate: the entry's effective frontmatter satisfies the schema
+        # bound to the target key. For accept, the frontmatter lives under
+        # envelope.meta["frontmatter"]; for a direct put it is envelope.meta.
         class SchemaValid
           attr_reader :reason
 
-          def name
-            "schema_valid"
+          def initialize(schemas:)
+            @schemas = schemas
           end
 
-          def call(entry:, schemas:, manifest:) # rubocop:disable Metrics/PerceivedComplexity, Metrics/CyclomaticComplexity
-            return true if entry.nil? || manifest.nil? || schemas.nil?
+          def name = "schema_valid"
+
+          def call(eval)
+            manifest = eval.manifest
+            return true if eval.envelope.nil? || manifest.nil? || @schemas.nil?
 
-            target_key = entry.meta&.dig("proposal", "target_key")
+            target_key = eval.target
             return true unless target_key
 
             mentry = manifest.resolver.resolve(target_key).entry
             schema_ref = mentry&.schema
             return true unless schema_ref
 
-            schema = schemas.fetch_or_nil(schema_ref)
+            schema = @schemas.fetch_or_nil(schema_ref)
             return true unless schema
 
-            frontmatter = entry.meta&.dig("frontmatter") || {}
+            frontmatter =
+              eval.envelope.meta&.dig("frontmatter") || eval.envelope.meta || {}
             begin
               schema.validate!(frontmatter)
+              true
             rescue Textus::SchemaViolation => e
-              @reason = e.message.dup
-              d = e.details
-              if d.is_a?(Hash)
-                if d["missing"]
-                  @reason = "missing required fields: #{Array(d["missing"]).join(", ")}"
-                elsif d["field"]
-                  @reason = "field '#{d["field"]}': #{d["reason"]}"
-                end
-              end
-              return false
+              @reason = humanize(e)
+              false
             end
-
-            true
           rescue StandardError => e
             @reason = "schema validation error: #{e.message}"
             false
           end
+
+          private
+
+          def humanize(err)
+            d = err.details
+            return err.message.dup unless d.is_a?(Hash)
+            return "missing required fields: #{Array(d["missing"]).join(", ")}" if d["missing"]
+            return "field '#{d["field"]}': #{d["reason"]}" if d["field"]
+
+            err.message.dup
+          end
         end
       end
     end

data/lib/textus/domain/policy/predicates/target_is_canon.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Textus
+  module Domain
+    module Policy
+      module Predicates
+        # Predicate: a proposal may only target a `canon` zone (ADR 0035). Runs
+        # on the `accept` floor, where Evaluation#target is the proposal's
+        # resolved target_key. Refuses promotion into workspace/derived/
+        # quarantine/queue — the queue→canon path is the only coherent one.
+        # No bespoke #error; failures accumulate into GuardFailed (ADR 0031).
+        class TargetIsCanon
+          attr_reader :reason
+
+          def name = "target_is_canon"
+
+          def call(eval)
+            zone = eval.manifest.resolver.resolve(eval.target).entry.zone
+            kind = eval.manifest.policy.declared_kind(zone.to_s)
+            return true if kind == :canon
+
+            @reason = "proposal target '#{eval.target}' is in zone '#{zone}' " \
+                      "(kind: #{kind || "none"}); proposals may only target a canon zone"
+            false
+          rescue Textus::UnknownKey
+            @reason = "proposal target '#{eval.target}' resolves to no declared entry"
+            false
+          end
+        end
+      end
+    end
+  end
+end

data/lib/textus/domain/policy/predicates/zone_writable_by.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Textus
+  module Domain
+    module Policy
+      module Predicates
+        # Predicate #0 of every write guard. Wraps the post-0.31.0 capability
+        # topology gate (role.can ⊇ verb_for(zone.kind)). On failure, #error
+        # raises the capability-shaped WriteForbidden so the topology refusal
+        # — textus's signature product feature — is unchanged.
+        class ZoneWritableBy
+          attr_reader :reason
+
+          def name = "zone_writable_by"
+
+          def call(eval)
+            manifest = eval.manifest
+            @mentry = manifest.resolver.resolve(eval.target).entry
+            return true if manifest.policy.permission_for(@mentry.zone.to_s).allows_write?(eval.actor)
+
+            @verb    = manifest.policy.verb_for_zone(@mentry.zone) # capability the kind requires
+            @holders = manifest.policy.roles_with_capability(@verb)
+            @reason  = "zone '#{@mentry.zone}' needs capability '#{@verb}'; '#{eval.actor}' lacks it"
+            false
+          end
+
+          # Matches the capability-shaped WriteForbidden landed by ADR 0030
+          # Task 3:
+          #   WriteForbidden.new(key, zone, verb:, holders:)
+          #   → "writing '<k>' (zone '<z>') needs capability '<verb>'",
+          #     hint: "held by: <holders>; pass --as=<role>".
+          def error(_eval)
+            Textus::WriteForbidden.new(@mentry.key, @mentry.zone, verb: @verb, holders: @holders)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/textus/domain/staleness/intake_check.rb

@@ -15,7 +15,7 @@ module Textus
         def rows_for(mentry)
           return [] unless mentry.is_a?(Textus::Manifest::Entry::Intake)
 
-          ttl = @manifest.rules.for(mentry.key).refresh&.ttl_seconds
+          ttl = @manifest.rules.for(mentry.key).fetch&.ttl_seconds
           return [] unless ttl
 
           path = Textus::Key::Path.resolve(@manifest.data, mentry)
@@ -26,17 +26,17 @@ module Textus
         private
 
         def ttl_reason(mentry, path, ttl)
-          return "never refreshed" unless @file_stat.exists?(path)
+          return "never fetched" unless @file_stat.exists?(path)
 
-          last_str = last_refreshed_of(mentry, path)
-          return "never refreshed (no last_refreshed_at)" if last_str.nil?
+          last_str = last_fetched_of(mentry, path)
+          return "never fetched (no last_fetched_at)" if last_str.nil?
 
           last = parse_time(last_str)
           "ttl exceeded (#{ttl}s)" if last.nil? || (@clock.now - last) > ttl
         end
 
-        def last_refreshed_of(mentry, path)
-          Entry.for_format(mentry.format).parse(@file_stat.read(path), path: path)["_meta"]["last_refreshed_at"]
+        def last_fetched_of(mentry, path)
+          Entry.for_format(mentry.format).parse(@file_stat.read(path), path: path)["_meta"]["last_fetched_at"]
         end
 
         def parse_time(str)

data/lib/textus/envelope.rb

@@ -55,10 +55,10 @@ module Textus
       freshness.stale == true
     end
 
-    def refreshing?
+    def fetching?
       return false if freshness.nil?
 
-      freshness.refreshing == true
+      freshness.fetching == true
     end
   end
 end

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
@@ -87,6 +92,10 @@ module Textus
       end
       File.write(File.join(target_root, "hooks", "README.md"), HOOKS_README)
       File.write(File.join(target_root, "manifest.yaml"), DEFAULT_MANIFEST)
+      FileUtils.mkdir_p(Textus::Layout.audit_dir(target_root))
+      FileUtils.mkdir_p(Textus::Layout.state(target_root))
+      FileUtils.mkdir_p(Textus::Layout.locks(target_root))
+      File.write(File.join(target_root, ".gitignore"), Textus::Layout::GITIGNORE)
       { "protocol" => PROTOCOL, "initialized" => target_root }
     end
   end

data/lib/textus/layout.rb

@@ -0,0 +1,41 @@
+module Textus
+  # Single source of truth for every path textus owns under a store root.
+  # All disposable runtime state nests under <root>/.run/ so the
+  # tracked/disposable boundary is a directory boundary. ADR 0038.
+  module Layout
+    RUN = ".run"
+
+    def self.run(root)
+      File.join(root, RUN)
+    end
+
+    def self.state(root)
+      File.join(run(root), "state")
+    end
+
+    def self.cursor(root, role)
+      File.join(state(root), "cursor.#{role}")
+    end
+
+    def self.locks(root)
+      File.join(run(root), "locks")
+    end
+
+    def self.build_lock(root)
+      File.join(run(root), "build.lock")
+    end
+
+    def self.audit_dir(root)
+      File.join(run(root), "audit")
+    end
+
+    def self.audit_log(root)
+      File.join(audit_dir(root), "audit.log")
+    end
+
+    GITIGNORE = <<~GITIGNORE
+      # textus runtime artifacts — safe to delete, never commit
+      #{RUN}/
+    GITIGNORE
+  end
+end

data/lib/textus/maintenance/key_delete_prefix.rb

@@ -2,6 +2,15 @@ module Textus
   module Maintenance
     # Bulk-delete every leaf key under `prefix`.
     class KeyDeletePrefix
+      extend Textus::Contract::DSL
+
+      verb     :key_delete_prefix
+      summary  "Bulk-delete every leaf key under prefix."
+      surfaces :cli, :ruby, :mcp
+      arg :prefix,  String, required: true
+      arg :dry_run, :boolean
+      response(&:to_h)
+
       def initialize(container:, call:)
         @container    = container
         @call         = call

data/lib/textus/maintenance/key_mv_prefix.rb

@@ -3,6 +3,16 @@ module Textus
     # Bulk-rename every leaf key under `from_prefix` to `to_prefix`.
     # Calls Write::Mv directly for each entry — emits one audit row per file moved.
     class KeyMvPrefix
+      extend Textus::Contract::DSL
+
+      verb     :key_mv_prefix
+      summary  "Bulk-rename every leaf key under from_prefix to to_prefix. Dry-run returns a Plan; apply with dry_run: false."
+      surfaces :cli, :ruby, :mcp
+      arg :from_prefix, String, required: true
+      arg :to_prefix,   String, required: true
+      arg :dry_run,     :boolean
+      response(&:to_h)
+
       def initialize(container:, call:)
         @container    = container
         @call         = call

data/lib/textus/maintenance/migrate.rb

@@ -5,6 +5,15 @@ module Textus
     # Loads a YAML migration plan and dispatches each op to the
     # appropriate Maintenance use case. Concatenates resulting Plans.
     class Migrate
+      extend Textus::Contract::DSL
+
+      verb     :migrate
+      summary  "Run a YAML migration plan (multi-op)."
+      surfaces :cli, :ruby, :mcp
+      arg :plan_yaml, String, required: true
+      arg :dry_run,   :boolean
+      response(&:to_h)
+
       def initialize(container:, call:)
         @container    = container
         @call         = call

data/lib/textus/maintenance/rule_lint.rb

@@ -6,6 +6,14 @@ module Textus
     # YAML string. Returns a Plan describing rule additions/removals/
     # changes. Does NOT write anything.
     class RuleLint
+      extend Textus::Contract::DSL
+
+      verb     :rule_lint
+      summary  "Diff candidate manifest YAML's rules against the live manifest. No writes."
+      surfaces :cli, :ruby, :mcp
+      arg :candidate_yaml, String, required: true
+      response(&:to_h)
+
       def initialize(container:, call:)
         @container = container
         @call      = call

data/lib/textus/maintenance/zone_mv.rb

@@ -6,6 +6,16 @@ module Textus
     # the `zone:` field on every entry under the old zone, and moves
     # every file from zones/<old>/ to zones/<new>/.
     class ZoneMv
+      extend Textus::Contract::DSL
+
+      verb     :zone_mv
+      summary  "Rename a zone — manifest + files. Refuses if destination exists."
+      surfaces :cli, :ruby, :mcp
+      arg :from,    String, required: true
+      arg :to,      String, required: true
+      arg :dry_run, :boolean
+      response(&:to_h)
+
       def initialize(container:, call:)
         @container = container
         @call      = call
@@ -15,7 +25,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