HiveGrid-Wireframes/hivegrid-cloud/docs/boilerplate-mapping/M18-ki-layer.md

Boilerplate-Abgleich: M18 — KI-Layer / LLM-Gateway

Faktischer Abgleich der HiveGrid-Detail-Spec (M18) gegen die Boilerplate. Boilerplate-Wurzel (NUR LESEN): /Users/raffaelsheikh/Documents/GitHub/boilerplate Spec-Quelle: /Users/raffaelsheikh/Documents/GitHub/HiveGrid-Cloud/_bmad-output/specs/M18-ki-layer.md Alle Pfade absolut. Nichts erfunden — jeder Eintrag verweist auf konkrete Datei(en); fehlt etwas, ist es klar als Lücke markiert.

Kopf

Feld	Wert
Modul-ID	M18
Name	KI-Layer / LLM-Gateway
Milestones	M083 (EU-Provider-Layer), M084 (Multi-Provider-Fallback), M085 (Promptfoo-Eval-Suite), M086 (Sprach-zu-Automation), M087 (RAG + Aktions-Grenze), M088 (Token-Limits + Pay-as-you-go)
Block	Block 4 — Integrationen, Automation & KI (_bmad-output/pflichtenheft/blocks/block4.md, Modul 18)
Reuse-Level	HIGH

Kernaussage: Das ist die USP-Säule mit dem höchsten Wiederverwendungs-Grad im KI-Bereich. Die Boilerplate liefert den kompletten EU-Provider-Layer (Mistral/Scaleway/Aleph Alpha — exakt der von der Spec geforderte Stack, KEIN OpenAI/Anthropic im aktiven Pfad), den 30-Min-Multi-Provider-Fallback (M084 quasi fertig), die RAG/Embeddings-Pipeline + pgvector-Store (M087-Retrieval), die Promptfoo-Eval-Suite mit OWASP-Injection-Vektoren + Gitea-CI-Workflow (M085 quasi fertig), das Cost-/Quota-Tracking inkl. Pay-as-you-go-Overage-Logik (M088-Engine fertig) und die Guards/Action-Boundary-Bausteine (M087-Aktions-Grenze). Die Hauptlücken liegen bei: HiveGrid-spezifische Daten-Modelle (LlmGatewayProvider/Model, AiSettings, Conversation als HiveGrid-Variante, TenantEmbedding-Tabelle), Whisper-EU-Transkription (komplett nicht vorhanden), die Use-Case-Orchestrierung (Lead-Zusammenfassung, Sprach→Automation, Stuck-Deal, Email-Klassifizierung) und das gesamte UI (Chat, Usage-Dashboard, Settings, Voice-Assistant).

---

Übernehmbar aus Boilerplate

