textus 0.20.2 → 0.26.0

data/lib/textus/doctor.rb

@@ -30,7 +30,7 @@ module Textus
 
     module_function
 
-    def run(store, checks: nil)
+    def run(session, checks: nil)
       selected_keys = checks ? Array(checks).map(&:to_s) : ALL_CHECKS
       unknown = selected_keys - ALL_CHECKS
       unless unknown.empty?
@@ -40,8 +40,8 @@ module Textus
       end
 
       selected = CHECKS.select { |c| selected_keys.include?(c.name_key) }
-      issues = selected.flat_map { |c| c.new(store).call }
-      issues.concat(run_registered_checks(store))
+      issues = selected.flat_map { |c| c.new(session).call }
+      issues.concat(run_registered_checks(session))
 
       summary = LEVELS.to_h { |l| [l, issues.count { |i| i["level"] == l }] }
       {
@@ -52,30 +52,27 @@ module Textus
       }
     end
 
-    def run_registered_checks(store)
-      out = []
-      store.bus.rpc_names(:validate).each do |name|
-        callable = store.bus.rpc_callable(:validate, name)
-        begin
-          result = Timeout.timeout(DOCTOR_CHECK_TIMEOUT_SECONDS) { callable.call(store: store) }
-          if result.is_a?(Array)
-            out.concat(result.map { |h| h.transform_keys(&:to_s) })
-          else
-            out << fail_issue(name, code: "doctor_check.bad_return",
-                                    message: "doctor_check '#{name}' returned #{result.class} (expected Array)",
-                                    fix: "return an array of issue hashes from the doctor_check block")
-          end
-        rescue Timeout::Error
-          out << fail_issue(name, code: "doctor_check.timeout",
-                                  message: "doctor_check '#{name}' exceeded #{DOCTOR_CHECK_TIMEOUT_SECONDS}s",
-                                  fix: "shorten the check or split it into smaller checks")
-        rescue StandardError => e
-          out << fail_issue(name, code: "doctor_check.failed",
-                                  message: "#{e.class}: #{e.message}",
-                                  fix: "fix the :validate hook in .textus/hooks/")
-        end
+    def run_registered_checks(session)
+      session.rpc.names(:validate).flat_map { |name| invoke_registered_check(session, name) }
+    end
+
+    def invoke_registered_check(session, name)
+      result = Timeout.timeout(DOCTOR_CHECK_TIMEOUT_SECONDS) do
+        session.rpc.invoke(:validate, name, caps: session.write_caps)
       end
-      out
+      return result.map { |h| h.transform_keys(&:to_s) } if result.is_a?(Array)
+
+      [fail_issue(name, code: "doctor_check.bad_return",
+                        message: "doctor_check '#{name}' returned #{result.class} (expected Array)",
+                        fix: "return an array of issue hashes from the doctor_check block")]
+    rescue Timeout::Error
+      [fail_issue(name, code: "doctor_check.timeout",
+                        message: "doctor_check '#{name}' exceeded #{DOCTOR_CHECK_TIMEOUT_SECONDS}s",
+                        fix: "shorten the check or split it into smaller checks")]
+    rescue StandardError => e
+      [fail_issue(name, code: "doctor_check.failed",
+                        message: "#{e.class}: #{e.message}",
+                        fix: "fix the :validate hook in .textus/hooks/")]
     end
 
     def fail_issue(name, code:, message:, fix:)
@@ -88,6 +85,6 @@ module Textus
       }
     end
 
-    private_class_method :run_registered_checks, :fail_issue
+    private_class_method :run_registered_checks, :invoke_registered_check, :fail_issue
   end
 end

data/lib/textus/domain/authorizer.rb

@@ -11,24 +11,24 @@ module Textus
       end
 
       def can_write?(zone, role:)
-        @manifest.permission_for(zone.to_s).allows_write?(role)
+        @manifest.policy.permission_for(zone.to_s).allows_write?(role)
       end
 
       def can_read?(zone, role:)
-        @manifest.permission_for(zone.to_s).allows_read?(role)
+        @manifest.policy.permission_for(zone.to_s).allows_read?(role)
       end
 
       def authorize_write!(mentry, role:)
         return if can_write?(mentry.zone, role: role)
 
