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