activeadmin-graphql 0.3.1 → 0.3.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5fc45489403fdf5c4d16bd66966cc4c7c5641440663d3f5b229b0d627a0d0978
-  data.tar.gz: '04786131baffbec749af13c347660836c1ca31efa074c73eddfc49c5fbfb588e'
+  metadata.gz: 36bec145bd90193ae32e34aa54b7a6ed01dff13a8b104269b771f797262b2480
+  data.tar.gz: 82724e08af33a67a1a9146813965e5d836006620ff503099842addcdeaab16cb
 SHA512:
-  metadata.gz: 1c93c24f91a208c8eb00076d1fd3d8b398c99d155a8ce92f4aaa075b6615ea321a3303b2186e85fa32178a4e8ad158fb4ab1f081752993c6a44e5466fad1ac83
-  data.tar.gz: f5c1acc62e5f1aa0cd925234c4df76d9870dd592cb97aeae7927df578340d70936e02bcf727635a8f07d7caacfb84316e037383c7666b35cb472d11b8776240e
+  metadata.gz: 0b9ddc6e9d85447807e5cbbf9d1e5c9b5c87b756eaa8325cb57fe8ce291e221b40e1afd200ddb683a73cba036b83b6eac6f8f5ab3e0ff9788c1864e7f550cc16
+  data.tar.gz: 806443d03640f31e48d893998cd9f693bafd5efce162798ff406ed2eee2ad43d7c0c588467b8fbd37fdab4a3a6049a9efcbadffbe337469cac7bc5ff958bf36f

data/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 ## Unreleased
 
+## 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)
+
+- Add `graphql { identity ... }` so keyless views can declare GraphQL id columns, optional `separator`, and `encode` / `decode` (RFC 0007).
+- Fail schema build when a registered model has neither a primary key nor an `id` column and no `identity` declaration; set `self.primary_key`, use `identity`, or `graphql { disable! }`.
+
 ## 0.3.1 (2026-10-10)
 
 - Fix GraphQL identity handling for database views and nonconventional primary keys: keep one `id` field, support inferred `id` lookups, reject ambiguous identifiers, and honor attribute filters.

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/20261010101500_nonconventional-id-fields.md

@@ -11,7 +11,10 @@ primary key is blank. Object types skip emitting a column field named `id`
 (interface owns GraphQL `id`) and expose a single non-`id` primary-key column
 as a readable scalar unless the resource's attribute configuration omits it.
 Models with neither a primary key nor an `id` column fail schema build with an
-`ArgumentError` that asks for `self.primary_key`. Inferred `id` values must be
+`ArgumentError` that asks for `self.primary_key`. On 0.3.0 those models could
+still enter the schema with a broken GraphQL `id`. Apps that keep such a
+resource registered must set `self.primary_key` or use `graphql { disable! }`
+so the rest of the namespace schema still builds. Inferred `id` values must be
 unique and non-null; ambiguous member and batched lookups fail closed.
 
 Member lookup uses the inferred column while preserving an explicitly
@@ -21,9 +24,19 @@ entries for distinct records when ActiveRecord has no declared primary key.
 Dummy coverage includes SQLite views that project `code AS id` and
 `id AS row_key`, plus a table with an `id` column and no primary key.
 
+## Later pass 2026-10-10
+
+Downstream check: a database view with neither primary key nor `id` column
+could stay GraphQL-disabled via `graphql { disable! }`. Spec covers that
+escape hatch next to the ArgumentError path.
+
+Later the same day: RFC 0007 adds `graphql { identity ... }` so those views
+can stay enabled when columns (and optional separator) are declared. See
+docs/changelogs/20261010110600_graphql-identity-dsl.md.
+
 ## Next
 
-Folded into 0.3.1 release metadata. Tag and gem push wait on make release.
+Core fix shipped in 0.3.1. Identity DSL follow-on is 0.3.2.
 
 ## Source
 
@@ -32,3 +45,4 @@ Folded into 0.3.1 release metadata. Tag and gem push wait on make release.
   `spec/unit/resource_query_proxy_identity_spec.rb`,
   `spec/unit/policy_set_cache_spec.rb`
 - Views: `spec/dummy/db/schema.rb` (`string_id_records`, `alternate_key_records`)
+- Follow-on: docs/changelogs/20261010110600_graphql-identity-dsl.md

data/docs/changelogs/20261010103800_release-0-3-1.md

@@ -6,7 +6,11 @@ Andrei Makarov
 
 ## Decisions
 
-Cut 0.3.1 after published 0.3.0. One user-visible fix: GraphQL identity for database views and nonconventional primary keys.
+Cut 0.3.1 after published 0.3.0. User-visible work: GraphQL identity for
+database views and nonconventional primary keys; fail-closed when a model has
+neither a primary key nor an `id` column without configuration; and
+`graphql { identity ... }` (RFC 0007) for keyless views with a virtual
+composite id.
 
 CHANGELOG 0.3.1 dated 2026-10-10. Version constant is 0.3.1. Path gem pins in Gemfile.lock and appraisal lockfiles match.
 