-        writers = @manifest.zone_writers(mentry.zone)
+        writers = @manifest.policy.zone_writers(mentry.zone)
         raise WriteForbidden.new(mentry.key, mentry.zone, writers: writers)
       end
 
       def authorize_read!(mentry, role:)
         return if can_read?(mentry.zone, role: role)
 
-        readers = @manifest.zone_readers[mentry.zone]
+        readers = @manifest.policy.zone_readers[mentry.zone]
         readers = nil if readers == :all
         raise ReadForbidden.new(mentry.key, mentry.zone, readers: readers)
       end

data/lib/textus/{application → domain}/policy/predicates/accept_authority_signed.rb

@@ -1,5 +1,5 @@
 module Textus
-  module Application
+  module Domain
     module Policy
       module Predicates
         # Promotion predicate: the role driving the promotion must have
@@ -20,7 +20,7 @@ module Textus
             role_str = role&.to_s
             return true if role_str.nil? || role_str.empty?
 
-            kind = manifest.role_kind(role_str)
+            kind = manifest.policy.role_kind(role_str)
             return true if kind == :accept_authority
 
             @reason = "role '#{role_str}' has kind '#{kind.inspect}', expected ':accept_authority'"

data/lib/textus/{application → domain}/policy/predicates/schema_valid.rb

@@ -1,5 +1,5 @@
 module Textus
-  module Application
+  module Domain
     module Policy
       module Predicates
         class SchemaValid

data/lib/textus/{application → domain}/policy/promotion.rb

@@ -2,7 +2,7 @@ require_relative "predicates/schema_valid"
 require_relative "predicates/accept_authority_signed"
 
 module Textus
-  module Application
+  module Domain
     module Policy
       class Promotion
         Result = Struct.new(:ok?, :reasons, keyword_init: true)

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

@@ -19,7 +19,7 @@ module Textus
           src = mentry.source
           return [] unless src.is_a?(Textus::Manifest::Entry::Derived::External)
 
-          path = Textus::Key::Path.resolve(@manifest, mentry)
+          path = Textus::Key::Path.resolve(@manifest.data, mentry)
           return [stale_row(mentry, path, "derived entry has never been generated")] unless File.exist?(path)
 
           parsed = Entry.for_format(mentry.format).parse(File.binread(path), path: path)
@@ -63,7 +63,7 @@ module Textus
         end
 
         def check_filesystem_source(src, gen_time)
-          abs = File.absolute_path?(src) ? src : File.join(File.dirname(@manifest.root), src)
+          abs = File.absolute_path?(src) ? src : File.join(File.dirname(@manifest.data.root), src)
           if File.directory?(abs)
             Dir.glob(File.join(abs, "**", "*")).each do |fp|
               next unless File.file?(fp)

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

@@ -13,10 +13,10 @@ 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).refresh&.ttl_seconds
           return [] unless ttl
 
-          path = Textus::Key::Path.resolve(@manifest, mentry)
+          path = Textus::Key::Path.resolve(@manifest.data, mentry)
           return [row(mentry, path, "never refreshed")] unless File.exist?(path)
 
           meta = Entry.for_format(mentry.format).parse(File.binread(path), path: path)["_meta"]

data/lib/textus/domain/staleness.rb

@@ -8,7 +8,7 @@ module Textus
       end
 
       def call(prefix: nil, zone: nil)
-        @manifest.entries
+        @manifest.data.entries
                  .select { |m| entry_matches?(m, prefix: prefix, zone: zone) }
                  .flat_map { |m| @generator_check.rows_for(m) + @intake_check.rows_for(m) }
       end

data/lib/textus/errors.rb

@@ -215,4 +215,20 @@ module Textus
       )
     end
   end
+
+  class CursorExpired < Error
+    attr_reader :requested, :min_available
+
+    def initialize(requested:, min_available:)
+      @requested = requested
+      @min_available = min_available
+      super(
+        "cursor_expired",
+        "audit cursor expired: requested seq=#{requested} but oldest available is #{min_available}; " \
+        "call `textus boot` to re-orient and resume from latest_seq",
+        details: { "requested" => requested, "min_available" => min_available },
+        hint: "call `textus boot` to get the current latest_seq and resume from there",
+      )
+    end
+  end
 end

data/lib/textus/hooks/builtin.rb

