Initial curated RAGcore source from c16667f0c9397e2bfc8dd0255b114fba23c8d05e

docs/05_RETRIEVAL/ANSWERABILITY.md

@@ -0,0 +1,23 @@
+# Answerability
+
+## Statussen
+
+- `answerable`: voldoende consistente evidence dekt de vraag.
+- `partially_answerable`: slechts een aantoonbaar deel is gedekt.
+- `not_answerable`: onvoldoende of te zwakke evidence.
+- `conflicting_evidence`: relevante bronnen spreken elkaar materieel tegen.
+
+## Signalen
+
+Fusievolgorde, documentdiversiteit, dekking van queryfacetten, trust level, freshness, exacte identifier match, source independence en conflictregels. Een retrievalscore wordt nooit als kans of menselijk confidencepercentage gepresenteerd.
+
+## Gedrag
+
+- `answerable`: grounded generatie toegestaan volgens databeleid.
+- `partially_answerable`: beantwoorde deel duidelijk scheiden van ontbrekend deel.
+- `not_answerable`: geen inhoudelijke invulling; toon wat wel en niet gevonden is.
+- `conflicting_evidence`: bronnen en verschillen presenteren; geen willekeurige keuze.
+
+## Kalibratie
+
+Drempels worden uitsluitend aangepast op versioned evaluation datasets. Iedere wijziging rapporteert false-answerable en false-not-answerable regressies.

docs/05_RETRIEVAL/CITATIONS.md

@@ -0,0 +1,39 @@
+# Citations
+
+## Eigenschappen
+
+Een citation is immutable en verwijst naar:
+
+- workspace/space;
+- document en documentversion;
+- chunk en parentchunk;
+- pagina, sectie of regelbereik;
+- excerpt en excerptchecksum;
+- source URI en acquisition timestamp;
+- retrieval run en gebruikte index/profileversie.
+
+## ID
+
+Deterministische UUIDv5 of stabiele opaque ID op immutable citationinputs. Een latere documentversion verandert een bestaande citation niet.
+
+## Presentatie (1.2.0)
+
+Naast de machine-velden levert iedere citation in `/v1/search`, `/v1/context` en
+`/v1/answers` leesbare provenance, opgelost uit het Source Registry:
+`source_id`, `source_name`, `source_kind`, `locator` (item binnen de bron),
+`revision` (bijv. Git-commit van de geciteerde versie) en `display`, bijvoorbeeld
+`Network Design.pdf · p. 18 · Firewall Segmentation` of
+`infrastructure/runbooks/backup.md · commit 3fc821a · lines 118-143`.
+`source_uri` (`ragcore://source/<source_id>`) blijft de stabiele interne locator.
+Een citation is herleidbaar tot bron → item (`locator`) → versie
+(`document_version_id` + `revision`) → chunk (`id`, `excerpt_sha256`) → locatie
+(sectie/pagina/regels). Autorisatie verandert hierdoor niet: de presentatie
+resolvet alleen documenten die de caller al geautoriseerd terugkreeg.
+
+## API
+
+Antwoorden refereren citation IDs in tekst/structured claims. `GET /v1/citations/{id}` autoriseert opnieuw en levert alleen content die de caller nu mag lezen. Audit kan historische metadata bewaren terwijl gevoelige excerptretentie policy volgt.
+
+## Claimondersteuning
+
+Generatie-output moet claims aan citations koppelen. Niet-ondersteunde feitelijke claims worden verwijderd, opnieuw gegenereerd of leiden tot een expliciete failure afhankelijk van profiel.

docs/05_RETRIEVAL/MODEL_REGISTRY.md

