Track HiveGrid Cloud planning reference

This commit is contained in:
david committed 2026-06-26 20:48:01 +02:00
1 parent b3d5ea6764
commit e341c5938a
5784 files changed
+1104929 -3

No files matched your search

@@ -0,0 +1,267 @@
# 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.