# Prisma-Baseline-Cutover

Seit dem Wartungsschnitt vom 2026-07-22 besteht die aktive Prisma-Historie aus
`00000000000000_hivegrid_baseline`. Die Baseline ersetzt 195 Migrationen bis
`20260721160000_ak_p21_detach_guard_null_safety`, ohne das Fachschema zu ändern.
Die ersetzte Historie bleibt am Git-Commit
`090e2558a6965e1c5804eb24d3eab5da8c8611a8` rekonstruierbar. Zusätzlich liegt
sie für flache CI-Checkouts als checksum-geprüftes Audit-Archiv unter
`prisma/baseline-legacy-migrations.tar.gz`; Prisma behandelt dieses Archiv
nicht als aktive Migrationshistorie.

## Laufzeitvertrag

- Frische Datenbanken haben noch keine Prisma-Historie. Der Adopter führt keine
  Schreibaktion aus; `prisma migrate deploy` wendet die Baseline normal an.
- Bestehende Datenbanken werden nur übernommen, wenn ihre erfolgreichen
  Legacy-Einträge entweder alle 195 Migrationen oder ein lückenloses Präfix
  dieser Kette bilden. Zulässig sind die kanonische SHA-256 oder eine der zehn
  im Manifest mit ihrem Git-Quellcommit belegten historischen
  SHA-256-Varianten. Ein exaktes Präfix wird ausschließlich über
  `prisma migrate deploy` aus dem checksum-geprüften Audit-Archiv auf die
  vollständige 195er-Kette vorwärts migriert. Lücken, fremde Namen, doppelte
  erfolgreiche Einträge und unbekannte Checksums bleiben harte Abbrüche. Bei
  einer historischen Variante werden vor der Baseline-Adoption zusätzlich
  Nullability/FK-Semantik, der tenant-gebundene Booking-Constraint sowie Owner
  und ACLs der betroffenen Security-Definer-Funktionen direkt im
  PostgreSQL-Katalog geprüft. Erst dann markiert
  `prisma migrate resolve --applied` die Baseline als angewendet. Die
  Baseline-DDL läuft dabei nicht. Nach dem regulären `prisma migrate deploy` muss ein
  `prisma migrate diff` die reale Datenbank gegen das aktuelle Prisma-Schema
  driftfrei bestätigen. Diese Reihenfolge erlaubt Forward-Migrationen nach der
  Baseline, ohne den noch nicht migrierten Legacy-Stand fälschlich gegen das
  bereits weiterentwickelte Schema zu vergleichen.
- Bereits baselinierte Datenbanken sind für die Adoption ein No-op.
  Fehlgeschlagene, lückenhafte, unbekannt checksum-abweichende,
  katalog-abweichende oder fremde Legacy-Historien brechen vor der Adoption ab.
  Scheitert eine Forward-Migration des exakten Präfixes, bleibt Primas eigener
  fehlgeschlagener Ledger-Eintrag sichtbar und jeder weitere Lauf stoppt
  fail-closed.
  Eine Abweichung vom aktuellen Prisma-Schema bricht nach den atomaren
  Forward-Migrationen und vor Permission-Sync beziehungsweise Rollout ab.
- Historie und Varianten-Katalog werden nach dem unveränderten
  Migrator-Rollen-Probe und vor `prisma migrate deploy` geprüft; die
  Prisma-Schema-Parität wird direkt danach im selben kurzlebigen
  `start.sh migrate`-Container geprüft. Nur dieser Prozess erhält `DIRECT_URL`;
  Runtime-Ressourcen erhalten sie nie.
- `_prisma_migrations` wird weder gelöscht noch umgeschrieben. Der zusätzliche
  Baseline-Eintrag ist der auditierbare Übergang zwischen alter und neuer
  Historie.

## Einmaliger Merge- und Rollout-Ablauf

1. Während der PR offen ist, gilt Schema-Freeze. Parallele Schema-Branches
   werden nach dem Merge auf `main` rebased und erzeugen ihre Merge-Migration
   anschließend neu gegen die Baseline.
2. Vor dem Merge müssen Baseline-Äquivalenz, Migrations-Parity, der strikte
   RLS-Live-Test und die normalen Commit-/Push-Gates grün sein.
3. Der reguläre Main-Deploy baut zuerst das unveränderliche Image. Der
   Staging-One-shot-Migrator prüft die Rolle, vervollständigt bei Bedarf ein
   checksum-geprüftes Legacy-Präfix aus dem Audit-Archiv, übernimmt die
   vollständige Legacy-Historie, führt `migrate deploy` aus, prüft danach die
   aktuelle Schema-Parität und synchronisiert erst dann den Permission-Katalog.
4. Erst nach grünem Staging-Deploy und geprüftem Restore-Punkt wird derselbe
   Image-SHA über den bestehenden Promote-Ablauf nach Produktion gebracht.
   Der input-freie Production-Promote darf erst nach bestätigter Backup- oder
   Restore-Point-Bereitschaft gestartet werden; der manuelle Run ist die
   auditierte Operator-Bestätigung.
5. Der Produktions-One-shot-Migrator führt dieselbe fail-closed Adoption aus.
   Erst danach werden die Runtime-Ressourcen ausgerollt.

Keine manuelle `migrate resolve`-Ausführung ist Teil dieses Ablaufs. Wenn der
Adopter stoppt, wird zuerst die gemeldete Historienabweichung untersucht; die
Prisma-Tabelle wird nicht per SQL „repariert".

## Verifikation

```bash
pnpm run verify:prisma-baseline
pnpm run verify:prisma-baseline-equivalence
pnpm exec prisma validate --config prisma.config.ts
pnpm run verify:migrations-parity
pnpm run verify:tenant-policy-contract
pnpm run verify:rls-release-readiness
HIVEGRID_RLS_REQUIRE_MIGRATION_CHAIN_PARITY=1 pnpm run verify:rls-live
```

Der Äquivalenztest entpackt die 195 Legacy-Dateien aus dem Audit-Archiv, prüft
Archiv- und Einzeldatei-Checksums, spielt Legacy und Baseline in getrennte PostgreSQL-16-
Datenbanken ein, simuliert alle acht Migrationen mit den zehn belegten
historischen Ledger-Checksums, probt Adoption und wiederholten No-op und
vergleicht Schema, RLS, Funktionen, ACLs, Extensions, Constraints, Indizes sowie
die von Migrationen angelegten Referenzdaten.

## Rollback

- Vor Merge: PR verwerfen. Es gab keine externe Datenbankmutation.
- Nach Merge, vor Adoption: Merge revertieren und die Legacy-Verzeichnisse aus
  Git wiederherstellen.
- Nach Adoption: Die Adoption hat keine DDL ausgeführt. Für einen Code-Rollback
  werden die Legacy-Dateien wiederhergestellt; ein altes Image darf jedoch
  nicht erneut `migrate deploy` ausführen, solange der zusätzliche Baseline-
  Eintrag nicht mit dem getesteten Rollback-Ablauf vereinbar ist.
- Bei einer frischen, nur aus der Baseline aufgebauten Wegwerf-Datenbank wird
  die Datenbank verworfen und neu erstellt. In Produktion wird niemals ein
  `DROP SCHEMA` als Rollback ausgeführt; dort gilt Restore-Punkt/Backup plus
  forward-only Korrekturmigration.