Initial curated RAGcore source from c16667f0c9397e2bfc8dd0255b114fba23c8d05e

docs/03_DATA/DATABASE_SCHEMA.md

@@ -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.