activeadmin-graphql 0.3.3 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 36bec145bd90193ae32e34aa54b7a6ed01dff13a8b104269b771f797262b2480
-  data.tar.gz: 82724e08af33a67a1a9146813965e5d836006620ff503099842addcdeaab16cb
+  metadata.gz: c03a6abe474dea238c1dec40f75bb03b2f3203e4874d4639e2327a0562c9a9ce
+  data.tar.gz: 3bb9bd9cf8b55e796cf87cf8f51dca817b41b5ae9a515132ff0e56a218afe6db
 SHA512:
-  metadata.gz: 0b9ddc6e9d85447807e5cbbf9d1e5c9b5c87b756eaa8325cb57fe8ce291e221b40e1afd200ddb683a73cba036b83b6eac6f8f5ab3e0ff9788c1864e7f550cc16
-  data.tar.gz: 806443d03640f31e48d893998cd9f693bafd5efce162798ff406ed2eee2ad43d7c0c588467b8fbd37fdab4a3a6049a9efcbadffbe337469cac7bc5ff958bf36f
+  metadata.gz: 9e0a6930217123a83432a072410be640d618371c062eb83e27c86786461218f4d48d524edd9a7c00749914ac3c216d015d565fbc60a7f5fcdf7fc0d2f57d48b7
+  data.tar.gz: 639363956ab8b19349df04e7a5c5f9f6610705206b3d7d8f82838cde74b4dc10ab5e7b53f993def3c2de016885d1a1ecd267698252b877f655c87b49ef1a8f9f

data/CHANGELOG.md

@@ -1,6 +1,22 @@
 # Changelog
 
-## Unreleased
+## 0.4.0 (2026-10-13)
+
+- Add field `capability_mode` (`:omit` / `:null`) and namespace hooks
+  `graphql_field_capability_mode_default` and `graphql_field_visible` (RFC 0009).
+- Add `member_action_mutation … dry_run: true` with `preview`, `extra_params`,
+  `ok` / `refuse`, and optional `graphql_run_action_audit` (RFC 0010).
+- Add `graphql_collection_query_policy` and
+  `CollectionQueryPolicy.require_visible_fields!`, inferring filter grants from
+  resource field capabilities by default (RFC 0011).
+- Add `graphql_member_action_capability_default`,
+  `graphql_batch_action_capability_default`,
+  `graphql_collection_action_capability_default`, and `capability:` on
+  `batch_action_mutation` / `member_action_mutation` /
+  `collection_action_mutation` (RFC 0012).
+- Add `dry_run:` / `confirm:` / `preview:` on `SchemaField`, preview
+  short-circuit via `RunActionControlExtension`, and
+  `RunActionField.define` DSL sugar for custom run-action fields (RFC 0013).
 
 ## 0.3.3 (2026-10-12)
 

data/docs/changelogs/20261012200000_host-customization-hooks.md

@@ -0,0 +1,27 @@
+# Host customization hooks
+
+## Decisions
+
+Ship generic namespace hooks and DSL for field capability null mode, member-action
+dry-run with preview, collection query policy, default run-action capabilities,
+and confirm/dry-run/preview plus RunActionField.define for custom mutations.
+Product allowlists and auth grants stay in the host application.
+
+## Effects
+
+RFCs 0009 through 0013 claimed and drafted. Implementation under 0.4.0 in
+CHANGELOG.md. Request specs cover null-mode introspection, dry-run short-circuit,
+collection filter refusal, default capability omit, and confirm_required.
+
+## Next
+
+Metadata prepared in docs/changelogs/20261013080000_release-0-4-0.md. Run make
+release when ready to push the gem and tag. Host apps can drop prepends that
+duplicated these mechanics after upgrading.
+
+## Source
+
+RFCs 0009–0013. Specs under spec/requests/graphql_capability_mode_spec.rb,
+graphql_member_action_dry_run_spec.rb, graphql_collection_query_policy_spec.rb,
+graphql_run_action_capability_default_spec.rb,
+graphql_run_action_confirm_spec.rb.