@@ -7,23 +7,23 @@ module Textus
   module Hooks
     module Builtin
       # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
-      def self.register_all(bus)
-        bus.on(:resolve_intake, :json) do |store:, config:, args:|
-          _ = store
+      def self.register_all(events:, rpc:) # rubocop:disable Lint/UnusedMethodArgument
+        rpc.register(:resolve_intake, :json) do |caps:, config:, args:|
+          _ = caps
           _ = args
           data = JSON.parse(config["bytes"].to_s)
           { _meta: {}, body: YAML.dump(data) }
         end
 
-        bus.on(:resolve_intake, :csv) do |store:, config:, args:|
-          _ = store
+        rpc.register(:resolve_intake, :csv) do |caps:, config:, args:|
+          _ = caps
           _ = args
           rows = CSV.parse(config["bytes"].to_s, headers: true).map(&:to_h)
           { _meta: {}, body: YAML.dump(rows) }
         end
 
-        bus.on(:resolve_intake, :"markdown-links") do |store:, config:, args:|
-          _ = store
+        rpc.register(:resolve_intake, :"markdown-links") do |caps:, config:, args:|
+          _ = caps
           _ = args
           links = config["bytes"].to_s.scan(%r{\[([^\]]+)\]\((https?://[^)\s]+)\)}).map do |text, href|
             { "text" => text, "href" => href }
@@ -31,27 +31,27 @@ module Textus
           { _meta: {}, body: YAML.dump(links) }
         end
 
-        bus.on(:resolve_intake, :"ical-events") do |store:, config:, args:|
-          _ = store
+        rpc.register(:resolve_intake, :"ical-events") do |caps:, config:, args:|
+          _ = caps
           _ = args
-          events = []
+          events_list = []
           current = nil
           config["bytes"].to_s.each_line do |line|
             line = line.strip
             case line
             when "BEGIN:VEVENT" then current = {}
             when "END:VEVENT"
-              events << current if current
+              events_list << current if current
               current = nil
             when /\A(SUMMARY|DTSTART|DTEND|UID|LOCATION|DESCRIPTION):(.*)\z/
               current[Regexp.last_match(1).downcase] = Regexp.last_match(2) if current
             end
           end
-          { _meta: {}, body: YAML.dump(events) }
+          { _meta: {}, body: YAML.dump(events_list) }
         end
 
-        bus.on(:resolve_intake, :rss) do |store:, config:, args:|
-          _ = store
+        rpc.register(:resolve_intake, :rss) do |caps:, config:, args:|
+          _ = caps
           _ = args
           doc = REXML::Document.new(config["bytes"].to_s)
           items = doc.elements.to_a("//item").map do |item|

data/lib/textus/hooks/context.rb

@@ -3,31 +3,31 @@
 module Textus
   module Hooks
     # A narrow handle passed to user hooks in place of the raw Store.
-    # All writes route back through Operations so authorization, audit
+    # All writes route back through the Session so authorization, audit
     # logging, and schema validation always fire.
     class Context
       attr_reader :role, :correlation_id
 
-      def initialize(ops:)
-        @ops = ops
-        @role = ops.ctx.role
-        @correlation_id = ops.ctx.correlation_id
+      def initialize(session:)
+        @session = session
+        @role = session.ctx.role
+        @correlation_id = session.ctx.correlation_id
       end
 
       # read
-      def get(key)                = @ops.get(key)
-      def list(**)                = @ops.list(**)
-      def deps(key)               = @ops.deps(key)
-      def freshness(key)          = @ops.freshness(key)
+      def get(key)                = @session.get(key)
+      def list(**)                = @session.list(**)
+      def deps(key)               = @session.deps(key)
+      def freshness(key)          = @session.freshness(key)
 
       # write (authorized + audited)
-      def put(key, **)          = @ops.put(key, **)
-      def delete(key, **)       = @ops.delete(key, **)
-      def audit(verb, key:, **) = @ops.store.audit_log.append(role: @role, verb: verb, key: key, **)
+      def put(key, **)          = @session.put(key, **)
+      def delete(key, **)       = @session.delete(key, **)
+      def audit(verb, key:, **) = @session.write_caps.audit_log.append(role: @role, verb: verb, key: key, **)
 
       # fan-out
       def publish_followup(event, **)
-        @ops.store.bus.publish(event, ctx: self, **)
+        @session.write_caps.events.publish(event, ctx: self, **)
       end
 
       def inspect

data/lib/textus/hooks/error_log.rb

@@ -0,0 +1,32 @@
+module Textus
+  module Hooks
+    # Bounded in-memory ring buffer of recent hook failures (errored and
+    # timed_out). Each row carries the audit `seq` observed at the time of
+    # failure so pulse can filter "errors since cursor".
+    class ErrorLog
+      DEFAULT_CAPACITY = 256
+
+      def initialize(capacity: DEFAULT_CAPACITY)
+        @capacity = capacity
+        @rows = []
+        @mutex = Mutex.new
+      end
+
+      def record(seq:, event:, hook:, key:, error_class:, error_message:)
+        row = {
+          seq: seq, event: event, hook: hook, key: key,
+          error_class: error_class, error_message: error_message,
+          at: Time.now.utc.iso8601
+        }
+        @mutex.synchronize do
+          @rows << row
+          @rows.shift while @rows.size > @capacity
+        end
+      end
+
+      def since(seq)
+        @mutex.synchronize { @rows.select { |r| r[:seq] > seq }.dup }
+      end
+    end
+  end
+end

data/lib/textus/hooks/{bus.rb → event_bus.rb}

@@ -2,67 +2,55 @@
 
 module Textus
   module Hooks
-    class Bus
+    class EventBus
       HOOK_TIMEOUT_SECONDS = 2
 
       class HookTimeout < StandardError; end
 
       EVENTS = {
-        # RPC events — gem-internal, keep :store
-        resolve_intake: { mode: :rpc, args: %i[store config args] },
-        transform_rows: { mode: :rpc, args: %i[store rows config] },
-        validate: { mode: :rpc, args: %i[store] },
-
-        # Pubsub events — ship :ctx (Hooks::Context) instead of raw store
-        entry_put: { mode: :pubsub, args: %i[ctx key envelope] },
-        entry_deleted: { mode: :pubsub, args: %i[ctx key] },
-        entry_refreshed: { mode: :pubsub, args: %i[ctx key envelope change] },
-        entry_renamed: { mode: :pubsub, args: %i[ctx key from_key to_key envelope] },
-        build_completed: { mode: :pubsub, args: %i[ctx key envelope sources] },
-        proposal_accepted: { mode: :pubsub, args: %i[ctx key target_key] },
-        proposal_rejected: { mode: :pubsub, args: %i[ctx key target_key] },
-        file_published: { mode: :pubsub, args: %i[ctx key envelope source target] },
-        store_loaded: { mode: :pubsub, args: %i[ctx] },
-        refresh_started: { mode: :pubsub, args: %i[ctx key mode] },
-        refresh_failed: { mode: :pubsub, args: %i[ctx key error_class error_message] },
-        refresh_backgrounded: { mode: :pubsub, args: %i[ctx key started_at budget_ms] },
+        entry_put: %i[ctx key envelope],
+        entry_deleted: %i[ctx key],
+        entry_refreshed: %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],
       }.freeze
 
-      def initialize
-        @rpc    = Hash.new { |h, k| h[k] = {} }
+      RPC_EVENTS = %i[resolve_intake transform_rows validate].freeze
+
+      def initialize(error_log: ErrorLog.new)
         @pubsub = Hash.new { |h, k| h[k] = [] }
         @error_handlers = []
+        @error_log = error_log
       end
 
+      attr_reader :error_log
+
       def on(event, name, keys: nil, &) = register(event, name, keys: keys, &)
 
       def register(event, name, keys: nil, &blk)
         event_sym = event.to_sym
-        spec = EVENTS[event_sym] or raise UsageError.new("unknown event: #{event}")
-        shape_check!(event_sym, spec, blk)
-        name = name.to_sym
-
-        case spec[:mode]
-        when :rpc
-          raise UsageError.new("#{event_sym} '#{name}' already registered") if @rpc[event_sym].key?(name)
+        raise UsageError.new("#{event_sym} is an RPC event; register on RpcRegistry") if RPC_EVENTS.include?(event_sym)
 
-          @rpc[event_sym][name] = blk
-        when :pubsub
-          raise UsageError.new("#{event_sym} hook '#{name}' already registered") if @pubsub[event_sym].any? { |h| h[:name] == name }
+        required = EVENTS[event_sym] or raise UsageError.new("unknown event: #{event}")
+        shape_check!(event_sym, required, blk)
+        name = name.to_sym
+        raise UsageError.new("#{event_sym} hook '#{name}' already registered") if @pubsub[event_sym].any? { |h| h[:name] == name }
 
-          @pubsub[event_sym] << { name: name, callable: blk, keys: keys }
-        end
+        @pubsub[event_sym] << { name: name, callable: blk, keys: keys }
       end
 
       def on_error(&block) = @error_handlers << block
 
-      def rpc_callable(event, name)
-        @rpc[event.to_sym][name.to_sym] or raise UsageError.new("unknown #{event}: #{name}")
-      end
+      def listeners(event, key:) = @pubsub[event.to_sym].select { |h| match?(h[:keys], key) }
 
-      def rpc_names(event)        = @rpc[event.to_sym].keys
-      def pubsub_handlers(event)  = @pubsub[event.to_sym]
-      def listeners(event, key:)  = @pubsub[event.to_sym].select { |h| h[:keys].nil? || matches_any?(h[:keys], key) }
+      def pubsub_handlers(event) = @pubsub[event.to_sym]
 
       def publish(event, strict: false, **kwargs)
         key = kwargs[:key] || "-"
@@ -93,29 +81,33 @@ module Textus
       def invoke(event, sub, key, kwargs)
         accepted = filter_kwargs(sub[:callable], kwargs)
         error = nil
-
         thread = Thread.new do
           sub[:callable].call(**accepted)
         rescue StandardError => e
           error = e
         end
-
         if thread.join(HOOK_TIMEOUT_SECONDS).nil?
           thread.kill
           err = HookTimeout.new("hook #{sub[:name]} exceeded #{HOOK_TIMEOUT_SECONDS}s on event #{event}")
           notify_error(event, sub, key, kwargs, err)
           return [:timed_out, err]
         end
-
         if error
           notify_error(event, sub, key, kwargs, error)
           return [:errored, error]
         end
-
         [:ok, nil]
       end
 
       def notify_error(event, sub, key, kwargs, error)
+        @error_log.record(
+          seq: kwargs[:_audit_seq] || -1,
+          event: event,
+          hook: sub[:name],
+          key: key,
+          error_class: error.class.name,
+          error_message: error.message,
+        )
         @error_handlers.each do |handler|
           handler.call(event: event, hook: sub[:name], key: key, kwargs: kwargs, error: error)
         rescue StandardError => e
@@ -127,18 +119,16 @@ module Textus
         params = callable.parameters
         return kwargs if params.any? { |type, _| type == :keyrest }
 
-        accepted = params.each_with_object([]) do |(type, name), acc|
-          acc << name if %i[key keyreq].include?(type)
-        end
+        accepted = params.each_with_object([]) { |(t, n), acc| acc << n if %i[key keyreq].include?(t) }
         kwargs.slice(*accepted)
       end
 
-      def shape_check!(event, spec, blk)
-        required = spec[:args]
+      def shape_check!(event, required, blk)
         provided = blk.parameters.select { |t, _| %i[keyreq key keyrest].include?(t) } # rubocop:disable Style/HashSlice
-        keyrest  = provided.any? { |t, _| t == :keyrest }
-        missing  = required - provided.map { |_, n| n }
-        return if keyrest || missing.empty?
+        return if provided.any? { |t, _| t == :keyrest }
+
+        missing = required - provided.map { |_, n| n }
+        return if missing.empty?
 
         raise UsageError.new("#{event} hooks must accept kwargs: #{required.join(", ")} (missing: #{missing.join(", ")})")
       end
@@ -148,8 +138,6 @@ module Textus
 
         Array(globs).any? { |g| File.fnmatch?(g, key.to_s, File::FNM_PATHNAME) }
       end
-
-      def matches_any?(globs, key) = match?(globs, key)
     end
   end
 end

data/lib/textus/hooks/loader.rb

@@ -1,8 +1,34 @@
 module Textus
   module Hooks
     class Loader
-      def initialize(bus:)
-        @bus = bus
+      # A small DSL object passed to user hook blocks. Routes `.on(...)` to the
+      # EventBus and `.rpc(...)` / `.register(...)` to the RpcRegistry.
+      class Dsl
+        def initialize(events:, rpc:)
+          @events = events
+          @rpc    = rpc
+        end
+
+        # Pubsub registration — delegates to EventBus.
+        # Also handles RPC event names by delegating to RpcRegistry.
+        def on(event, name, keys: nil, &)
+          if Hooks::RpcRegistry::EVENTS.key?(event.to_sym)
+            @rpc.register(event, name, &)
+          else
+            @events.register(event, name, keys: keys, &)
+          end
+        end
+
+        # Explicit RPC registration.
+        def register(event, name, &)
+          @rpc.register(event, name, &)
+        end
+      end
+
+      def initialize(events:, rpc:)
+        @events = events
+        @rpc    = rpc
+        @dsl    = Dsl.new(events: @events, rpc: @rpc)
       end
 
       def load_dir(dir)
@@ -18,7 +44,7 @@ module Textus
         end
 
         Textus.drain_hook_blocks.each do |blk|
-          blk.call(@bus)
+          blk.call(@dsl)
         rescue StandardError, ScriptError => e
           raise UsageError.new("failed registering hook: #{e.class}: #{e.message}")
         end

data/lib/textus/hooks/rpc_registry.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Textus
+  module Hooks
+    class RpcRegistry
+      EVENTS = {
+        resolve_intake: %i[caps config args],
+        transform_rows: %i[caps rows config],
+        validate: %i[caps],
+      }.freeze
+
+      PUBSUB_EVENTS = EventBus::EVENTS.keys.freeze
+
+      def initialize
+        @table = Hash.new { |h, k| h[k] = {} }
+      end
+
+      def register(event, name, &blk)
+        event_sym = event.to_sym
+        raise UsageError.new("#{event_sym} is a pubsub event; register on EventBus") if PUBSUB_EVENTS.include?(event_sym)
+
+        required = EVENTS[event_sym] or raise UsageError.new("unknown RPC event: #{event}")
+        shape_check!(event_sym, required, blk)
+        name = name.to_sym
+        raise UsageError.new("#{event_sym} '#{name}' already registered") if @table[event_sym].key?(name)
+
+        @table[event_sym][name] = blk
+      end
+
+      def names(event) = @table[event.to_sym].keys
+
+      def callable(event, name)
+        @table[event.to_sym][name.to_sym] or raise UsageError.new("unknown #{event}: #{name}")
+      end
+
+      # Invoke a registered callable, injecting `caps:` under the kwarg name
+      # the callable declares. Legacy `store:` is rejected (no shim).
+      def invoke(event, name, caps:, **other)
+        blk = callable(event, name)
+        params = blk.parameters
+        accepts_keyrest = params.any? { |t, _| t == :keyrest }
+        declared = params.each_with_object([]) { |(t, n), acc| acc << n if %i[key keyreq].include?(t) }
+
+        if declared.include?(:store)
+          raise UsageError.new(
+            "RPC callable for #{event} '#{name}' declares legacy `store:`; rename to `caps:` " \
+            "(Textus::Application::ReadCaps / WriteCaps)",
+          )
+        end
+
+        kwargs = other.dup
+        kwargs[:caps] = caps if accepts_keyrest || declared.include?(:caps)
+        blk.call(**kwargs)
+      end
+
+      private
+
+      def shape_check!(event, required, blk)
+        provided = blk.parameters.select { |t, _| %i[keyreq key keyrest].include?(t) } # rubocop:disable Style/HashSlice
+        return if provided.any? { |t, _| t == :keyrest }
+
+        param_names = provided.map { |_, n| n }
+        # Allow `store:` as a stand-in for `caps:` so registration succeeds;
+        # invoke will raise UsageError when the callable is actually called.
+        effective_required = if param_names.include?(:store)
+                               required.map { |r| r == :caps ? :store : r }
+                             else
+                               required
+                             end
+        missing = effective_required - param_names
+        return if missing.empty?
+
+        raise UsageError.new("#{event} RPC must accept kwargs: #{required.join(", ")} (missing: #{missing.join(", ")})")
+      end
+    end
+  end
+end