feat(ai): rank capability discovery by operation shape

Cargo.toml

@@ -38,7 +38,7 @@ futures = "0.3"
 getrandom = "0.3"
 graphql-composition = "=0.12.2"
 graphql-orm = { path = "crates/graphql-orm", version = "0.26.0", default-features = false }
-graphql-orm-ai-tool-profiles = { path = "crates/graphql-orm-ai-tool-profiles", version = "0.9.0" }
+graphql-orm-ai-tool-profiles = { path = "crates/graphql-orm-ai-tool-profiles", version = "0.10.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" }
 graphql-orm-router-protocol = { path = "crates/graphql-orm-router-protocol", version = "0.2.1" }

crates/graphql-orm-ai-tool-profiles/CHANGELOG.md

@@ -10,6 +10,27 @@ supersedes: []
 
 # Changelog
 
+## [0.10.0] - 2026-08-23
+
+### Added
+
+- Capability indexes now carry conservative compiler-owned maximum root and
+  total result-record costs and whether an explicit root bound is required.
+
+### Changed
+
+- Discovery ranks a narrowly inferred mechanical list, details, search,
+  keyset, or aggregate shape before entity, execution target, namespace, and
+  lexical relevance without discarding relevant mixed-shape results.
+- The canonical capability-index contract version is now `2`; index and set
+  fingerprints intentionally change.
+
+### Security
+
+- Shape and cost metadata remain descriptive only. Current host policy,
+  short-lived load bindings, compiler validation, and resolver authorization
+  remain mandatory.
+
 ## [0.9.0] - 2026-08-22
 
 ### Added

crates/graphql-orm-ai-tool-profiles/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "graphql-orm-ai-tool-profiles"
-version = "0.9.0"
+version = "0.10.0"
 edition = "2024"
 authors = ["Toby Martin <toby@dastari.net>"]
 description = "Backend-neutral GraphQL AI tool profile compiler and manifest contracts"

crates/graphql-orm-ai-tool-profiles/MIGRATION.md

@@ -10,6 +10,24 @@ supersedes: []
 
 # Migration Guide
 
+## 0.9.0 to 0.10.0: shape-aware discovery and record-cost metadata
+
+Adopt `graphql-orm-ai-tool-profiles` 0.10.0 with `graphql-orm-ai` 0.94.0 from
+one reviewed full monorepo revision. Recompile every capability index and
+refresh retained provider-session bindings: the canonical index contract is
+now version `2`, and the added result-record cost metadata changes entry,
+index, and index-set fingerprints.
+
+Search callers keep the same request type. Explicit
+list/details/search/keyset/aggregate language now ranks the matching mechanical
+operation shape before entity, namespace, and lexical relevance while keeping
+other lexically relevant shapes eligible. Fixed-broker descriptions add
+`resultRecordCost` with compiler-owned `maximumRootRecords`,
+`maximumTotalRecords`, and `rootBoundRequired` fields.
+
+There is no database, data, GraphQL SDL, protected-content, backup, restore, or
+persistent AI schema-module migration. Discovery remains non-authoritative.
+
 ## 0.8.0 to 0.9.0: proof-bearing stateless native-item refusal
 
 Adopt `graphql-orm-ai-tool-profiles` 0.9.0 with `graphql-orm-ai` 0.86.0 from

crates/graphql-orm-ai-tool-profiles/README.md

@@ -24,7 +24,7 @@ are separate runtime decisions and must remain default-deny.
 
 ```toml
 [dependencies]
-graphql-orm-ai-tool-profiles = { git = "https://github.com/Dastari/graphql-orm.git", rev = "<reviewed-full-40-character-commit-sha>", version = "0.9.0" }
+graphql-orm-ai-tool-profiles = { git = "https://github.com/Dastari/graphql-orm.git", rev = "<reviewed-full-40-character-commit-sha>", version = "0.10.0" }
 serde_json = "1"
 ```
 
@@ -121,12 +121,17 @@ semantic summaries and exact fingerprints. It intentionally contains no JSON
 Schema, GraphQL document/SDL, database name, resolver URL, policy expression,
 credential, authority or secret/hidden field.
 
-`AiCapabilityIndex::search` provides bounded deterministic lexical discovery
-with exact namespace/kind/entity filters and stable ID tie-breaking. Search
+`AiCapabilityIndex::search` provides bounded deterministic discovery with
+exact namespace/kind/entity filters and stable ID tie-breaking. Explicit list,
+details, search, keyset, or aggregate intent ranks the matching compiler-owned
+operation shape first; public entity, execution-target, and namespace relevance
+rank next. Every candidate still requires positive lexical relevance, and
+non-matching shapes remain eligible. Search
 returns exact candidate/index/schema/semantic/target-policy fingerprints but
-grants no authority. The runtime package owns current-principal rehydration,
-policy reapplication, short-lived loaded bindings and ordinary resolver
-execution.
+grants no authority. Each entry also carries conservative compiler-owned root
+and total result-record bounds for later planning. The runtime package owns
+current-principal rehydration, policy reapplication, short-lived loaded
+bindings and ordinary resolver execution.
 
 Opt-in aggregate roots use the same catalogue and a fixed result projection.
 Their filters, grouping, metrics, operators, and group limits remain typed and