data/docs/changelogs/20261013080000_release-0-4-0.md

@@ -0,0 +1,48 @@
+# Release 0.4.0 metadata
+
+## Participants
+
+Andrei Makarov
+
+## Decisions
+
+Cut 0.4.0 after published 0.3.3. User-visible work since the 0.3.3 tag:
+field capability null mode and visibility hooks (RFC 0009), member-action
+dry-run with preview and optional audit (RFC 0010), collection query policy
+with filter grants inferred from field capabilities (RFC 0011), default
+run-action capabilities and per-mutation `capability:` (RFC 0012), and
+confirm / dry-run / preview plus `RunActionField.define` for custom
+run-action fields (RFC 0013). Product allowlists and auth grants stay in the
+host application.
+
+CHANGELOG Unreleased bullets moved under 0.4.0 dated 2026-10-13.
+
+Version constant is 0.4.0. Path gem pins in Gemfile.lock and appraisal
+lockfiles match.
+
+make release (usr/bin/release.rb) still owns gem build, gem push, git tag, and
+GitHub release. This pass only prepares metadata.
+
+## Effects
+
+lib/active_admin/graphql/version.rb VERSION is 0.4.0.
+
+CHANGELOG host-customization bullets live under 0.4.0.
+
+PATH specs for activeadmin-graphql in Gemfile.lock,
+gemfiles/rails72.gemfile.lock, gemfiles/rails8ruby4.gemfile.lock, and
+gemfiles/rails8ruby34.gemfile.lock are 0.4.0.
+
+## Next
+
+Run make release from a clean tree when ready to push the gem and tag 0.4.0.
+
+## Source
+
+docs/changelogs/20261012200000_host-customization-hooks.md
+rfcs/0009-field-capability-mode.md
+rfcs/0010-member-action-dry-run.md
+rfcs/0011-collection-query-policy.md
+rfcs/0012-run-action-capability-defaults.md
+rfcs/0013-run-action-confirm-dry-run.md
+usr/bin/release.rb

data/docs/graphql-api.md

@@ -108,6 +108,22 @@ Each namespace inherits these options (defaults in parentheses):
   Cannot be combined with named `graphql_visibility` `profiles:`; schema build
   forces `dynamic: true` and omits `visibility_profile` from the request context
   so introspection uses the live capability set.
+* `graphql_field_capability_mode_default` — `:omit` or `:null` when a field has a
+  capability but no per-field mode (RFC 0009). Default `:omit`.
+* `graphql_field_visible` — optional `Proc` `(context, meta) -> Boolean` to omit
+  fields after capability checks (RFC 0009). Meta includes `graphql_type_name`,
+  `field_name`, and `resource` when known.
+* `graphql_run_action_audit` — optional `Proc` `(context, meta) -> void` after
+  member-action dry-run, refused preview, or completed run (RFC 0010).
+* `graphql_collection_query_policy` — optional `Proc` `(context, meta) -> void`
+  at the start of collection resolve (RFC 0011). Meta includes `aa_resource`,
+  `q`, `scope`, `order`, and `filter`.
+* `graphql_member_action_capability_default` — optional capability symbol applied
+  to member-action mutation fields when the resource map has no entry (RFC 0012).
+* `graphql_batch_action_capability_default` — same for the aggregate batch-action
+  field and per-action authorize checks (RFC 0012).
+* `graphql_collection_action_capability_default` — same for collection-action
+  mutation fields (RFC 0012).
 * `graphql_configure_schema` — `Proc` receiving the schema class after build
   (extensions, extra types, and so on).
 
