activeadmin-graphql 0.3.2 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 95e56a00a0c78ea55f44c186012af72c1ba6ff80ada2adbf905ce9b2d190c47d
-  data.tar.gz: 1e1dc89e1ffd41d05c6f2962a83857188a239ba677e6f492dbc304a09bb123b9
+  metadata.gz: c03a6abe474dea238c1dec40f75bb03b2f3203e4874d4639e2327a0562c9a9ce
+  data.tar.gz: 3bb9bd9cf8b55e796cf87cf8f51dca817b41b5ae9a515132ff0e56a218afe6db
 SHA512:
-  metadata.gz: 02533503de4c86355e28bc7212115b043a9d7da293db40d1134251f7892539fca8257d6c03140c110d12da8e4de1b4112668c7e6fc2d721273c990d9fff930e3
-  data.tar.gz: 6e13f9a69b6cc7df900cf9883ab60600be21bfea50196209c7324306030d74784cb3e66082ffc3ec225192c3c0c385fffb3f24840061e9f12415b60479de9d3c
+  metadata.gz: 9e0a6930217123a83432a072410be640d618371c062eb83e27c86786461218f4d48d524edd9a7c00749914ac3c216d015d565fbc60a7f5fcdf7fc0d2f57d48b7
+  data.tar.gz: 639363956ab8b19349df04e7a5c5f9f6610705206b3d7d8f82838cde74b4dc10ab5e7b53f993def3c2de016885d1a1ecd267698252b877f655c87b49ef1a8f9f

data/CHANGELOG.md

@@ -1,6 +1,32 @@
 # 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)
+
+- Add `graphql { capability ... }` and namespace `graphql_capabilities` so one named grant can gate many fields, queries, and mutations (RFC 0008).
+- Apply `fields:` capabilities to wired `belongs_to` associations; reject unknown capability field names and named visibility `profiles:` combined with `graphql_capabilities`.
+- Add namespace setting `graphql_resource_enabled_default` (`true` by default) and `graphql { enable! }` so apps can opt resources into the schema instead of opting out with `disable!`.
+- Add namespace toggles for `registered_resource` and `belongs_to` wiring (`graphql_registered_resource_enabled`, `graphql_belongs_to_associations_enabled`; both `true` by default).
+- Add `graphql_policies_enabled` / `graphql_policies_enabled_default` for policy field publishing and per-resource seeds, plus `graphql_policy_adapter` (default `ActiveAdmin::GraphQL::PolicyAdapter`) for payload construction.
+- Add per-resource surface defaults and DSL (`graphql_queries_enabled_default`, `graphql_mutations_enabled_default`, `graphql_run_actions_enabled_default`, plus `enable_*!` / `disable_*!`) so apps can trim list/show, CRUD, run-action, and policy fields without disabling the whole resource.
+- Treat `queries_enabled` as the read surface: omit `registered_resource` union membership when queries are off; fail schema build when `Query` would have no fields.
 
 ## 0.3.2 (2026-10-10)
 

data/app/controllers/active_admin/graphql_controller.rb

@@ -51,16 +51,31 @@ module ActiveAdmin
 
     def graphql_context
       ns = active_admin_namespace
-      {
+      context = {
         auth: ActiveAdmin::GraphQL::AuthContext.new(
           user: current_active_admin_user,
           namespace: ns
         ),
         namespace: ns,
         request: request,
-        current_user: current_active_admin_user,
-        visibility_profile: graphql_visibility_profile_for(ns)
-      }.compact
+        current_user: current_active_admin_user
+      }
+      # Named visibility profiles cache a fixed context; per-request capabilities
+      # need the live request context (dynamic visibility). Skip the profile key.
+      unless ns.graphql_capabilities.respond_to?(:call)
+        profile = graphql_visibility_profile_for(ns)
+        context[:visibility_profile] = profile if profile
+      end
+      capabilities = graphql_capabilities_for(ns, context)
+      context[:capabilities] = capabilities unless capabilities.nil?
+      context
+    end
+
+    def graphql_capabilities_for(ns, context)
+      hook = ns.graphql_capabilities
+      return nil unless hook.respond_to?(:call)
+
+      ActiveAdmin::GraphQL::Capability.normalize_set(hook.call(context))
     end
 
     def graphql_visibility_profile_for(ns)