Boilerplate-Pfad	Was	Wie nutzbar
packages/ai/src/index.ts	Provider-Adapter-Interface + Registry: AIProviderName = "mistral"|"scaleway"|"aleph-alpha", getAIProviderAdapter(), getAIProviderAdapterForModel(), getPrimaryProvider(), getAIProviderDiagnostics(), Modell-Katalog aiModels (mit Preisen pro Mio Tokens), defaultAIModel = "mistral-large-latest"	1:1 — exakt der von Spec Block B geforderte EU-Stack. Deckt M083 Erfolgskriterium (Mistral-Aufruf, Switch via Env-Var, keine US-Endpunkte)
packages/ai/src/providers/mistral.ts	Mistral-Provider via @ai-sdk/mistral, resolveMistralModel(env), MISTRAL_API_KEY/MISTRAL_MODEL	1:1 — Primary-Provider (Spec: Mistral Large Chat / Mistral Small)
packages/ai/src/providers/scaleway.ts	Scaleway-Provider (OpenAI-kompatibel), Default mistral-small-3.2-24b-instruct-2506, SCALEWAY_*-Env	1:1 — Secondary-Provider (France-EU)
packages/ai/src/providers/aleph-alpha.ts	Aleph-Alpha-Provider (OpenAI-kompatibel), Default pharia-1-llm-7b-control, ALEPH_ALPHA_*-Env	1:1 — Tertiary-Provider (Germany-EU)
packages/ai/src/providers/compatible.ts	createCompatibleLanguageModel() (gemeinsame OpenAI-kompatible Basis für Scaleway + Aleph Alpha)	1:1
packages/ai/src/fallback.ts	AIProviderHealthTracker (30-Min-Failure-Window = fallbackWindowMs), getFallbackProviderSelection(), fallbackProviderOrder = ["mistral","scaleway","aleph-alpha"]	1:1 / anpassen — deckt M084 (Auto-Fallback + 30-Min-Window) fast vollständig. Spec verlangt zusätzlich 1-Min-Health-Ping + 5-Min-Sperre (Block H / 18.6.3) — der Health-Tracker ist reaktiv (failure-on-call), nicht aktiv-pingend → kleine Erweiterung nötig
packages/ai/src/cost/executeLLMCall.ts	LLM-Wrapper: wrappt jeden Provider-Call, leitet Token/Kosten ab, emittiert Outbox-Event ai.cost.event.persist, Quota-Pre-Check + Soft-Degradation + Concurrency-Slot; Killswitch AI_COST_TRACKING_ENABLED=false; Capabilities chat/chat-stream/embedding/completion/rerank/tool-call	1:1 — zentraler Gateway-Aufruf-Wrapper (Spec Block B Interface + Block F Token-Tracking)
packages/ai/src/cost/assertCredit.ts	assertTenantAICreditAccess() — Pre-Call-Quota-Assertion (3 Outcomes: allow / allow+degradeTo / throw AIQuotaExceededError), Concurrency-Counter, Soft-Degradation (90%-Threshold), per-Capability-Caps, Killswitch AI_QUOTA_ENFORCEMENT_ENABLED=false	1:1 / anpassen — M088-Kern. WICHTIG: Default-Verhalten ist Hard-Deny (HTTP 402) bei Limit. HiveGrid [N13] verlangt Pay-as-you-go statt Pause → die Hard-Deny-Pfade durch Overage-Pfad ersetzen (Overage-Logik existiert separat, s.u.)
packages/entitlements/src/ai-overage.ts	Pay-as-you-go-Overage: AI_OVERAGE_DEFAULT_MULTIPLIER = 1.5, computeMarkedUpCostCents(), roundUpToBlock(), resolveTenantAIOverage(), standardAIOverageDefaults pro Plan, TenantAIOverageOverride (parse/resolve)	anpassen — genau das von M088/[N13] geforderte Aufschlags-Tarif-Modell. Markup-Faktor + Block-Rundung fertig; HiveGrid-Plan-Werte + Notbremse-Threshold (18.8.7) einsetzen
packages/entitlements/src/ai-quotas.ts	aiQuotaCapabilityKeys, AIQuotaPlanDefaults (aiQuotaCentsPerMonth / aiPerCapabilityCaps / aiMaxConcurrentCalls / aiDegradeTo), standardAIQuotaDefaults (starter/pro/business), resolveTenantAIQuota(), parseTenantAIQuotaOverride()	anpassen — Inklusiv-Kontingent + per-Capability-Caps pro Plan. HiveGrid-Token/Cent-Werte einsetzen (Spec: „konkrete Mengen mit Pricing-Festlegung", noch offen)
packages/ai/src/cost/spend-cache.ts	createSpendCache() — Monatsspend-Caching (TTL) als Watermark für 80%-Banner und Forecast	1:1 — Datenbasis für 80%-Soft-Limit-Banner + Email (18.8.2) und Usage-Dashboard-Forecast (18.8.9)
packages/ai/src/cost/tokens.ts	countTokens/countMessageTokens (gpt-tokenizer + Heuristik-Fallback)	1:1 — Token-Zählung für Budget pro Use-Case (Spec C: ~2000 in / 800 out etc.)
packages/ai/src/cost/pricing/v2026-05-16.ts + pricing/index.ts	Versionierte Pricing-Tabelle (getPricingTable, LATEST_PRICING_VERSION)	anpassen — EU-Provider-Preise sind als aiModels[].costPerM* bereits hinterlegt; HiveGrid-Aufschlags-Tarife ergänzen
packages/ai/src/guards/index.ts	assertAICostBudget(), createFixedWindowAIRateLimiter() (pro userId), createAIAuditEvent()/createAI{Prompt,ToolCall,Mutation}AuditEvent(), redactAIAuditPayload() (PII-Redaction), createReviewRequiredResult(), AIGuardError	1:1 / anpassen — createReviewRequiredResult() + Mutation-Audit-Events sind das Fundament der Action-Boundary (M087, Spec Block G/18.5.3: KI generiert nur Vorschläge, User bestätigt). Audit-Redaction deckt AV#6
packages/ai/src/embeddings/factory.ts + embeddings/types.ts	createEmbeddingProvider(), registerEmbeddingProviderAdapter(), resolveEmbeddingProviderName(env), resolveEmbeddingDimensions(env), EmbeddingProvider-Interface	1:1 — RAG-Schreib-/Leseseite-Fundament (M087 / Spec Block D)
packages/ai/src/embeddings/providers/scaleway.ts	Scaleway-Embeddings-Adapter, Default bge-multilingual-gemma2 (1024 dim), Batch 64, max 4096 Tokens	1:1 — Spec Block D: „Scaleway-Embeddings, 1024-Dim Default" — exakter Match
packages/ai/src/embeddings/embed-and-upsert.ts	embedAndUpsert() — chunked Embed + Upsert in VectorUpsertSink; erzwingt tenantId im Payload; deterministische buildChunkId(); optionale Kostenverfolgung über executeLLMCall	1:1 / anpassen — Embedding-Pipeline (Spec D: bei Anlage/Update Embedding). Re-Embed-bei-Text-Änderung via Hash (Spec D) muss als Trigger-Wiring ergänzt werden
packages/ai/src/embeddings/retrieve.ts	retrieveRelevantContext() — Query embedden, Fan-out über Collections, Rank-Merge, min-Score 0.7, top-K 8; tenant-scoped via RagRetrievalStore.searchForTenant	1:1 — RAG-Leseseite. Spec D Permission-Pre-Filter andocken
packages/ai/src/embeddings/chunking.ts	splitForEmbedding(), countTokens(), DEFAULT_CHUNK_TOKENS/...OVERLAP_TOKENS	1:1
packages/ai/src/embeddings/outbox-publisher.ts	publishRagUpsertEvent/publishRagDeleteEvent, ragEventType() → rag.index.<entity>.<verb> (BullMQ-Queue outbox.rag-index), Idempotenz via dispatchKey	1:1 — async Re-Index bei jedem Domain-Write (Spec D Embedding-Pipeline)
packages/vector-store/src/factory.ts + adapters/pgvector.ts	createVectorStore() (pgvector Default / Qdrant Upgrade), PgvectorAdapter mit HNSW-Index (m/efConstruction), Payload-Filter	1:1 — Spec D: „pgvector mit HNSW-Index" — exakter Match. Offener Detail-Punkt der Spec (IVFFlat vs. HNSW) ist durch BP bereits auf HNSW entschieden
packages/vector-store/src/wrappers/tenant-scoped.ts	withTenantScope() → TenantScopedVectorStore; searchForTenant() erzwingt tenantId-must-Filter; bare searchVectors() wirft	1:1 — Spec D: „kein Cross-Tenant!" + M087 Permission-aware. Tenant-Isolation built-in
prisma/migrations/20260517085146_04_enable_pgvector/migration.sql	Aktiviert pgvector-Extension	1:1 — Voraussetzung für TenantEmbedding-Tabelle
packages/ai/src/prompts/index.ts	createAIPromptRegistry() mit Versionierung, render(selection, variables), {{var}}-Templates, AIPromptRegistryError	1:1 / als-vorlage — System-Prompt-Trennung (Spec G/18.5.2) + Use-Case-Prompts. Strikte System/User-Daten/Frage-Trennung als Template-Konvention
packages/ai/src/tools/index.ts	createAIToolRegistry() (scoped Tools für Vercel AI SDK ToolSet), toToolSet(selection), Secret-Redaction	1:1 — Tool-Calling-Architektur (Spec G: Tools nur per Tool-Call-Output, nicht aus Text geparst). Basis für Sprach→Automation-Tools (M086)
packages/ai/src/streaming/index.ts	createAITextStream() via streamText, Guard-Evaluator, Prompt-/Tool-Registry-Integration, getAITextStreamDiagnostics() mit Redaction	1:1 — Streaming-Chat-UX für Programm-Hilfe-Chat (Use-Case 3). Guard-Evaluator-Seam = Action-Boundary-Andock-Punkt
packages/ai/src/promptfoo-provider.ts + promptfoo.config.yaml (Repo-Root) + tests/promptfoo/injection-vectors.yaml + .gitea/workflows/promptfoo.yml	Promptfoo-Eval-Harness mit OWASP-LLM-Vektoren (LLM01/LLM02/LLM06…), Mistral-als-Primary-Label, deterministischer Test-Provider, CI-Workflow	1:1 / anpassen — M085 quasi fertig: description: EU-only OWASP LLM injection-vector eval suite. Pro neuem HiveGrid-Prompt-Flow eigene Eval-Vektoren ergänzen (Spec G: „pro Prompt-Flow eigene Eval-Suite")
packages/ai/test/evals/promptfoo-baseline.test.ts + prompt-registry-cases.yaml	Eval-Baseline-Vitest + Prompt-Registry-Testfälle	als-vorlage — Muster für HiveGrid-Prompt-Flow-Evals
prisma/schema/ai.prisma → Chat, ChatMessage, ChatMessagePart	Chat-Datenmodell (Typ tenant/admin/marketing, Scope, anonym via sessionId, Multi-Part-Messages)	als-vorlage / anpassen — deckt Spec Conversation/ConversationMessage strukturell. Chat.kind/HiveGrid-kind-Enum (programm_help/automation_builder) ergänzen; lastMessageAt/archivedAt bereits vorhanden
prisma/schema/ai.prisma → GeneratedObject	Strukturierte AI-Outputs mit Token/Cost-Feldern, status pending/success/error, model, chatId	1:1 / anpassen — Spec GeneratedObject (JSON-Schema-validierte Outputs). schema_version-Feld ergänzen
prisma/schema/ai.prisma → AICostEvent	Append-only Cost-Log (requestId @unique, KEINE Prompt-Bodies, capability/provider/model/Tokens/Cents, isOverage, markedUpCostCents, stripeReportedAt)	1:1 — Spec AiTokenUsage (Verbrauch pro Tenant/User/Use-Case). Overage-Felder + Stripe-Watermark für M088 bereits da
prisma/schema/ai.prisma → TenantAICostSummary	Vor-aggregierte Cost-Summary pro Periode (@@unique([tenantId, periodStart]), breakdown JSON)	1:1 — Spec AiCredits-Aggregat + Usage-Dashboard O(1)-Top-Line (18.8.9)
prisma/schema/accounts.prisma → Tenant AI-Felder	aiQuotaOverrideJson (Json, geformt als TenantAIQuotaOverride), aiCostLastAlertedThreshold, aiCostLastAlertedPeriod	1:1 / anpassen — Spec AiSettings.usage_limit_tokens_per_month + idempotente 80%-Alert-State. HiveGrid-AiSettings braucht zusätzlich enabled_use_cases[], default_models, data_residency (s. Lücken)
prisma/schema/promptFlows.prisma → PromptFlow, PromptTemplate, PromptFlowExecution, PromptFlowOutput*, PromptFlowInputVariable	LLM-Prompt-Pipelines an Entity/Property gekoppelt, executionType sequential/parallel, Streaming-Flag, Execution + Result-Log, Output→Row-Property-Mapping	als-vorlage — Phase-2-PromptFlow/PromptTemplate (visueller Prompt-Editor, Spec Block J) bereits strukturell vorhanden. Für Phase 1 optional als Use-Case-Prompt-Definitionen
packages/queue/src/payloads.ts → AiJob	Typisierte AI-Jobs: ai.chat-completion / ai.embedding / ai.browser-task; Queue toolctrl.ai-chatbot (names.ts)	1:1 / anpassen — async KI-Verarbeitung. Whisper-Transkriptions-Job-Typ fehlt → ergänzen (ai.transcribe)
packages/queue/src/* (producers/priority/connection/runtime)	enqueueJob(), Idempotenz (buildIdempotentJoben), Plan-basierte Prioritäten (resolveJobPriorityForTenant), BullMQ-Runtime-Factory	1:1 — Whisper-Async-Pipeline (Spec E: Audio-Upload → Job-Queue → Whisper → Resultat) baut hierauf
packages/storage/src/index.ts + signed/index.ts + scan/*	Scaleway-S3-Adapter, Signed-Upload/Download-URLs, ClamAV + magic-bytes Virus-Scan, Quarantäne	1:1 — Audio-Upload für Whisper-Transkription (Spec E) + DSGVO-EU-Storage
packages/db/src/outbox.ts + prisma/schema/outbox.prisma	publishOutboxEvent(tx, args) transaktional, OutboxEvent-Modell	1:1 — alle KI-Side-Effects (Cost-Persist, RAG-Reindex, Notifications) transaktional
prisma/schema/notifications.prisma → NotificationDelivery, UserNotificationPreference	In-App + Email + Push Notification-Delivery	1:1 — 80%-Budget-Email an Tenant-Admin (18.8.2), Notbremse-Warnung (18.8.7) — via notify() (M011), nicht direkt
prisma/schema/permissions.prisma → Role, Permission, RolePermission, UserRole, Group	RBAC-Fundament	1:1 — die 6 ai.*-Permissions (Spec Block I) als Permission-Rows + Bundle-Mapping + Default-Rollen-Zuweisung
prisma/schema/featureFlags.prisma → FeatureFlag	Feature-Toggles (scope global/tenant/user)	1:1 — DoD verlangt Feature-Flag-Abschaltbarkeit; ai-quota-soft-degradation-Flag wird von assertCredit.ts bereits erwartet
prisma/schema/knowledgeBase.prisma → KnowledgeBaseArticle etc.	Help-Center-Datenmodell	als-vorlage — RAG-Quelle für Programm-Hilfe-Chat (Use-Case 3) + HelpArticleEmbedding (M38-Kopplung)
packages/search/src/* (Meilisearch) + schemas/kb-articles.ts	Tenant-scoped Volltext-Index	1:1 — Spec D Hybrid-Suche (Volltext + Embeddings) + Graceful-Degradation-Fallback bei Provider-Down (Spec D/H: „Standard-Volltext-Suche aktiv")

---

Vorhandene Daten-Modelle (konkret)

Alle in /Users/raffaelsheikh/Documents/GitHub/boilerplate/prisma/schema/:

Spec-Modell (M18 Block A)	Boilerplate-Entsprechung	Datei	Bewertung
Conversation	Chat (type tenant/admin/marketing, scope, sessionId, title, lastMessageAt, archivedAt, metadata)	ai.prisma	strukturell vorhanden — kind-Werte (programm_help/automation_builder/tenant_assistant) als HiveGrid-Anpassung
ConversationMessage	ChatMessage + ChatMessagePart (role, Multi-Part content, order)	ai.prisma	vorhanden — Token-Felder (tokens_input/output) pro Message ergänzen (aktuell auf GeneratedObject/AICostEvent-Ebene)
GeneratedObject	GeneratedObject (object/type/model, userPrompt/fullPrompt, generatedData JSON, Token+Cost, status, chatId)	ai.prisma	nahezu 1:1 — schema_version ergänzen
AiTokenUsage	AICostEvent (capability, provider, model, in/out/total Tokens, costCents, requestId @unique, isOverage, markedUpCostCents, stripeReportedAt)	ai.prisma	1:1 — append-only, KEINE Prompt-Bodies (PII-konform)
AiCredits (Aggregat-Teil)	TenantAICostSummary (periodStart/End, totalCostCents, total Tokens, breakdown JSON)	ai.prisma	1:1 für vor-aggregierte Sicht
AiSettings (Teil)	Tenant.aiQuotaOverrideJson + aiCostLastAlertedThreshold/Period	accounts.prisma	teilweise — Quota-Override + Alert-State da; restliche AiSettings-Felder fehlen
Plan-Defaults / Inklusiv-Kontingent	standardAIQuotaDefaults + AIQuotaPlanDefaults (Code, kein DB-Modell)	packages/entitlements/src/ai-quotas.ts	1:1 (Code-Registry-Stil)
Overage-/Aufschlags-Tarif	standardAIOverageDefaults + resolveTenantAIOverage (Code)	packages/entitlements/src/ai-overage.ts	1:1 (Code-Registry-Stil)
PromptFlow/PromptTemplate (Phase 2)	PromptFlow, PromptTemplate, PromptFlowExecution, PromptFlowOutput(+Mapping), PromptFlowInputVariable, PromptFlowGroup(+Template+Entity)	promptFlows.prisma	12 Modelle bereits vorhanden (visueller Prompt-Editor Phase 2)

Provider-Registry als Code, nicht als DB: Die Spec modelliert LlmGatewayProvider / LlmGatewayModel als „Plattform-weit, Code-Registry". Die Boilerplate setzt das genau so um: providerMetadata + aiModels-Katalog in packages/ai/src/index.ts (mit costPerMInputTokens/costPerMOutputTokens/maxOutputTokens pro Modell). Es gibt keine Prisma-Modelle LlmGatewayProvider/LlmGatewayModel — das ist konform mit der Spec (Code-Registry) und kein Defizit.

---

Lücken / komplett neu zu bauen

Daten-Layer (in prisma/schema/app.prisma — leerer HiveGrid-Platzhalter)

1. AiSettings (HiveGrid-spezifisch) — kein Modell vorhanden. Benötigt: enabled_use_cases[], default_models (Use-Case→Modell-Key JSON), data_residency (Default eu, Hard-Constraint). Teilweise durch Tenant.aiQuotaOverrideJson gedeckt; HiveGrid-Settings-Modell neu.
2. TenantEmbedding-Tabelle — als Prisma-Modell nicht vorhanden. Die Boilerplate legt Vektoren über pgvector in vec_<namespace>_<collection>-Tabellen per Raw-SQL an (kein Prisma-Modell). Spec verlangt zusätzlich Metadaten-Tracking (entity_type, entity_id, text_source für Re-Embed-Hash, embedding_model_id, last_embedded_at) — Metadaten-Begleittabelle neu bauen (die Vektoren selbst kommen aus dem vorhandenen pgvector-Adapter).
3. HelpArticleEmbedding (M38-Kopplung) — nicht vorhanden; analog zu TenantEmbedding über pgvector + Begleit-Metadaten.
4. Conversation-kind-Enum + per-Message-Token-Felder — kleine Schema-Erweiterung an Chat/ChatMessage.
5. Whisper-Transkriptions-Modell (Job-Status, Audio-Ref, Transkript, Sprache, Edit-State) — komplett neu.

Whisper-EU-Transkription (Spec Block E) — KOMPLETT FEHLT

• Kein Transcription-Adapter, keine transcribe()-Methode in packages/ai, kein Audio/Whisper-Code (grep über packages/ai/src ergab 0 Treffer für transcri/whisper/audio/speech).
• Queue-Payload AiJob kennt nur ai.chat-completion/ai.embedding/ai.browser-task — ai.transcribe fehlt.
• Neu zu bauen: Whisper-auf-Scaleway-GPU-Adapter (DSGVO-konform), Async-Pipeline (Storage-Upload → Queue → Whisper → Resultat — Bausteine storage + queue vorhanden), Auto-Sprache-Erkennung (DE/EN), Mikrofon-Aufnahme-UI, Edit-Funktion, Klartext-Fehler.

Use-Case-Orchestrierung (Spec Block C) — Gateway-Bausteine da, Use-Cases neu

• Lead-Zusammenfassung / Pre-Termin-Brief (Use-Case 2): Activity-Stream + Custom-Felder + Form-Submissions als Kontext sammeln, Cache-Hit-Logik (gleiche Datenbasis), Widget im Kontakt-Detail. Neu.
• Programm-Hilfe-Chat (Use-Case 3): RAG über Help-Articles + Conversation-Historie. Streaming-Chat-Baustein vorhanden, Orchestrierung + UI neu.
• Klartext-Diagnostik-Fallback (Use-Case 4): KI nur Fallback bei unbekannten Fehler-Codes, klar markiert. Neu.
• Stuck-Deal-Vorschläge (Use-Case 5): wöchentlicher Cron-Job, Widget. Neu (Cron via M-Infra).
• Email-Klassifizierung (Use-Case 7): lead|customer_question|invoice|spam|newsletter|other, Inbox-Auto-Verknüpfung (M9). Neu.
• Sprach-zu-Automation (M086, USP-Hauptstütze): Sprach-Befehl → Wenn-Dann-Vorschlag im visuellen Editor, Rückfrage bei Mehrdeutigkeit, Existenz-Probe referenzierter Pipelines/Mitarbeiter/Templates, Risiko-Warnungen, „Vorher/Nachher"-Diff, NIE Auto-Aktivierung. Tool-Registry + Streaming + Prompt-Registry als Fundament; die gesamte Orchestrierung + Editor-Integration (M078) + Voice-Input (Web-Speech-API) neu.

Sicherheits-Layer (Spec Block G) — teilweise

• Input-Sanitization (Runtime): FEHLT als Modul. Die Boilerplate hat Promptfoo-Test-Vektoren (tests/promptfoo/injection-vectors.yaml, deterministischer Test-Provider), aber keine produktive Sanitizer-Funktion, die Marker (---SYSTEM:, [INST], <|im_start|>) in externen Daten neutralisiert oder Eingabe-Länge cappt (grep ergab 0 Runtime-Treffer). Neu bauen.
• System-Prompt-Trennung: Prompt-Registry ({{var}}-Templates) ist da; strikte 3-Block-Trennung (System / User-Daten „nicht als Anweisung" / Frage) als Konvention/Template neu definieren.
• Action-Boundary (M087): Bausteine vorhanden (createReviewRequiredResult(), Mutation-Audit-Events, Streaming-Guard-Evaluator) — die Bestätigungs-Workflow-Verdrahtung im UI + Tool-Output-only-Policy neu.

Multi-Provider-Fallback (M084) — fast fertig, 2 Lücken

• Aktiver 1-Min-Health-Ping + 5-Min-Sperre (Spec 18.6.3): vorhandener AIProviderHealthTracker ist reaktiv (failure-on-call, 30-Min-Window). Aktives Pingen + 5-Min-Re-Check-Fenster ergänzen.
• Deterministischer Response-Cache (Spec H/18.7: Cache-Hit auch bei KI-Down): nicht vorhanden — es gibt spend-cache (Kosten), aber keinen Output-Cache für deterministische Prompts. Neu (Hash-basiert).

Pay-as-you-go (M088) — Engine da, Verdrahtung + Notbremse neu

• Overage-Berechnung (ai-overage.ts) + Cost-Felder (AICostEvent.markedUpCostCents/stripeReportedAt) fertig.
• Umstellung Hard-Deny → Overage: assertCredit.ts wirft aktuell bei Limit (HTTP 402). [N13] verlangt weiterlaufen + Aufschlag. Pfad umbauen.
• Notbremse (18.8.7): absolute Euro-Obergrenze pro Tenant → Drosselungs-Modus (nur geschäftskritische KI). Neu (Threshold + Capability-Whitelist).
• Stripe-Metered-Billing-Reporter (18.8.6): stripeReportedAt-Watermark + nightly Cron vorgesehen; Stripe-Anbindung kommt aus M153/M156. Verdrahtung neu.
• Upsell-Logik (18.8.5): Vergleich Overage-Kosten vs. Plan-Differenz → Soft-Recommendation. Neu.

UI — KOMPLETT NEU (Boilerplate liefert KEIN HiveGrid-UI)

• Programm-Hilfe-Chat-Oberfläche (Streaming)
• KI-Sprach-Assistent (M086, Sidebar-Gruppe „AUTOMATION & KI" → laut INTEGRATION-CONTRACTS §1)
• Usage-Dashboard /{tenant}/admin/usage/ai (Pie pro Use-Case, Verbrauch über Zeit, Top-User, Forecast, Tarif, Notbremse-Stand)
• AI-Settings-Seite (EU-DSGVO-Klartext, Modell-Defaults pro Use-Case, Token-Override) — Sidebar „EINSTELLUNGEN → Mandant"
• Voice-Aufnahme-Komponente (Mikrofon-Tap/Toggle, Edit, Klartext-Fehler)
• Lead-Zusammenfassungs-Widget, Stuck-Deal-Widget
• Action-Boundary-Bestätigungs-Dialog
• DoD-Pflicht (alle Milestones): View-Model-Loader-Trennung, keine Prisma-Imports in packages/ui-hivegrid/**, Subframe-Adapter, i18n-Keys, Smoke-Tests, Hot-Swap-Drill gegen packages/ui-mock, Visual-Regression — alles HiveGrid-seitig neu.

Querschnitt-Wiring (HiveGrid-seitig)

• Sidebar-Registrierung in packages/ui-hivegrid/src/app-shell/sidebar.config.ts (M086 → Gruppe „AUTOMATION & KI"; Usage/Settings → „EINSTELLUNGEN")
• Routes unter Tenant-URL-Pattern, Breadcrumbs, Customer-Portal-Sichtbarkeit
• i18n-Keys für alle Klartext-Fehler (Spec 18.12 — 5 konkrete Beispiele) aus M002-Catalog
• Activity-Stream (logActivity) + Notifications (notify()) Anbindung
• Permission-Seed der 6 ai.*-Permissions + 3 Bundles + Default-Rollen-Zuweisung
• Feature-Flag pro KI-Modul

---

Empfohlenes Vorgehen (Reihenfolge)

Phase 0 — Voraussetzung (vor M083): EU-Sterilisation der Boilerplate prüfen. Der aktive Provider-Pfad ist bereits EU-only (Mistral/Scaleway/Aleph Alpha); Anthropic/OpenAI existieren nur als Embedding-Stub bzw. @ai-sdk/openai-compatible-Bibliothek (packages/ai/src/embeddings/providers/{openai,anthropic}.ts). Sicherstellen, dass diese nicht aktiviert/registriert werden (DSGVO-Hard-Constraint, Spec 18.2.2).

M083 (EU-Provider-Layer) — überwiegend ÜBERNEHMEN:

1. packages/ai Provider-Registry + Mistral/Scaleway/Aleph-Alpha-Adapter 1:1 nutzen.
2. executeLLMCall als zentralen Gateway-Wrapper verdrahten (Boundary in apps/api injiziert Env-Snapshots + Cost-Publisher + Prisma-Adapter).
3. EU-DSGVO-Klartext in AiSettings (Spec 18.2.4) als i18n-Key.

M084 (Fallback) — ÜBERNEHMEN + 2 Erweiterungen:

1. fallback.ts (30-Min-Window, Mistral→Scaleway→Aleph-Alpha) 1:1.
2. NEU: aktiver 1-Min-Health-Ping + 5-Min-Sperre.
3. NEU: deterministischer Output-Cache (Hash-basiert, Cache-Hit bei KI-Down).
4. Graceful-Degradation-Klartexte + Editor-Fallback-Hinweis (UI).

M085 (Promptfoo) — fast fertig ÜBERNEHMEN:

1. promptfoo.config.yaml + tests/promptfoo/injection-vectors.yaml + .gitea/workflows/promptfoo.yml 1:1.
2. NEU: pro HiveGrid-Prompt-Flow eigene Eval-Vektoren ergänzen; CI-Gate verifizieren.

M087 (RAG + Aktions-Grenze) — Bausteine ÜBERNEHMEN, Wiring neu:

1. pgvector-Migration aktivieren; vector-store tenant-scoped + embeddings-Pipeline 1:1.
2. NEU: TenantEmbedding-Metadaten-Modell in app.prisma (Re-Embed-Hash, embedding_model_id, last_embedded_at).
3. NEU: Permission-Pre-Filter vor Vector-Search (Spec 18.3.3).
4. NEU: Embedding-Trigger bei Entity-Anlage/Update (Outbox rag.index.* vorhanden — Domain-Writes andocken).
5. Action-Boundary: createReviewRequiredResult() + Mutation-Audit + UI-Bestätigungs-Dialog.
6. NEU: Runtime-Input-Sanitizer (Marker-Neutralisierung + Längen-Cap).

M086 (Sprach-zu-Automation, USP) — meiste Eigenleistung:

1. Tool-Registry + Streaming + Prompt-Registry als Fundament.
2. NEU: Sprach→Wenn-Dann-Orchestrierung, Existenz-Probe, Rückfrage-Loop, Risiko-Warnung, Vorher/Nachher-Diff, Voice-Input (Web-Speech-API), Editor-Integration (M078). NIE Auto-Aktivierung.
3. Abhängig von M087 (Aktions-Grenze) + M075-M077 (Automation-Schema).

M088 (Token-Limits + Pay-as-you-go) — Engine ÜBERNEHMEN, Policy umbauen:

1. ai-quotas.ts + ai-overage.ts + AICostEvent/TenantAICostSummary 1:1 (HiveGrid-Plan-Werte einsetzen, sobald Pricing fixiert).
2. UMBAU: assertCredit.ts Hard-Deny → Pay-as-you-go-Overage-Pfad ([N13]).
3. NEU: Notbremse (absolute Euro-Obergrenze → Drosselung statt Pause), Upsell-Logik, 80%-Banner+Email, Usage-Dashboard.
4. Stripe-Metered-Reporter andocken (M153/M156).

Whisper-EU (Spec Block E) — separater Neubau-Strang (parallel/danach):

1. NEU: Whisper-auf-Scaleway-GPU-Adapter + transcribe()-Methode in packages/ai.
2. NEU: ai.transcribe-Queue-Job + Async-Pipeline (storage + queue vorhanden).
3. NEU: Voice-Aufnahme-UI + Edit + Klartext-Fehler.

Querschnitt zum Schluss jedes Milestones (DoD): Sidebar-Wiring, Routes/Breadcrumbs, Permission-Seed (6 ai.* + Bundles + Default-Rollen), i18n-Klartexte (18.12), Activity/Notifications, Feature-Flags, View-Model-Loader-Trennung, Smoke- + Hot-Swap- + Visual-Regression-Tests.