@@ -284,14 +300,27 @@ admin.graphql_capabilities = lambda { |ctx|
 
 A gated member fails closed when the capability is missing from that set:
 resolve returns null for the field (graphql-ruby unauthorized field). Enable
-`graphql_visibility` so introspection and validation also omit ungated members.
+`graphql_visibility` so introspection and validation also omit ungated members
+when the field mode is `:omit` (default). Use `capability_mode: :null` (or
+`capability :pii, fields: %i[body], mode: :null`) so the field stays in the
+schema and resolves to `null` without the grant (RFC 0009).
+
 `fields:` applies to generated attributes and wired `belongs_to` associations.
 Unknown field names raise at schema build. Capabilities do not replace the
 authorization adapter.
 
-Custom `SchemaField` definitions may pass `capability: :name` the same way.
-Do not use named visibility `profiles:` together with `graphql_capabilities`
-(cached profile context ignores per-request grants).
+Custom `SchemaField` definitions may pass `capability: :name` and
+`capability_mode: :null` the same way. Set `graphql_field_visible` for a second
+omit gate (for example a request allowlist). Do not use named visibility
+`profiles:` together with `graphql_capabilities` (cached profile context ignores
+per-request grants).
+
+Collection list fields may call a host `graphql_collection_query_policy`. The
+helper `ActiveAdmin::GraphQL::CollectionQueryPolicy.require_visible_fields!`
+rejects Ransack `q` keys for hidden fields and requires capabilities from the
+resource field map by default (needed for `capability_mode: :null` columns).
+Optional `field_grants` overrides inference; `infer_field_grants: false` turns
+it off (RFC 0011).
 
 ## Schema overview
 
@@ -572,8 +601,12 @@ graphql do
     type(Members::MemberRunPayload)
   end
 
-  member_action_mutation(:send_invoice) do
+  member_action_mutation(:send_invoice, dry_run: true, capability: :support_act) do
     type(Members::SendInvoicePayload)
+    preview do |record, **|
+      record.may_send_invoice? ? ok("would_run:send_invoice:#{record.id}") : refuse("not_ready")
+    end
+    extra_params :note
     arguments do
       argument :note, GraphQL::Types::String, required: false, camelize: false
     end
@@ -583,7 +616,21 @@ end
 
 Call the named field as `posts_member_send_invoice(id: "...", note: "…")`. Extra
 arguments are merged with `params` for the controller and passed as keyword args
-to a custom `resolve` block.
+to a custom `resolve` block. With `dry_run: true`, the field gains a Boolean
+`dry_run` argument: preview runs first, dry-run returns without
+`run_member_action`, and a refused preview never runs the action (RFC 0010).
+`extra_params` allowlists which GraphQL kwargs forward into the AA request
+(`id` cannot be rebound). `capability:` on batch / member / collection mutation
+DSL overrides the resource map; otherwise the matching
+`graphql_*_action_capability_default` applies (RFC 0012).
+
+Custom mutations in `graphql_configure_schema` may use
+`ActiveAdmin::GraphQL::RunActionField.define` (or `SchemaField` keywords
+`dry_run:`, `confirm:`, `preview:`) for confirm/dry-run wiring (RFC 0013). When
+`confirm` is required and both flags are false, the field returns
+`body: "confirm_required"`. When `preview` is set, dry-run and refused preview
+return without calling `resolve`; without `preview`, dry-run still calls
+`resolve` with `dry_run: true`.
 
 With no symbol argument, `member_action_mutation { … }` configures only the
 aggregate `posts_member_action` field. With a symbol, it configures the

data/docs/issues/20261012200000_host-customization-gaps.md

@@ -0,0 +1,26 @@
+# Host customization gaps
+
+## Decisions
+
+The gem owns mechanics: when a field is visible, null, or omitted; dry-run
+argument wiring; filter-key policy hooks; default member-action capability;
+confirm/dry_run injection on custom fields. Hosts own product grants, domain
+preview bodies, and audit storage.
+
+Capabilities remain grant names in context[:capabilities]. Named visibility
+profiles stay incompatible with graphql_capabilities.
+
+## Effects
+
+RFCs 0009–0013 specify the contract. Implementation landed on the feature
+branch with request coverage for each hook.
+
+## Next
+
+Publish a release. Hosts migrate off local prepends in the order: capability
+null mode and dry-run DSL, then collection policy, then field_visible and
+capability defaults, then confirm helpers.
+
+## Source
+
+RFCs 0009–0013. docs/changelogs/20261012200000_host-customization-hooks.md.

data/lib/active_admin/graphql/capability_definition_dsl.rb

@@ -2,7 +2,7 @@
 
 module ActiveAdmin
   module GraphQL
-    # Block body for +capability :name do ... end+ (RFC 0008).
+    # Block body for +capability :name do ... end+ (RFC 0008, RFC 0009).
     class CapabilityDefinitionDSL
       QUERY_ALIASES = {
         index: :collection,
@@ -14,13 +14,18 @@ module ActiveAdmin
         delete: :destroy
       }.freeze
 
-      def initialize(config, capability_name)
+      def initialize(config, capability_name, mode: nil)
         @config = config
         @capability_name = capability_name.to_sym
+        @mode = mode
       end
 
-      def fields(*names)
-        @config.assign_field_capabilities!(@capability_name, names)
+      def fields(*names, mode: nil)
+        @config.assign_field_capabilities!(
+          @capability_name,
+          names,
+          mode: mode.nil? ? @mode : mode
+        )
       end
 
       def queries(*names)

data/lib/active_admin/graphql/collection_query_policy.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module ActiveAdmin
+  module GraphQL
+    # Built-in helpers for +graphql_collection_query_policy+ (RFC 0011).
+    module CollectionQueryPolicy
+      module_function
+
+      def require_visible_fields!(
+        context:,
+        aa_resource:,
+        q: nil,
+        order: nil,
+        allow_q_keys: [],
+        field_grants: {},
+        infer_field_grants: true
+      )
+        allow = Array(allow_q_keys).map(&:to_s)
+        grants = merge_field_grants(aa_resource, field_grants, infer: infer_field_grants)
+
+        normalize_q(q).each_key do |raw_key|
+          key = raw_key.to_s
+          next if allow.include?(key)
+
+          field_name = field_from_predicate_key(key)
+          unless field_name
+            raise ::GraphQL::ExecutionError, "unsupported collection filter key #{key.inspect}"
+          end
+
+          assert_field_filterable!(context, aa_resource, field_name, grants)
+        end
+
+        assert_order_filterable!(context, aa_resource, order, grants) if order.present?
+      end
+
+      def merge_field_grants(aa_resource, field_grants, infer: true)
+        explicit = field_grants.to_h.transform_keys(&:to_s).transform_values(&:to_sym)
+        return explicit unless infer
+
+        inferred = aa_resource.graphql_config.field_capabilities.to_h do |name, capability|
+          [name.to_s, capability.to_sym]
+        end
+        inferred.merge(explicit)
+      end
+
+      def normalize_q(q)
+        return {} if q.nil?
+        return q.to_unsafe_h if q.respond_to?(:to_unsafe_h)
+
+        q.respond_to?(:to_h) ? q.to_h : {}
+      end
+
+      def field_from_predicate_key(key)
+        predicates = ransack_predicate_names
+        predicates.sort_by(&:length).reverse_each do |predicate|
+          suffix = "_#{predicate}"
+          return key[0...-suffix.length] if key.end_with?(suffix) && key.length > suffix.length
+        end
+        nil
+      end
+
+      def ransack_predicate_names
+        if defined?(Ransack) && Ransack.respond_to?(:predicates)
+          Ransack.predicates.keys.map(&:to_s)
+        else
+          %w[eq cont start end gt lt gteq lteq in not_in null present blank matches does_not_match]
+        end
+      end
+
+      def assert_order_filterable!(context, aa_resource, order, grants)
+        column = order.to_s.sub(/_(asc|desc|ascs|descs)\z/i, "")
+        return if column.blank?
+
+        assert_field_filterable!(context, aa_resource, column, grants)
+      end
+
+      def assert_field_filterable!(context, aa_resource, field_name, grants)
+        unless field_schema_visible?(context, aa_resource, field_name)
+          raise ::GraphQL::ExecutionError, "not authorized to filter on #{field_name}"
+        end
+
+        capability = grants[field_name.to_s]
+        return if capability.nil?
+        return if Capability.granted?(context, capability)
+
+        raise ::GraphQL::ExecutionError, "not authorized to filter on #{field_name}"
+      end
+
+      def field_schema_visible?(context, aa_resource, field_name)
+        type_name = graphql_type_name_for(aa_resource)
+        type = context.schema.get_type(type_name, context)
+        return false unless type
+
+        !context.schema.get_field(type, field_name.to_s, context).nil?
+      end
+
+      def graphql_type_name_for(aa_resource)
+        aa_resource.graphql_config.graphql_type_name.presence ||
+          aa_resource.resource_class.name.delete_prefix("::").gsub("::", "__")
+      end
+    end
+  end
+end

data/lib/active_admin/graphql/integration.rb

@@ -26,6 +26,12 @@ module ActiveAdmin
 
       def register_namespace_settings!
         ns = ActiveAdmin::NamespaceSettings
+        register_surface_namespace_settings!(ns)
+        register_capability_namespace_settings!(ns)
+        register_limit_namespace_settings!(ns)
+      end
+
+      def register_surface_namespace_settings!(ns)
         ns.register :graphql, false
         # true preserves 0.3.x: every ActiveRecord resource is in the schema once the namespace endpoint is on.
         # Set false for opt-in per resource (empty graphql block or enable!).
@@ -45,8 +51,26 @@ module ActiveAdmin
         ns.register :graphql_visibility, nil
         ns.register :graphql_visibility_profile, nil
         ns.register :graphql_schema_visible, nil
+      end
+
+      def register_capability_namespace_settings!(ns)
         # Optional Proc +(context_hash) -> Enumerable+ of capability names (RFC 0008).
         ns.register :graphql_capabilities, nil
+        # RFC 0009: default field capability mode (:omit or :null).
+        ns.register :graphql_field_capability_mode_default, :omit
+        # RFC 0009: optional Proc +(context, meta) -> Boolean+ to omit object/root fields.
+        ns.register :graphql_field_visible, nil
+        # RFC 0010: optional Proc +(context, meta) -> void+ after run-action outcomes.
+        ns.register :graphql_run_action_audit, nil
+        # RFC 0011: optional Proc +(context, meta) -> void+ at collection resolve start.
+        ns.register :graphql_collection_query_policy, nil
+        # RFC 0012: optional default capabilities for run-action mutation fields.
+        ns.register :graphql_member_action_capability_default, nil
+        ns.register :graphql_batch_action_capability_default, nil
+        ns.register :graphql_collection_action_capability_default, nil
+      end
+
+      def register_limit_namespace_settings!(ns)
         ns.register :graphql_max_complexity, 300
         ns.register :graphql_max_depth, 18
         ns.register :graphql_batch_action_max_ids, 5000

data/lib/active_admin/graphql/member_action_capability.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module ActiveAdmin
+  module GraphQL
+    # Compatibility wrapper around {RunActionCapability} for member actions (RFC 0012).
+    module MemberActionCapability
+      module_function
+
+      def resolve(namespace, aa_res, action_name = nil)
+        RunActionCapability.resolve(namespace, aa_res, :member, action_name)
+      end
+    end
+  end
+end

data/lib/active_admin/graphql/member_action_dry_run.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module ActiveAdmin
+  module GraphQL
+    # Preview context and resolve helpers for +member_action_mutation dry_run:+ (RFC 0010).
+    class MemberActionDryRun
+      PreviewContext = RunActionPreview
+
+      def self.resolve(
+        aa_res,
+        proxy:,
+        context:,
+        action:,
+        id:,
+        params_h:,
+        extras:,
+        per:,
+        dry_run:
+      )
+        new(aa_res, proxy:, context:, action:, id:, params_h:, extras:, per:, dry_run:).call
+      end
+
+      def initialize(aa_res, proxy:, context:, action:, id:, params_h:, extras:, per:, dry_run:)
+        @aa_res = aa_res
+        @proxy = proxy
+        @context = context
+        @action = action
+        @id = id
+        @params_h = params_h
+        @extras = extras
+        @per = per
+        @dry_run = dry_run
+      end
+
+      def call
+        record = @proxy.find_member(@id)
+        preview_result = run_preview(record)
+
+        if @dry_run
+          result = preview_result || default_dry_run_result(record)
+          audit!(result, dry_run: true)
+          return result
+        end
+
+        if preview_result && !preview_result.ok
+          audit!(preview_result, dry_run: false)
+          return preview_result
+        end
+
+        result = run_action
+        audit!(result, dry_run: false)
+        result
+      end
+
+      private
+
+      def run_preview(record)
+        return nil unless @per.preview_proc
+
+        PreviewContext.new.instance_exec(
+          record,
+          proxy: @proxy,
+          context: @context,
+          aa_resource: @aa_res,
+          auth: @context[:auth],
+          action: @action,
+          id: @id,
+          params: @params_h,
+          **@extras,
+          &@per.preview_proc
+        )
+      end
+
+      def default_dry_run_result(record)
+        body = if record
+          "would_run:#{@action}:#{record.id}"
+        else
+          "would_run:#{@action}"
+        end
+        RunActionPayload::Result.new(ok: true, status: 200, location: nil, body: body)
+      end
+
+      def run_action
+        resolve = @per.resolve_proc || @aa_res.graphql_config.member_run_action.resolve_proc
+        if resolve
+          resolve.call(
+            proxy: @proxy,
+            context: @context,
+            aa_resource: @aa_res,
+            auth: @context[:auth],
+            action: @action,
+            id: @id,
+            params: @params_h,
+            **@extras
+          )
+        else
+          @proxy.run_member_action(@action, @id, extra_params: @params_h)
+        end
+      end
+
+      def audit!(result, dry_run:)
+        hook = @context[:namespace]&.graphql_run_action_audit
+        return if hook.nil?
+
+        hook.call(
+          @context,
+          {
+            action: @action,
+            id: @id,
+            status: result.respond_to?(:status) ? result.status : nil,
+            dry_run: dry_run,
+            ok: result.respond_to?(:ok) ? result.ok : nil,
+            reason: result.respond_to?(:body) ? result.body : nil
+          }
+        )
+      rescue
+        nil
+      end
+    end
+  end
+end

data/lib/active_admin/graphql/resource_capability_dsl.rb

@@ -4,7 +4,7 @@ require_relative "capability_definition_dsl"
 
 module ActiveAdmin
   module GraphQL
-    # +capability+ entry on {ResourceDefinitionDSL} (RFC 0008).
+    # +capability+ entry on {ResourceDefinitionDSL} (RFC 0008, RFC 0009).
     module ResourceCapabilityDSL
       def capability(
         name,
@@ -14,10 +14,11 @@ module ActiveAdmin
         member_actions: nil,
         batch_actions: nil,
         collection_actions: nil,
+        mode: nil,
         &block
       )
-        body = CapabilityDefinitionDSL.new(@config, name)
-        body.fields(*fields) if fields
+        body = CapabilityDefinitionDSL.new(@config, name, mode: mode)
+        body.fields(*fields, mode: mode) if fields
         body.queries(*queries) if queries
         body.mutations(*mutations) if mutations
         body.member_actions(*member_actions) if member_actions

data/lib/active_admin/graphql/resource_capability_maps.rb

@@ -2,12 +2,16 @@
 
 module ActiveAdmin
   module GraphQL
-    # Capability → member maps on {ResourceConfig} (RFC 0008).
+    # Capability → member maps on {ResourceConfig} (RFC 0008, RFC 0009).
     module ResourceCapabilityMaps
       def field_capabilities
         @field_capabilities ||= {}
       end
 
+      def field_capability_modes
+        @field_capability_modes ||= {}
+      end
+
       def query_capabilities
         @query_capabilities ||= {}
       end
@@ -20,6 +24,10 @@ module ActiveAdmin
         field_capabilities[name.to_sym]
       end
 
+      def capability_mode_for_field(name)
+        field_capability_modes[name.to_sym]
+      end
+
       def capability_for_query(kind)
         query_capabilities[kind.to_sym]
       end
@@ -28,8 +36,18 @@ module ActiveAdmin
         mutation_capabilities[kind.to_sym]
       end
 
-      def assign_field_capabilities!(capability_name, names)
+      def assign_field_capabilities!(capability_name, names, mode: nil)
         assign_capabilities!(field_capabilities, capability_name, names, label: "field")
+        return if mode.nil?
+
+        resolved = mode.to_sym
+        unless %i[omit null].include?(resolved)
+          raise ArgumentError, "capability mode must be :omit or :null, got #{mode.inspect}"
+        end
+
+        names.flatten.each do |name|
+          field_capability_modes[name.to_sym] = resolved
+        end
       end
 
       def assign_query_capabilities!(capability_name, names)

data/lib/active_admin/graphql/resource_definition_dsl.rb

@@ -103,21 +103,32 @@ module ActiveAdmin
       end
 
       # Pair +type+ and +resolve+ for +posts_batch_action+ (graphql-ruby-style block).
-      def batch_action_mutation(&block)
-        RunActionMutationDSL.new(@config.batch_run_action).instance_exec(&block)
+      # +capability:+ overrides the resource map / namespace default for the aggregate field (RFC 0012).
+      def batch_action_mutation(capability: nil, &block)
+        cfg = @config.batch_run_action
+        cfg.capability = capability.to_sym if capability
+        RunActionMutationDSL.new(cfg).instance_exec(&block) if block
+        cfg
       end
 
       # With no name: configures the aggregate +posts_member_action(action: …)+ field.
       # With a symbol/string: configures +posts_member_<action>+ (one field per +member_action+), so each
       # action can use its own +type+, +resolve+, +arguments+, and GraphQL inputs.
-      def member_action_mutation(name = nil, &block)
+      # +dry_run:+ / +capability:+ apply to named per-action fields (RFC 0010, RFC 0012).
+      def member_action_mutation(name = nil, dry_run: false, capability: nil, &block)
         cfg = name.nil? ? @config.member_run_action : @config.member_action_mutation_for(name)
-        RunActionMutationDSL.new(cfg).instance_exec(&block)
+        cfg.dry_run = true if dry_run
+        cfg.capability = capability.to_sym if capability
+        RunActionMutationDSL.new(cfg).instance_exec(&block) if block
+        cfg
       end
 
-      def collection_action_mutation(name = nil, &block)
+      def collection_action_mutation(name = nil, dry_run: false, capability: nil, &block)
         cfg = name.nil? ? @config.collection_run_action : @config.collection_action_mutation_for(name)
-        RunActionMutationDSL.new(cfg).instance_exec(&block)
+        cfg.dry_run = true if dry_run
+        cfg.capability = capability.to_sym if capability
+        RunActionMutationDSL.new(cfg).instance_exec(&block) if block
+        cfg
       end
 
       # Default return type for all run-action fields unless a kind-specific +type+ is set inside