@@ -0,0 +1,27 @@
+# Model Registry
+
+## Profieltypes
+
+- Embedding profile
+- Sparse encoder profile
+- Reranker profile (toekomstige optionele capability; niet actief in V1)
+- Generation profile
+
+## Verplichte metadata
+
+Provider, model identifier, immutable digest/revision, dimensie, contextlimiet, inputprefixes, normalisatie, tokenizer, databeleid, timeout, concurrency en activation status.
+
+## Local-first policy
+
+Knowledge spaces kiezen `local_only`, `local_preferred`, `cloud_allowed`, `retrieval_only` of `no_generation`. De providerrouter kiest nooit een ruimere route dan het strengste effectieve spacebeleid.
+
+## Modelwijziging
+
+1. Registreer immutable nieuw profiel.
+2. Bouw shadow index waar embeddings veranderen.
+3. Draai retrieval-, security- en latencyevaluaties.
+4. Vergelijk tegen actieve baseline.
+5. Activeer via alias/configversie.
+6. Bewaar vorige versie voor rollback.
+
+Geen `latest` tags of automatische upgrades in productie.

docs/05_RETRIEVAL/PIPELINE.md

@@ -0,0 +1,39 @@
+# Retrieval Pipeline
+
+## Stappen
+
+1. Authenticeer caller en resolveer application/user.
+2. Bereken effective spaces en toegestane trust/data policies.
+3. Normaliseer vraag; bewaar originele query.
+4. Detecteer identifiers, paden, versies, foutcodes en taal.
+5. Maak dense queryembedding en sparse queryrepresentatie.
+6. Voer parallel dense en sparse retrieval uit met verplichte payloadfilters.
+7. Fuseer rankings via Reciprocal Rank Fusion.
+8. Verwijder duplicate/near-duplicate chunks en beperk per document.
+9. Selecteer de hoogste gefuseerde kandidaten.
+10. Expandeer geselecteerde children naar toegestane parentcontext.
+11. Stel context samen binnen token- en diversiteitsbudget.
+12. Bepaal answerability/conflictstatus.
+13. Materialiseer immutable citations en emit timings/metrics.
+
+## Standaardbudgetten V1
+
+- dense candidates: 50;
+- sparse candidates: 50;
+- fused candidates: 40;
+- geselecteerde fused results: 10;
+- maximaal 3 children per document;
+- minimaal 2 documenten waar beschikbaar;
+- contextbudget configureerbaar per generationprofiel.
+
+Dit zijn beginwaarden, geen harde kwaliteitswaarheid. Evaluation bepaalt wijzigingen.
+
+## Degradatie
+
+- Sparse unavailable: dense-only met expliciete degraded metadata.
+- Generator unavailable: search/context blijven werken.
+- Geen voldoende evidence: antwoordstatus `not_answerable`; geen geforceerde generatie.
+
+V1 heeft geen actieve reranker: de fused ranking is de normale productieroute,
+niet een degradatiefallback. Een toekomstige reranker krijgt pas een profiel en
+provider nadat die end-to-end is gevalideerd.

docs/05_RETRIEVAL/PROFILES.md

@@ -0,0 +1,25 @@
+# Retrieval Profiles
+
+## `exact-v1`
+
+Voor foutcodes, bestandsnamen, hashes en configuratiewaarden. Hoge sparseweging, geen queryrewrite, sterke identifierboost.
+
+## `semantic-v1`
+
+Voor conceptuele vragen. Dense dominant, queryexpansie alleen deterministisch/geconfigureerd, sterke documentdiversiteit.
+
+## `hybrid-v1`
+
+Standaard voor technische kennis. Dense + sparse, RRF, optionele local reranker en parentexpansie.
+
+## `code-v1`
+
+Code-embedding/index, filters op repository/commit/path/language/symbol en groepering per module/symbol.
+
+## `strict-evidence-v1`
+
+Voor antwoorden met hogere onderbouwingseisen. Minimum evidence coverage, minstens twee onafhankelijke bronnen wanneer relevant, verplichte citations en weigering bij conflict of onvoldoende dekking.
+
+## Profielimmutability
+
+Een gepubliceerd profiel is immutable. Wijziging maakt een nieuwe versie. RetrievalRun registreert exacte profile ID, modeldigests, indexalias en parameters.