data/docs/changelogs/20261010091415_graphql-resource-enabled-default.md

@@ -0,0 +1,34 @@
+# GraphQL resource enabled default
+
+## Participants
+
+Andrei Makarov
+
+## Decisions
+
+Add namespace setting `graphql_resource_enabled_default`, default `true`, so
+0.3.x behavior stays: turning on the namespace endpoint still includes every
+ActiveRecord resource unless `graphql { disable! }` is set.
+
+Apps that want support-style opt-in set the setting to `false`. Then a resource
+enters the schema only when registration runs `graphql { }` or
+`graphql { enable! }`. `disable!` still omits.
+
+`ResourceConfig` takes the initial `enabled` flag from the namespace setting.
+Entering a `graphql` block sets `enabled = true` before the block body runs so
+an empty block is a conscious opt-in.
+
+## Effects
+
+New request specs cover default true, default false without a block, empty
+block, `enable!`, and `disable!`.
+
+## Next
+
+Folded into 0.3.3 release metadata.
+
+## Source
+
+CHANGELOG 0.3.3. docs/graphql-api.md namespace settings and per-resource
+DSL. spec/requests/graphql_resource_enabled_default_spec.rb.
+docs/changelogs/20261012113500_release-0-3-3.md.

data/docs/changelogs/20261012050051_graphql-surface-toggles.md

@@ -0,0 +1,40 @@
+# GraphQL surface toggles
+
+## Participants
+
+Andrei Makarov
+
+## Decisions
+
+Add namespace and per-resource controls for schema surfaces that were always on
+once a resource was enabled. Defaults stay `true` so 0.3.x behavior is
+unchanged.
+
+Namespace-only switches: `graphql_registered_resource_enabled`,
+`graphql_belongs_to_associations_enabled`, `graphql_policies_enabled`.
+Policy payloads use `graphql_policy_adapter` (default `PolicyAdapter`).
+Per-resource policy seed is `graphql_policies_enabled_default`.
+
+Per-resource seeds from namespace defaults: queries, mutations (CRUD),
+run-actions, and policies. Resource DSL exposes matching `enable_*!` /
+`disable_*!` methods. `queries_enabled` also gates `registered_resource`
+membership. Schema build raises if `Query` would have no fields.
+
+## Effects
+
+Schema builder skips policy query fields, registered_resource union, belongs_to
+wiring, list/show fields, CRUD mutations, and run-action mutations when the
+matching flag is off. Request specs cover the new settings and DSL, including
+empty-Query rejection and registered_resource gating by queries.
+
+## Next
+
+Folded into 0.3.3 release metadata.
+
+## Source
+
+CHANGELOG 0.3.3. docs/graphql-api.md.
+spec/requests/graphql_surface_toggles_spec.rb.
+spec/requests/graphql_policy_surface_spec.rb.
+spec/requests/graphql_query_surface_contract_spec.rb.
+docs/changelogs/20261012113500_release-0-3-3.md.

data/docs/changelogs/20261012064500_graphql-capabilities.md

