Reuse capability discovery metadata across fenced runs

crates/graphql-orm-ai/CHANGELOG.md

@@ -20,6 +20,15 @@ checkpoint facts. For the current workspace baseline and active gates, use the
 
 ## [0.98.0] - 2026-09-15
 
+### Added
+
+Optional `AiCapabilityDiscoveryBroker::with_discovery_cache` retains bounded
+principal/session-specific discovery metadata across fenced runs for up to seven days.
+A cached candidate can be described without repeating discovery. Current index fingerprints,
+principal rehydration and host policy are checked before a fresh run-bound execution handle
+is issued. Cache expiry, eviction or process restart requires discovery again. No data migration
+or GraphQL contract change is required; the cache is disabled by default.
+
 ### Fixed
 
 Conversation bootstrap now includes nullable `AiConversationRunSummary::failure_disposition`

crates/graphql-orm-ai/Cargo.toml

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

crates/graphql-orm-ai/MIGRATION.md

@@ -3,7 +3,7 @@ title: "Migration Guide"
 kind: reference
 status: active
 owner: graphql-orm-ai-maintainers
-last_reviewed: 2026-09-02
+last_reviewed: 2026-09-15
 review_by: 2027-02-01
 supersedes: []
 ---
@@ -19,6 +19,17 @@ 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.98.1
+
+Hosts may opt into `AiCapabilityDiscoveryBroker::with_discovery_cache(ttl, maximum_searches)`
+to reuse discovery candidates across runs of the same principal and AI session. Keep the broker
+(or its clones) for the desired cache lifetime. The TTL is one second through seven days and
+capacity is one through 1,024 bounded searches, with oldest-first eviction. The default remains
+disabled. Each new run still creates a fresh `AiCapabilityBrokerSession` and describes a cached
+candidate before execution; old loaded references do not become reusable. Describe revalidates
+current metadata and authority, and execution retains all existing fences and resolver checks.
+No data migration is needed; no durable schema, GraphQL SDL, backup or restore format changes.
+
 ## 0.98.0
 
 Conversation bootstrap now includes nullable `AiConversationRunSummary::failure_disposition`

crates/graphql-orm-ai/README.md

@@ -365,3 +365,12 @@ contracts, and security checks.
 - [Read-only tools](docs/read-only-tool-loop.md), [supervised mutations](docs/supervised-tool-loop.md), and [provider turns](docs/worker-provider-turn.md)
 - [Recovery and restore](docs/recovery-and-restore.md)
 - [Migration guide](MIGRATION.md) and [changelog](CHANGELOG.md)
+
+### Discovery reuse across runs
+
+A long-lived `AiCapabilityDiscoveryBroker` may enable `with_discovery_cache(ttl, maximum_searches)`
+to retain `dispatch_discover` results for the same principal and AI session across fixed-broker runs. This avoids
+repeating model-driven discovery when catalogue fingerprints are unchanged. Cached descriptions
+still rehydrate current principals and issue fresh run-bound execution handles. Permissions,
+loaded handles and application results are not cache entries. The cache is bounded, process-local,
+disabled by default, and expires entries after at most seven days; see [MIGRATION.md](MIGRATION.md).