mainsequence-metatable 0.1.0__py3-none-any.whl

api/app/bootstrap.py

@@ -0,0 +1,607 @@
+"""Explicit, mode-independent initialization of the selected runtime database."""
+import json
+import os
+from contextlib import ExitStack, contextmanager
+from dataclasses import replace
+from pathlib import Path
+from threading import Lock
+from types import SimpleNamespace
+from typing import Literal
+from uuid import UUID, uuid4
+
+from alembic.migration import MigrationContext
+from alembic.script import ScriptDirectory
+from fastapi import APIRouter, Depends, HTTPException, Request
+from pydantic import BaseModel, ConfigDict, Field
+from sqlalchemy import inspect, select
+from sqlalchemy.engine import URL
+from sqlalchemy.orm import sessionmaker
+
+from api.app.auth.boundary import AdmittedCaller, require_admin
+from api.backend.backends.contracts import CatalogConfigurationError
+from api.backend.integrations.catalog_data_sources import parse_configuration, resolve_source
+from api.backend.integrations.credential_store import (
+    CredentialStoreError,
+    SDKCredentialStore,
+    UnavailableCredentialStore,
+    bind_store,
+)
+from api.backend.integrations.local_workspace import _bind_file, _read_marker
+from api.backend.integrations.runtime_binding import RuntimeStorageBinding
+from api.backend.persistence.database import (
+    create_catalog_engine,
+    migration_config,
+    upgrade_catalog,
+)
+from api.backend.persistence.models import Base, DataSource, MetaTable, PhysicalOperation
+from metatables.runtime_contract import RuntimeBootstrapDescriptor
+
+VERSION_TABLE = "metatables_catalog_version"
+
+
+class RuntimeSourceInput(BaseModel):
+    model_config = ConfigDict(extra="forbid", str_strip_whitespace=True)
+    display_name: str = Field(min_length=1, max_length=255)
+    class_type: str
+    configuration: dict
+
+
+class BootstrapError(RuntimeError):
+    pass
+
+
+class DestroyLocalInput(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    path: str
+    confirmation: Literal["DESTROY"]
+
+
+class RuntimeBootstrap:
+    def __init__(self, config, identity):
+        self.config, self.identity = config, identity
+        self.credential_store = UnavailableCredentialStore() if config.local_mode else SDKCredentialStore()
+        self.candidate = None
+        self.owner = None
+        self.reader = None
+        self.engine = None
+        self.backend = None
+        self.factory = None
+        self.resources = ExitStack()
+        self.lock = Lock()
+        self.status = "unconfigured"
+        self.error = None
+        self.current = []
+        self.expected = list(ScriptDirectory.from_config(migration_config()).get_heads())
+        self.workspace = identity.workspace if identity else None
+        self.active = False
+        self.uid = None
+        self.selected_source_uid = None
+        self.saved_path = (config.configuration_path or Path.cwd() / "configuration.yaml").resolve().parent / ".local/runtime-data-sources.json"
+        self.selection_key = str(self.workspace.uid) if self.workspace else "hosted"
+
+    def descriptor(self, user_uid, *, is_admin=False):
+        can_configure = is_admin
+        return dict(status=self.status, error=self.error, candidate=self.candidate if can_configure else None,
+                    can_configure=can_configure, selected_source_uid=str(self.uid) if self.uid else self.selected_source_uid,
+                    **self.migration_descriptor(),
+                    active=self.active)
+
+    def migration_descriptor(self):
+        """Compare live Alembic heads with the files without applying migrations."""
+        result = dict(current_revisions=[], required_revisions=[], pending_revisions=[],
+                      migration_status="unavailable", migration_error=None)
+        try:
+            script = ScriptDirectory.from_config(migration_config())
+            result["required_revisions"] = sorted(script.get_heads())
+            if not result["required_revisions"]:
+                raise ValueError("Migration files have no head revision")
+        except Exception:
+            result["migration_error"] = "Cannot read the API's migration files. Check the migration directory and refresh."
+            return result
+        if not self.candidate:
+            result["migration_status"] = "unconfigured"
+            return result
+        if self.status == "migrating":
+            result.update(current_revisions=self.current, migration_status="migrating")
+            return result
+        try:
+            engine = self.reader if self.reader is not None else self.open_engine()
+            if engine is not None:
+                with engine.connect() as connection:
+                    result["current_revisions"] = sorted(MigrationContext.configure(
+                        connection, opts={"version_table": VERSION_TABLE}).get_current_heads())
+        except Exception:
+            result["migration_error"] = "Cannot read the database's applied migrations. Check its connection and refresh."
+            return result
+        try:
+            current = result["current_revisions"]
+            known = {revision.revision for revision in script.walk_revisions()}
+            if not set(current).issubset(known):
+                raise ValueError("Unknown database revision")
+            pending = list(script.iterate_revisions("heads", tuple(current)))
+            result["pending_revisions"] = [revision.revision for revision in reversed(pending)]
+            if not pending and set(current) != set(result["required_revisions"]):
+                raise ValueError("Database heads do not match the migration files")
+            result["migration_status"] = "pending" if pending else "up_to_date"
+        except Exception:
+            result.update(migration_status="incompatible",
+                          migration_error="The database revision is not compatible with these migration files. Review the migration history before applying changes.")
+        return result
+
+    def initial_candidate(self):
+        if self.saved_path.exists():
+            try:
+                saved = json.loads(self.saved_path.read_text())
+                if self.selection_key in saved:
+                    if self.selection_key == "hosted":
+                        self.selected_source_uid = saved.get("hosted_source_uid")
+                    return saved[self.selection_key]
+            except (OSError, ValueError):
+                self.error = "Saved runtime selection cannot be read. Configure the DataSource again."
+        if self.workspace:
+            return dict(display_name=self.workspace.data_source.display_name, class_type="sqlite",
+                        configuration={"path": str(self.workspace.tables_path)})
+        return None
+
+    def close(self):
+        if self.engine is not None:
+            self.engine.dispose()
+        if self.reader is not None:
+            self.reader.dispose()
+        self.reader = None
+        self.resources.close()
+
+    def configure(self, body, owner):
+        # Validate public configuration before replacing the current candidate.
+        values = RuntimeSourceInput.model_validate(body).model_dump(mode="json")
+        kind = values["class_type"]
+        if self.config.local_mode:
+            if kind != "sqlite" or set(values["configuration"]) != {"path"}:
+                raise BootstrapError("Local runtime requires one SQLite file.")
+            path = Path(values["configuration"]["path"]).expanduser()
+            if not path.is_absolute() or path.name == ":memory:" or path.is_dir():
+                raise BootstrapError("Choose an absolute SQLite file path.")
+            path = path.resolve()
+            marker = _read_marker(path.with_name(path.name + ".metatables-scope.json"))
+            if marker and marker != {"workspace_uid": str(self.workspace.uid), "purpose": "runtime"}:
+                raise BootstrapError("This file belongs to another workspace or the retired two-file layout.")
+            self.workspace = replace(self.workspace, database_path=path)
+            values["configuration"] = {"path": str(path)}
+        else:
+            from api.backend.backends.registry import engine_descriptor
+            descriptor = engine_descriptor(kind)
+            if kind == 'sqlite':
+                raise BootstrapError('This engine does not support hosted runtime workflows.')
+            parsed = parse_configuration(kind, values['configuration'])
+            descriptor.catalog.validate_configuration(parsed)
+            values["configuration"] = parsed.model_dump(mode="json")
+        self.close()
+        self.resources = ExitStack()
+        self.engine = self.factory = self.backend = None
+        self.candidate, self.owner = values, owner
+        self.active, self.uid = False, None
+        self.status, self.error, self.current = "unconfigured", None, []
+        self.inspect()
+
+    def open_engine(self, *, create=False):
+        from api.backend.backends.registry import backend_for_engine
+        if self.backend is None:
+            self.backend = backend_for_engine(self.candidate, self.credential_store, workspace=self.workspace)
+        if self.engine is not None:
+            return self.engine
+        self.engine = self.backend.catalog.open_engine(self.backend.source, self.resources,
+            create=create, workspace=self.workspace)
+        if self.engine is not None:
+            self.engine.update_execution_options(metatables_binding={key: self.candidate[key] for key in ("class_type", "configuration")})
+            self.factory = sessionmaker(self.engine, expire_on_commit=False)
+        return self.engine
+
+    def inspect(self):
+        self.error = None
+        try:
+            script = ScriptDirectory.from_config(migration_config())
+            self.expected = list(script.get_heads())
+            self.current = []
+            engine = self.open_engine()
+            if engine is None:
+                self.status = "migration_required"
+                return
+            with engine.connect() as connection:
+                catalog = inspect(connection)
+                tables = set(catalog.get_table_names())
+                self.current = list(MigrationContext.configure(connection, opts={"version_table": VERSION_TABLE}).get_current_heads())
+                from api.backend.operations.bootstrap_migrations import validate_progress
+                progress = validate_progress(connection, engine)
+                if VERSION_TABLE not in tables and tables.intersection(Base.metadata.tables) and progress is None:
+                    self.status = "incompatible"
+                    self.error = "Existing system tables have no current MetaTables migration history. Select a fresh development database in Settings."
+                    return
+                try:
+                    for revision in self.current:
+                        if script.get_revision(revision) is None:
+                            raise ValueError("Unknown revision")
+                except Exception:
+                    self.status, self.error = "incompatible", "The database has an unsupported MetaTables migration revision. Earlier development databases require recreation."
+                    return
+                if set(self.current) != set(self.expected):
+                    self.status = "migration_required"
+                    return
+                from api.backend.operations.catalog_schema import validate_system_schema
+                validate_system_schema(connection, self.backend.catalog)
+            with self.factory() as session:
+                row = session.scalar(select(DataSource).where(DataSource.is_runtime.__eq__(True)))
+                if row is None:
+                    self.status = "registration_required"
+                elif not self.matches(row):
+                    self.status = "incompatible"
+                    self.error = "The stored runtime DataSource does not match this connection."
+                else:
+                    binding = RuntimeStorageBinding(str(engine.url), self.workspace, row.uid, self.candidate["configuration"])
+                    for registered in session.scalars(select(DataSource)):
+                        binding.validate_source(registered)
+                    for model in (MetaTable, PhysicalOperation):
+                        query = select(model.uid).where(model.data_source_uid != row.uid)
+                        if model is MetaTable:
+                            query = query.where(MetaTable.management_mode != "external_registered")
+                        if session.scalar(query.limit(1)):
+                            raise BootstrapError("Managed runtime catalog references another DataSource.")
+                    if session.scalar(select(MetaTable.uid).where(~MetaTable.data_source_uid.in_(select(DataSource.uid))).limit(1)):
+                        raise BootstrapError("MetaTable references an unregistered DataSource.")
+                    self.uid = row.uid
+                    self.status = "ready"
+        except (BootstrapError, CatalogConfigurationError) as exc:
+            self.status, self.error = "incompatible", str(exc)
+        except CredentialStoreError as exc:
+            self.status, self.error = "unavailable", exc.message
+        except Exception:
+            self.status = "unavailable"
+            self.error = "Cannot verify the selected database or its Alembic history. Check configuration, Secret access and the API's migration version."
+
+    def matches(self, row):
+        return (row.class_type == self.candidate["class_type"]
+                and row.configuration == self.candidate["configuration"]
+                and row.is_default and row.storage_access_mode == "read_write" and row.status == "AVAILABLE")
+
+    @contextmanager
+    def migration_lock(self):
+        engine = self.open_engine(create=True)
+        with self.backend.catalog.bootstrap_lock(engine):
+            yield
+
+    def migrate(self, user_uid):
+        if not self.candidate:
+            raise BootstrapError("Configure a runtime DataSource first.")
+        try:
+            # Check before creating a file or scope marker: an earlier local
+            # store must remain untouched even when this target is absent.
+            self.inspect()
+            if self.status not in {"migration_required", "registration_required", "ready"}:
+                raise BootstrapError(self.error or "The selected database cannot be migrated.")
+            with self.migration_lock():
+                self.inspect()
+                if self.status not in {"migration_required", "registration_required", "ready"}:
+                    raise BootstrapError(self.error or "The selected database cannot be migrated.")
+                self.status = "migrating"
+                upgrade_catalog(self.engine)
+                # The registry is used only after Alembic created/upgraded it.
+                with self.factory() as session:
+                    row = session.scalar(select(DataSource).where(DataSource.is_runtime.__eq__(True)))
+                    if row is None:
+                        if session.scalar(select(DataSource.uid).where(DataSource.is_default.__eq__(True))):
+                            raise BootstrapError("An existing default requires explicit reconciliation before runtime registration.")
+                        row = DataSource(uid=self.workspace.data_source.uid if self.workspace else
+                            UUID(self.selected_source_uid) if self.selected_source_uid else uuid4(),
+                            created_by_user_uid=user_uid, **self.candidate, is_runtime=True,
+                            is_default=True, status="AVAILABLE", storage_access_mode="read_write")
+                        session.add(row)
+                    elif not self.matches(row):
+                        raise BootstrapError("The existing runtime registration cannot be replaced by this configuration or caller.")
+                    from api.backend.backends.registry import backend_for
+                    session.flush()
+                    if self.workspace:
+                        # Existing local candidate metadata is materialized into
+                        # the catalog, retaining UIDs. Credentials require the
+                        # explicit import or password replacement procedure.
+                        from api.app.source_registrations import read_registry
+                        saved = read_registry(self.saved_path.with_name("runtime-source-candidates.json"))
+                        for candidate in saved.values():
+                            if candidate.get("class_type") not in {"postgresql", "timescale_db", "mysql", "mssql"}:
+                                continue
+                            candidate_uid = UUID(candidate["uid"])
+                            if session.get(DataSource, candidate_uid) is None:
+                                session.add(DataSource(uid=candidate_uid, created_by_user_uid=user_uid,
+                                    display_name=candidate["display_name"], class_type=candidate["class_type"],
+                                    configuration=candidate["configuration"], storage_access_mode=candidate["storage_access_mode"],
+                                    status=candidate["status"], is_default=False, is_runtime=False))
+                    backend_for(replace(self.backend.source, uid=row.uid)).access.initialize(session)
+                    credentials = bind_store(self.credential_store, session, user_uid)
+                    if hasattr(credentials, "initialize"):
+                        credentials.initialize()
+                    session.commit()
+            self.inspect()
+            if self.status != "ready":
+                raise BootstrapError(self.error or "Migration finished but the runtime is not ready.")
+        except BootstrapError:
+            self.inspect()
+            raise
+        except Exception as exc:
+            self.inspect()
+            if isinstance(exc, CredentialStoreError):
+                self.error = exc.message
+                raise BootstrapError(exc.message) from None
+            from api.backend.backends.contracts import SQLExecutionError
+            if isinstance(exc, SQLExecutionError):
+                self.error = f"Database access setup failed ({exc.code}). Check the DataSource password Secret and database permissions, then retry setup."
+                raise BootstrapError(self.error) from None
+            self.error = "MetaTables migration or registration failed. The runtime was not activated; inspect the database before retrying."
+            raise BootstrapError(self.error) from None
+
+    def persist_selection(self):
+        from api.app.runtime_control import write_state
+        self.saved_path.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
+        # Public configuration only: password and TLS material remain Secret references.
+        saved = json.loads(self.saved_path.read_text()) if self.saved_path.exists() else {}
+        saved[self.selection_key] = self.candidate
+        if self.selection_key == "hosted":
+            if self.selected_source_uid:
+                saved["hosted_source_uid"] = self.selected_source_uid
+            else:
+                saved.pop("hosted_source_uid", None)
+        write_state(self.saved_path, saved)
+
+    def destroy_local(self, request, path, user_uid):
+        import fcntl
+
+        from api.app.runtime_control import write_state
+        from api.backend.integrations.local_workspace import local_store_files
+
+        if not self.config.local_mode or self.workspace is None:
+            raise BootstrapError("Database destruction is available only in Local mode.")
+        if not self.candidate or path != self.candidate["configuration"]["path"]:
+            raise BootstrapError("The selected local database changed. Reload Settings before destruction.")
+        try:
+            with ExitStack() as stack:
+                target = self.workspace.database_path
+                if target.parent.exists():
+                    descriptor = os.open(str(target) + ".bootstrap.lock",
+                                         os.O_CREAT | os.O_RDWR | os.O_NOFOLLOW, 0o600)
+                    stream = stack.enter_context(os.fdopen(descriptor, "a"))
+                    try:
+                        fcntl.flock(stream, fcntl.LOCK_EX | fcntl.LOCK_NB)
+                    except BlockingIOError:
+                        raise BootstrapError("Another local initialization is in progress. Retry when it finishes.") from None
+                files = local_store_files(self.workspace)
+                saved = json.loads(self.saved_path.read_text()) if self.saved_path.exists() else {}
+                if self.selection_key in saved:
+                    del saved[self.selection_key]
+                    write_state(self.saved_path, saved)
+                # Admission is drained before closing pools or deleting files.
+                self.close()
+                self.resources = ExitStack()
+                self.engine = self.factory = None
+                self.active, self.uid, self.owner = False, None, user_uid
+                self.current, self.error = [], None
+                self.status = "migration_required"
+                request.app.state.runtime = replace(request.app.state.runtime,
+                    data_sources=None, binding=RuntimeStorageBinding())
+                request.app.state.runtime_control.instance_id = str(uuid4())
+                from metatables.local_run_logs import destroy_store
+                destroy_store(target, str(self.workspace.uid))
+                for file in files:
+                    file.unlink(missing_ok=True)
+                self.inspect()
+        except BootstrapError:
+            raise
+        except RuntimeError as exc:
+            raise BootstrapError(str(exc)) from None
+        except Exception:
+            if not self.active:
+                self.status = "unavailable"
+                self.error = "Unable to finish local database destruction. Check file access and retry."
+            raise BootstrapError("Unable to finish local database destruction. Check file access and retry.") from None
+
+    def activate(self, request, user_uid=None, *, persist=True):
+        self.inspect()
+        if self.status != "ready":
+            raise BootstrapError(self.error or "Run MetaTables migrations before selecting this DataSource.")
+        with self.factory() as session:
+            row = session.get(DataSource, self.uid)
+            self.owner = row.created_by_user_uid
+            if not self.workspace:
+                from api.app.source_registrations import reconcile_runtime
+                reconcile_runtime(self, row, persist=persist)
+        if self.workspace:
+            _bind_file(Path(self.candidate["configuration"]["path"]),
+                       workspace_uid=self.workspace.uid, purpose="runtime")
+        if persist:
+            try:
+                self.persist_selection()
+            except Exception:
+                raise BootstrapError("Unable to save runtime selection. The database is initialized but was not activated.") from None
+        binding = RuntimeStorageBinding(catalog_url=str(self.engine.url), workspace=self.workspace,
+                                        source_uid=self.uid, source_configuration=self.candidate["configuration"])
+        from sqlalchemy import create_engine
+
+        from api.backend.integrations.catalog_data_sources import CatalogDataSourceProvider
+        if self.reader is not None:
+            self.reader.dispose()
+        self.reader = self.backend.catalog.open_reader(self.backend.source, self.resources)
+        state = request.app.state.runtime
+        identity = replace(state.identity, workspace=self.workspace) if self.workspace else state.identity
+        request.app.state.runtime = replace(state, identity=identity, binding=binding,
+            data_sources=CatalogDataSourceProvider(sessionmaker(self.reader, expire_on_commit=False), self.credential_store, binding=binding),
+            credential_store=self.credential_store)
+        self.active = True
+        request.app.state.runtime_control.instance_id = str(uuid4())
+
+
+router = APIRouter(prefix="/runtime-bootstrap", tags=["Runtime bootstrap"])
+
+
+def manager(request):
+    value = request.app.state.runtime.bootstrap
+    if value is None:
+        raise HTTPException(503, "Runtime bootstrap is unavailable.")
+    return value
+
+
+@contextmanager
+def mutation(request, caller):
+    value = manager(request)
+    if not value.lock.acquire(blocking=False):
+        raise HTTPException(409, "Runtime configuration is already in progress.")
+    try:
+        control = request.app.state.runtime_control
+        control.begin()
+        try:
+            if value.active:
+                from api.app.runtime_control import unfinished_work
+                with value.factory() as session:
+                    if unfinished_work(session):
+                        raise HTTPException(409, "Finish updates, migrations and physical operations before reconfiguring the runtime.")
+            yield value
+        finally:
+            control.cancel()
+    except BootstrapError as exc:
+        raise HTTPException(409, str(exc)) from None
+    finally:
+        value.lock.release()
+
+
+class RuntimeSourceSelection(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    source_uid: UUID
+
+
+def registered_hosted_source(request, uid):
+    from api.app.source_registrations import get_row, registry_path, remember
+    state = request.app.state.runtime
+    row = None
+    if state.bootstrap.active:
+        with state.bootstrap.factory() as session:
+            registered = session.get(DataSource, uid)
+            if registered is not None:
+                if registered.class_type == "sqlite":
+                    raise HTTPException(409, "Select an enabled hosted database DataSource.")
+                remember(registered, request)
+                row = dict(display_name=registered.display_name, class_type=registered.class_type,
+                    configuration=registered.configuration, storage_access_mode=registered.storage_access_mode)
+    if row is None:
+        row = get_row(registry_path(request), uid)
+    from api.backend.backends.registry import engine_descriptor
+    engine_descriptor(row["class_type"])
+    if row["class_type"] == "sqlite" or row["storage_access_mode"] != "read_write":
+        raise HTTPException(409, "Select an enabled hosted database DataSource.")
+    return {key: row[key] for key in ("display_name", "class_type", "configuration")}
+
+
+def persist_registered_selection(candidate):
+    if candidate.uid:
+        from api.app.source_registrations import reconcile_runtime
+        with candidate.factory() as session:
+            reconcile_runtime(candidate, session.get(DataSource, candidate.uid))
+    else:
+        candidate.persist_selection()
+
+
+@router.post("/hosted/select/", response_model=RuntimeBootstrapDescriptor)
+def select_hosted_before_switch(body: RuntimeSourceSelection, request: Request,
+                                   caller: AdmittedCaller = Depends(require_admin)):
+    """Select a registered hosted DataSource without changing the active local runtime."""
+    state = request.app.state.runtime
+    current = state.hosted_bootstrap
+    if not state.config.local_mode or current is None:
+        raise HTTPException(403, "Hosted DataSource preparation is available only in Local mode.")
+    if not current.lock.acquire(blocking=False):
+        raise HTTPException(409, "Hosted DataSource configuration is already in progress.")
+    try:
+        if request.app.state.runtime.hosted_bootstrap is not current:
+            raise HTTPException(409, "Hosted DataSource configuration changed. Refresh Settings.")
+        source = registered_hosted_source(request, body.source_uid)
+        candidate = RuntimeBootstrap(replace(state.config, local_mode=False),
+                                     replace(state.identity, workspace=None))
+        try:
+            candidate.selected_source_uid = str(body.source_uid)
+            candidate.configure(source, caller.user_uid)
+            if candidate.status == "unavailable":
+                raise BootstrapError(candidate.error or "Cannot verify the hosted DataSource connection.")
+            persist_registered_selection(candidate)
+            request.app.state.runtime = replace(request.app.state.runtime, hosted_bootstrap=candidate)
+            current.close()
+            return candidate.descriptor(caller.user_uid, is_admin=caller.is_admin)
+        except BootstrapError as exc:
+            candidate.close()
+            raise HTTPException(409, str(exc)) from None
+        except Exception:
+            candidate.close()
+            raise HTTPException(503, "Unable to save the hosted DataSource configuration.") from None
+    finally:
+        current.lock.release()
+
+
+@router.post("/select/", response_model=RuntimeBootstrapDescriptor)
+def select_hosted_runtime_source(body: RuntimeSourceSelection, request: Request,
+                                 caller: AdmittedCaller = Depends(require_admin)):
+    if request.app.state.runtime.config.local_mode:
+        raise HTTPException(409, "Use hosted selection while Local mode is active.")
+    source = registered_hosted_source(request, body.source_uid)
+    with mutation(request, caller) as current:
+        state = request.app.state.runtime
+        candidate = RuntimeBootstrap(state.config, state.identity)
+        try:
+            candidate.selected_source_uid = str(body.source_uid)
+            candidate.configure(source, caller.user_uid)
+            if candidate.status == "unavailable":
+                raise BootstrapError(candidate.error or "Cannot verify the DataSource connection.")
+            persist_registered_selection(candidate)
+            request.app.state.runtime = replace(state, bootstrap=candidate,
+                                                data_sources=None, binding=RuntimeStorageBinding())
+            request.app.state.runtime_control.instance_id = str(uuid4())
+            current.close()
+            return candidate.descriptor(caller.user_uid, is_admin=caller.is_admin)
+        except BootstrapError as exc:
+            candidate.close()
+            raise HTTPException(409, str(exc)) from None
+        except Exception:
+            candidate.close()
+            raise HTTPException(503, "Unable to select the runtime DataSource.") from None
+
+
+@router.post("/configure/", response_model=RuntimeBootstrapDescriptor)
+def configure(body: RuntimeSourceInput, request: Request, caller: AdmittedCaller = Depends(require_admin)):
+    with mutation(request, caller) as value:
+        try:
+            value.configure(body, caller.user_uid)
+        except BootstrapError:
+            raise
+        except Exception:
+            raise BootstrapError("Invalid runtime DataSource configuration.") from None
+        request.app.state.runtime = replace(request.app.state.runtime, data_sources=None, binding=RuntimeStorageBinding())
+        request.app.state.runtime_control.instance_id = str(uuid4())
+        return value.descriptor(caller.user_uid, is_admin=caller.is_admin)
+
+
+@router.post("/migrate/", response_model=RuntimeBootstrapDescriptor)
+def migrate(request: Request, caller: AdmittedCaller = Depends(require_admin)):
+    with mutation(request, caller) as value:
+        value.active = False
+        request.app.state.runtime = replace(request.app.state.runtime, data_sources=None, binding=RuntimeStorageBinding())
+        value.migrate(caller.user_uid)
+        value.activate(request, caller.user_uid)
+        return value.descriptor(caller.user_uid, is_admin=caller.is_admin)
+
+
+@router.post("/activate/", response_model=RuntimeBootstrapDescriptor)
+def activate(request: Request, caller: AdmittedCaller = Depends(require_admin)):
+    with mutation(request, caller) as value:
+        value.activate(request, caller.user_uid)
+        return value.descriptor(caller.user_uid, is_admin=caller.is_admin)
+
+
+@router.post("/destroy-local/", response_model=RuntimeBootstrapDescriptor)
+def destroy_local(body: DestroyLocalInput, request: Request, caller: AdmittedCaller = Depends(require_admin)):
+    if not request.app.state.runtime.config.local_mode:
+        raise HTTPException(403, "Database destruction is available only in Local mode.")
+    with mutation(request, caller) as value:
+        value.destroy_local(request, body.path, caller.user_uid)
+        return value.descriptor(caller.user_uid, is_admin=caller.is_admin)

api/app/configuration.py

@@ -0,0 +1,37 @@
+"""Deployment capabilities are code-owned configuration, never environment switches."""
+
+from pathlib import Path
+from typing import Literal
+
+import yaml
+from pydantic import BaseModel, ConfigDict, Field, StrictBool, StrictStr
+
+
+class LocalCredentialConfiguration(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True)
+    provider: Literal["native", "file"] = "native"
+    key_directory: Path | None = None
+
+
+class DeploymentConfiguration(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True)
+    local_mode_available: StrictBool = False
+    application_migration_providers: dict[StrictStr, StrictStr] = Field(default_factory=dict)
+    local_credentials: LocalCredentialConfiguration = Field(default_factory=LocalCredentialConfiguration)
+
+    @classmethod
+    def load(cls, path: Path | None = None):
+        selected = path or Path.cwd() / "configuration.yaml"
+        if not selected.exists():
+            if path is not None:
+                raise RuntimeError(f"Configuration file does not exist: {selected}")
+            return cls()
+        try:
+            values = yaml.safe_load(selected.read_text(encoding="utf-8"))
+            return cls.model_validate(values)
+        except (OSError, ValueError, yaml.YAMLError) as exc:
+            raise RuntimeError(f"Invalid deployment configuration: {selected}") from exc
+
+    def require_development(self):
+        if not self.local_mode_available:
+            raise RuntimeError("Local development is disabled by configuration.yaml.")