simulo 0.26.0__py3-none-any.whl

simulo/_client/config.py

@@ -0,0 +1,186 @@
+"""Base-URL + login-endpoint resolution for the cloud submit surface (stdlib only).
+
+Every HTTP-talking module in the thin client (``jobs_api``, ``submit_api``, ``login``)
+resolves "where is the platform?" through this module so the precedence rule is
+defined exactly once. Resolution order for the API base URL:
+
+1. ``SIMULO_API_URL`` — an explicit override always wins.
+2. ``SIMULO_ENV`` (``staging``/``prod``) — a named-environment preset.
+3. ``api_base_url`` recorded in ``~/.simulo/credentials`` at login time (the URL
+   the user last logged in against).
+4. The production preset (``https://api.simulo.ai``) — the cloud is the default
+   target, so a bare ``simulo login`` signs in to production. The local
+   stand-in (``simulo-backend serve``,
+   ``http://127.0.0.1:<JOBS_API_DEFAULT_PORT>``) is targeted EXPLICITLY
+   (``SIMULO_API_URL=http://127.0.0.1:8765``) — never by default.
+
+This bottom-of-the-chain default decides only WHERE resolution points once a
+cloud call is being made — it is NOT a cloud *signal*. The offline-vs-cloud
+submit decision (``JobFunction.spawn``) keys off :func:`has_explicit_cloud_env`
+(is ``SIMULO_API_URL``/``SIMULO_ENV`` actually SET?) and saved credentials, so
+a bare ``simulo run`` with no login still writes a local package and never
+auto-submits to production.
+
+Named-environment presets mirror the (pydantic-based) ``simulo.cli.config``
+presets in the ``simulo-backend`` parked CLI 1:1 — the two clients log in
+against the same Cognito app clients and the same control plane, so the
+values must never drift between the two implementations.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from typing import Any, Mapping, Optional
+
+from simulo.interfaces.platform.runs import JOBS_API_DEFAULT_PORT
+
+#: Explicit API base-URL override. Highest precedence.
+API_URL_ENV = "SIMULO_API_URL"
+#: Named-environment preset selector (``staging``/``prod``).
+ENV_PRESET_ENV = "SIMULO_ENV"
+#: Explicit local-only override — ``SIMULO_SUBMIT=local`` forces offline submit
+#: even when credentials or ``SIMULO_API_URL``/``SIMULO_ENV`` are present.
+SUBMIT_MODE_ENV = "SIMULO_SUBMIT"
+#: Value of :data:`SUBMIT_MODE_ENV` that forces offline (local-disk) submit.
+SUBMIT_MODE_LOCAL = "local"
+
+COGNITO_HOSTED_UI_ENV = "SIMULO_COGNITO_HOSTED_UI"
+CLI_APP_CLIENT_ID_ENV = "SIMULO_CLI_APP_CLIENT_ID"
+CONSOLE_BASE_URL_ENV = "SIMULO_CONSOLE_BASE_URL"
+
+#: The local stand-in (``simulo-backend serve``). NOT a resolution default —
+#: local dev targets it explicitly (``SIMULO_API_URL=http://127.0.0.1:8765``).
+LOCAL_DEFAULT_BASE_URL = f"http://127.0.0.1:{JOBS_API_DEFAULT_PORT}"
+
+# Mirrors simulo-backend's sdk/src/simulo/cli/config.py _ENV_PRESETS exactly —
+# the two clients share one Cognito app-client-id set per environment. Every
+# preset MUST define all four keys: resolve_login_settings indexes them
+# directly (a partial preset should fail loudly, not fall back silently).
+_ENV_PRESETS: Mapping[str, Mapping[str, str]] = {
+    "staging": {
+        "api_base_url": "https://api.staging.simulo.ai",
+        "cognito_hosted_ui": "https://auth.staging.simulo.ai",
+        "cli_app_client_id": "284of1ali7881488nc9n26jskt",
+        "console_base_url": "https://console.staging.simulo.ai",
+    },
+    "prod": {
+        "api_base_url": "https://api.simulo.ai",
+        "cognito_hosted_ui": "https://auth.simulo.ai",
+        "cli_app_client_id": "1dc72f0scqbtguj66b74k8a244",
+        "console_base_url": "https://console.simulo.ai",
+    },
+}
+
+#: The preset used when ``SIMULO_ENV`` is unset/empty: production. A bare
+#: ``simulo login`` signs in to the real cloud; every explicit signal —
+#: ``SIMULO_API_URL``, ``SIMULO_ENV``, the individual login env vars above,
+#: and the login-time ``api_base_url`` recorded in the credentials file —
+#: wins over this default. It plays NO part in the offline-vs-cloud submit
+#: decision (see :func:`has_explicit_cloud_env` and the module docstring).
+DEFAULT_ENV_PRESET = "prod"
+
+
+class UnknownEnvPresetError(ValueError):
+    """``SIMULO_ENV`` was set to a value that is not a known preset."""
+
+
+def _preset() -> Optional[Mapping[str, str]]:
+    """Return the active ``SIMULO_ENV`` preset dict, or ``None`` if unset."""
+    raw = os.environ.get(ENV_PRESET_ENV, "").strip().lower()
+    if not raw:
+        return None
+    preset = _ENV_PRESETS.get(raw)
+    if preset is None:
+        raise UnknownEnvPresetError(
+            f"Unknown {ENV_PRESET_ENV} value: {os.environ.get(ENV_PRESET_ENV)!r}. "
+            f"Supported values: {sorted(_ENV_PRESETS)}"
+        )
+    return preset
+
+
+def resolve_base_url(credentials: Optional[Mapping[str, Any]] = None) -> str:
+    """Resolve the API base URL: env override -> env preset -> credentials -> the prod default.
+
+    Credentials outrank the trailing production default deliberately: after
+    ``SIMULO_ENV=staging simulo login``, a bare ``simulo run``/``simulo jobs``
+    (no env vars set) must keep targeting the platform the user logged in
+    against, not jump to production.
+    """
+    explicit = os.environ.get(API_URL_ENV)
+    if explicit:
+        return explicit
+    preset = _preset()
+    if preset is not None and preset.get("api_base_url"):
+        return preset["api_base_url"]
+    if credentials is not None:
+        from_creds = credentials.get("api_base_url")
+        if isinstance(from_creds, str) and from_creds:
+            return from_creds
+    return _ENV_PRESETS[DEFAULT_ENV_PRESET]["api_base_url"]
+
+
+def resolve_console_base_url(credentials: Optional[Mapping[str, Any]] = None) -> str:
+    """Resolve the console base URL: env override -> env preset -> credentials -> the prod default.
+
+    Mirrors :func:`resolve_base_url` exactly, field-for-field. Used by the
+    login flow (``login.py``) to build the OAuth loopback ``redirect_uri``
+    when no local loopback port can be bound, and to record the console
+    origin the user authenticated against in ``~/.simulo/credentials``.
+
+    Also used by ``simulo asset`` output (via ``cli._asset_console_base_url``)
+    to resolve the base URL for its console deep link — a staging-logged-in
+    user must never see a production console link. That deep link is printed
+    only when ``cli._console_reachable`` confirms the console is actually
+    up — never a dead link to a console that isn't running/deployed.
+    """
+    explicit = os.environ.get(CONSOLE_BASE_URL_ENV)
+    if explicit:
+        return explicit
+    preset = _preset()
+    if preset is not None and preset.get("console_base_url"):
+        return preset["console_base_url"]
+    if credentials is not None:
+        from_creds = credentials.get("console_base_url")
+        if isinstance(from_creds, str) and from_creds:
+            return from_creds
+    return _ENV_PRESETS[DEFAULT_ENV_PRESET]["console_base_url"]
+
+
+def is_submit_forced_local() -> bool:
+    """``True`` when ``SIMULO_SUBMIT=local`` explicitly disables cloud submit."""
+    return os.environ.get(SUBMIT_MODE_ENV, "").strip().lower() == SUBMIT_MODE_LOCAL
+
+
+def has_explicit_cloud_env() -> bool:
+    """``True`` when ``SIMULO_API_URL`` or ``SIMULO_ENV`` names a cloud target explicitly."""
+    return bool(os.environ.get(API_URL_ENV)) or bool(os.environ.get(ENV_PRESET_ENV))
+
+
+@dataclass(frozen=True)
+class LoginSettings:
+    """Resolved settings for the ``simulo login`` PKCE flow."""
+
+    api_base_url: str
+    cognito_hosted_ui: str
+    cli_app_client_id: str
+    console_base_url: str
+
+
+def resolve_login_settings() -> LoginSettings:
+    """Resolve login-flow settings: individual env vars win over the ``SIMULO_ENV`` preset (prod when unset).
+
+    A bare ``simulo login`` therefore signs in to the production cloud. Local
+    dev keeps working unchanged because it sets the individual env vars
+    explicitly (``SIMULO_API_URL`` / ``SIMULO_CLI_APP_CLIENT_ID`` /
+    ``SIMULO_COGNITO_HOSTED_UI`` / ``SIMULO_CONSOLE_BASE_URL`` — see
+    ``scripts/dev-local-env.sh`` and demos/WALKTHROUGH.md Part 1), and those
+    are checked FIRST, field by field.
+    """
+    preset = _preset() or _ENV_PRESETS[DEFAULT_ENV_PRESET]
+    return LoginSettings(
+        api_base_url=os.environ.get(API_URL_ENV) or preset["api_base_url"],
+        cognito_hosted_ui=os.environ.get(COGNITO_HOSTED_UI_ENV) or preset["cognito_hosted_ui"],
+        cli_app_client_id=os.environ.get(CLI_APP_CLIENT_ID_ENV) or preset["cli_app_client_id"],
+        console_base_url=os.environ.get(CONSOLE_BASE_URL_ENV) or preset["console_base_url"],
+    )

simulo/_client/credentials.py

@@ -0,0 +1,210 @@
+"""Credentials file helpers — ``~/.simulo/credentials`` (mode 0600).
+
+Mirrors the credentials file format the ``simulo-backend`` parked CLI writes
+(``simulo.cli.auth.credentials``)
+field-for-field, plus one addition: ``api_base_url``, the base URL this
+client logged in against (so a bare ``simulo jobs`` on a laptop that only ever
+ran ``SIMULO_ENV=staging simulo login`` still targets staging without the env
+var set on every subsequent invocation — see ``config.resolve_base_url``).
+
+Credentials file schema (version 1)::
+
+    {
+        "version": 1,
+        "access_token": "<jwt>",
+        "refresh_token": "<opaque>",
+        "expires_at": "2026-04-24T15:00:00Z",
+        "active_organization_id": "<org-uuid>",
+        "user_email": "user@example.com",
+        "api_base_url": "https://api.staging.simulo.ai"
+    }
+
+Field names are canonical — do NOT rename without also updating
+``cli-auth/SKILL.md`` and the ``simulo-backend`` CLI's own credentials module.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import stat
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+from typing import Any, Optional
+
+from simulo._client import config, http
+
+CREDENTIALS_PATH = Path.home() / ".simulo" / "credentials"
+
+#: Refresh path is on the client-facing control plane, not a routes-module
+#: constant (it belongs to the identity/auth surface, not the submit/runs
+#: contract) — see ``.claude/skills/cli-auth/SKILL.md`` Control-Plane Endpoints.
+TOKEN_REFRESH_PATH = "/auth/token/refresh"
+
+#: Refresh a token this many seconds before its recorded expiry, to absorb the
+#: round-trip latency of the call that is about to use it.
+_EXPIRY_SKEW_S = 30.0
+
+
+def _posix_permissions_enforced() -> bool:
+    """Whether POSIX file-mode bits are meaningful (and enforced) here.
+
+    On Windows (``os.name == "nt"``) ``os.chmod`` can only toggle the
+    read-only flag and ``st_mode`` reports ``0o666`` for any writable file —
+    the group/other bits can never be cleared, so a mode check would always
+    reject the very file :func:`save_credentials` just wrote (P1, 2026-07-11:
+    ``simulo login`` succeeded and then every credential-using command was
+    permanently locked out, with a ``chmod`` remedy that does not exist on
+    Windows). Windows protects ``%USERPROFILE%`` with ACLs instead, so both
+    the trailing ``chmod`` in :func:`save_credentials` and the fail-loud mode
+    check in :func:`load_credentials` are skipped there. On every POSIX
+    platform the 0600 write + unsafe-permissions check are a real security
+    invariant and behave exactly as before.
+    """
+    return os.name != "nt"
+
+
+class CredentialsError(RuntimeError):
+    """Base error for the local credentials file: missing, unsafe, or malformed."""
+
+
+class TokenRefreshError(CredentialsError):
+    """Silent refresh of an expired access token failed."""
+
+    def __init__(self, message: str, *, code: Optional[str] = None) -> None:
+        super().__init__(message)
+        self.code = code
+
+
+def save_credentials(data: dict[str, Any]) -> None:
+    """Write *data* to the credentials file with mode 0600, atomically.
+
+    Creates the parent directory (``~/.simulo``) with mode 0700 if absent.
+    Opens the file via ``os.open`` with the target mode passed at creation
+    time (rather than ``write_text`` followed by a separate ``chmod``) so the
+    file's permissions are 0600 from the instant it is created — never a
+    world/group-readable file for however brief a window before the chmod
+    call lands (a TOCTOU gap another local process could win). The trailing
+    ``chmod`` still runs because ``os.open``'s ``mode`` argument only applies
+    when the file is newly created (an overwrite of a pre-existing file
+    ignores it, and is also masked by ``umask`` in either case).
+
+    On Windows the trailing ``chmod`` is skipped (`_posix_permissions_enforced`):
+    mode bits cannot express owner-only there, and the file is protected by the
+    user profile's ACLs instead — the loader's mode check is skipped to match.
+    (``os.open``'s mode and ``mkdir``'s mode are harmless no-ops on Windows and
+    stay unconditional.)
+    """
+    CREDENTIALS_PATH.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
+    payload = json.dumps(data, indent=2)
+    fd = os.open(CREDENTIALS_PATH, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+    with os.fdopen(fd, "w") as handle:
+        handle.write(payload)
+    if _posix_permissions_enforced():
+        CREDENTIALS_PATH.chmod(0o600)
+
+
+def credentials_file_exists() -> bool:
+    """``True`` when a credentials file is present (no permission check)."""
+    return CREDENTIALS_PATH.exists()
+
+
+def load_credentials() -> dict[str, Any]:
+    """Read and return the credentials dict.
+
+    Fails loudly (:class:`CredentialsError`) if:
+    - the file does not exist (not logged in)
+    - the file has group- or world-readable permissions (security invariant;
+      POSIX only — on Windows ``st_mode`` reports ``0o666`` for any writable
+      file and ``chmod`` cannot clear the group/other bits, so the check is
+      meaningless there and is skipped: see `_posix_permissions_enforced`)
+    """
+    if not CREDENTIALS_PATH.exists():
+        raise CredentialsError("Not logged in. Run: simulo login")
+    if _posix_permissions_enforced():
+        mode = CREDENTIALS_PATH.stat().st_mode
+        if mode & (stat.S_IRWXG | stat.S_IRWXO):
+            raise CredentialsError(
+                f"Credentials file {CREDENTIALS_PATH} has unsafe permissions. Run: chmod 600 {CREDENTIALS_PATH}"
+            )
+    loaded: Any = json.loads(CREDENTIALS_PATH.read_text())
+    if not isinstance(loaded, dict):
+        raise CredentialsError(f"Credentials file {CREDENTIALS_PATH} is malformed (not a JSON object).")
+    return loaded
+
+
+def clear_credentials() -> None:
+    """Remove the credentials file if it exists."""
+    if CREDENTIALS_PATH.exists():
+        CREDENTIALS_PATH.unlink()
+
+
+def is_expired(creds: dict[str, Any], *, skew_s: float = _EXPIRY_SKEW_S) -> bool:
+    """``True`` when ``creds["expires_at"]`` is at or before now (plus *skew_s*)."""
+    expires_at = datetime.fromisoformat(str(creds["expires_at"]))
+    if expires_at.tzinfo is None:
+        expires_at = expires_at.replace(tzinfo=timezone.utc)
+    return datetime.now(timezone.utc) + timedelta(seconds=skew_s) >= expires_at
+
+
+def refresh_access_token(creds: dict[str, Any], *, base_url: str) -> dict[str, Any]:
+    """``POST {base_url}/auth/token/refresh``; merge + persist the new access token.
+
+    Preserves ``refresh_token`` / ``active_organization_id`` / every other field
+    from the existing credentials — the refresh response carries only
+    ``access_token`` + ``expires_at`` (see cli-auth SKILL "Refresh response").
+    """
+    url = base_url.rstrip("/") + TOKEN_REFRESH_PATH
+    # The refresh token travels in the POST BODY here, not a bearer header, so
+    # ``http.request_json``'s own https-when-token guard (which only inspects
+    # the ``token=`` header-attachment path) never sees it. It is just as
+    # sensitive as a bearer — apply the same https-or-loopback check
+    # explicitly, BEFORE the request is ever attempted, so a misconfigured
+    # plain-http non-loopback SIMULO_API_URL/SIMULO_ENV can never leak it.
+    try:
+        http.require_https_or_loopback_for_bearer(url)
+    except http.InsecureBearerError as exc:
+        raise TokenRefreshError(str(exc)) from exc
+    try:
+        payload = http.request_json(
+            "POST",
+            url,
+            json_body={"refresh_token": creds.get("refresh_token")},
+            unavailable_hint="Cannot refresh the session — check your network connection.",
+        )
+    except http.HttpHTTPError as exc:
+        raise TokenRefreshError("Session refresh was rejected. Run: simulo login", code=exc.code) from exc
+    except http.HttpUnavailable as exc:
+        raise TokenRefreshError(
+            "Cannot refresh the session — check your network connection. Run: simulo login"
+        ) from exc
+    if not isinstance(payload, dict) or "access_token" not in payload or "expires_at" not in payload:
+        raise TokenRefreshError("Malformed response from the token refresh endpoint.")
+    new_creds = {**creds, "access_token": payload["access_token"], "expires_at": payload["expires_at"]}
+    save_credentials(new_creds)
+    return new_creds
+
+
+def get_valid_credentials(*, base_url: Optional[str] = None) -> dict[str, Any]:
+    """Load credentials, silently refreshing the access token if it has expired.
+
+    Raises :class:`CredentialsError` (not logged in / unsafe permissions) or
+    :class:`TokenRefreshError` (refresh attempted and failed) — never returns
+    an expired token.
+    """
+    creds = load_credentials()
+    if not is_expired(creds):
+        return creds
+    resolved_base_url = base_url or config.resolve_base_url(creds)
+    return refresh_access_token(creds, base_url=resolved_base_url)
+
+
+def try_get_valid_credentials(*, base_url: Optional[str] = None) -> Optional[dict[str, Any]]:
+    """Like :func:`get_valid_credentials`, but ``None`` when simply not logged in.
+
+    Still raises on unsafe permissions or a failed refresh — those are real
+    errors, not "offline mode" signals.
+    """
+    if not CREDENTIALS_PATH.exists():
+        return None
+    return get_valid_credentials(base_url=base_url)

simulo/_client/discovery.py

@@ -0,0 +1,214 @@
+"""Discovery-mode import interception + the ``discover(app_file)`` entrypoint.
+
+In discovery mode the thin client imports a user app to harvest metadata, but it
+must NOT resolve the heavy imports the user wrote inside ``runtime.imports()``
+(``torch`` / Isaac / …) — those only exist in the cloud. ``_StubImportFinder`` is
+a *find-phase fallback*: installed at the END of ``sys.meta_path`` (so it is only
+consulted when every real finder has already failed), it satisfies an otherwise
+unresolvable import with a harmless stub module and records the top-level name as
+a deferred remote import.
+
+Because it is a find-phase fallback it cannot rescue a module that is *found* and
+then raises while executing — hence the authoring rule that only leaf, uninstalled
+packages belong in the ``runtime.imports()`` guard.
+"""
+
+import importlib.util
+import os
+import sys
+from contextlib import AbstractContextManager
+from importlib.abc import Loader, MetaPathFinder
+from importlib.machinery import ModuleSpec
+from pathlib import Path
+from types import FrameType, ModuleType, TracebackType
+from typing import Optional, Sequence
+
+from simulo._client.mode import DISCOVERY
+from simulo._client.registry import find_app
+from simulo._client.stub import Stub
+from simulo.interfaces.platform.app import AppProtocol
+
+#: Prefix of the synthetic module name a user app file is imported under (see
+#: ``_load_module_from_path``). The stub finder uses it to recognise imports the
+#: user app wrote directly, versus transitive imports issued by a real library.
+_USER_MODULE_PREFIX = "_simulo_user_"
+
+
+def _import_is_user_initiated() -> bool:
+    """True if the in-flight import statement lives in the user app module.
+
+    Walks outward from the finder frame, skipping the import machinery and this
+    module, to the frame that executed the ``import`` statement. The stub finder
+    must satisfy only the *leaf* imports the user wrote inside ``runtime.imports()``
+    (e.g. ``import torch``). It must NOT satisfy imports a genuinely-installed
+    library issues transitively while loading — on a GPU/dev box where ``torch``
+    is present, ``import torch`` resolves for real and torch then probes optional
+    deps (``import monkeytype``) with ``try/except ImportError``; stubbing those
+    turns an expected ImportError into a broken half-real module and crashes the
+    real library. Declining transitive imports lets them raise naturally.
+
+    The user app is the synthetic ``_simulo_user_*`` module (``simulo run`` / the
+    packager imports the file by path) OR the ``__main__`` module (``python
+    app.py`` runs the file directly). Both are first-party authoring contexts.
+    """
+    frame: Optional[FrameType] = sys._getframe(1)  # caller == find_spec
+    while frame is not None:
+        name = str(frame.f_globals.get("__name__", ""))
+        if name == __name__ or name == "importlib" or name.startswith("importlib."):
+            frame = frame.f_back
+            continue
+        return name.startswith(_USER_MODULE_PREFIX) or name == "__main__"
+    return False
+
+
+class _StubModule(ModuleType):
+    """A module whose missing attributes resolve to :class:`Stub` placeholders."""
+
+    __path__: list[str]
+
+    def __getattr__(self, item: str) -> Stub:
+        if item.startswith("__") and item.endswith("__"):
+            raise AttributeError(item)
+        return Stub(f"{self.__name__}.{item}")
+
+
+class _StubLoader(Loader):
+    """Loader that materialises :class:`_StubModule` instances."""
+
+    def create_module(self, spec: ModuleSpec) -> ModuleType:
+        module = _StubModule(spec.name)
+        # Mark as a package so ``import torch.nn`` re-enters the finder for the
+        # submodule rather than failing outright.
+        module.__path__ = []
+        return module
+
+    def exec_module(self, module: ModuleType) -> None:
+        return None
+
+
+class _StubImportFinder(MetaPathFinder):
+    """Find-phase fallback that stubs otherwise-unresolvable imports.
+
+    Records each intercepted *top-level* module name into ``remote_imports`` and
+    every stubbed fullname into ``stubbed`` (so the context manager can purge them
+    from ``sys.modules`` on exit, keeping torch & friends out of the process).
+    """
+
+    def __init__(self, remote_imports: list[str], stubbed: list[str]) -> None:
+        self._remote_imports = remote_imports
+        self._stubbed = stubbed
+        self._loader = _StubLoader()
+
+    def find_spec(
+        self,
+        fullname: str,
+        path: Optional[Sequence[str]] = None,
+        target: Optional[ModuleType] = None,
+    ) -> Optional[ModuleSpec]:
+        # Only satisfy imports the user app wrote directly. A transitive import
+        # issued by a genuinely-installed library (e.g. torch probing the optional
+        # `monkeytype`) must be declined so it raises ImportError as that library
+        # expects, instead of becoming a broken half-stubbed module.
+        if not _import_is_user_initiated():
+            return None
+        top = fullname.split(".", 1)[0]
+        if top not in self._remote_imports:
+            self._remote_imports.append(top)
+        if fullname not in self._stubbed:
+            self._stubbed.append(fullname)
+        return ModuleSpec(fullname, self._loader, is_package=True)
+
+
+class _DiscoveryImports(AbstractContextManager[None]):
+    """Context manager installing :class:`_StubImportFinder` for the duration of
+    a ``with runtime.imports():`` block in discovery mode.
+
+    On exit it removes the finder and purges every stub it created from
+    ``sys.modules`` so heavy libraries are never observable post-discovery.
+    """
+
+    def __init__(self, remote_imports: list[str]) -> None:
+        self._remote_imports = remote_imports
+        self._stubbed: list[str] = []
+        self._finder: Optional[_StubImportFinder] = None
+
+    def __enter__(self) -> None:
+        self._finder = _StubImportFinder(self._remote_imports, self._stubbed)
+        # Append (not insert) so real finders always win — we are a fallback.
+        sys.meta_path.append(self._finder)
+        return None
+
+    def __exit__(
+        self,
+        exc_type: Optional[type[BaseException]],
+        exc: Optional[BaseException],
+        traceback: Optional[TracebackType],
+    ) -> None:
+        if self._finder is not None:
+            try:
+                sys.meta_path.remove(self._finder)
+            except ValueError:
+                pass
+            self._finder = None
+        for name in self._stubbed:
+            sys.modules.pop(name, None)
+
+
+def stub_import_context(remote_imports: list[str]) -> AbstractContextManager[None]:
+    """Build the discovery-mode ``runtime.imports()`` context manager."""
+    return _DiscoveryImports(remote_imports)
+
+
+def _load_module_from_path(app_file: Path) -> ModuleType:
+    """Import a user app file by path under a synthetic module name."""
+    resolved = app_file.resolve()
+    parent = str(resolved.parent)
+    # Let the app import sibling local modules during discovery. Append (not
+    # ``insert(0, ...)``) so a user file named like a stdlib module cannot shadow
+    # the standard library during discovery. ``discover`` restores ``sys.path``.
+    if parent not in sys.path:
+        sys.path.append(parent)
+    module_name = f"{_USER_MODULE_PREFIX}{resolved.stem}"
+    spec = importlib.util.spec_from_file_location(module_name, resolved)
+    if spec is None or spec.loader is None:
+        raise ImportError(f"Could not load a Python module from {resolved}")
+    module = importlib.util.module_from_spec(spec)
+    # Register before exec so dataclasses / typing references resolve.
+    sys.modules[module_name] = module
+    spec.loader.exec_module(module)
+    return module
+
+
+def import_app_module(app_file: "str | Path") -> ModuleType:
+    """Import a user app file by path under the CURRENT ``SIMULO_MODE``.
+
+    Unlike :func:`discover`, this does not force discovery mode or restore it — the
+    caller sets the mode it wants (``simulo run`` sets ``discovery`` for a
+    torch-free submit and keeps it set while invoking the entrypoint). The module's
+    parent is appended to ``sys.path`` so sibling-module imports resolve.
+    """
+    return _load_module_from_path(Path(app_file))
+
+
+def discover(app_file: "str | Path", *, name: Optional[str] = None) -> AppProtocol:
+    """Import ``app_file`` in discovery mode and return its declared ``App``.
+
+    Sets ``SIMULO_MODE=discovery``, imports the module by path (running no job
+    bodies and stubbing guarded heavy imports), and resolves the single app via
+    the imported module's globals.
+
+    Process-global state (``SIMULO_MODE`` and ``sys.path``) is restored on exit
+    so discovery leaves no residue for whatever runs next in the same process.
+    """
+    previous_mode = os.environ.get("SIMULO_MODE")
+    previous_sys_path = list(sys.path)
+    os.environ["SIMULO_MODE"] = DISCOVERY
+    try:
+        module = _load_module_from_path(Path(app_file))
+        return find_app(module=module, name=name)
+    finally:
+        sys.path[:] = previous_sys_path
+        if previous_mode is None:
+            os.environ.pop("SIMULO_MODE", None)
+        else:
+            os.environ["SIMULO_MODE"] = previous_mode