feat(router): configure generic scope matching

CHANGELOG.md

@@ -14,6 +14,25 @@ This file is the authoritative user-facing release chronology. The former
 [release-notes ledger](docs/archive/2026/graphql-orm-release-notes.md) is retained
 for historical context.
 
+## 0.24.0 - 2026-08-22
+
+Companion macros crate: `graphql-orm-macros` **0.24.0**. Generated ORM and
+macro behavior is unchanged.
+
+- Updated the optional `auth-agql` dependency to `agql-auth` 0.16.0 at merged
+  revision `3bc38cd94794f1e868a9cc3a5551047b95a32105`. The bridge remains a
+  projection of an already accepted principal and does not select matcher
+  policy or gain token-issuer responsibilities.
+- Hosts that enable `auth-agql` and also depend directly on `agql-auth` must
+  use the same exact revision so public principal and assurance types resolve
+  from one source universe.
+- Collapsed an equivalent macro-generation branch and removed a redundant
+  doctest wrapper to remain warnings-clean under the pinned Clippy toolchain;
+  emitted tokens and the compile-fail probe are unchanged.
+
+No database, GraphQL SDL, generated-code, migration-history, backup, token, or
+stored-data migration is required.
+
 ## 0.23.0 - 2026-08-14
 
 Companion macros crate: `graphql-orm-macros` **0.23.0**. Backend-neutral

Cargo.toml

@@ -27,7 +27,7 @@ license = "MIT"
 repository = "https://github.com/Dastari/graphql-orm"
 
 [workspace.dependencies]
-agql-auth = { git = "https://github.com/Dastari/agql-auth.git", rev = "e841ffd382082ad7419be259fe957f949b956ff7", version = "0.15.0" }
+agql-auth = { git = "https://github.com/Dastari/agql-auth.git", rev = "3bc38cd94794f1e868a9cc3a5551047b95a32105", version = "0.16.0" }
 arc-swap = "1.7"
 async-graphql = { version = "7", features = ["dataloader", "uuid"] }
 async-graphql-parser = "7"
@@ -37,7 +37,7 @@ cynic-parser = { version = "=0.11.2", features = ["pretty"] }
 futures = "0.3"
 getrandom = "0.3"
 graphql-composition = "=0.12.2"
-graphql-orm = { path = "crates/graphql-orm", version = "0.23.0", default-features = false }
+graphql-orm = { path = "crates/graphql-orm", version = "0.24.0", default-features = false }
 graphql-orm-ai-tool-profiles = { path = "crates/graphql-orm-ai-tool-profiles", version = "0.9.0" }
 graphql-orm-backup = { path = "crates/graphql-orm-backup", version = "0.7.1", default-features = false }
 graphql-orm-operation-catalog = { path = "crates/graphql-orm-operation-catalog", version = "0.3.0" }

MIGRATION.md

@@ -13,6 +13,18 @@ supersedes: []
 `graphql-orm` is distributed from GitHub only. Use a reviewed full 40-character commit in `rev`;
 neither the runtime nor macros crate is published to crates.io.
 
+## 0.23.0 to 0.24.0: agql-auth 0.16 alignment
+
+Hosts enabling `auth-agql` or depending directly on `agql-auth` must align to
+version 0.16.0 at merged revision
+`3bc38cd94794f1e868a9cc3a5551047b95a32105`. Adopt `graphql-orm` and the
+aligned `graphql-orm-macros` 0.24.0 from the same reviewed monorepo revision.
+This retains one public auth type universe. Version 0.16 adds
+consumer-supplied exact-only hierarchical matcher policy; the ORM bridge
+remains projection-only and does not select or install that policy. No
+database, schema, GraphQL SDL, generated-code, token, backup, or stored-data
+migration is required.
+
 ## 0.22.1 to 0.23.0: explicit collection-bound semantics
 
 Update `graphql-orm`, `graphql-orm-macros`, and
@@ -1183,6 +1195,6 @@ access path.
 
 - No JWT, OIDC, cookie, wildcard, or application-specific scope logic was added to `graphql-orm`.
 - PostgreSQL RLS helper functions still use exact scope matching.
