# Upgrade Strategy

## Applicatie

Build immutable image, run migrations/preflight, deploy, verify health and smoke tests. Database migrations are backward compatible for at least one application rollout whenever practical.

## Embedding/index

Never in place. Register new profile, build shadow collection, evaluate, activate alias, retain old build for rollback.

## PostgreSQL/Qdrant

Pin exact supported versions, read release notes, test backup restore and application suite in staging/temporary environment, then maintenance deployment. No automatic major upgrades.

## Rollback

Application image rollback plus compatible migration strategy; index alias rollback for retrieval; config/profile activation history. Restore is last resort, not ordinary rollback.

## Upgrade naar 1.2.1

Deze release bundelt drie rondes: SOURCE-CONVERGENCE (migratie `0017`),
OPERATIONS-ISOLATION (`0018`) en RELEASE-CLEANUP (`0019`). Eén
`alembic upgrade head` voert ze in volgorde uit; de stappen hieronder
beschrijven wat er per ronde verandert en wat je vóór de uitrol moet zetten.

### SOURCE-CONVERGENCE (`0017`)

1. **Eerst configureren, dan uitrollen.** `RAGCORE_SOURCE_ROOTS` is een expliciete
   allowlist van server-side paden die een Folder- of Git-bron mag lezen, en is
   *leeg by default* -- fail closed. Zolang die leeg is kan geen enkele
   filesystem-bron worden aangemaakt of gesynchroniseerd, en falen bestaande
   folder/Git-syncs **terminaal** (`source path is outside every allowed source
   root`). Zet de waarde dus vóór de uitrol, met de paden zoals de *worker* ze
   ziet, en zorg dat elk pad ook read-only in de worker gemount is
   (`RAGCORE_SOURCE_MOUNT` in `compose.yaml`). Mount zonder allowlist leest
   niets; allowlist zonder mount resolvet niet. Er is bewust geen impliciete
   default, `/` al helemaal niet.
2. Migratie `0017_source_convergence` (`alembic upgrade head`) voegt de
   convergentie-administratie toe aan `content.source_items`
   (`applied_fingerprint`, `applied_at`, `pending_job_id`, `attempts`,
   `last_failure_code`, `last_failure_retryable`), `pending` aan
   `source_sync_runs`, verbreedt `sync_state`/`outcome` naar 32 tekens, en
   vervangt de foreign key van `content.documents` door een samengestelde
   `(source_id, workspace_id, space_id)` met een bijbehorende unique key op
   `content.sources`.
3. **Twee datawijzigingen in die migratie, geen schemawijzigingen:**
   (a) bestaande onthouden items worden als *applied* gebackfilld -- ze zijn
   geïngest onder het oude model, waarin een afgeronde discovery het enige
   completion-signaal was; (b) een bron die door `0016` over meerdere knowledge
   spaces heen mocht liggen wordt gesplitst naar per-space zusterbronnen
   (deterministisch afgeleid id) en de documenten daarvan worden omgehangen.
4. Qdrant-punten van zulke *gesplitste* documenten dragen nog het oude
   `source_id`. Draai daarna een authoritative reconcile/rebuild van de actieve
   collectie, net als bij de 1.2.0-upgrade. Controleer vooraf of er iets te
   splitsen valt:

   ```sql
   SELECT DISTINCT d.source_id, d.workspace_id, d.space_id
   FROM content.documents AS d
   JOIN content.sources AS s ON s.id = d.source_id
   WHERE d.workspace_id <> s.workspace_id OR d.space_id <> s.space_id;
   ```

   Geen rijen = geen split en geen rebuild nodig voor deze stap.
5. **Downgrade is niet symmetrisch.** De split wordt niet teruggedraaid (de
   zusterbronnen zijn echte bronnen geworden), en `awaiting_ingest` /
   `completed_with_failures` bestaan niet in het oude schema: die vallen bij een
   downgrade terug op `applying` respectievelijk `failed`, zodat een
   gedowngrade deployment "onaf of mislukt" leest in plaats van "geslaagd".
