Initial curated RAGcore source from c16667f0c9397e2bfc8dd0255b114fba23c8d05e

docs/03_DATA/QDRANT_INDEX.md

@@ -0,0 +1,48 @@
+# Qdrant Index Contract
+
+## M6 embedding-space identity
+
+New ModelForge shadow collections and payloads carry the exact `embedding_space_id`; dimensions
+alone never establish compatibility. The current production collection remains legacy-observed and
+unchanged. Evaluation-only shadow reads name a server-owned profile and never mutate the alias.
+
+## Collecties
+
+Collecties worden per indexprofiel/embeddingruimte gemaakt, niet per project:
+
+```text
+rag_dense_<profile>_<version>
+rag_code_<profile>_<version>
+```
+
+Een alias verwijst naar de actieve build. Verschillende dimensies of modeldigests worden nooit gemengd.
+
+## Named vectors
+
+- `dense`: semantische embedding;
+- `sparse`: lexicale/tokenrepresentatie;
+- latere multivector alleen via nieuw profiel en evaluatie.
+
+## Verplichte payload
+
+`workspace_id`, `space_id`, `document_id`, `document_version_id`, `chunk_id`, `parent_chunk_id`, `source_id`, `status`, `content_type`, `language`, `trust_level`, location, profile versions en tekst/excerpt.
+
+## Payload indexes
+
+Minimaal: workspace, space, document, version, status, content_type, language en trust_level. Voeg geen index toe zonder gemeten filtergebruik.
+
+## Query invariant
+
+Iedere query bevat server-side workspace/space/statusfilters. Raw clientfilters worden nooit rechtstreeks doorgestuurd; toegestane filters worden gecompileerd uit typed requestvelden.
+
+## Rebuild
+
+Qdrant is afgeleid. Rebuild maakt een shadow collection, controleert counts/samples/golden queries, activeert alias en houdt de vorige build voor rollback.
+
+Elke build-, rollback- en reconcile-aanroep wordt per alias geserialiseerd door een PostgreSQL-backed lease lock (`indexes.index_build_operations`), niet door een proceslokale lock, zodat meerdere app-/workerreplicas nooit dezelfde aliasmigratie gelijktijdig uitvoeren. Acquisitie is begrensd (timeout + backoff) en een gecrashte houder laat geen permanent vastgelopen lock achter: een verlopen lease wordt bij de volgende poging gereclaimed en als `needs_repair` gemarkeerd zodat de eerdere afbraak zichtbaar blijft.
+
+Elke stap van een operatie wordt in dezelfde rij gelogd (saga log) zodat een gedeeltelijk mislukte build gecompenseerd kan worden: vóór activatie wordt de shadow collection verwijderd; na (een poging tot) activatie wordt de alias geforceerd teruggezet naar de vorige collectie en geverifieerd. Een compensatie die zelf niet bevestigd kan worden resulteert in `needs_repair` en een `IndexRepairError`, nooit in een stilzwijgend geslaagde melding.
+
+Malformed of legacy points blokkeren reconciliatie niet: ze worden gedetecteerd, uitgesloten van gebruik en vervolgens hersteld (deterministisch herbouwd vanuit de authoritative bron) wanneer hun ID bij een verwachte chunk hoort, of gequarantained (verwijderd op exact opgeslagen ID) wanneer dat niet zo is.
+
+Batchquota voor Qdrant-schrijfoperaties tellen de werkelijke UTF-8-geserialiseerde bytes van het volledige payload, de sparse-vectoren en de fingerprintvelden, niet alleen tekst/excerpt-lengte; een build kent daarnaast een cumulatieve bytequota over alle batches heen.