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/__tests__/advisor-evidence-adapter.test.ts

@@ -1,105 +0,0 @@
-import { describe, it, expect } from 'vitest'
-import { adaptEvidence } from '../advisor/evidence-adapter'
-import type { SdkRagResult } from '../agents/advisor-rag'
-
-describe('adaptEvidence', () => {
-  it('maps a structured RAG result to a hierarchical Knowledge Unit', () => {
-    const results: SdkRagResult[] = [
-      {
-        text: 'Der Verantwortliche fuehrt ein Verzeichnis ...',
-        regulation_code: 'DSGVO',
-        regulation_short: 'DSGVO',
-        article_label: 'Art. 30 DSGVO',
-        article: 'Art. 30',
-        paragraph: 'Abs. 1',
-        source_url: 'https://example.test/dsgvo-30',
-        score: 0.9,
-      },
-    ]
-    const { sources, stats } = adaptEvidence({ results })
-    expect(sources).toHaveLength(1)
-    expect(sources[0].label).toBe('Art. 30 DSGVO')
-    expect(sources[0].section).toBe('Art. 30')
-    expect(sources[0].paragraph).toBe('Abs. 1')
-    expect(sources[0].open?.originalUrl).toBe('https://example.test/dsgvo-30')
-    expect(sources[0].snippet).toContain('Verzeichnis')
-    expect(stats.sources).toBe(1)
-    expect(stats.regulations).toBe(1)
-  })
-
-  it('dedupes the same citation and keeps the highest score', () => {
-    const base: SdkRagResult = {
-      text: 'x',
-      regulation_code: 'CRA',
-      regulation_short: 'CRA',
-      article_label: 'Annex I',
-      article: 'Annex I',
-    }
-    const { sources } = adaptEvidence({
-      results: [
-        { ...base, score: 0.4 },
-        { ...base, score: 0.8 },
-      ],
-    })
-    expect(sources).toHaveLength(1)
-    expect(sources[0].score).toBe(0.8)
-  })
-
-  it('counts distinct regulations in stats', () => {
-    const { stats } = adaptEvidence({
-      results: [
-        { text: 'a', regulation_code: 'DSGVO', article_label: 'Art. 5' },
-        { text: 'b', regulation_code: 'DSGVO', article_label: 'Art. 6' },
-        { text: 'c', regulation_code: 'BDSG', article_label: '§ 38' },
-      ],
-    })
-    expect(stats.sources).toBe(3)
-    expect(stats.regulations).toBe(2)
-  })
-
-  it('labels recitals as Erwaegungsgrund', () => {
-    const { sources } = adaptEvidence({
-      results: [{ text: 'r', regulation_code: 'DSGVO', is_recital: true, article: '47' }],
-    })
-    expect(sources[0].section).toBe('Erwägungsgrund 47')
-  })
-
-  it('maps figures (C8) to figure units and counts them', () => {
-    const { figures, stats } = adaptEvidence({
-      results: [],
-      figures: [
-        {
-          figure_id: 'fig-pdca',
-          label: 'Abbildung 3',
-          caption: 'PDCA-Zyklus',
-          regulation_short: 'EDPB WP248',
-          vision_summary: 'Kreislauf Plan-Do-Check-Act',
-          image_url: 'https://example.test/abb3.png',
-        },
-      ],
-    })
-    expect(figures).toHaveLength(1)
-    expect(figures[0].label).toBe('Abbildung 3')
-    expect(figures[0].caption).toBe('PDCA-Zyklus')
-    expect(figures[0].imageUrl).toBe('https://example.test/abb3.png')
-    expect(stats.figures).toBe(1)
-  })
-
-  it('maps footnotes (C-FN) and counts them', () => {
-    const { footnotes, stats } = adaptEvidence({
-      results: [],
-      footnotes: [{ number: 17, regulation_short: 'EDPB WP248', section: 'Kapitel III.B', text: 'siehe ...' }],
-    })
-    expect(footnotes).toHaveLength(1)
-    expect(footnotes[0].ref).toBe('Fußnote 17')
-    expect(stats.footnotes).toBe(1)
-  })
-
-  it('returns empty evidence for empty input', () => {
-    const meta = adaptEvidence({})
-    expect(meta.sources).toEqual([])
-    expect(meta.figures).toEqual([])
-    expect(meta.footnotes).toEqual([])
-    expect(meta.stats).toEqual({ sources: 0, regulations: 0, figures: 0, footnotes: 0 })
-  })
-})

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

@@ -0,0 +1,70 @@
+import { describe, it, expect } from 'vitest'
+import {
+  resolveMode,
+  mapClarity,
+  mapFootnotes,
+  buildCitations,
+  numberedEvidenceForPrompt,
+} from '../advisor/retrieve-mapping'
+import type { EvidenceUnit } from '../advisor/contract'
+
+describe('resolveMode', () => {
+  it('a chosen context always forces answer', () => expect(resolveMode('clarify', true)).toBe('answer'))
+  it('clarify + no context -> clarify', () => expect(resolveMode('clarify', false)).toBe('clarify'))
+  it('answer -> answer', () => expect(resolveMode('answer', false)).toBe('answer'))
+  it('unknown/undefined -> answer', () => expect(resolveMode(undefined, false)).toBe('answer'))
+})
+
+describe('mapClarity', () => {
+  it('clarify maps candidate_contexts -> suggested_contexts', () => {
+    const c = mapClarity(
+      { mode: 'clarify', concentration: 0.3, candidate_contexts: [{ id: 'ds', label: 'Datenschutz', hits: 5 }] },
+      'clarify',
+    )
+    expect(c.is_underspecified).toBe(true)
+    expect(c.suggested_contexts).toEqual([{ id: 'ds', label: 'Datenschutz' }])
+  })
+  it('answer keeps dominant_context, drops suggestions', () => {
+    const c = mapClarity({ mode: 'answer', concentration: 0.88, dominant_context: 'ds' }, 'answer')
+    expect(c.is_underspecified).toBe(false)
+    expect(c.dominant_context).toBe('ds')
+    expect(c.suggested_contexts).toBeUndefined()
+  })
+})
+
+const ev: EvidenceUnit[] = [
+  { evidence_id: 'e1', document: 'DSGVO', section: 'Art. 30', paragraph: 'Abs. 1', snippet: 'x' },
+  { evidence_id: 'e2', document: 'BDSG', section: '§ 38' },
+]
+
+describe('buildCitations', () => {
+  it('numbers citations 1..n mapped to evidence', () => {
+    const cs = buildCitations(ev)
+    expect(cs).toHaveLength(2)
+    expect(cs[0]).toMatchObject({ citation_id: 'c1', number: 1, evidence_id: 'e1' })
+    expect(cs[1].number).toBe(2)
+  })
+})
+
+describe('numberedEvidenceForPrompt', () => {
+  it('prefixes each unit with [n] + its location', () => {
+    const s = numberedEvidenceForPrompt(ev)
+    expect(s).toContain('[1] DSGVO Art. 30 Abs. 1')
+    expect(s).toContain('[2] BDSG § 38')
+  })
+})
+
+describe('mapFootnotes', () => {
+  it('remaps a /retrieve footnote to the contract footnote', () => {
+    const fns = mapFootnotes([
+      { id: 'f1', number: 17, regulation_short: 'EDPB WP248', section: 'Kap III', text: 't' },
+    ])
+    expect(fns[0]).toMatchObject({
+      footnote_id: 'f1',
+      ref: 'Fußnote 17',
+      document: 'EDPB WP248',
+      section: 'Kap III',
+      text: 't',
+    })
+  })
+})