refactoring

Author: KSemenenko

AGENTS.md

@@ -168,6 +168,8 @@ If no new rule is detected -> do not update the file.
 - If a user adds or corrects a persistent workflow rule, update `AGENTS.md` first and only then continue with the task.
 - When a search-quality fix is requested as a concrete architectural change, finish the intended runtime behavior in the same task instead of stopping at a partial scoring-only step, because partial search fixes leave the real retrieval defect unresolved.
 - When the user asks for a shipped feature set, implement the runtime behavior end-to-end with production-ready code and tests instead of leaving placeholder, mocked, or temporary execution paths, because partial delivery is explicitly rejected in this repository.
+- During stabilization and release-hardening work, proactively search for analogous fragile patterns after fixing the first defect, and fix every confirmed issue with the correct SDK, platform, or .NET primitive plus tests instead of hacks, suppressions, or narrow one-off reactions.
+- Do not hide runtime or transport timeouts as magic numbers in package code; when a timeout is required, expose it as an explicit `TimeSpan` option with a clear default, caller override, and validation. Test-only bounded waits are acceptable only as harness hang guards, not as product behavior.
 - When adopting new upstream graph/search capabilities such as `ManagedCode.MarkdownLd.Kb` schema-aware search, implement the real hybrid runtime benefits with tests and docs instead of limiting the task to dependency bumps or export helpers, because the user expects the package to capture the upstream search value end-to-end.
 - When adding federated graph search, do not reject federation as a category; expose it through explicit allowlisted APIs or built-in tools with diagnostics and tests, because the user wants powerful hybrid/federated search while keeping hidden unconfigured network calls out of the default path.
 - Keep graph/search/index-specific capabilities on the appropriate search or indexing public surface instead of forcing them directly onto the MCP-facing `IMcpGateway` facade, because graph federation and graph export are search/index concerns rather than generic MCP gateway operations.

README.md

