Files
HiveGrid-Wireframes/hivegrid-cloud/docs/improvement-plan/04-search-rag/VERIFICATION.md
T

268 lines
22 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Phase 04 — Search + RAG — Verifikation
**Verifier:** Claude (Opus 4.7, read-only)
**Datum:** 2026-05-16
**Scope:** `README.md`, `meilisearch.md`, `vector-store.md`, `embedding-pipeline.md`
**Referenzen:** `../README.md`, `../AGENT-INSTRUCTIONS.md`, `../00-execution-order.md`, `../DETAIL-MD-TEMPLATE.md`
## Verdikt auf einen Blick
| File | Template-Konformität | Dependencies | Implementation | Tests | Staging | Security | Gesamt |
|---|---|---|---|---|---|---|---|
| `README.md` | n/a (kein Detail-MD) | OK | OK | OK | OK | OK | **PASS** |
| `meilisearch.md` | PASS | PASS | PASS | PASS | PASS | PASS (Hinweis #1) | **PASS** |
| `vector-store.md` | PASS | PASS | PASS (Hinweis #2) | PASS | PASS | PASS | **PASS mit Hinweisen** |
| `embedding-pipeline.md` | PASS | PASS | PASS (Hinweise #3, #4) | PASS | PASS | PASS (Hinweis #5) | **PASS mit Hinweisen** |
Keine Blocker. Vier inhaltliche Hinweise (siehe unten), zwei Fehlende-Aspekte-Empfehlungen, ein kleines optionales Nit.
---
## 1. Template-Konformität (DETAIL-MD-TEMPLATE.md)
Alle drei Detail-MDs (meilisearch / vector-store / embedding-pipeline) enthalten **alle 15 Sections in der vorgeschriebenen Reihenfolge**:
1. Frontmatter (Status, Task-ID, Phase, Estimated Effort, Owner) ✔
2. Problem ✔
3. Depends on ✔
4. Blocks ✔
5. Approach ✔
6. Implementation Steps ✔
7. Test Requirements ✔
8. Acceptance Criteria ✔
9. Rollback Strategy ✔
10. Security Notes ✔
11. Subagent Recommendations ✔
12. Staging-Deployment-Steps ✔
13. Deviations from Plan ✔ (leer, korrekt)
14. Progress Log ✔ (leer, korrekt)
15. Lessons Learned ✔ (Platzhalter)
Task-IDs `#48`, `#49`, `#50` matchen die Reihenfolge aus `00-execution-order.md` Tabelle Reihe 4. Phasen-Felder = `04`. Estimated-Effort-Summe (1 + 1.5 + 1 = 3.5 Wochen) matcht README-Header und Plan-README ("3.5 Wochen").
**README.md (Phase-Übersicht):** kein Detail-MD-Template anwendbar; struktur folgt dem Muster der Phase-03-README. Done-Definition ist konkret, mess- und prüfbar, Dependency-Graph enthält Inputs (Phase 03) und Outputs (Phase 07).
## 2. Dependencies-Konsistenz
**Cross-Phase:**
- meilisearch.md `Depends on` → Phase 03 `outbox-pattern.md` (#42), `worker-queues.md` (#43) ✔ matched mit `00-execution-order.md` "Phase 04 depends on Phase 03 (insbesondere Outbox + Worker-Queues)".
- vector-store.md `Depends on` → Phase 03 `outbox-pattern.md` (#42), `read-write-split.md` (#41) ✔ — die `prismaWrite`-Nutzung wird in Approach + Security-Notes konsistent referenziert.
- embedding-pipeline.md `Depends on` → Phase 03 `outbox-pattern.md`, `worker-queues.md` plus die zwei Phase-04-Tasks ✔.
**Intra-Phase:**
- meilisearch.md `Blocks` listet embedding-pipeline.md (Pattern-Quelle) ✔
- vector-store.md `Blocks` listet embedding-pipeline.md ✔
- embedding-pipeline.md `Depends on` listet beide ✔ — Dreieck schließt sich.
**Blocks-Ausgang:**
- Alle drei Files referenzieren korrekt `07-chatbot/chatbot-v2.md` als blockierten Konsumenten ✔ — matched `00-execution-order.md` Phase 07 Sub-Dep "chatbot-v2: Phase 04 komplett (RAG)".
**Parallelisierbarkeit:**
- README + execution-order ("meilisearch + vector-store parallel") + meilisearch.md ("Parallelisierbar mit #49") + vector-store.md (Subagent-Recs) konsistent ✔.
**Keine zirkulären Dependencies.** Topologische Reihenfolge stimmt.
## 3. Implementation-Steps-Qualität
### 3.1 Meilisearch Tenant-Isolation via filterableAttributes + Filter-Wrap
`createSearchIndex` validiert dass `tenantId` in `filterableAttributes` enthalten ist (Step 4); `searchInIndex` injiziert immer den Filter `tenantId = "${tenantId}"` (Step 5). Raw-Client wird **nicht** exportiert. Custom-ESLint-Rule blockiert Direktimport der SDK außerhalb des Packages (Security-Notes).
**Bewertung: korrekt und sicher.** Drei Verteidigungslinien (Index-Schema-Guard + Wrapper-Pflicht-Filter + ESLint-Rule) ist gut layered. Klein: das `escape Special-Characters in TenantID`-Detail in Unit-Tests (Step Test Reqs) ist wichtig — Meilisearch-Filter-DSL erlaubt sonst Injection, wenn `tenantId` user-controlled wäre (im Boilerplate ist es UUID-format, aber Defense-in-Depth ist richtig). ✔
### 3.2 pgvector mit HNSW-Index in Postgres 16+
Step 2: `CREATE EXTENSION IF NOT EXISTS vector;` Migration. Step 3: HNSW-Index `USING hnsw (vector vector_cosine_ops)` plus GIN auf payload + B-Tree auf tenant_id (`tenant_id TEXT GENERATED ALWAYS AS (payload->>'tenantId') STORED`).
**Bewertung: technisch realistisch.** HNSW ist ab pgvector 0.5 (Q3 2023) verfügbar; Boilerplate-Stack ist auf Postgres 15+/16+ — Migration-User-Rechte werden in Security-Notes adressiert (Superuser für `CREATE EXTENSION` — relevant für Scaleway-Managed-Postgres, dort muss Extension out-of-band durch Provider freigegeben werden). Generated-Column für `tenant_id` ist eine elegante Lösung — sorgt dafür, dass Tenant-Filter ohne JSONB-Path-Lookup b-tree-served läuft.
**Hinweis #2 (minor):** Die Doku in Step 8 erwähnt "pgvector HNSW-Tuning-Parameter" (Lessons-Learned-Platzhalter), aber die Implementation Step 3 setzt die HNSW-Parameter (`m`, `ef_construction`) nicht explizit. Empfehlung: in Step 3 Default-Parameter explizit als ausdokumentierten SQL-Schnipsel hinterlegen (`m=16, ef_construction=64`) damit der ausführende Subagent nicht selber raten muss. Das ist Polishing, kein Blocker.
### 3.3 Qdrant-Adapter parallel — Adapter-Pattern-Konsistenz
Interface `VectorStoreAdapter` (vector-store.md Approach, Zeilen 33-49) ist gleich für pgvector und Qdrant. Conformance-Test-Suite (Step 7) läuft identisch gegen beide via testcontainers. Filter-Übersetzung in jeweiligem Adapter-File, payload-Schema (`Record<string, unknown> & { tenantId: string }`) TS-erzwungen.
**Bewertung: konsistent.** Das Pattern ist sauber: ein Interface, zwei Adapter, eine Conformance-Suite die beide austauschbar beweist. Migration pgvector→Qdrant explizit als "Re-Embed aus Source-of-Truth" dokumentiert — kein riskanter direkter Datentransfer.
### 3.4 Chunking via tiktoken für Multi-Provider
`splitForEmbedding` (embedding-pipeline Step 7) nutzt tiktoken für OpenAI-kompatible Modelle, fallback auf model-spezifisch. Default 512/50.
**Hinweis #3:** tiktoken-Token-Counts sind nur für OpenAI-Modelle (cl100k_base, o200k_base) exakt. Bei Scaleway-Inference (OpenAI-kompatibles Endpoint, gleicher Tokenizer für ihre kompatiblen Modelle) ist es fast immer OK; bei Aleph-Alpha (eigener BPE-Tokenizer, andere Vokabular-Größe) und für Anthropic (eigener Tokenizer, kein offizieller Public-Tokenizer in 2026) ist tiktoken-Count nur eine Heuristik — Token-Counts können um 10-30% abweichen. Realistisch ist es trotzdem nutzbar (mit Safety-Margin auf `maxTokens`), aber:
- Empfehlung: `splitForEmbedding` sollte die per-Provider `maxTokensPerInput` aus dem Provider-Interface lesen und einen konservativen Safety-Faktor (z.B. 0.8) anwenden, statt einen statischen Default. Aktuell `maxTokens?: number` in der Signatur — vom Aufrufer übergebbar, aber kein automatischer Provider-Sync.
- Step 7 sollte expliziter erwähnen: "encoding optional override, default basierend auf konfiguriertem Provider, mit 20% Safety-Margin auf provider.maxTokensPerInput".
Das ist eine Verbesserung, kein Blocker — der Code ist baubar wie spezifiziert.
### 3.5 retrieveRelevantContext Multi-Collection-Fan-Out
Step 10 in embedding-pipeline.md: `retrieveRelevantContext` embedded Query → sucht parallel in allen aktiven RAG-Collections des Tenants → ranked Score-merged → topK.
**Bewertung: sinnvoll.** Für Chatbot V2 ist das genau richtig — der Bot weiß nicht vorab ob die Antwort aus KB, CRM-Notes oder Rows kommt; Multi-Collection-Fan-Out + Score-Merge ist Standard-RAG-Pattern.
**Hinweis #4:** Score-Merge über Collections hinweg ist nicht trivial — verschiedene Collections können unterschiedliche Score-Verteilungen haben (z.B. wenn ein KB-Korpus klein und specific ist, sind alle Scores hoch; ein CRM-Notes-Korpus breit und vielfältig hat alle Scores niedriger). Reines `sort by score desc` kann eine Collection systematisch unterrepräsentieren. Optionen:
- Per-Collection topK/N statt globalem topK
- Score-Normalisierung pro Collection (z.B. z-score)
- Reciprocal Rank Fusion (RRF) — wenig Code, robust gegen Score-Skalen
Empfehlung: Step 10 sollte einen Satz zur Score-Merge-Strategie ergänzen ("RRF" oder "per-collection cap of topK/collections.length, dann global topK") damit der Implementer das nicht ad-hoc entscheidet.
## 4. Test-Requirements
**Container-basierte Integration-Tests:**
- meilisearch.md: `@testcontainers/meilisearch` (oder generic-container + Health-Wait) für E2E-Indizierung, Bulk-Reindex, Tenant-Isolation ✔
- vector-store.md: testcontainers für `pgvector/pgvector:pg16` und `qdrant/qdrant` ✔ — Conformance-Suite läuft parameterisiert gegen beide
- embedding-pipeline.md: Postgres-mit-pgvector + Redis (für BullMQ), E2E-Flow KB-Article → Outbox → Worker → Vector-Store → `retrieveRelevantContext` ✔
**Conformance-Test-Suite gegen beide Vector-Adapter:** vector-store.md Step 7 + Test Requirements explizit — beide Adapter durchlaufen identische Test-Cases (Lifecycle, Tenant-Isolation, Recall-Smoke, Filter-Kombination, Edge-Cases). Das ist die genau richtige Garantie für Austauschbarkeit.
**Coverage-Targets:** 85% packages, 80% worker — konsistent mit `AGENT-INSTRUCTIONS.md` Regel 3 (Per-Module-Gates für neuen Code).
**Provider-Smoke-Tests gated by env (embedding-pipeline):** `vitest --grep=@live-provider` — gute Practice (kein CI-Cost-Blow-Up durch echte API-Calls).
**Bewertung: vollständig.** Alle drei Tasks haben Unit, Integration, Worker, E2E (wo sinnvoll), Coverage-Targets und Test-File-Locations. Acceptance-Criteria-Bullets matchen die Test-Requirements.
## 5. Staging-Deployment-Steps
**Coolify-Setup:**
- meilisearch.md Step 2 verweist auf `docs/deploy/meilisearch.md` (zu erstellen) mit Coolify-Snippet + Volume-Backup-Cron + Master-Key-Rotation ✔
- vector-store.md: Qdrant als optional-Service in docker-compose mit Profile `qdrant`, Staging-Steps inkl. `QDRANT_API_KEY`-Secret + Snapshot-Skript ✔
- embedding-pipeline.md Staging-Steps verlangen Provider-Secrets in Coolify (`OPENAI_API_KEY`/`SCALEWAY_INFERENCE_TOKEN`) ✔
**Backup-Strategy pro Adapter:**
- pgvector: über Postgres-Backup (verweist korrekt auf Phase 03 `backup-cli.md`) ✔
- Qdrant: Snapshot-API + Cron + S3-Push, Skript `scripts/qdrant-snapshot.sh`, Doku `docs/deploy/vector-store-backup.md` ✔ — sogar SSE-Encryption-Check (Security-Notes) erwähnt
- Meilisearch: Volume-Backup-Cron ✔ (kein Snapshot-API erwähnt — aktuell OK, Meilisearch hat ab v1.6 ein Snapshot-Feature; Empfehlung als Phase-11-Backlog-Item siehe Abschnitt 7)
**Performance-Erwartungen explizit:**
- Meilisearch P95 <50ms bei 1M Docs ✔
- pgvector <30ms / Qdrant <15ms bei topK=10 ✔
- Search-Hit innerhalb 2s nach Save (Phase-README Done-Definition) ✔
- Vector-Hit innerhalb 5s nach Save ✔
**Bewertung: detailliert und realistisch.** Smoke-Tests pro Task sind konkret (CLI-Commands, Dashboard-Checks, Failure-Tests wie "Meilisearch-Container stoppen → SQL-Fallback").
## 6. Konsistenz mit User-Wünschen
| User-Wunsch | Status in Phase 04 | Beleg |
|---|---|---|
| "17a/A1 Meilisearch" | ✔ umgesetzt | meilisearch.md ist eigener Task, Image-Pinning `getmeili/meilisearch:v1.8`, Approach explizit "Meilisearch als richtige Wahl vs Elasticsearch/Typesense" |
| "pgvector als Default + Qdrant als optional" | ✔ Adapter-Pattern korrekt | vector-store.md Factory-Logik: `explicit > QDRANT_URL > pgvector`. README "Default ist pgvector (zero-ops), Qdrant wird optional aktiviert wenn QDRANT_URL gesetzt" |
| "Indexer async via Outbox" | ✔ durchgängig | Alle drei Tasks haben in `Depends on` `outbox-pattern.md`; Approach-Sections sagen explizit "async via Outbox-Events"; sync Pfade in Alternativen explizit verworfen ("Synchrones Embedding bei Save: blockiert Save-Latenz") |
| "Scaleway Managed Postgres + pgvector als Default-Pfad" | ⚠ teilweise dokumentiert | pgvector als Default ist klar; Scaleway-Managed-Postgres-Spezifika werden in Security-Notes von vector-store.md angeschnitten (`CREATE EXTENSION` braucht Superuser → out-of-band via DBA bei Managed-Postgres), aber nicht prominent in der README oder einer Deploy-Doku. **Empfehlung:** README sollte einen Bullet ergänzen wie "Scaleway-Managed-Postgres als Default-Deploy-Target: pgvector-Extension muss einmalig im Scaleway-Console aktiviert werden bevor die Migration durchläuft." Aktuell stehts versteckt in vector-store.md Security-Notes. Kein Blocker, aber Sichtbarkeit verbessern. |
## 7. Security-Notes — Tenant-Isolation Tiefe
**Embedding-Leak-Schutz:** embedding-pipeline.md Security-Notes adressiert es explizit — "Embeddings können theoretisch Source-Text rekonstruieren — kein Cross-Tenant-Read, kein Logging von Vektoren in Cleartext". Vector-store.md macht das gleiche Statement.
**Query-Filter-Pflicht:**
- Meilisearch: TS-Signatur erzwingt `tenantId` als required Param in `searchInIndex` + Wrapper injiziert in Filter (3 Verteidigungslinien)
- Vector-Store: `VectorItem.payload` ist `Record<string, unknown> & { tenantId: string }` (TS-erzwungen), `semanticSearch` verlangt `tenantId`-Param, Adapter injiziert als `must`-Filter
- Embedding-Pipeline: `retrieveRelevantContext` verlangt `tenantId`-Pflicht-Param
**Bewertung: stark.** Defense-in-depth auf jeder Ebene. Drei Hinweise:
**Hinweis #1 (Meilisearch Master-Key):** Security-Notes erwähnt "Master-Key + Application-side-Filter (einfacher); in Phase 11 evaluieren ob tenant-tokens echten Mehrwert geben". Das ist eine bewusste Trade-off-Entscheidung. Für Production-Härtung würde ich **stärker formulieren**: Meilisearch-Tenant-Tokens sind ein cheap-extra-defense-layer (sie escapen das Application-side-Filter-Risiko komplett — selbst bei Wrapper-Bug greift Meilisearch's eigene Tenant-Trennung). Empfehlung: für Phase 04 OK, aber Phase 11 Backlog-Item sollte priorisiert sein, nicht "vielleicht".
**Hinweis #5 (Provider-Datenabfluss):** embedding-pipeline.md adressiert es vorbildlich:
- DSGVO-relevant: EU-Region-Provider-Liste (Scaleway, Aleph-Alpha) explizit
- CRM-Notes-Indexing default-off mit explizitem Opt-In ✔
- No-Log-Policy für Input-Text (nur Hashes) ✔
- Per-Tenant-Provider-Override als Phase-11-Backlog markiert ✔
Sehr gut. Keine Lücke.
**Code-Review-Hook (Vector-Store):** Vector-store.md Security-Notes sagt "Direkter Adapter-Zugriff ohne Helper ist nicht abgeschnitten (für Power-User), aber Code-Review-Guideline: Adapter-Direct-Use nur in `packages/vector-store/` und in `embedding-pipeline`-Worker." Das ist schwächer als Meilisearchs ESLint-Rule-Approach. Empfehlung: konsistent machen — entweder beides via ESLint-Rule abblocken, oder beim Meilisearch-Package gleiche Guideline statt Rule. Aktuell asymmetrisch.
## 8. Fehlende Aspekte (vom Verifier identifiziert)
### 8.1 SearchIndex-Versioning für Schema-Changes (fehlt)
**Was fehlt:** Wenn das Schema eines Meilisearch-Index sich ändert (neuer `searchableAttribute`, anderes Ranking-Rule), gibt es keinen dokumentierten Migration-Pfad. Meilisearch erlaubt manche Schema-Updates online (filterableAttributes hinzufügen), andere nicht (primaryKey-Wechsel).
**Empfehlung:** meilisearch.md Step 10 (Doku) sollte einen Abschnitt "Schema-Versioning + Migration" enthalten mit:
- Online-fähige Updates (filterable/sortable Attributes hinzufügen)
- Re-Index-pflichtige Updates (primaryKey, fundamentale Tokenizer-Änderungen)
- Convention: bei breaking-Schema-Change → neuer Index `kb-articles-v2`, parallel-betreiben, swap-via-feature-flag, dann alten löschen
- Aktuell nicht in der Detail-MD — Implementer würde ad-hoc entscheiden.
Kein Phase-04-Blocker — kann nachgereicht werden, aber sollte vor Phase-07-Chatbot-V2 stehen.
### 8.2 Reindex-Strategy bei Embedding-Model-Wechsel (teilweise vorhanden)
**Was vorhanden:** embedding-pipeline.md Rollback-Strategy adressiert Dimension-Mismatch-Recovery: "alte Collection löschen, neue mit korrekter Dimension anlegen, `rag:reindex` triggern".
**Was fehlt:** Online-Migration ohne Downtime. Wenn ein Tenant von `text-embedding-3-small` (1536d) auf `text-embedding-3-large` (3072d) umsteigt, ist die obige Strategie destructive (Search liefert während Reindex 0 Hits oder veraltete Hits).
**Empfehlung:** Doku-File `docs/features/rag.md` (Step 12) sollte einen "Embedding-Model-Migration-Guide" enthalten:
- Parallele Collection mit neuem Suffix anlegen
- `rag:reindex --collection=<new>` befüllen
- Atomic-Swap via Config-Flag
- Alte Collection nach Verifikation löschen
Auch kein Phase-04-Blocker, aber für Chatbot-V2-Production wichtig.
### 8.3 Cost-Estimation pro Embedding-Operation (teilweise vorhanden)
**Was vorhanden:** embedding-pipeline.md Security-Notes "Cost-Guard (vorläufig): Worker hartcoded auf max 10k Embed-Calls pro Tenant pro Stunde, sonst Job-Stop mit Alert. Wird abgelöst sobald Quota-Enforcement aus Phase 05 verfügbar ist."
**Was fehlt:** Ex-ante Cost-Estimation. Wenn `rag:reindex --tenant=all` läuft, sollte das CLI vorab Token-Schätzung + Cost-Schätzung loggen ("Geschätzt: 12.4M Tokens × $0.02/M = $0.25 für OpenAI text-embedding-3-small. Continue? [y/N]"). Ist ein UX-Sicherheitsnetz gegen versehentliche Mega-Backfills.
**Empfehlung:** Step 11 (CLI-Backfill) sollte einen `--dry-run` und ein `--confirm`-Pattern enthalten, plus eine `estimateBackfillCost`-Funktion. Provider-Pricing pro 1M Tokens in einem `pricing.ts`-File (auch wenn nur Snapshot — wird durch AI-Cost-Tracking-Phase-05 ersetzt).
Kein Blocker, aber wäre ein günstiges Add-On.
### 8.4 Embedding-Cache (optional, nice-to-have)
**Was fehlt:** Idempotenz-Cache — bei `rag.index`-Event mit unverändertem `text` (gleicher SHA-256-Hash) re-embed unnötig. Spart Provider-Cost bei Webhook-Storms oder Update-Loops.
**Empfehlung:** `embedding-pipeline.md` Step 8 könnte einen Bullet ergänzen: "Vor Embed: Hash(text) gegen `embedding_cache`-Tabelle prüfen; bei Cache-Hit nur Vector-Store-Upsert mit gecached'tem Vector, kein Provider-Call". Optional, kann auch als Phase-05-Optimierung kommen.
## 9. Konsistenz mit Phase-03-Outputs
Phase 03 liefert (laut `00-execution-order.md`):
- `prismaWrite`-Client aus `read-write-split.md` → von vector-store.md (pgvector-Adapter) konsumiert ✔
- Outbox aus `outbox-pattern.md` → von allen 3 Phase-04-Tasks konsumiert ✔
- Worker-Queues aus `worker-queues.md` → `worker-general`-Service registriert Phase-04-Jobs ✔
- Backup-CLI aus `backup-cli.md` → wird von vector-store.md Backup-Doku referenziert ✔
Keine Lücke. Keine Forward-Reference auf Phase-03-Items, die in Phase 03 noch nicht definiert sind (geprüft gegen execution-order Listings).
## 10. Konsistenz mit Phase-07-Konsument (Chatbot V2)
Alle drei Files erwähnen `07-chatbot/chatbot-v2.md` als blockierten Konsumenten. Public-APIs die Chatbot V2 brauchen wird:
- `searchInIndex` (Meilisearch, für strukturierte Filter-Searches) ✔
- `semanticSearch` (Vector-Store, für Vektor-Retrieval) ✔ — oder besser direkt
- `retrieveRelevantContext` (Embedding-Pipeline, RAG-Hauptpfad) ✔
Phase 04 liefert genau diese drei Endpoints. Konsistent.
## 11. Kleinere Nits
- **meilisearch.md Step 8** listet "Hot-Paths: KB-Article-Public-Search, CRM-Contacts-Filter, Rows-Search in Entities". Acceptance-Criteria-Liste enthält die gleichen drei. Outbox-Producer-Hooks in Step 7 listen aber **fünf** Services (KB-Articles, CRM-Contacts, Rows, Entities, Users). Done-Definition der Phase-README listet auch "Users". Frage: warum wird Users indexiert wenn es keinen User-Search-Hot-Path im Migrations-Step gibt? Vermutlich für Admin-Suche / Tenant-Member-Liste. Empfehlung: Step 8 ergänzen mit "User-Search in Admin-UI" oder klären dass User-Index nur indexiert wird ohne aktiven Read-Path-Switch (für Phase-08-CLI?).
- **vector-store.md Approach** sagt "Eine Tabelle pro Collection: `vec_<collection_name>`". Implikation: bei vielen Collections viele Tabellen. Empfehlung: in `docs/features/vector-store.md` einen Hinweis ergänzen "Bei >50 Collections pro DB Performance prüfen (pg_catalog-Last)". Optional.
- **embedding-pipeline.md Step 5** Anthropic-Adapter als Placeholder mit clear-error-throw — sehr saubere Lösung. Empfehlung: Throw-Message sollte explizit auf Scaleway oder Aleph-Alpha als EU-Alternative verweisen, nicht nur "use other providers".
- **Phase-04-README Done-Definition** Bullet "Tenant-Isolation-Test (positiv und negativ)": gut, dass beide Polaritäten verlangt werden — wird gerne in Reviews vergessen.
## Fazit
**Phase 04 ist solide spezifiziert und ausführungsreif.** Drei Detail-MDs sind template-konform, intern + extern dependency-konsistent, technisch realistisch (HNSW/pgvector 0.5+, Meilisearch v1.8, Adapter-Pattern für Vector-Store), und mit ausreichender Test-Tiefe (Conformance-Suite gegen beide Vector-Adapter via testcontainers ist ein Highlight). Tenant-Isolation ist als Defense-in-depth implementiert (TS-Signatur + Wrapper-Pflicht + ESLint-Rule bei Meilisearch).
**Hinweise (alle non-blocking):**
1. Meilisearch-Tenant-Tokens als Phase-11-Hardening explizit priorisieren
2. pgvector HNSW-Default-Parameter (m=16, ef_construction=64) in Step 3 ausdokumentieren
3. `splitForEmbedding` Provider-Aware-MaxTokens mit Safety-Margin in Step 7 ergänzen
4. `retrieveRelevantContext` Score-Merge-Strategie (RRF empfohlen) in Step 10 explizit machen
5. Code-Review-Guideline für Vector-Store-Adapter-Direct-Use auf ESLint-Rule-Niveau heben (Konsistenz mit Meilisearch)
**Fehlende-Aspekte-Empfehlungen:**
1. SearchIndex-Versioning-Pattern (online vs reindex-required) in `docs/features/search.md`
2. Embedding-Model-Migration-Guide (parallele Collection, atomic-swap) in `docs/features/rag.md`
3. Cost-Estimation für `rag:reindex --dry-run` (UX-Sicherheitsnetz)
4. (optional) Embedding-Cache via Text-Hash zur Idempotenz-Optimierung
**Scaleway-Managed-Postgres + pgvector als Default-Pfad** ist umgesetzt, aber Sichtbarkeit der Scaleway-Spezifika (Extension-Aktivierung out-of-band) ist im Detail vergraben — Empfehlung: in Phase-04-README einen Bullet hinzufügen.
**Verdikt: APPROVE für Ausführungsstart.** Hinweise und Fehlende-Aspekte können als Sub-Issues während der Implementation adressiert oder im Phase-Summary nachgereicht werden. Kein Re-Plan nötig.