# External function mapping schema repair

Access owns `access_external_function_role_assignments`. Some older databases
record the Access baseline (`4a5b6c7d8e9f`) without this table. The mapping list
and `/api/v1/admin/external-function-role-mappings/delta` then fail with an
undefined-table error. This is a schema/history mismatch, not a reason to change
user permissions or recreate tenant data.

Forward repair revision `d8f1b4e7a0c3` follows Access `c7e0a3d6f9b2` on the
release track and `b6d9f2a5c8e1` on the disposable-development track. The latter
also requires Core's existing scope-table rename `4f2a9c8e7b6d`; this is a Core
contract and does not require the optional Tenancy or Organizations modules.

Before applying deployment migrations, back up and verify the database backup.
Use the configured migration track and ordinary deployment migration workflow,
including its deployment-wide advisory lock. Inspect the pending revision plan
before any targeted repair. Never replay or stamp the baseline, initialize dev
data, reset the database, or switch migration tracks to bypass the error.

The development launcher can run pending migrations when its file watcher
reloads the backend. Prepare and test a migration outside the watched source
tree, and complete the backup/preflight before placing a new migration file in
that tree. Do not assume that waiting to invoke a migration command prevents a
running development instance from applying it automatically.

The repair:

- Creates the absent mapping table only, with its baseline columns, role/scope
  cascade foreign keys, primary key, tenant/source/function/role uniqueness,
  and four lookup indexes.
- Does nothing if the table already exists. It does not alter partial tables;
  any other schema mismatch needs separate inspection.
- Never invents mappings or changes roles, memberships, permissions, or other
  application records. An empty list means no mappings have been configured.
- Keeps the table and any stored mappings on downgrade, because the table
  belongs to the baseline and removing it would delete authorization policy.

After migration, verify both mapping list endpoints return success for an
authorized user in the active tenant, and check the table's constraints and
indexes. Existing read scopes and tenant isolation remain enforced. A missing
table cannot reveal whether historical mappings were once removed: this repair
does not reconstruct lost policy; investigate backups if mappings were expected.

Regression coverage in `tests/test_external_function_mapping_migration.py`
recreates the observed missing-table failure in isolated databases on both
tracks. It checks the HTTP list/delta responses, repeated upgrades, no-op
upgrades with existing mappings, downgrade/re-upgrade preservation, unchanged
parent rows/permissions, constraints, denied unprivileged reads, and tenant
isolation.

## Deutsch

Bei älteren Datenbanken kann die Access-Basismigration als angewendet vermerkt
sein, obwohl `access_external_function_role_assignments` fehlt. Die Liste der
Funktions-Rollenzuordnungen und ihre Delta-API melden dann einen internen Fehler.
Dies ist ein Widerspruch zwischen Schema und Migrationsstand, kein Anlass zur
Erweiterung von Berechtigungen oder zum Neuerstellen von Mandantendaten.

Vor der regulären, vorwärtsgerichteten Migration `d8f1b4e7a0c3` eine überprüfte
Datenbanksicherung erstellen. Den konfigurierten Migrationstrack und den
regulären Bereitstellungsablauf mit installationsweiter Migrationssperre nutzen;
bei einer gezielten Reparatur zuvor die ausstehenden Revisionen prüfen.
Basismigrationen nicht erneut ausführen oder lediglich als angewendet markieren,
keine Entwicklungsdaten initialisieren und die Datenbank nicht zurücksetzen.
Der Entwicklungsstarter kann ausstehende Migrationen bereits beim automatischen
Neuladen des Backends anwenden. Neue Migrationsdateien deshalb außerhalb des
überwachten Quellbaums vorbereiten und testen; Sicherung und Vorprüfung vor dem
Kopieren in den überwachten Quellbaum abschließen. Das Warten mit einem manuellen
Migrationsaufruf verhindert die automatische Anwendung nicht.

Die Reparatur erstellt nur die fehlende Tabelle einschließlich Fremdschlüsseln,
Eindeutigkeitsbedingung und Indizes. Vorhandene Tabellen und Datensätze bleiben
unverändert; auch ein Downgrade entfernt keine Zuordnungsdaten. Teilweise
vorhandene Tabellen werden nicht umgebaut und erfordern eine gesonderte Prüfung.
Es entstehen keine automatischen Zuordnungen oder neuen Rechte. Anschließend
beide Listenendpunkte im aktiven Mandanten mit einer berechtigten Person prüfen.
Eine leere Liste bedeutet, dass keine Zuordnungen konfiguriert sind. Falls früher
Zuordnungen erwartet wurden, Sicherungen prüfen: Verlorene Berechtigungsregeln
lassen sich aus einer fehlenden Tabelle nicht rekonstruieren.