@@ -0,0 +1,35 @@
+# GraphQL capabilities
+
+## Participants
+
+Andrei Makarov
+
+## Decisions
+
+Add RFC 0008 capability grants. Resource DSL `capability` associates many
+object fields, queries, and mutations with one name. Namespace
+`graphql_capabilities` fills `context[:capabilities]` per request. SchemaField
+checks capability in `visible?` and `authorized?`. Capabilities do not replace
+ActiveAdmin authorization. Subscriptions stay out of scope.
+
+## Effects
+
+Gated members fail closed without the grant. With `graphql_visibility`,
+introspection omits them. Aggregate run-action resolvers also check
+per-action capability keys (`member_*`, `batch_*`, `collection_*`).
+`belongs_to` association fields honor `fields:` capabilities. Schema build
+rejects unknown capability field names and rejects named visibility profiles
+combined with `graphql_capabilities` (dynamic visibility required).
+
+## Next
+
+Folded into 0.3.3 release metadata. Follow-ons remain: policy payloads listing
+field capabilities, mutation input attribute maps, and transport gates if
+subscriptions ship later.
+
+## Source
+
+RFC 0008. CHANGELOG 0.3.3. docs/graphql-api.md. spec/unit/capability_spec.rb,
+spec/unit/capability_dsl_spec.rb, spec/requests/graphql_capabilities_spec.rb,
+spec/requests/graphql_capabilities_edge_spec.rb.
+docs/changelogs/20261012113500_release-0-3-3.md.

data/docs/changelogs/20261012113500_release-0-3-3.md

@@ -0,0 +1,45 @@
+# Release 0.3.3 metadata
+
+## Participants
+
+Andrei Makarov
+
+## Decisions
+
+Cut 0.3.3 after published 0.3.2. User-visible work since the 0.3.2 tag:
+`graphql_resource_enabled_default` and `enable!` opt-in, surface toggles for
+queries, mutations, run-actions, policies, `registered_resource`, and
+`belongs_to`, plus GraphQL capabilities (RFC 0008). Defaults stay `true` so
+0.3.x schema shape is unchanged unless an app opts in to narrower surfaces.
+
+CHANGELOG Unreleased bullets moved under 0.3.3 dated 2026-10-12.
+
+Version constant is 0.3.3. Path gem pins in Gemfile.lock and appraisal
+lockfiles match.
+
+Internal `stringify_attrs` safe-navigation cleanup stays out of CHANGELOG.md.
+
+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.3.3.
+
+CHANGELOG surface-toggle and capability bullets live under 0.3.3.
+
+PATH specs for activeadmin-graphql in Gemfile.lock,
+gemfiles/rails72.gemfile.lock, gemfiles/rails8ruby4.gemfile.lock, and
+gemfiles/rails8ruby34.gemfile.lock are 0.3.3.
+
+## Next
+
+Run make release from a clean tree when ready to push the gem and tag 0.3.3.
+
+## Source
+
+docs/changelogs/20261010091415_graphql-resource-enabled-default.md
+docs/changelogs/20261012050051_graphql-surface-toggles.md
+docs/changelogs/20261012064500_graphql-capabilities.md
+rfcs/0008-graphql-capabilities.md
+usr/bin/release.rb

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

@@ -33,6 +33,12 @@ ActiveAdmin.setup do |config|
     admin.graphql = true
     # Optional — default is "graphql", i.e. POST /admin/graphql
     # admin.graphql_path = "graphql"
