mainsequence 6.0.20__tar.gz → 6.0.22__tar.gz

{mainsequence-6.0.20/mainsequence.egg-info → mainsequence-6.0.22}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mainsequence
-Version: 6.0.20
+Version: 6.0.22
 Summary: Main Sequence SDK 
 Author-email: Main Sequence GmbH <dev@main-sequence.io>
 License-Expression: LicenseRef-MainSequence-Proprietary

{mainsequence-6.0.20 → mainsequence-6.0.22}/mainsequence/cli/api.py

@@ -4689,7 +4689,7 @@ def list_project_job_runs(
         ClientJobRun.ROOT_URL = root_url
 
         merged_filters = dict(filters or {})
-        merged_filters["job__uid"] = [str(job_uid)]
+        merged_filters["job__uid"] = str(job_uid)
         runs = ClientJobRun.filter(timeout=timeout, **merged_filters)
         out: list[dict[str, Any]] = []
         for run in runs:

{mainsequence-6.0.20 → mainsequence-6.0.22}/mainsequence/cli/cli.py

@@ -2163,7 +2163,8 @@ def _current_project_runtime_auth_env(backend_url: str) -> dict[str, str]:
     Return auth environment entries for local project `.env` provisioning.
 
     The output follows the active auth mode:
-    - runtime credential mode writes runtime credential keys and an exchanged access token
+    - a backend-injected runtime credential mode preserves its credential keys
+      and an exchanged access token
     - default JWT mode writes the current CLI session access/refresh token pair
     """
     if _runtime_credential_mode_enabled():
@@ -2308,9 +2309,11 @@ def login(
     Interactive login uses browser-based authentication and finishes with
     standard JWT access/refresh tokens persisted by the CLI.
 
-    If `MAINSEQUENCE_AUTH_MODE=runtime_credential`, login exchanges the
-    configured runtime credential for a short-lived access token instead of
-    opening the browser or persisting CLI JWT tokens.
+    When a backend-launched process already has
+    `MAINSEQUENCE_AUTH_MODE=runtime_credential`, login exchanges the injected
+    runtime credential for a short-lived access token instead of opening the
+    browser or persisting CLI JWT tokens. This is not a user branch/runtime
+    selection mechanism.
 
     Parameters
     ----------
@@ -2345,7 +2348,6 @@ def login(
     mainsequence login --access-token "$TOKEN" --refresh-token "$REFRESH"
     mainsequence login --access-token "$TOKEN" --refresh-token "$REFRESH" --backend http://127.0.0.1:8000 --projects-base mainsequence-dev
     mainsequence login --export
-    MAINSEQUENCE_AUTH_MODE=runtime_credential mainsequence login
     ```
     """
     using_jwt = bool((access_token or "").strip() or (refresh_token or "").strip())
@@ -9222,7 +9224,7 @@ def project_job_runs_list_cmd(
     """
     List runs for a specific job.
 
-    Uses SDK client `JobRun.filter(job__uid=[job_uid])` as the single source of truth.
+    Uses SDK client `JobRun.filter(job__uid=job_uid)` as the single source of truth.
 
     Examples
     --------

{mainsequence-6.0.20 → mainsequence-6.0.22}/mainsequence/cli/migrations.py

@@ -18,7 +18,6 @@ from mainsequence.client.metatables import (
     MetaTableMigrationConnectionRequest,
     TimeIndexMetaTable,
 )
-from mainsequence.client.metatables.core import _current_metatable_project_context
 from mainsequence.meta_tables.migrations import (
     AlembicMetaTableMigration,
     alembic_config_for_provider,
@@ -432,10 +431,8 @@ def _prepare_alembic_config(
     alembic_output: _AlembicOutput,
     prepare_provider_metatables: bool = True,
 ) -> tuple[Any, Any]:
-    project_context = _current_metatable_project_context()
     _emit_status("Ensuring Alembic registry MetaTable...")
     registry_meta_table = migration.ensure_alembic_registry(
-        project_context=project_context,
         timeout=timeout,
         on_metatable_reserved=_emit_metatable_reservation,
     )
@@ -443,7 +440,6 @@ def _prepare_alembic_config(
     if prepare_provider_metatables:
         _emit_status("Preparing platform-managed MetaTable reservations...")
         prepared = migration.prepare_for_alembic(
-            project_context=project_context,
             timeout=timeout,
             on_metatable_reservation_request=_emit_metatable_reservation_request,
             on_metatable_reservation_status=_emit_status,
@@ -455,7 +451,6 @@ def _prepare_alembic_config(
             data_source_uid=migration._resolve_provider_data_source_uid(),
             meta_table_uids=[],
             owner_role_name=None,
-            project_context=project_context,
         )
     _emit_status(
         "Prepared migration scope "
@@ -472,7 +467,6 @@ def _prepare_alembic_config(
             migration_namespace=migration.migration_namespace,
             migration_provider_key=migration.migration_provider_key,
             ttl_seconds=ttl_seconds,
-            project_context=prepared.project_context,
         ),
         timeout=timeout,
     )
@@ -501,10 +495,8 @@ def _build_revision_alembic_config(
     _emit_status("Building local Alembic config for revision...")
     owner_role_name = None
     if requires_database and sqlalchemy_url in (None, ""):
-        project_context = _current_metatable_project_context()
         _emit_status("Ensuring Alembic registry MetaTable for revision...")
         registry_meta_table = migration.ensure_alembic_registry(
-            project_context=project_context,
             timeout=timeout,
             on_metatable_reserved=_emit_metatable_reservation,
         )
@@ -518,7 +510,6 @@ def _build_revision_alembic_config(
                 migration_namespace=migration.migration_namespace,
                 migration_provider_key=migration.migration_provider_key,
                 ttl_seconds=ttl_seconds,
-                project_context=project_context,
             ),
             timeout=timeout,
         )

{mainsequence-6.0.20 → mainsequence-6.0.22}/mainsequence/client/metatables/core.py

@@ -31,6 +31,7 @@ from pydantic import (
 )
 
 from mainsequence.logconf import logger
+from mainsequence.runtime_context import _get_backend_runtime_project_context_state
 
 from ..base import BaseObjectOrm, BasePydanticModel, LabelableObjectMixin, ShareableObjectMixin
 from ..data_sources_interfaces import get_duckdb_interface_class, get_sqlite_interface_class
@@ -53,6 +54,7 @@ from ..utils import (
     bios_uuid,
     get_network_ip,
     is_process_running,
+    loaders,
     make_request,
     serialize_to_json,
 )
@@ -868,7 +870,6 @@ class ManagedMetaTableCollectionCreateRow(BasePydanticModel):
     physical_schema: str = Field(..., min_length=1)
     physical_table_name: str = Field(..., min_length=1)
     protect_from_deletion: bool = False
-    project_context: MetaTableProjectContextRequest
     table_contract: dict[str, Any]
 
     @model_validator(mode="before")
@@ -930,7 +931,6 @@ class MetaTableMigrationConnectionRequest(BasePydanticModel):
     migration_namespace: str = ""
     migration_provider_key: str = ""
     ttl_seconds: int = Field(default=900, ge=60, le=3600)
-    project_context: MetaTableProjectContextRequest | None = None
 
 
 class MetaTableMigrationConnection(BasePydanticModel):
@@ -947,7 +947,6 @@ class MetaTableMigrationConnection(BasePydanticModel):
 
 
 class ManagedMetaTableFinalizeRequest(BasePydanticModel):
-    project_context: MetaTableProjectContextRequest | None = None
     meta_table_uids: list[str] = Field(
         ...,
         min_length=1,
@@ -1406,10 +1405,7 @@ class MetaTable(BasePydanticModel, LabelableObjectMixin, ShareableObjectMixin, B
         )
         if isinstance(payload, Mapping):
             payload = MetaTableMigrationConnectionRequest(**payload)
-        if payload.project_context is None:
-            payload = payload.model_copy(
-                update={"project_context": _current_metatable_project_context()}
-            )
+        payload = _with_current_metatable_project_context(payload)
         response = self._post_detail_action(
             "migration-connection",
             payload,
@@ -1597,13 +1593,13 @@ class MetaTable(BasePydanticModel, LabelableObjectMixin, ShareableObjectMixin, B
         if request is not None and kwargs:
             raise ValueError("Pass either request or keyword fields, not both.")
         unvalidated_payload = _payload_json(request) if request is not None else dict(kwargs)
-        project_context = unvalidated_payload.pop("project_context", None)
+        if "project_context" in unvalidated_payload:
+            raise ValueError(
+                "project_context is SDK-controlled and cannot be supplied by the caller."
+            )
         payload = MetaTableRegistrationRequest.model_validate(unvalidated_payload)
         if payload.management_mode != "external_registered":
-            payload_json = _payload_json(payload)
-            if project_context is not None:
-                payload_json["project_context"] = project_context
-            payload = _with_current_metatable_project_context(payload_json)
+            payload = _with_current_metatable_project_context(payload)
         response_json = cls._post_action(
             "register",
             payload,
@@ -1624,10 +1620,10 @@ class MetaTable(BasePydanticModel, LabelableObjectMixin, ShareableObjectMixin, B
         if on_status is not None:
             on_status(f"Serializing POST {url} payload...")
         payload_json = _payload_json_sequence(rows)
-        payload_json = _with_current_metatable_project_context_collection(payload_json)
         _ = [
             cls.COLLECTION_CREATE_ROW_MODEL.model_validate(row) for row in payload_json
         ]
+        payload_json = _with_current_metatable_project_context_collection(payload_json)
         if on_status is not None:
             payload_size = len(json.dumps(payload_json, default=str))
             on_status(f"Serialized POST {url} payload bytes={payload_size}.")
@@ -1667,10 +1663,7 @@ class MetaTable(BasePydanticModel, LabelableObjectMixin, ShareableObjectMixin, B
         payload = request if request is not None else ManagedMetaTableFinalizeRequest(**kwargs)
         if isinstance(payload, Mapping):
             payload = ManagedMetaTableFinalizeRequest(**payload)
-        if payload.project_context is None:
-            payload = payload.model_copy(
-                update={"project_context": _current_metatable_project_context()}
-            )
+        payload = _with_current_metatable_project_context(payload)
         response_json = cls._post_action(
             "finalize-managed",
             payload,
@@ -2458,15 +2451,26 @@ class DataNodeUpdate(TableUpdateNode, BaseObjectOrm):
     @classmethod
     def get_or_create(cls, **kwargs):
         url = cls.get_object_url() + "/get-or-create/"
+        if "current_project_branch_uid" in kwargs:
+            raise ValueError(
+                "current_project_branch_uid is SDK-controlled and cannot be supplied "
+                "by the caller."
+            )
         kwargs = serialize_to_json(kwargs)
-        project_branch = _require_local_pod_project_branch("DataNodeUpdate.get_or_create")
+        resolution = _resolve_local_pod_project()
+        project_branch = resolution.project_branch
+        if project_branch is None:
+            project_branch = _require_local_pod_project_branch(
+                "DataNodeUpdate.get_or_create"
+            )
         project_branch_uid = str(getattr(project_branch, "uid", "") or "").strip()
         if not project_branch_uid:
             raise RuntimeError(
                 "DataNodeUpdate.get_or_create requires a ProjectBranch uid, "
                 "but the active branch does not expose one."
             )
-        kwargs["current_project_branch_uid"] = project_branch_uid
+        if not resolution.backend_runtime_context:
+            kwargs["current_project_branch_uid"] = project_branch_uid
         payload = {"json": kwargs}
         s = cls.build_session()
         r = make_request(s=s, loaders=cls.LOADERS, r_type="POST", url=url, payload=payload)
@@ -3406,14 +3410,14 @@ class TimeIndexMetaTable(MetaTable):
         if request is not None and kwargs:
             raise ValueError("Pass either request or keyword fields, not both.")
         unvalidated_payload = _payload_json(request) if request is not None else dict(kwargs)
-        project_context = unvalidated_payload.pop("project_context", None)
+        if "project_context" in unvalidated_payload:
+            raise ValueError(
+                "project_context is SDK-controlled and cannot be supplied by the caller."
+            )
         payload = TimeIndexMetaTableRegistrationRequest.model_validate(
             unvalidated_payload
         )
-        payload_json = _payload_json(payload)
-        if project_context is not None:
-            payload_json["project_context"] = project_context
-        payload_json = _with_current_metatable_project_context(payload_json)
+        payload_json = _with_current_metatable_project_context(payload)
         request_payload = {"json": serialize_to_json(payload_json)}
         response = make_request(
             s=cls.build_session(),
@@ -4780,6 +4784,7 @@ class _PodProjectResolution:
     repository_branch: str | None
     status: str
     detail: str = ""
+    backend_runtime_context: bool = False
 
     @property
     def remote_cache_key(self) -> tuple[str, str, str]:
@@ -4808,11 +4813,9 @@ def _reset_local_pod_project_resolution_cache() -> None:
 
 def _current_repository_branch() -> str | None:
     runtime_auth_mode = (os.environ.get("MAINSEQUENCE_AUTH_MODE") or "").strip()
-    runtime_project_branch_uid = (
-        os.environ.get("MAIN_SEQUENCE_PROJECT_BRANCH_UID") or ""
-    ).strip()
-    if runtime_project_branch_uid:
-        return (os.environ.get("MAINSEQUENCE_REPOSITORY_BRANCH") or "").strip() or None
+    runtime_state = _get_backend_runtime_project_context_state()
+    if runtime_state.verified and runtime_state.context is not None:
+        return runtime_state.context.repository_branch
     if runtime_auth_mode in {"session_jwt", "runtime_credential"}:
         return None
     try:
@@ -4837,11 +4840,11 @@ def _build_local_pod_project_resolution(
     running_project_uid: str,
     running_project_branch_uid: str = "",
     repository_branch: str | None,
+    backend_runtime_context: bool = False,
 ) -> _PodProjectResolution:
     from ..models_foundry import Project, ProjectBranch
 
-    runtime_auth_mode = (os.environ.get("MAINSEQUENCE_AUTH_MODE") or "").strip()
-    if runtime_auth_mode in {"session_jwt", "runtime_credential"} and (
+    if backend_runtime_context and (
         not running_project_uid or not running_project_branch_uid
     ):
         return _PodProjectResolution(
@@ -4855,6 +4858,7 @@ def _build_local_pod_project_resolution(
                 "Deployed runtime authentication did not provide a complete "
                 "backend-issued ProjectBranch context."
             ),
+            backend_runtime_context=True,
         )
 
     if not running_project_uid:
@@ -4994,6 +4998,7 @@ def _build_local_pod_project_resolution(
         project_branch=project_branch,
         repository_branch=resolved_repository_branch,
         status="resolved",
+        backend_runtime_context=backend_runtime_context,
     )
 
 
@@ -5001,11 +5006,29 @@ def _resolve_local_pod_project(*, refresh: bool = False) -> _PodProjectResolutio
     global _POD_PROJECT_RESOLUTION_CACHE, _POD_PROJECT_RESOLUTION_CACHE_KEY
     global POD_PROJECT, POD_PROJECT_BRANCH
 
-    running_project_uid = (os.environ.get("MAIN_SEQUENCE_PROJECT_UID") or "").strip()
-    running_project_branch_uid = (
-        os.environ.get("MAIN_SEQUENCE_PROJECT_BRANCH_UID") or ""
-    ).strip()
-    repository_branch = _current_repository_branch()
+    runtime_auth_mode = (os.environ.get("MAINSEQUENCE_AUTH_MODE") or "").strip()
+    runtime_state = _get_backend_runtime_project_context_state()
+    if runtime_auth_mode == "runtime_credential" and not runtime_state.verified:
+        loaders.refresh_headers()
+        runtime_state = _get_backend_runtime_project_context_state()
+
+    backend_runtime_context = runtime_auth_mode in {
+        "session_jwt",
+        "runtime_credential",
+    }
+    runtime_context = runtime_state.context if runtime_state.verified else None
+    if backend_runtime_context and runtime_context is not None:
+        running_project_uid = runtime_context.project_uid
+        running_project_branch_uid = runtime_context.project_branch_uid
+        repository_branch = runtime_context.repository_branch
+    elif backend_runtime_context:
+        running_project_uid = ""
+        running_project_branch_uid = ""
+        repository_branch = None
+    else:
+        running_project_uid = (os.environ.get("MAIN_SEQUENCE_PROJECT_UID") or "").strip()
+        running_project_branch_uid = ""
+        repository_branch = _current_repository_branch()
     cache_key = (
         running_project_uid,
         running_project_branch_uid,
@@ -5022,6 +5045,7 @@ def _resolve_local_pod_project(*, refresh: bool = False) -> _PodProjectResolutio
                 running_project_uid=running_project_uid,
                 running_project_branch_uid=running_project_branch_uid,
                 repository_branch=repository_branch,
+                backend_runtime_context=backend_runtime_context,
             )
             _POD_PROJECT_RESOLUTION_CACHE_KEY = cache_key
             POD_PROJECT = _POD_PROJECT_RESOLUTION_CACHE.project
@@ -5089,18 +5113,28 @@ def _current_metatable_project_context() -> MetaTableProjectContextRequest:
     return _metatable_project_context_from_resolution(_resolve_local_pod_project())
 
 
+def _metatable_project_context_for_request() -> MetaTableProjectContextRequest | None:
+    resolution = _resolve_local_pod_project()
+    if resolution.backend_runtime_context:
+        if resolution.project_branch is None:
+            _metatable_project_context_from_resolution(resolution)
+        return None
+    return _current_metatable_project_context()
+
+
 def _with_current_metatable_project_context(
     payload: Mapping[str, Any] | BasePydanticModel,
 ) -> dict[str, Any]:
     payload_json = _payload_json(payload)
+    if "project_context" in payload_json:
+        raise ValueError(
+            "project_context is SDK-controlled and cannot be supplied by the caller."
+        )
     if payload_json.get("management_mode") == "external_registered":
         return payload_json
-    project_context = payload_json.get("project_context")
-    if project_context is None:
-        project_context = _current_metatable_project_context()
-    else:
-        project_context = MetaTableProjectContextRequest.model_validate(project_context)
-    payload_json["project_context"] = project_context.model_dump(mode="json")
+    project_context = _metatable_project_context_for_request()
+    if project_context is not None:
+        payload_json["project_context"] = project_context.model_dump(mode="json")
     return payload_json
 
 
@@ -5108,25 +5142,21 @@ def _with_current_metatable_project_context_collection(
     payloads: Sequence[Mapping[str, Any]],
 ) -> list[dict[str, Any]]:
     payload_rows = [dict(payload) for payload in payloads]
+    if any("project_context" in row for row in payload_rows):
+        raise ValueError(
+            "project_context is SDK-controlled and cannot be supplied by the caller."
+        )
     managed_rows = [
         row for row in payload_rows if row.get("management_mode") != "external_registered"
     ]
     if not managed_rows:
         return payload_rows
 
-    current_project_context: dict[str, str] | None = None
-    for row in managed_rows:
-        project_context = row.get("project_context")
-        if project_context is None:
-            if current_project_context is None:
-                current_project_context = _current_metatable_project_context().model_dump(
-                    mode="json"
-                )
+    project_context = _metatable_project_context_for_request()
+    if project_context is not None:
+        current_project_context = project_context.model_dump(mode="json")
+        for row in managed_rows:
             row["project_context"] = current_project_context
-        else:
-            row["project_context"] = MetaTableProjectContextRequest.model_validate(
-                project_context
-            ).model_dump(mode="json")
     return payload_rows
 
 

{mainsequence-6.0.20 → mainsequence-6.0.22}/mainsequence/client/utils.py

@@ -23,6 +23,11 @@ from urllib3.util.retry import Retry
 
 from mainsequence.defaults import resolve_backend_endpoint
 from mainsequence.logconf import logger
+from mainsequence.runtime_context import (
+    BackendRuntimeProjectContextError,
+    _get_backend_runtime_project_context_state,
+    _install_backend_runtime_project_context,
+)
 
 # ---- Backend defaults (single source of truth) ----
 MAINSEQUENCE_ENDPOINT = resolve_backend_endpoint()
@@ -62,40 +67,16 @@ class AuthError(Exception):
     pass
 
 
-RUNTIME_PROJECT_CONTEXT_ENV = {
-    "project_uid": "MAIN_SEQUENCE_PROJECT_UID",
-    "project_branch_uid": "MAIN_SEQUENCE_PROJECT_BRANCH_UID",
-    "repository_branch": "MAINSEQUENCE_REPOSITORY_BRANCH",
-    "organization_project_environment_uid": (
-        "MAIN_SEQUENCE_ORGANIZATION_PROJECT_ENVIRONMENT_UID"
-    ),
-}
-
-
-def apply_runtime_project_context(payload: object) -> None:
+def _apply_runtime_project_context_from_exchange(payload: object) -> None:
     if not isinstance(payload, dict):
-        return
-    context = payload.get("runtime_project_context")
-    if context is None:
-        return
-    if not isinstance(context, dict):
-        raise AuthError("runtime_project_context must be an object.")
-    missing = [key for key in RUNTIME_PROJECT_CONTEXT_ENV if not context.get(key)]
-    if missing:
-        raise AuthError(
-            "runtime_project_context is incomplete: " + ", ".join(sorted(missing))
+        raise AuthError("Runtime credential exchange response must be an object.")
+    try:
+        _install_backend_runtime_project_context(
+            payload,
+            source="runtime_credential_exchange",
         )
-    for key, environment_name in RUNTIME_PROJECT_CONTEXT_ENV.items():
-        expected = str(context[key])
-        current = str(os.environ.get(environment_name) or "").strip()
-        if current and current != expected:
-            raise AuthError(
-                "runtime_project_context does not match the existing deployed "
-                f"context for {key}."
-            )
-    for key, environment_name in RUNTIME_PROJECT_CONTEXT_ENV.items():
-        expected = str(context[key])
-        os.environ[environment_name] = expected
+    except BackendRuntimeProjectContextError as exc:
+        raise AuthError(str(exc)) from exc
 
 
 def set_mainsequence_endpoint(endpoint: str) -> None:
@@ -238,6 +219,8 @@ class RuntimeCredentialAuthProvider(BaseAuthProvider):
         return (os.getenv("MAINSEQUENCE_ACCESS_TOKEN") or "").strip() or None
 
     def _needs_exchange(self) -> bool:
+        if not _get_backend_runtime_project_context_state().verified:
+            return True
         access_token = self._current_access_token()
         if not access_token:
             return True
@@ -294,7 +277,7 @@ class RuntimeCredentialAuthProvider(BaseAuthProvider):
                 )
 
             data = response.json()
-            apply_runtime_project_context(data)
+            _apply_runtime_project_context_from_exchange(data)
             access = str(data.get("access") or "").strip()
             if not access:
                 raise AuthError(

{mainsequence-6.0.20 → mainsequence-6.0.22}/mainsequence/logconf.py

@@ -21,42 +21,26 @@ from structlog.stdlib import BoundLogger
 
 from .defaults import resolve_backend_endpoint
 from .instrumentation import OTelJSONRenderer
+from .runtime_context import (
+    RUNTIME_PROJECT_CONTEXT_ENV,
+    BackendRuntimeContextSource,
+    BackendRuntimeProjectContextError,
+    _get_backend_runtime_project_context_state,
+    _install_backend_runtime_project_context,
+)
 from .runtime_flags import is_running_in_pod
 
 logger = None
 
-RUNTIME_PROJECT_CONTEXT_ENV = {
-    "project_uid": "MAIN_SEQUENCE_PROJECT_UID",
-    "project_branch_uid": "MAIN_SEQUENCE_PROJECT_BRANCH_UID",
-    "repository_branch": "MAINSEQUENCE_REPOSITORY_BRANCH",
-    "organization_project_environment_uid": (
-        "MAIN_SEQUENCE_ORGANIZATION_PROJECT_ENVIRONMENT_UID"
-    ),
-}
-
-
-def _apply_runtime_project_context(payload: Mapping[str, Any]) -> None:
-    context = payload.get("runtime_project_context")
-    if context is None:
-        return
-    if not isinstance(context, Mapping):
-        raise RuntimeError("runtime_project_context must be an object.")
-    missing = [key for key in RUNTIME_PROJECT_CONTEXT_ENV if not context.get(key)]
-    if missing:
-        raise RuntimeError(
-            "runtime_project_context is incomplete: " + ", ".join(sorted(missing))
-        )
-    for key, environment_name in RUNTIME_PROJECT_CONTEXT_ENV.items():
-        expected = str(context[key])
-        current = str(os.environ.get(environment_name) or "").strip()
-        if current and current != expected:
-            raise RuntimeError(
-                "runtime_project_context does not match the existing deployed "
-                f"context for {key}."
-            )
-    for key, environment_name in RUNTIME_PROJECT_CONTEXT_ENV.items():
-        expected = str(context[key])
-        os.environ[environment_name] = expected
+def _apply_runtime_project_context(
+    payload: Mapping[str, Any],
+    *,
+    source: BackendRuntimeContextSource,
+) -> None:
+    try:
+        _install_backend_runtime_project_context(payload, source=source)
+    except BackendRuntimeProjectContextError as exc:
+        raise RuntimeError(str(exc)) from exc
 
 
 def _get_sdk_version() -> str:
@@ -157,7 +141,7 @@ def _request_job_startup_state(*, timeout_s: float = 10.0) -> dict[str, Any]:
         if not access_token:
             return False
 
-        _apply_runtime_project_context(data)
+        _apply_runtime_project_context(data, source="runtime_credential_exchange")
         os.environ["MAINSEQUENCE_ACCESS_TOKEN"] = access_token
         return True
 
@@ -256,7 +240,8 @@ def _apply_additional_environment(startup_state: Mapping[str, Any]) -> None:
             "runtime_project_context_missing: JobRun startup state did not "
             "include backend-issued ProjectBranch context."
         )
-    _apply_runtime_project_context(startup_state)
+    if "runtime_project_context" in startup_state:
+        _apply_runtime_project_context(startup_state, source="job_run_startup")
     extra = startup_state.get("additional_environment")
     if isinstance(extra, dict):
         for k, v in extra.items():
@@ -274,11 +259,10 @@ def _build_backend_bindings(
         "job_run_uid": startup_state.get("job_run_uid"),
         "command_id": startup_state.get("command_id"),
     }
-    runtime_context = startup_state.get("runtime_project_context")
-    if not isinstance(runtime_context, Mapping):
-        runtime_context = {}
-    for field, environment_name in RUNTIME_PROJECT_CONTEXT_ENV.items():
-        bindings[field] = runtime_context.get(field) or os.environ.get(environment_name)
+    runtime_state = _get_backend_runtime_project_context_state()
+    runtime_context = runtime_state.context.as_dict() if runtime_state.context else {}
+    for field in RUNTIME_PROJECT_CONTEXT_ENV:
+        bindings[field] = runtime_context.get(field)
 
     if not bindings.get("project_branch_uid"):
         if "user_id" in startup_state: