feat(ai-sdk): citation-graph assessment + opt-in graph expansion (Phase 2)

Add an `assessment` object to the legal RAG search response: primary norm,
connected norms (from the citation graph references_out/in of the primary),
cross_regime, human_review_flag, a norm-level winner_margin and a short
reasoning string. The margin is computed over DISTINCT norms, so a long
article split into several chunks no longer fabricates uncertainty. The
per-result schema stays frozen — graph fields are internal (json:"-").

Also wire optional citation-graph expansion (RAG_GRAPH_EXPANSION=true,
default off): top hits pull their referenced norms into the candidate pool
via the precise edge (e.g. Art. 13 CRA -> Anhang I). Measured to add no
rank gain over the existing binding-law augmentation, with +1 Qdrant call
per search and reverse-edge fan-out risk, so it ships off-by-default as a
recall safety net. The graph EXPLAINS retrieval (assessment), it does not
expand it by default.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

ai-compliance-sdk/internal/ucca/legal_rag_client.go

@@ -20,6 +20,7 @@ type LegalRAGClient struct {
 	httpClient       *http.Client
 	textIndexEnsured map[string]bool
 	hybridEnabled    bool
+	graphEnabled     bool
 }
 
 // NewLegalRAGClient creates a new Legal RAG client using Ollama bge-m3 embeddings.
@@ -38,6 +39,11 @@ func NewLegalRAGClient() *LegalRAGClient {
 	}
 
 	hybridEnabled := os.Getenv("RAG_HYBRID_SEARCH") != "false"
+	// Graph-Expansion ist OPT-IN: kein gemessener Rang-Nutzen ggue. der Binding-Augmentation,
+	// +1 Qdrant-Call/Suche, Flutungsrisiko ueber Reverse-Kanten. Bleibt als Recall-Sicherheitsnetz
+	// fuer spaetere Luecken (RAG_GRAPH_EXPANSION=true). Die Graph-Kanten werden in der Response
+	// zur Begruendung/Vollstaendigkeit genutzt, nicht zur Pool-Expansion (Default).
+	graphEnabled := os.Getenv("RAG_GRAPH_EXPANSION") == "true"
 
 	return &LegalRAGClient{
 		qdrantURL:        qdrantURL,
@@ -47,6 +53,7 @@ func NewLegalRAGClient() *LegalRAGClient {
 		collection:       "bp_compliance_ce",
 		textIndexEnsured: make(map[string]bool),
 		hybridEnabled:    hybridEnabled,
+		graphEnabled:     graphEnabled,
 		httpClient: &http.Client{
 			Timeout: 60 * time.Second,
 		},
@@ -100,6 +107,13 @@ func (c *LegalRAGClient) searchInternal(ctx context.Context, collection string,
 		hits = mergeDedupHits(hits, bindingHits)
 	}
 
+	// Graph-Augmentation: verbundene Normen (references_out/in) der Top-Hits ueber die
+	// praezise Zitations-Kante in den Pool ziehen — z.B. Art. 13 CRA zieht Anhang I (die
+	// eigentliche Pflichtquelle). Pool-Augmentation only; Re-Rank + topK bleiben.
+	if c.graphEnabled {
+		hits = c.expandViaGraph(ctx, collection, hits)
+	}
+
 	results := make([]LegalSearchResult, len(hits))
 	for i, hit := range hits {
 		// Legal-Metadaten nach rag_reingest_spec.md §2: bevorzugt die normalisierten Felder
@@ -131,6 +145,9 @@ func (c *LegalRAGClient) searchInternal(ctx context.Context, collection string,
 			AuthorityWeight: getInt(hit.Payload, "authority_weight"),
 			SourceClass:     getString(hit.Payload, "source_class"),
 			Jurisdiction:    getString(hit.Payload, "jurisdiction"),
+			CitationUnit:    getString(hit.Payload, "citation_unit"),
+			ReferencesOut:   getStringSlice(hit.Payload, "references_out"),
+			ReferencesIn:    getStringSlice(hit.Payload, "references_in"),
 		}
 	}