@@ -141,7 +141,7 @@ services.AddMcpGateway(options =>
 
 `AddHttpServer(...)` uses the official MCP C# SDK Streamable HTTP transport for modern remote MCP endpoints and keeps the source registered as an HTTP MCP source in gateway descriptors and downstream export metadata.
 Use the overload with `HttpTransportMode` only when a legacy endpoint requires `AutoDetect` or `Sse`.
-Use `McpGatewayHttpServerOptions` when a host needs the SDK HTTP transport knobs such as additional headers, connection timeout, known session id, session ownership, OAuth options, or SSE reconnection settings.
+Use `McpGatewayHttpServerOptions` when a host needs the SDK HTTP transport knobs such as additional headers, connection timeout, known session id, session ownership, OAuth options, or SSE reconnection settings. The package does not set a transport timeout by default; hosts can pass one explicitly or own deadline policy through cancellation tokens and hosting infrastructure.
 
 You can also register:
 
@@ -633,6 +633,8 @@ services.AddMcpGateway(options =>
 {
     options.AddMarkdownLdFederatedServiceEndpoint(
         new Uri("https://knowledge.example.com/sparql"));
+
+    options.MarkdownLdFederatedSparqlQueryTimeout = TimeSpan.FromSeconds(30);
 });
 ```
 
@@ -649,6 +651,7 @@ var federatedResult = await graphSearch.SearchGraphAsync(
 ```
 
 The gateway never discovers remote SPARQL endpoints on its own. It uses the configured allowlist, can bind the local gateway graph as a federated service, and reports diagnostics when a requested endpoint is invalid or blocked.
+Federated SPARQL execution defaults to `McpGatewayOptions.DefaultMarkdownLdFederatedSparqlQueryTimeout`, which is 30 seconds. Set `MarkdownLdFederatedSparqlQueryTimeout` to a larger `TimeSpan` for slower trusted endpoints, or set it to `null` when the host owns the deadline entirely through cancellation tokens or infrastructure policy.
 
 ## Graph Sources
 

docs/ADR/ADR-0012-schema-aware-sparql-graph-search.md

@@ -142,7 +142,7 @@ Negative / risks:
 - graph search now depends on more upstream `ManagedCode.MarkdownLd.Kb` behavior
 - schema-profile drift can reduce result quality if generated graph predicates change
 - large-catalog schema search still materializes a per-query candidate graph until upstream schema search exposes a candidate filter such as `CandidateNodeIds`
-- federated queries add endpoint and timeout configuration that operators must understand
+- federated queries add endpoint and configurable timeout policy that operators must understand
 
 Mitigations:
 
@@ -161,15 +161,15 @@ Mitigations:
 
 - `Search/Abstractions/IMcpGatewayGraphSearch.cs` adds the graph search/export boundary.
 - `McpGateway` and `McpGatewayRuntime` implement `IMcpGatewayGraphSearch`.
-- `McpGatewayOptions` adds graph search mode and federated endpoint configuration.
+- `McpGatewayOptions` adds graph search mode, federated endpoint configuration, and a configurable federated SPARQL query timeout.
 - `Search/Internal/Graph/*` owns schema profile creation, schema/profile description, schema/federated operations, graph export, and hybrid graph ranking.
 - `McpGatewayToolSet` adds graph schema/profile, index-build, search, federation, and export meta-tools while keeping basic meta-tools usable with a plain `IMcpGateway`.
 
 ### Data / Configuration
 
 - `ManagedCode.MarkdownLd.Kb` is upgraded to `0.2.5`.
 - `MarkdownLdGraphSearchMode` defaults to `Hybrid`.
-- Federated endpoints are configured through `AddMarkdownLdFederatedServiceEndpoint(...)`.
+- Federated endpoints are configured through `AddMarkdownLdFederatedServiceEndpoint(...)`; federated query timeout defaults to `McpGatewayOptions.DefaultMarkdownLdFederatedSparqlQueryTimeout` and can be overridden or disabled through `MarkdownLdFederatedSparqlQueryTimeout`.
 
 ### Documentation
 

docs/Architecture/Overview.md

@@ -201,7 +201,7 @@ flowchart LR
 - The built-in process-local embedding store may depend on `IMemoryCache`, but cross-instance persistence and cache replication must stay behind host-provided `IMcpGatewayToolEmbeddingStore` implementations.
 - Markdown-LD graph search is the default internal retrieval strategy. It may depend on `ManagedCode.MarkdownLd.Kb`, uses schema-aware SPARQL as the primary graph path in hybrid/schema-aware mode, uses gateway-built ranked candidate selection to bound large-catalog schema search, uses ranked candidate/fuzzy graph search only as focused hybrid support or fallback, still returns the same public `McpGatewaySearchMatch` contracts, calibrates user-facing confidence at the gateway layer, and must not create a separate invocation surface.
 - Graph-specific schema/profile inspection, evidence, generated SPARQL, explicit federated search, explicit index-build tooling, and runtime graph export belong to `IMcpGatewayGraphSearch` and `McpGatewayToolSet` graph tools, not to the MCP-facing `IMcpGateway` facade.
-- Federated graph search must use explicit configured endpoint allowlists and local graph bindings; the runtime must not perform hidden remote SPARQL discovery from the normal search path.
+- Federated graph search must use explicit configured endpoint allowlists, local graph bindings, and the `McpGatewayOptions.MarkdownLdFederatedSparqlQueryTimeout` `TimeSpan` option; the runtime must not perform hidden remote SPARQL discovery from the normal search path.
 - Markdown-LD graph sources may be generated from the live catalog at index build time, loaded from a file-system path, or provided through a host-supplied document factory configured in `McpGatewayOptions`. All modes must still map graph documents back to the current catalog before returning matches.
 - Tool metadata used for search enrichment must stay explicit and developer-controlled through registration hints or tool annotations; multilingual improvement should come from metadata plus scoring, not from one-off hardcoded phrase rules in runtime code.
 - Warmup remains optional. The package must work correctly with lazy indexing and must not require manual initialization for every host.

docs/Features/SearchQueryNormalizationAndRanking.md

@@ -118,7 +118,7 @@ flowchart LR
   - keyed optional search normalizer client from DI
   - optional embedding generator and embedding store from DI when vector strategy is selected
   - search and graph-source options from `McpGatewayOptions`
-  - schema-aware graph search mode and federated endpoint allowlist from `McpGatewayOptions`
+  - schema-aware graph search mode, federated endpoint allowlist, and federated SPARQL query timeout from `McpGatewayOptions`
   - file-system Markdown-LD graph source when `MarkdownLdGraphSource.FileSystem` is selected
   - host-supplied Markdown-LD graph documents when `UseMarkdownLdGraphDocuments(...)` is selected
 - Writes:

src/ManagedCode.MCPGateway/Gateway/Configuration/McpGatewayOptions.cs

@@ -5,6 +5,9 @@ namespace ManagedCode.MCPGateway;
 
 public sealed class McpGatewayOptions
 {
+    public static TimeSpan DefaultMarkdownLdFederatedSparqlQueryTimeout { get; } =
+        TimeSpan.FromSeconds(30);
+
     private readonly McpGatewayRegistrationCollection _sourceRegistrations = new();
     private readonly List<Uri> _markdownLdFederatedServiceEndpoints = [];
 
@@ -35,6 +38,9 @@ public Func<
 
     public int MaxDescriptorLength { get; set; } = 4096;
 
+    public TimeSpan? MarkdownLdFederatedSparqlQueryTimeout { get; set; } =
+        DefaultMarkdownLdFederatedSparqlQueryTimeout;
+
     internal IReadOnlyList<McpGatewayToolSourceRegistration> SourceRegistrations =>
         _sourceRegistrations.Snapshot();
 

src/ManagedCode.MCPGateway/Gateway/Internal/Runtime/McpGatewayRuntime.cs

@@ -345,7 +345,6 @@ internal sealed partial class McpGatewayRuntime : IMcpGateway, IMcpGatewayGraphS
     private const int GraphPluralNormalizationMinimumLength = 3;
     private const int GraphDefaultTermCollectionCapacity = 8;
     private const int GraphMaxCapabilityTerms = 4;
-    private const int FederatedSparqlQueryTimeoutMilliseconds = 15000;
     private const double SearchScoreMinimum = 0d;
     private const double SearchScoreMaximum = 1d;
     private const double GraphSchemaNameTextWeight = 1.2d;
@@ -573,6 +572,7 @@ private readonly Func<
     private readonly int _defaultSearchLimit;
     private readonly int _maxSearchResults;
     private readonly int _maxDescriptorLength;
+    private readonly TimeSpan? _markdownLdFederatedSparqlQueryTimeout;
     private readonly IReadOnlyList<Uri> _markdownLdFederatedServiceEndpoints;
     private readonly Uri _graphLocalFederationEndpoint;
     private readonly IMcpGatewaySearchCache _searchRuntimeCache;
@@ -608,6 +608,10 @@ ILoggerFactory loggerFactory
         _defaultSearchLimit = Math.Max(1, resolvedOptions.DefaultSearchLimit);
         _maxSearchResults = Math.Max(1, resolvedOptions.MaxSearchResults);
         _maxDescriptorLength = Math.Max(256, resolvedOptions.MaxDescriptorLength);
+        _markdownLdFederatedSparqlQueryTimeout = ValidateOptionalTimeout(
+            resolvedOptions.MarkdownLdFederatedSparqlQueryTimeout,
+            nameof(McpGatewayOptions.MarkdownLdFederatedSparqlQueryTimeout)
+        );
         _markdownLdFederatedServiceEndpoints = resolvedOptions.MarkdownLdFederatedServiceEndpoints;
         _graphLocalFederationEndpoint = new Uri(
             $"{GraphLocalFederationEndpointUriText}/{Guid.NewGuid():N}",
@@ -654,6 +658,34 @@ is IMcpGatewayCatalogSource registryCatalogSource
         throw new InvalidOperationException(CatalogSourceMissingMessage);
     }
 
+    private static TimeSpan? ValidateOptionalTimeout(TimeSpan? value, string paramName)
+    {
+        if (value is null)
+        {
+            return null;
+        }
+
+        if (value.Value <= TimeSpan.Zero)
+        {
+            throw new ArgumentOutOfRangeException(
+                paramName,
+                value,
+                "Timeout must be greater than zero."
+            );
+        }
+
+        if (value.Value.TotalMilliseconds > int.MaxValue)
+        {
+            throw new ArgumentOutOfRangeException(
+                paramName,
+                value,
+                "Timeout must fit into Int32 milliseconds for the Markdown-LD federated SPARQL executor."
+            );
+        }
+
+        return value;
+    }
+
     private void ThrowIfDisposed()
     {
         ObjectDisposedException.ThrowIf(Volatile.Read(ref _state).IsDisposed, this);

src/ManagedCode.MCPGateway/Hosting/Internal/Server/McpGatewayMcpServerBindingManager.cs

@@ -196,15 +196,18 @@ CancellationToken cancellationToken
 
         public async ValueTask DisposeAsync()
         {
+            IMcpGatewayServerBinding binding;
             try
             {
-                var binding = await BindingTask;
-                await binding.DisposeAsync();
+                binding = await BindingTask;
             }
             catch
             {
                 // Resolution failures have nothing to dispose and should not fail cleanup.
+                return;
             }
+
+            await binding.DisposeAsync();
         }
     }
 }

src/ManagedCode.MCPGateway/Hosting/Internal/Server/McpGatewayMcpServerProtocolMapper.cs

@@ -16,6 +16,8 @@ internal static class McpGatewayMcpServerProtocolMapper
         "' input schema must be a JSON object.";
     private const string InvalidPromptMessageContentMessage =
         "Prompt message content is not a valid MCP content block.";
+    private const string InvalidPromptMessageRolePrefix = "Prompt message role '";
+    private const string InvalidPromptMessageRoleSuffix = "' is not supported.";
 
     public static Tool ToProtocolTool(
         McpGatewayToolDescriptor descriptor,
@@ -226,13 +228,7 @@ public static GetPromptResult CreateErrorPromptResult(string message) =>
                 {
                     return new PromptMessage
                     {
-                        Role = Enum.TryParse<Role>(
-                            message.Role,
-                            ignoreCase: true,
-                            out var parsedRole
-                        )
-                            ? parsedRole
-                            : Role.User,
+                        Role = ParsePromptRole(message.Role),
                         Content = content,
                     };
                 }
@@ -254,9 +250,7 @@ out var parsedRole
 
         return new PromptMessage
         {
-            Role = Enum.TryParse<Role>(message.Role, ignoreCase: true, out var fallbackRole)
-                ? fallbackRole
-                : Role.User,
+            Role = ParsePromptRole(message.Role),
             Content = new TextContentBlock { Text = message.Text },
         };
     }
@@ -328,6 +322,21 @@ private static JsonElement ParseToolInputSchema(McpGatewayToolDescriptor descrip
     private static string CreateToolMessage(string toolId, string suffix) =>
         string.Concat(ToolMessagePrefix, toolId, suffix);
 
+    private static Role ParsePromptRole(string role)
+    {
+        if (
+            Enum.TryParse<Role>(role, ignoreCase: true, out var parsedRole)
+            && Enum.IsDefined(parsedRole)
+        )
+        {
+            return parsedRole;
+        }
+
+        throw new InvalidOperationException(
+            string.Concat(InvalidPromptMessageRolePrefix, role, InvalidPromptMessageRoleSuffix)
+        );
+    }
+
     private static JsonElement CreateDefaultObjectSchema() =>
         JsonSerializer.SerializeToElement(
             new { type = "object", properties = new { } },

src/ManagedCode.MCPGateway/Hosting/Internal/Server/McpGatewayMcpServerTaskStore.cs

@@ -925,8 +925,10 @@ private async Task<JsonElement> WaitForStoredTaskResultAsync(
         CancellationToken cancellationToken
     )
     {
-        while (!cancellationToken.IsCancellationRequested)
+        while (true)
         {
+            cancellationToken.ThrowIfCancellationRequested();
+
             var currentTask = await _innerStore.GetTaskAsync(taskId, sessionId, cancellationToken);
             switch (currentTask?.Status)
             {
@@ -946,9 +948,6 @@ CancellationToken cancellationToken
                     break;
             }
         }
-
-        cancellationToken.ThrowIfCancellationRequested();
-        return default;
     }
 
     private static string CreateTaskMessage(string taskId, string suffix) =>
@@ -960,8 +959,10 @@ private static string CreateTaskMessage(string taskId, string suffix) =>
         CancellationToken cancellationToken
     )
     {
-        while (!cancellationToken.IsCancellationRequested)
+        while (true)
         {
+            cancellationToken.ThrowIfCancellationRequested();
+
             var result = await TryGetProxyTaskResultAsync(binding, cancellationToken);
             if (result is { } proxiedResult)
             {
@@ -975,9 +976,6 @@ CancellationToken cancellationToken
 
             await Task.Delay(TaskResultPollDelay, cancellationToken);
         }
-
-        cancellationToken.ThrowIfCancellationRequested();
-        return null;
     }
 
     private async Task<JsonElement?> TryGetProxyTaskResultAsync(