feat(r5.2): assistant au contrat + suggestion de codes de bilan

apps/ai : /internal/ask — seuil de pertinence, extraits sourcés ou
refus honnête portant la taille du corpus cherché (D2), rédaction via
le Generateur opt-in ; /internal/suggest — similarité sémantique entre
la description libre et les libellés ACTIFS des référentiels, un code
par champ, confiance FORTE/MOYENNE, « N bilans similaires sur ce
parc ». Sans LLM : déterministe, explicable. 23 pytest.

Contrat (74 opérations) : POST /assistant/ask → AssistantAnswer
(EXTRACTIVE/GENERATED/REFUSAL, extraits cités, corpus cherché) et
POST /assistant/suggest-bilan (codes existants seulement) ; clients
web/mobile régénérés.

API NestJS : module assistant — proxy vers siop2-ai (AI_SERVICE_URL/
AI_SERVICE_TOKEN, ADR-004 §4), permissions matrice (ask=view,
suggest=edit), traduction interne→contrat, 503 propre si service
éteint. 6 e2e sur stub HTTP (76 tests API).

Bug débusqué par la vraie chaîne : fastembed ne norme pas ses
vecteurs — la similarité des suggestions dépassait 1 (pgvector
normalisait dans son opérateur, masquant l'écart). Normalisation à
l'encodage + réindexation : bilans en tête (0.41), refus hors corpus,
scores cosinus ≤ 1.

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

packages/shared/src/contract.ts

@@ -50,6 +50,12 @@ import {
   DocumentsResponseSchema,
 } from './schemas/documents';
 import { SearchResponseSchema } from './schemas/search';
+import {
+  AssistantAnswerSchema,
+  AssistantAskSchema,
+  BilanSuggestionsResponseSchema,
+  SuggestBilanSchema,
+} from './schemas/assistant';
 import {
   ConsumePartSchema,
   LaborTimeCreateSchema,
@@ -508,6 +514,30 @@ export const API_CONTRACT: ApiOperation[] = [
       200: { description: 'Synthèse', name: 'AnalyticsSummary', schema: AnalyticsSummarySchema },
     },
   },
+  {
+    operationId: 'askAssistant',
+    method: 'post',
+    path: '/assistant/ask',
+    summary: 'Assistant R5 — sourcé ou silencieux : extraits cités ou refus honnête (D2)',
+    tags: ['assistant'],
+    request: { name: 'AssistantAsk', schema: AssistantAskSchema },
+    responses: {
+      200: { description: 'Réponse sourcée ou refus', name: 'AssistantAnswer', schema: AssistantAnswerSchema },
+      503: { description: 'Service IA indisponible' },
+    },
+  },
+  {
+    operationId: 'suggestBilan',
+    method: 'post',
+    path: '/assistant/suggest-bilan',
+    summary: 'Suggérer des codes de bilan depuis une description libre (D1 — l’humain valide)',
+    tags: ['assistant'],
+    request: { name: 'SuggestBilan', schema: SuggestBilanSchema },
+    responses: {
+      200: { description: 'Suggestions (codes existants seulement)', name: 'BilanSuggestions', schema: BilanSuggestionsResponseSchema },
+      503: { description: 'Service IA indisponible' },
+    },
+  },
   {
     operationId: 'globalSearch',
     method: 'get',