+    # Optional — set false so only resources with a graphql block enter the schema
+    # admin.graphql_resource_enabled_default = false
+    # Optional — trim always-on surfaces for a narrow API
+    # admin.graphql_policies_enabled = false
+    # admin.graphql_registered_resource_enabled = false
+    # admin.graphql_belongs_to_associations_enabled = false
   end
 end
 ```
@@ -45,6 +51,33 @@ Run `bin/rails active_admin:install` or reload routes if needed so
 Each namespace inherits these options (defaults in parentheses):
 
 * `graphql` — set to `true` to mount the endpoint (`false` by default).
+* `graphql_resource_enabled_default` — whether each registered ActiveRecord
+  resource is included in the schema without a `graphql` block (`true` by
+  default, matching 0.3.x). Set to `false` for opt-in: only resources that call
+  `graphql { }` (or `graphql { enable! }`) appear in the schema. `disable!`
+  still omits a resource.
+* `graphql_queries_enabled_default` — seed for per-resource read fields
+  (`true` by default): named list/show fields and membership in
+  `registered_resource` / `ActiveAdminRegisteredResource`. Set `false` and use
+  `enable_queries!` for opt-in reads. Object types may still exist for mutations.
+* `graphql_mutations_enabled_default` — seed for per-resource CRUD mutations
+  (`true` by default). Set `false` and use `enable_mutations!` for opt-in writes.
+* `graphql_run_actions_enabled_default` — seed for batch/member/collection
+  action mutations (`true` by default).
+* `graphql_policies_enabled` — publish `activeadmin_policies` query fields and
+  allow per-object policy fields (`true` by default).
+* `graphql_policies_enabled_default` — seed for per-resource `policies_enabled`
+  (`true` by default). Use `enable_policies!` / `disable_policies!` per resource.
+* `graphql_policy_adapter` — class that builds `activeadmin_policies` payloads
+  (`ActiveAdmin::GraphQL::PolicyAdapter` by default). Set a subclass (or constant
+  `String`) to replace payload logic; the default adapter still honors
+  `graphql_policy_actions` / `graphql_policy_action_mapper` /
+  `graphql_policy_extra` / `graphql_policy_transform`.
+* `graphql_registered_resource_enabled` — include `registered_resource` and the
+  `ActiveAdminRegisteredResource` union when at least one queryable resource
+  exists (`true` by default).
+* `graphql_belongs_to_associations_enabled` — wire non-polymorphic `belongs_to`
+  fields between registered resource types (`true` by default).
 * `graphql_path` — path segment under the namespace mount (`"graphql"`).
 * `graphql_multiplex_max` — maximum operations per multiplexed JSON array
   request (`20`).
@@ -70,6 +103,27 @@ Each namespace inherits these options (defaults in parentheses):
   default `context[:visibility_profile]` for each HTTP request (symbols accepted).
 * `graphql_schema_visible` — optional `Proc` `(context, meta) -> Boolean` when
   `graphql_visibility` is enabled; see Schema visibility below.
+* `graphql_capabilities` — optional `Proc` `(context) -> Enumerable` of capability
+  names for the request (RFC 0008). Normalized into `context[:capabilities]`.
+  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).
 
@@ -199,21 +253,103 @@ UI, including any `authorize!` or `authorize_resource!` calls.
 
 See the ActiveAdmin guide [Authorization adapter](https://activeadmin.info/13-authorization-adapter) for adapter setup; the same rules apply to GraphQL.
 
+Policy preflight fields (`activeadmin_policies`, `activeadmin_policies_for`, and
+per-object `activeadmin_policies`) are published when `graphql_policies_enabled`
+is true. Payloads come from `graphql_policy_adapter`. The default
+`ActiveAdmin::GraphQL::PolicyAdapter` asks the authorization adapter which
+actions are allowed and applies the optional `graphql_policy_*` hooks. Assign a
+subclass that implements `policy_set` (and optionally `include_resource?`) to
+replace the payload builder.
+
+### Capabilities (RFC 0008)
+
+Associate many object fields, queries, and mutations with one named capability
+inside `graphql do`. The same capability name can cover a mixed set of members:
+
+```ruby
+ActiveAdmin.register Post do
+  graphql do
+    capability :pii do
+      fields :body
+    end
+
+    capability :editor do
+      fields :title
+      queries :index, :show
+      mutations :create, :update, :destroy
+    end
+
+    capability :publish, member_actions: %i[publish]
+  end
+end
+```
+
+Kwargs (`fields:`, `queries:`, `mutations:`, `member_actions:`,
+`batch_actions:`, `collection_actions:`) work without a block. Query aliases:
+`index` / `list` → collection, `show` → member. Mutation alias: `delete` →
+`destroy`. Run-action sugar builds keys like `member_publish`.
+
+Grant capabilities per request with `graphql_capabilities`. Map OAuth scopes or
+roles there; the gem stores a symbol set on `context[:capabilities]`:
+
+```ruby
+admin.graphql_capabilities = lambda { |ctx|
+  Array(ctx[:current_user]&.oauth_scopes)
+}
+```
+
+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
+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` 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
 