-- The current `auth-agql` feature targets `agql-auth` 0.15.0 at revision
-  `e841ffd382082ad7419be259fe957f949b956ff7`; earlier release sections above
+- The current `auth-agql` feature targets `agql-auth` 0.16.0 at revision
+  `3bc38cd94794f1e868a9cc3a5551047b95a32105`; earlier release sections above
   retain their historical pins.

README.md

@@ -47,7 +47,7 @@ reviewed full SHA for the release:
 
 ```toml
 [dependencies]
-graphql-orm = { git = "https://github.com/Dastari/graphql-orm.git", rev = "<reviewed-full-40-character-commit-sha>", version = "0.23.0", default-features = false, features = ["sqlite"] }
+graphql-orm = { git = "https://github.com/Dastari/graphql-orm.git", rev = "<reviewed-full-40-character-commit-sha>", version = "0.24.0", default-features = false, features = ["sqlite"] }
 ```
 
 Choose exactly the backend support needed by each service. Cargo can unify

crates/graphql-orm-ai/CHANGELOG.md

@@ -18,6 +18,23 @@ checkpoint facts. For the current workspace baseline and active gates, use the
 [implementation status](docs/implementation-status.md) and the central
 [AI production-readiness plan](../../docs/plans/active/ai-production-readiness/README.md).
 
+## [0.89.0] - 2026-08-22
+
+Persistent schema module: **0.63.0** (unchanged from 0.88.0).
+
+### Changed
+
+- Aligned the public `agql-auth` type universe to 0.16.0 at merged revision
+  `3bc38cd94794f1e868a9cc3a5551047b95a32105`. This matters to consumers because
+  the AI prelude publicly re-exports `CurrentPrincipalResolver`,
+  `PrincipalReference`, and `ResolvedPrincipal`.
+- Hosts that depend directly on `agql-auth` must use that same full revision.
+  AI authorization, principal rehydration, provider, and persistence behavior
+  are unchanged.
+
+There is no schema, data, protected-payload, GraphQL SDL, backup or restore
+migration in this release.
+
 ## [0.88.0] - 2026-08-22
 
 Persistent schema module: **0.63.0** (unchanged from 0.87.0).

crates/graphql-orm-ai/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "graphql-orm-ai"
-version = "0.88.0"
+version = "0.89.0"
 edition = "2024"
 authors = ["Toby Martin <toby@dastari.net>"]
 description = "Project-agnostic AI agent runtime for graphql-orm applications"

crates/graphql-orm-ai/MIGRATION.md

@@ -19,6 +19,21 @@ they describe. For the current workspace baseline and active delivery gates,
 use [implementation status](docs/implementation-status.md) and the central
 [AI production-readiness plan](../../docs/plans/active/ai-production-readiness/README.md).
 
+## 0.88.0 to 0.89.0: agql-auth 0.16 type-universe alignment
+
+Adopt `graphql-orm-ai` 0.89.0 from one reviewed full monorepo revision and
+align every direct `agql-auth` dependency to version 0.16.0 at merged revision
+`3bc38cd94794f1e868a9cc3a5551047b95a32105`. The AI prelude publicly
+re-exports `CurrentPrincipalResolver`, `PrincipalReference`, and
+`ResolvedPrincipal`, so resolving another source revision would create a
+different public Rust type universe even though these type contracts are
+otherwise unchanged.
+
+The AI schema module remains **0.63.0**. There is no database, data, table,
+column, index, constraint, backfill, GraphQL SDL, protected-payload, backup or
+restore migration. AI authorization, principal rehydration, and provider
+behavior are unchanged.
+
 ## 0.87.0 to 0.88.0: direct GPT-5.6 dynamic tools on Codex 0.148.0
 
 Adopt `graphql-orm-ai` 0.88.0 from one reviewed full monorepo revision. The AI

crates/graphql-orm-ai/README.md