@@ -24,9 +28,12 @@ PATH specs for activeadmin-graphql in Gemfile.lock, gemfiles/rails72.gemfile.loc
 
 ## Next
 
-Run make release from a clean tree when ready to push the gem and tag 0.3.1.
+0.3.1 tagged and published on RubyGems. Post-tag identity DSL work ships in
+0.3.2; see docs/changelogs/20261010111800_release-0-3-2.md.
 
 ## Source
 
 docs/changelogs/20261010101500_nonconventional-id-fields.md
+docs/changelogs/20261010110600_graphql-identity-dsl.md
+rfcs/0007-graphql-identity.md
 usr/bin/release.rb

data/docs/changelogs/20261010110600_graphql-identity-dsl.md

@@ -0,0 +1,34 @@
+# GraphQL identity DSL (RFC 0007)
+
+## Decisions
+
+Ship `graphql { identity *columns, separator:, encode:, decode: }` so resources
+without an ActiveRecord primary key and without an `id` column can stay in the
+schema. Prefer resource configuration over forcing `self.primary_key`.
+
+Separator form matches HTML admins that use a virtual `id` method such as
+`[entry_type, entry_id, event_type].join(":")`. Without separator, multi-column
+identity keeps the existing composite JSON string.
+
+## Effects
+
+Schema build, member lookup, mutations that resolve by where/id, and policy
+cache keys go through `ActiveAdmin::GraphQL::ResourceIdentity` when identity is
+configured. Ambiguous matches still fail closed.
+
+Dummy coverage: view `alert_events` / model `AlertEvent` with virtual composite
+`id`.
+
+## Next
+
+Folded into 0.3.2 release metadata (0.3.1 already published without this DSL).
+Tag and gem push wait on make release.
+
+## Source
+
+rfcs/0007-graphql-identity.md
+docs/changelogs/20261010101500_nonconventional-id-fields.md
+docs/issues/20261010111159_rails-composite-primary-keys-alignment.md
+https://guides.rubyonrails.org/active_record_composite_primary_keys.html
+spec/unit/resource_identity_spec.rb
+spec/requests/graphql_identity_dsl_spec.rb

data/docs/changelogs/20261010111800_release-0-3-2.md

@@ -0,0 +1,46 @@
+# Release 0.3.2 metadata
+
+## Participants
+
+Andrei Makarov
+
+## Decisions
+
+Cut 0.3.2 after published 0.3.1. User-visible work since the 0.3.1 tag:
+`graphql { identity ... }` (RFC 0007) for keyless views, and schema-build
+error text that names `identity` alongside `self.primary_key` and `disable!`.
+
+CHANGELOG 0.3.1 restored to the published one-bullet text. Identity DSL bullets
+live under 0.3.2 dated 2026-10-10.
+
+Version constant is 0.3.2. Path gem pins in Gemfile.lock and appraisal
+lockfiles match.
+
+Docs-only notes (Rails composite PK alignment, partitions/shards unsupported,
+federation unsupported) stay 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.2.
+
+CHANGELOG identity DSL bullets moved from the post-tag 0.3.1 draft under 0.3.2.
+
+PATH specs for activeadmin-graphql in Gemfile.lock,
+gemfiles/rails72.gemfile.lock, gemfiles/rails8ruby4.gemfile.lock, and
+gemfiles/rails8ruby34.gemfile.lock are 0.3.2.
+
+## Next
+
+Run make release from a clean tree when ready to push the gem and tag 0.3.2.
+
+## Source
+
+docs/changelogs/20261010110600_graphql-identity-dsl.md
+rfcs/0007-graphql-identity.md
+docs/issues/20261010111159_rails-composite-primary-keys-alignment.md
+docs/issues/20261010111300_partitions-and-shards-support.md
+docs/issues/20261010111500_graphql-federation-support.md
+usr/bin/release.rb

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/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,11 @@ 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_configure_schema` — `Proc` receiving the schema class after build
   (extensions, extra types, and so on).
 
@@ -199,21 +237,90 @@ 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.
+`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).
+
 ## 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):
@@ -229,12 +336,28 @@ GraphQL `id` always comes from `ActiveAdminResource` (`ID!`). An ActiveRecord
 `id` column is never added as a second field. When `self.primary_key` is blank
 but the model still has an `id` column (common for database views that project
 `… AS id`), that column supplies the GraphQL `id` value. When the model has
