feat(advisor): Clarity-Gate orchestration in route.ts (consumes /retrieve)

Completes the advisor stack (FE + orchestration; /retrieve is SDK/RAG-owned). The route
now returns the FE contract instead of a text stream:
- retrieveFull() calls /retrieve with {query, context}; consumes clarity/evidence/
  visual_evidence/footnotes (exact shape per board 2026-07-01 12:25).
- mode-routing (resolveMode): clarify unless a context was chosen and /retrieve's
  clarity.mode says so. clarify -> L1 general answer (completeAdvisorAnswer, ungrounded,
  no sources). answer -> L2 answer over numbered evidence with [n] markers.
- citations generated here ([n] -> nth evidence unit); footnotes remapped; evidence /
  visual_evidence passed through.
- advisor-llm: non-streaming completeAdvisorAnswer(). Pure mappings in retrieve-mapping.ts
  (+ tests). Removed the dead v2 evidence.ts/evidence-adapter (RegulationRef moved to
  regulation-display). controls-augmentation kept (tested; re-integrable later).

NOT deployed: joint deploy with the SDK /retrieve endpoint (deploy-coupling). tsc clean,
25 vitest (mapping/clarify/answer/markdown/registry/rag), check-loc 0.

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

admin-compliance/lib/sdk/advisor/retrieve-mapping.ts

@@ -0,0 +1,83 @@
+// Pure mappings from the Go /retrieve response (SDK/RAG-owned; board 2026-07-01 12:25)
+// to the FE-facing advisor contract. Kept pure + testable; the orchestration (route.ts) wires them.
+
+import type { Citation, ClarityInfo, EvidenceUnit, Footnote, VisualEvidence } from './contract'
+
+export interface RetrieveClarity {
+  mode?: string // 'clarify' | 'answer'
+  reason?: string // e.g. 'middle_band_llm_needed'
+  concentration?: number
+  domain_count?: number
+  dominant_context?: string
+  candidate_contexts?: { id: string; label: string; hits?: number }[]
+}
+
+export interface RetrieveFootnote {
+  id?: string
+  ref?: string
+  number?: number
+  regulation_code?: string
+  regulation_short?: string
+  regulation_name?: string
+  section?: string
+  text?: string
+}
+
+export interface RetrieveResponse {
+  evidence?: EvidenceUnit[]
+  visual_evidence?: VisualEvidence[]
+  footnotes?: RetrieveFootnote[]
+  clarity?: RetrieveClarity
+  results?: unknown[]
+  tables?: unknown[] // C6 — not in the FE contract yet (future TablesPane)
+}
+
+/** clarify unless a context was chosen; /retrieve's clarity.mode decides for un-scoped queries. */
+export function resolveMode(clarityMode: string | undefined, hasContext: boolean): 'clarify' | 'answer' {
+  if (hasContext) return 'answer'
+  return clarityMode === 'clarify' ? 'clarify' : 'answer'
+}
+
+export function mapClarity(c: RetrieveClarity | undefined, mode: 'clarify' | 'answer'): ClarityInfo {
+  return {
+    is_underspecified: mode === 'clarify',
+    concentration: c?.concentration ?? 0,
+    dominant_context: c?.dominant_context,
+    suggested_contexts:
+      mode === 'clarify' ? (c?.candidate_contexts ?? []).map((cc) => ({ id: cc.id, label: cc.label })) : undefined,
+  }
+}
+
+export function mapFootnotes(fns: RetrieveFootnote[] | undefined): Footnote[] {
+  return (fns ?? []).map((f) => ({
+    footnote_id: f.id,
+    ref: f.ref ?? (f.number != null ? `Fußnote ${f.number}` : undefined),
+    document: f.regulation_short || f.regulation_name || f.regulation_code,
+    section: f.section,
+    text: f.text,
+  }))
+}
+
+/** Citations are generated by the orchestration (not by /retrieve): [n] -> nth evidence unit. */
+export function buildCitations(evidence: EvidenceUnit[]): Citation[] {
+  return evidence.map((e, i) => ({
+    citation_id: `c${i + 1}`,
+    number: i + 1,
+    evidence_id: e.evidence_id,
+    document: e.document,
+    section: e.section ?? null,
+    paragraph: e.paragraph ?? null,
+    footnote: null,
+    figure: null,
+  }))
+}
+
+/** Numbered evidence list injected into the L2 prompt so the LLM can cite [n]. */
+export function numberedEvidenceForPrompt(evidence: EvidenceUnit[]): string {
+  return evidence
+    .map((e, i) => {
+      const loc = [e.document, e.section, e.paragraph].filter(Boolean).join(' ')
+      return `[${i + 1}] ${loc}\n${e.snippet ?? ''}`.trim()
+    })
+    .join('\n\n')
+}