@@ -28,7 +28,7 @@ for AI, ORM, storage, backup, and tool-profile packages:
 
 ```toml
 [dependencies]
-graphql-orm-ai = { git = "https://github.com/Dastari/graphql-orm.git", rev = "<reviewed-full-40-character-commit-sha>", version = "0.87.0", default-features = false, features = ["sqlite"] }
+graphql-orm-ai = { git = "https://github.com/Dastari/graphql-orm.git", rev = "<reviewed-full-40-character-commit-sha>", version = "0.89.0", default-features = false, features = ["sqlite"] }
 ```
 
 Exactly one persistence backend is required: `sqlite` (default), `postgres`,

crates/graphql-orm-ai/docs/implementation-status.md

@@ -10,10 +10,10 @@ supersedes: []
 
 # Implementation Status
 
-`graphql-orm-ai` is at crate version `0.87.0` with AI schema module
-`0.63.0`. It uses workspace `graphql-orm` `0.23.0`, backend-neutral
+`graphql-orm-ai` is at crate version `0.89.0` with AI schema module
+`0.63.0`. It uses workspace `graphql-orm` `0.24.0`, backend-neutral
 `graphql-orm-ai-tool-profiles` `0.9.0`, and external `agql-auth`
-`0.15.0` at `e841ffd382082ad7419be259fe957f949b956ff7`.
+`0.16.0` at `3bc38cd94794f1e868a9cc3a5551047b95a32105`.
 
 Completed stateless local-provider turns can carry a proof-bearing contained
 native-item refusal after authoritative usage settlement. Those runs close as

crates/graphql-orm-ai/src/providers/codex_app_server.rs

@@ -6601,7 +6601,7 @@ pub(crate) mod tests {
                 .and_then(Value::as_str)
                 .is_some_and(|description| description.contains("maximum 25"))
         );
-        assert!(schema.to_string().find("anyOf").is_none());
+        assert!(!schema.to_string().contains("anyOf"));
     }
 
     fn named_semantic_type(name: &str, nullable: bool) -> GraphqlSemanticTypeRef {

crates/graphql-orm-backup/AGENTS.md

@@ -32,13 +32,13 @@ This crate is a reusable backup and restore companion for applications that use
 ## Current Agent Handoff
 
 - Current crate version is `0.7.1`.
-- The optional ORM adapter resolves `graphql-orm` 0.22.1 from the workspace.
+- The optional ORM adapter resolves `graphql-orm` 0.24.0 from the workspace.
   Internal packages use workspace path dependencies and the root `Cargo.lock`.
   Keep downstream applications on one reviewed monorepo revision so ORM,
   backup, and storage share the same canonical source/type universe.
 - `graphql-orm` owns its optional `agql-auth` integration and pins
-  `agql-auth` 0.15.0 at
-  `e841ffd382082ad7419be259fe957f949b956ff7`. This crate must not enable or
+  `agql-auth` 0.16.0 at
+  `3bc38cd94794f1e868a9cc3a5551047b95a32105`. This crate must not enable or
   depend directly on application authorization.
 - Applying and dry-run restore compare the manifest backend/schema hash with
   the target before target checks or writes. Preserve that fail-closed

crates/graphql-orm-macros/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "graphql-orm-macros"
-version = "0.23.0"
+version = "0.24.0"
 edition = "2024"
 authors = ["Toby Martin"]
 description = "Procedural macros for async-graphql and ORM-backed entities, relations, and CRUD operations."

crates/graphql-orm-macros/README.md

@@ -16,13 +16,13 @@ macro/runtime versions aligned:
 
 ```toml
 [dependencies]
-graphql-orm = { git = "https://github.com/Dastari/graphql-orm.git", rev = "<reviewed-full-40-character-commit-sha>", version = "0.23.0", default-features = false, features = ["sqlite"] }
+graphql-orm = { git = "https://github.com/Dastari/graphql-orm.git", rev = "<reviewed-full-40-character-commit-sha>", version = "0.24.0", default-features = false, features = ["sqlite"] }
 ```
 
 Direct use is supported for tooling that needs the macro package:
 
 ```toml
-graphql-orm-macros = { git = "https://github.com/Dastari/graphql-orm.git", rev = "<reviewed-full-40-character-commit-sha>", version = "0.23.0", default-features = false, features = ["sqlite"] }
+graphql-orm-macros = { git = "https://github.com/Dastari/graphql-orm.git", rev = "<reviewed-full-40-character-commit-sha>", version = "0.24.0", default-features = false, features = ["sqlite"] }
 ```
 
 The direct dependency still requires a compatible `graphql-orm` runtime in the

crates/graphql-orm-macros/src/operations.rs

@@ -4867,12 +4867,10 @@ pub(crate) fn generate_graphql_operations(
             #(#retention_event_id_values)*
             ::graphql_orm::graphql::orm::composite_key_id(&bind_values)
         }}