-neither a primary key nor an `id` column, schema build raises until you set
-`self.primary_key` on the model (for example a view keyed by `row_key`). A
-single-column primary key named something other than `id` is also exposed as
-its own readable field beside `id`, unless `only` or `exclude` omits it. An
-inferred `id` column must contain a unique, non-null value for every row;
-ambiguous member and batched lookups fail instead of selecting one row.
+neither a primary key nor an `id` column, declare GraphQL identity on the
+resource (RFC 0007), set `self.primary_key` on the model, or omit the resource
+with `graphql { disable! }`. A single-column primary key named something other
+than `id` is also exposed as its own readable field beside `id`, unless `only`
+or `exclude` omits it. An inferred `id` column must contain a unique, non-null
+value for every row; ambiguous member and batched lookups fail instead of
+selecting one row.
+
+```ruby
+# View with no PK and no id column; virtual identity matches HTML admin.
+ActiveAdmin.register AlertEvent do
+  graphql do
+    identity :entry_type, :entry_id, :event_type, separator: ":"
+    # optional: encode: ->(record) { record.id }, decode: ->(id) { ... }
+  end
+end
+```
+
+With `separator: ":"`, GraphQL `id` is `entry_type:entry_id:event_type`. Keep
+the model’s `def id` (if any) in the same shape so HTML and GraphQL share
+member ids. Without `separator`, multi-column identity uses the same JSON
+object string as composite ActiveRecord primary keys.
 
 ### Composite primary keys (Rails 7.1+)
 
@@ -242,8 +365,10 @@ For models with `self.primary_key = [:book_code, :seq]` (and no separate `id`
 column), Active Admin treats GraphQL as follows:
 
 * `id` on the object type — JSON object string with all key columns in
-  model order (same format Rails uses when casting composite ids), for example
-  `{"book_code":"CPK","seq":7}`.
+  model order, for example `{"book_code":"CPK","seq":7}`. This is the GraphQL
+  wire format. It is not the Rails form/URL underscore packing described in
+  the Composite Primary Keys guide (`/books/2_25` with
+  `params.extract_value(:id)`).
 * Readable fields — each primary-key column is also exposed as its own field
   (in addition to `id`) so clients can load scalars without parsing JSON.
 * `LibraryEditionWhereInput` (and similar) — either optional `id` (that JSON
@@ -255,12 +380,20 @@ column), Active Admin treats GraphQL as follows:
   inputs (unlike single `id` tables, where the key is omitted from assignable
   attributes).
 
-For REST/HTML member routes, `ResourceController#find_resource` must resolve composite ids from `params[:id]` (JSON string) or from individual primary-key params. Stock ActiveAdmin 3.x only passes a single `params[:id]` into `find`; an ActiveAdmin fork (or patch) that implements composite-aware `find_resource` keeps the admin UI aligned with GraphQL. The GraphQL layer also works with `ActiveAdmin::GraphQL::ResourceQueryProxy` using Rails’ tuple id convention for `Relation#find`.
+For REST/HTML member routes, `ResourceController#find_resource` must resolve
+composite ids from `params[:id]` or from individual primary-key params. Stock
+ActiveAdmin 3.x only passes a single `params[:id]` into `find`; an ActiveAdmin
+fork (or patch) that implements composite-aware `find_resource` keeps the
+admin UI aligned with GraphQL. After decoding the GraphQL JSON `id`, the gem
+uses Rails’ array/tuple conventions for `Relation#find` and
+`where(primary_key => [tuple, …])` as in the guide.
 
-The gem ships `ActiveAdmin::PrimaryKey` when the core constant is missing (upstream). A fork may define `PrimaryKey` and extended `find_resource` in `ResourceController` instead.
+The gem ships `ActiveAdmin::PrimaryKey` when the core constant is missing
+(upstream). A fork may define `PrimaryKey` and extended `find_resource` in
+`ResourceController` instead.
 
-`ActiveAdmin::GraphQL::RecordSource` batch-loads composite associations using
-Rails `where(primary_key => [tuple, …])`.
+Alignment notes versus the Rails guide:
+`docs/issues/20261010111159_rails-composite-primary-keys-alignment.md`.
 
 ### Collection query arguments
 
@@ -359,6 +492,7 @@ Inside `ActiveAdmin.register` you can narrow the GraphQL surface:
 ActiveAdmin.register Post do
   graphql do
     disable!                          # omit this resource from the schema
+    # identity :entry_type, :entry_id, :event_type, separator: ":"  # RFC 0007
     type_name "BlogPost"              # GraphQL object / mutation type basename (`graphql_name` alias)
     only :title, :body, :published_at # expose only these attributes on queries
     exclude :internal_score           # or `except` / `exclude`
@@ -378,7 +512,19 @@ 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).
 * `type_name` (or `graphql_name`) — overrides the default GraphQL type name
   derived from the model (object types, mutations, and Rails enum GraphQL
   types use this basename).