fix: guarantee per-namespace representation in federated search results

The caller's limit was applied to the globally reranked merged pool, so
one namespace with high-scoring hits could push every other namespace
out of the response entirely. Rank globally without truncation, then
select with a per-namespace quota (limit/namespaces, minimum one) and
fill the remaining slots in global rank order.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: tae2089

internal/adapters/inbound/mcp/handler_federated_test.go

@@ -2,8 +2,10 @@ package mcp
 
 import (
 	"encoding/json"
+	"fmt"
 	"os"
 	"path/filepath"
+	"strings"
 	"testing"
 
 	"github.com/mark3labs/mcp-go/mcp"
@@ -79,6 +81,58 @@ func TestSearch_FederatesAcrossNamespaces(t *testing.T) {
 	}
 }
 
+func TestSearch_FederatedLimitDoesNotStarveNamespaces(t *testing.T) {
+	deps := setupTestDeps(t)
+
+	alphaDir := t.TempDir()
+	betaDir := t.TempDir()
+	var alphaSrc strings.Builder
+	alphaSrc.WriteString("package alpha\n")
+	for i := 1; i <= 5; i++ {
+		fmt.Fprintf(&alphaSrc, "\nfunc Payment%d() string {\n\treturn \"payment\"\n}\n", i)
+	}
+	if err := os.WriteFile(filepath.Join(alphaDir, "pay.go"), []byte(alphaSrc.String()), 0o644); err != nil {
+		t.Fatalf("write alpha: %v", err)
+	}
+	if err := os.WriteFile(filepath.Join(betaDir, "refund.go"), []byte("package beta\n\nfunc PaymentZz() string {\n\treturn \"payment\"\n}\n"), 0o644); err != nil {
+		t.Fatalf("write beta: %v", err)
+	}
+	deps.Runtime.RepoRoot = alphaDir
+	if res := callTool(t, deps, "build_or_update_graph", map[string]any{"path": alphaDir, "namespace": "alpha"}); res.IsError {
+		t.Fatalf("parse alpha failed: %+v", res)
+	}
+	deps.Runtime.RepoRoot = betaDir
+	if res := callTool(t, deps, "build_or_update_graph", map[string]any{"path": betaDir, "namespace": "beta"}); res.IsError {
+		t.Fatalf("parse beta failed: %+v", res)
+	}
+
+	result := callTool(t, deps, "search", map[string]any{
+		"query":      "Payment",
+		"limit":      3,
+		"namespaces": []string{"alpha", "beta"},
+	})
+	var items []struct {
+		QualifiedName string `json:"qualified_name"`
+		Namespace     string `json:"namespace"`
+	}
+	if err := json.Unmarshal([]byte(resultTextOf(t, result)), &items); err != nil {
+		t.Fatalf("unmarshal: %v", err)
+	}
+	if len(items) != 3 {
+		t.Fatalf("result count = %d, want limit 3", len(items))
+	}
+	perNS := map[string]int{}
+	for _, item := range items {
+		perNS[item.Namespace]++
+	}
+	if perNS["beta"] == 0 {
+		t.Fatalf("federated limit starved namespace beta: %v", perNS)
+	}
+	if perNS["alpha"] == 0 {
+		t.Fatalf("federated limit starved namespace alpha: %v", perNS)
+	}
+}
+
 func TestSearch_SingleNamespaceResponseUnchanged(t *testing.T) {
 	deps := setupTestDeps(t)
 	seedFederatedNamespaces(t, deps)

internal/adapters/inbound/mcp/handler_query.go

@@ -285,7 +285,8 @@ func (h *handlers) searchFederated(ctx context.Context, query string, limit int,
 			merged = filtered
 		}
 
-		merged = searchrank.Rerank(query, merged, limit)
+		merged = searchrank.Rerank(query, merged, 0)
+		merged = selectWithNamespaceQuota(merged, limit, len(namespaces))
 		log.Info("federated search completed", "query", query, "namespaces", namespaces, "result_count", len(merged))
 
 		items := make([]searchResultItem, len(merged))
@@ -300,6 +301,46 @@ func (h *handlers) searchFederated(ctx context.Context, query string, limit int,
 	}))
 }
 
+// selectWithNamespaceQuota bounds globally-ranked federated results while guaranteeing
+// every namespace with hits at least limit/namespaceCount slots (minimum one).
+// @intent keep one high-scoring repository from starving the other namespaces out of a federated result.
+// @domainRule remaining slots after the per-namespace quota pass are filled in global rank order.
+func selectWithNamespaceQuota(ranked []graph.Node, limit, namespaceCount int) []graph.Node {
+	if limit <= 0 || len(ranked) <= limit {
+		return ranked
+	}
+	quota := max(limit/max(namespaceCount, 1), 1)
+	chosen := make([]bool, len(ranked))
+	count := 0
+	perNamespace := map[string]int{}
+	for i, n := range ranked {
+		if count == limit {
+			break
+		}
+		if perNamespace[n.Namespace] < quota {
+			chosen[i] = true
+			perNamespace[n.Namespace]++
+			count++
+		}
+	}
+	for i := range ranked {
+		if count == limit {
+			break
+		}
+		if !chosen[i] {
+			chosen[i] = true
+			count++
+		}
+	}
+	selected := make([]graph.Node, 0, limit)
+	for i, n := range ranked {
+		if chosen[i] {
+			selected = append(selected, n)
+		}
+	}
+	return selected
+}
+
 // getAnnotation returns stored annotation metadata for a graph node.
 // @intent fetch stored annotation tags and summary data so semantic search results can show business context.
 // @param request qualified_name is the fully qualified node name whose annotations should be loaded.