-The `Query` type includes one Relay-style connection field per resource route
-(for example `posts`), plus a singular field for a single record (for example
-`post`). Optional `graphql_field` entries on `register_page` appear here too,
-plus `registered_resource` (returning the `ActiveAdminRegisteredResource` union)
-when at least one resource is exposed.
+With the default surface flags (`true`), the `Query` type includes one
+Relay-style connection field per resource route (for example `posts`), plus a
+singular field for a single record (for example `post`). Optional
+`graphql_field` entries on `register_page` appear here too, plus
+`registered_resource` (returning the `ActiveAdminRegisteredResource` union)
+when at least one queryable resource exists.
+
+List and show fields require per-resource `queries_enabled` (seeded from
+`graphql_queries_enabled_default`). Turning queries off still leaves the object
+type available for mutations. `registered_resource` and the union also require
+`graphql_registered_resource_enabled`. Policy preflight fields require
+`graphql_policies_enabled`. Schema build fails when `Query` would have no
+fields: no list/show, no policies, no `registered_resource`, and no page
+`graphql_field`.
 
 Every resource object type implements the `ActiveAdminResource` interface
 (`id: ID!`) so clients can share fragments or rely on a common shape.
+Non-polymorphic `belongs_to` fields between registered types are wired when
+`graphql_belongs_to_associations_enabled` is true.
 
 The `Mutation` type is present when at least one operation exists: per-resource
-`create_*`, `update_*`, and `delete_*` when those controller actions exist, plus
-`*_batch_action`, `*_member_action`, and `*_collection_action` fields when the
-resource defines the corresponding batch, member, or collection actions.
+`create_*`, `update_*`, and `delete_*` when those controller actions exist and
+`mutations_enabled` is true, plus `*_batch_action`, `*_member_action`, and
+`*_collection_action` fields when the resource defines the corresponding batch,
+member, or collection actions and `run_actions_enabled` is true. Both flags are
+seeded from the matching namespace defaults.
 
 Object type names default to the model name (for example `Post`). Typed input
 objects use assignable columns (see the per-resource section below):
@@ -405,7 +541,16 @@ ActiveAdmin.register Post do
 end
 ```
 
+* `enable!` — include this resource when `graphql_resource_enabled_default` is
+  `false`. An empty `graphql` block has the same effect.
 * `disable!` — resource is not included in Query or Mutation.
+* `enable_queries!` / `disable_queries!` — list/show fields and
+  `registered_resource` membership for this resource.
+* `enable_mutations!` / `disable_mutations!` — create/update/delete mutations.
+* `enable_run_actions!` / `disable_run_actions!` — batch/member/collection
+  action mutations.
+* `enable_policies!` / `disable_policies!` — object `activeadmin_policies` and
+  inclusion in the `activeadmin_policies` resources matrix.
 * `identity` — declare GraphQL id columns (and optional `separator`, `encode`,
   `decode`) when the model has no ActiveRecord primary key and no `id` column
   (RFC 0007).
@@ -456,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
@@ -467,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.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module ActiveAdmin
+  module GraphQL
+    # Named grants carried in GraphQL +context[:capabilities]+ (RFC 0008).
+    module Capability
+      module_function
+
+      def normalize_set(raw)
+        return nil if raw.nil?
+
+        Set.new(
+          Array(raw).filter_map do |item|
+            next if item.nil?
+
+            name = item.to_s.strip
+            next if name.empty?
+
+            name.to_sym
+          end
+        )
+      end
+
+      def granted?(context, capability_name)
+        return true if capability_name.nil?
+
+        caps = context[:capabilities]
+        return false if caps.nil?
+
+        caps = normalize_set(caps) unless caps.is_a?(Set)
+        caps.include?(capability_name.to_sym)
+      end
+    end
+  end
+end