+    } else if pk_is_bytes {
+        quote! { ::graphql_orm::graphql::orm::binary_key_id(&self.#pk_field) }
     } else {
-        if pk_is_bytes {
-            quote! { ::graphql_orm::graphql::orm::binary_key_id(&self.#pk_field) }
-        } else {
-            quote! { self.#pk_field.to_string() }
-        }
+        quote! { self.#pk_field.to_string() }
     };
     let retention_surface = if entity_meta.retention_policy.is_some() {
         quote! {

crates/graphql-orm-router/CHANGELOG.md

@@ -10,6 +10,21 @@ supersedes: []
 
 # Changelog
 
+## 0.2.0 - 2026-08-22
+
+- Added strict `scopeMatcher` file configuration. Omission and `kind: exact`
+  preserve exact-string behavior; `kind: hierarchical` exposes the generic
+  separator, wildcard, universal-wildcard, super-scope, and exact-only options
+  from the optional resource-server matcher.
+- Updated the optional `agql-auth` adapter to 0.16.0 for consumer-supplied
+  exact-only fixed scopes and resource-qualified scope patterns.
+- Supplied the configured matcher to the existing authorization path shared by
+  fixed and rendered operation requirements; operation evaluation code is
+  unchanged. Subgraph resolver authorization remains authoritative.
+
+No descriptor, GraphQL schema, token wire, or stored-data migration is
+required. Hierarchical file configuration requires the `auth-agql` feature.
+
 ## 0.1.4 - 2026-08-13
 
 - Updated the optional resource-server-only `agql-auth` adapter to 0.15.0 at

crates/graphql-orm-router/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "graphql-orm-router"
-version = "0.1.4"
+version = "0.2.0"
 edition = "2024"
 rust-version = "1.90"
 description = "Federated GraphQL router for graphql-orm and project-neutral subgraphs"

crates/graphql-orm-router/MIGRATION.md

@@ -10,6 +10,23 @@ supersedes: []
 
 # graphql-orm-router migration guide
 
+## 0.1.4 to 0.2.0
+
+Replace the reviewed full-revision pin and rebuild the router. Hosts that also
+depend directly on `agql-auth` must align to version 0.16.0 at the exact
+reviewed revision so Cargo resolves one auth type universe.
+
+Omitted `scopeMatcher` configuration remains exact and needs no migration.
+To opt into the generic hierarchy, build with `auth-agql` and add
+`{"scopeMatcher":{"kind":"hierarchical"}}`; then explicitly review
+separator, wildcard, universal-wildcard, `superScopes`, `exactOnlyScopes`, and
+`exactOnlyScopePatterns` policy. Exact-only requirements are checked before a
+super scope or wildcard, including rendered resource-qualified requirements.
+
+No descriptor, GraphQL schema, token wire, or stored-data migration is
+required. Run `--check` against the complete graph and exercise both ordinary
+and exact-only authorization cases before deployment.
+
 ## 0.1.3 to 0.1.4
 
 Replace the reviewed full-revision pin and rebuild the router. When a host
@@ -91,8 +108,8 @@ New access tokens should use the OAuth space-delimited `scope` claim. The
 legacy `scopes` array is accepted only with `acceptLegacyScopes: true`; a token
 containing conflicting forms is rejected. The optional `auth-agql` feature is
 a validation/matching adapter only and introduces no issuer responsibilities.
-It resolves `agql-auth` 0.15.0 at exact revision
-`e841ffd382082ad7419be259fe957f949b956ff7`; hosts with a direct dependency
+It resolves `agql-auth` 0.16.0 at exact revision
+`3bc38cd94794f1e868a9cc3a5551047b95a32105`; hosts with a direct dependency
 must use the same source and revision. Configure legacy acceptance directly
 with `agql_auth::AccessTokenValidatorBuilder::legacy_scope_claims` before
 wrapping the validator in `AgqlAuthenticationProvider::new`.

crates/graphql-orm-router/README.md

@@ -26,7 +26,7 @@ This unpublished package is Git-only:
 
 ```toml
 [dependencies]
-graphql-orm-router = { git = "https://github.com/Dastari/graphql-orm.git", rev = "<reviewed-full-40-character-commit-sha>", version = "0.1.4" }
+graphql-orm-router = { git = "https://github.com/Dastari/graphql-orm.git", rev = "<reviewed-full-40-character-commit-sha>", version = "0.2.0" }
 ```
 
 Enable `auth-agql` only when adapting a separately configured
@@ -68,6 +68,7 @@ composition warnings before serving.
 | Surface | Default or boundary |
 | --- | --- |
 | Authentication | Fail-closed; anonymous mode is explicit development-only. |
+| Scope matching | Exact by default; hierarchical matching requires `auth-agql` and explicit file or programmatic configuration. |
 | Public path | `/graphql`; `/health` and `/readiness` are also exposed. |
 | Subgraphs | At least one static source; file configuration requires strict JSON. |
 | Dynamic registration | Disabled unless authenticated administration and exact network policy are configured. |

crates/graphql-orm-router/docs/configuration.md

@@ -58,6 +58,7 @@ an unbounded value.
 | `graphqlPath` | `/graphql`; absolute, non-root, without query or fragment. |
 | `anonymousDevelopment` | `false`; mutually exclusive with authentication and unsuitable for production. |
 | `authentication` | Required unless anonymous development is explicitly enabled. |
+| `scopeMatcher` | Omitted means exact-string matching. `kind: "hierarchical"` requires the `auth-agql` feature. |
 | `subgraphs` | At least one static source is required. |
 | `forwardedHeaders` | Empty. Sensitive, hop-by-hop, cookie, and authorization names are rejected. |
 | `schemaFetchTimeoutMs` | 10000. |
@@ -88,6 +89,25 @@ array. JWKS uses HTTPS. Plain HTTP is accepted only for loopback when
 The router validates RS256 public keys only. Configuration has no private-key,
 token-signing, session, refresh-token, or RSA-decryption field.
 
+Scope matching is a separate resource-server policy. Omission or
+`{"kind":"exact"}` preserves exact-string compatibility. With the
+`auth-agql` feature, `kind: "hierarchical"` accepts these optional fields:
+
+| Field | Default or rule |
+| --- | --- |
+| `separator` | `.`; one visible character. |
+| `wildcard` | `*`; one non-empty segment without whitespace. |
+| `wildcardMatchesMultiSegment` | `true`; a trailing wildcard matches the remaining hierarchy. |
+| `allowUniversalWildcard` | `false`; a bare wildcard has no implicit authority. |
+| `superScopes` | Empty; each listed grant satisfies ordinary requirements. |
+| `exactOnlyScopes` | Empty; each listed requirement accepts only an equal grant. |
+| `exactOnlyScopePatterns` | Empty; matching resource-qualified requirements accept only equal grants. |
+
+Exact-only requirements are evaluated before super-scope and wildcard rules.
+Lists are normalized and deduplicated at startup. The router applies this one
+matcher to fixed and rendered operation requirements; resolver guards remain
+authoritative.
+
 For programmatic setup, `JwksAuthenticationConfig::new` requires a JWKS URL,
 issuer, and non-empty audiences. It defaults to a 15-minute key cache,
 5-minute refresh interval, 5-second request timeout, 1 MiB JWKS body limit,

crates/graphql-orm-router/examples/router.example.json

@@ -8,6 +8,9 @@
     "refreshIntervalSeconds": 300,
     "cacheTtlSeconds": 900
   },
+  "scopeMatcher": {
+    "kind": "exact"
+  },
   "subgraphs": [
     {
       "name": "products",