6. Verwachte gedragsverandering na de uitrol: een sync meldt `awaiting_ingest`
   tot zijn child-`ingest_upload`-jobs teruggerapporteerd hebben, en
   `last_successful_sync_at` schuift alleen op bij een volledig geconvergeerde
   run. Een bron die eerder direct "Last sync ok" toonde, toont nu eerst
   "Indexing" -- dat is de correctie, geen regressie.

### OPERATIONS-ISOLATION (`0018`)

7. Migratie `0018_job_workspace_ownership` maakt eigenaarschap van een job een
   echte kolom (`jobs.jobs.workspace_id`, geïndexeerd) en voegt
   `content.source_items.last_failure_job_id` toe. De backfill is bewust
   fail-closed: alleen een `payload->>'workspace_id'` die zowel een geldige
   UUID is *als* een bestaande workspace aanwijst wordt overgenomen. Al het
   andere blijft `NULL` = *legacy*, en dat betekent onzichtbaar en
   onwijzigbaar voor elke workspace-gebonden principal; alleen een Platform
   Admin ziet zulke jobs nog. Verwachte gedragsverandering: een operator die
   vóór deze upgrade jobs van andere tenants zag, ziet nu alleen de eigen
   workspace. Controleer hoeveel rijen legacy blijven:

   ```sql
   SELECT count(*) FROM jobs.jobs WHERE workspace_id IS NULL;
   ```

   Die jobs zijn niet stuk; ze zijn alleen niet toewijsbaar. Laat ze aflopen of
   ruim ze op als Platform Admin.
8. **`FILESYSTEM_SOURCE_MANAGE` is nieuw en ligt uitsluitend bij
   `PLATFORM_ADMIN`.** Een Folder- of Git-bron aanmaken *of wijzigen* vereist
   die permissie bovenop `SOURCE_MANAGE`. Workspace Admins en Space Managers
   die vóór deze upgrade filesystem-bronnen beheerden, kunnen dat niet meer;
   plan wie dat overneemt. De permissie en de `RAGCORE_SOURCE_ROOTS`-sandbox
   zijn onafhankelijke poorten: een pad buiten de allowlist wordt ook voor een
   Platform Admin geweigerd.

### RELEASE-CLEANUP (`0019`)

9. Migratie `0019_job_listing_index` voegt alleen een index toe
   (`ix_jobs_workspace_status_recent` op `(workspace_id, status, updated_at)`).
   Geen datawijziging, geen gedragsverandering buiten performance: het
   jobsoverzicht filtert vanaf deze release in SQL over de hele workspace in
   plaats van over een opgehaalde pagina, en dit is de index waarop die query
   draait. Op een grote `jobs.jobs` kost het aanmaken kort een write-lock;
   gebruik zo nodig `CREATE INDEX CONCURRENTLY` buiten Alembic om en markeer de
   migratie daarna als uitgevoerd.

## Upgrade naar 1.2.0

1. Migratie `0016_sources_lifecycle` (`alembic upgrade head`) maakt `content.sources`,
   `source_sync_runs`, `source_items`, voegt `documents.source_id` (NOT NULL, FK) toe en
   backfillt die uit `source_key` met dezelfde regel die de runtime gebruikt
   (UUID-vormige key = caller-bron; anders de ingebouwde *Uploads*-bron van de space).
   Voor iedere backfilled bron ontstaat een registry-record (kind `upload`).
2. Qdrant-punten die vóór 1.2.0 zijn geïndexeerd dragen nog het oude synthetische
   `source_id` (uuid5 per document). Draai na de migratie een authoritative
   reconcile/rebuild van de actieve collectie (`IndexBuildService.reconcile`/`build`,
   beide gebruiken nu de canonical IndexPoint-mapping) zodat `source_ids`-filters en
   provenance ook voor bestaande content kloppen; tot die tijd matchen filters op die
   oude punten niet.
3. Worker en app opnieuw uitrollen (nieuwe job-operation `sync_source`; nieuwe
   Control Plane-routes `/admin/sources`, `/admin/documents`, `/admin/system`).
4. SDK-consumers: de citation-schema's kregen additieve optionele velden
   (`source_id`, `source_name`, `source_kind`, `locator`, `revision`, `display`).