Initial curated RAGcore source from c16667f0c9397e2bfc8dd0255b114fba23c8d05e

2026-10-01 01:34:21 +02:00
commit 7ca726caf2
@@ -0,0 +1,30 @@
+# Blob and Artifact Layout
+
+## Immutable blobs
+
+```text
+blobs/sha256/ab/cd/<full-sha256>.blob
+```
+
+Metadata staat in PostgreSQL: digest, size, MIME, oorspronkelijke naam, acquisition en security status. Identieke bytes worden fysiek gededupliceerd.
+
+## Parsed artifacts
+
+```text
+parsed/<workspace>/<document-version>/
+  canonical.json.zst
+  canonical.md
+  structure.json
+  extraction-report.json
+  assets/<digest>.<ext>
+```
+
+Canonical content is immutable en versieert parsernaam, parserversie, normalizerprofiel en source fingerprint.
+
+## Temp
+
+`tmp/<job-id>/` is alleen voor begrensde verwerking en wordt na jobfinalisatie of expiry opgeruimd. Tempfiles mogen nooit de enige kopie van evidence zijn.
+
+## Atomicity
+
+Schrijf naar uniek tijdelijk pad, fsync waar vereist, verifieer hash, rename atomair naar content-addressed doel en registreer pas daarna metadata.
@@ -0,0 +1,43 @@
+# Database Schema
+
+## Schema's
+
+- `identity`: users, service_accounts, credentials, sessions.
+- `control`: workspaces, applications, spaces, grants, policies, profiles.
+- `content`: sources, documents, versions, blobs, artifacts, chunks, citations.
+- `jobs`: jobs, attempts, events, schedules.
+- `query`: retrieval_runs, candidates, answers, feedback.
+- `evaluation`: suites, cases, runs, results.
+- `audit`: append-only audit_events.
+
+## Belangrijke constraints
+
+- Unieke actieve documentversion per document via partial unique index.
+- Unieke `(workspace_id, slug)` voor applications en spaces.
+- Tokenhash uniek; plaintext token nooit opgeslagen.
+- Chunk uniqueness op `(document_version_id, structure_path, content_hash, chunk_profile_version)`.
+- Foreign keys gebruiken restrict/cascade bewust; contentaudit wordt niet stil verwijderd.
+- Alle timestamps `timestamptz` in UTC.
+- `jobs.jobs.workspace_id` is de ownership-kolom waarop iedere operator-query
+  filtert, met indexen `(workspace_id, updated_at)` en --- sinds migratie 0019,
+  voor het gefilterde operatoroverzicht --- `(workspace_id, status, updated_at)`.
+  `operation` staat er bewust niet in: die kolom heeft twee waarden in deze
+  runtime en versmalt niets wat de eerste twee kolommen niet al versmallen.
+  Nullable *uitsluitend* voor
+  legacy rijen van vóór migratie 0018; nieuwe jobs worden door de repository
+  geweigerd zonder eigenaar. `NULL` betekent "geen eigenaar vast te stellen" en
+  faalt gesloten voor workspace-scoped principals --- nooit "van iedereen".
+- `content.source_items.last_failure_job_id` bewaart de child ingest job die als
+  laatste faalde. Een terminaal gefaald item met ongewijzigde fingerprint wordt
+  bewust niet opnieuw ge-enqueued; herstel loopt via retry van díe job.
+
+## Transaction boundaries
+
+- Nieuwe versie en jobregistratie in één transaction.
+- Publication update vergrendelt document en valideert indexbuildstatus.
+- Jobclaim gebruikt `FOR UPDATE SKIP LOCKED` met lease expiry.
+- Qdrant is geen distributed transaction participant; outbox/reconciliation herstelt divergentie.
+
+## Migrations
+
+Alle wijzigingen via Alembic, met upgrade, waar realistisch downgrade, data-backfillplan en migratietest tegen lege én representatieve database.
@@ -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.
@@ -0,0 +1,21 @@
+# Versioning and Retention
+
+## Version detection
+
+Connectorfingerprint + cryptografische contenthash bepalen `unchanged`, `new`, `changed` of `deleted_at_source`.
+
+## Publication
+
+De vorige actieve version blijft serving totdat de nieuwe `validated` is. Publication is een expliciete state transition. Bij mislukking blijft de vorige version actief.
+
+## Retention
+
+Per space instelbaar:
+
+- actieve versions onbeperkt zolang document bestaat;
+- superseded versions standaard 90 dagen;
+- source-deleted versions standaard 30 dagen;
+- audit/citationmetadata langer volgens policy;
+- quarantined bytes apart en beperkt.
+
+Citations kunnen een retentiehold op gebruikte documentversions plaatsen. Fysieke purge vereist dat geen geldige citation, legal hold of active index ernaar verwijst.