snowflake-sandbox-python 0.2.1a1__py3-none-any.whl

snowflake/sandbox/config.py

@@ -0,0 +1,1133 @@
+"""Configuration for ``snowflake.sandbox``.
+
+A connection is named EXPLICITLY, per call or per block, in one of three shapes --
+a name from ``~/.snowflake/connections.toml``, a live ``snowflake.connector``
+connection, or a `Config` of raw credentials:
+
+    Sandbox.create(connection="prod")       # this call
+    with using("prod"): ...                 # this block
+    Sandbox.create()                        # the ambient default, below
+
+`resolve_config` is the one resolver all three go through; `using` binds one to the
+current context. Neither stores process-wide state, so two threads or tasks can hold
+two different connections at once.
+
+A caller who names nothing gets the AMBIENT config from `current_config`, resolved
+(in precedence order) from:
+
+1. Environment variables (``SNOWFLAKE_PAT`` / ``SNOWFLAKE_ACCOUNT`` /
+   ``SNOWFLAKE_HOST``) — how a process inside a sandbox authenticates with no
+   config at all.
+2. The connection named by ``SNOWFLAKE_DEFAULT_CONNECTION_NAME`` (or
+   ``default_connection_name``) in ``~/.snowflake/connections.toml`` / ``config.toml``.
+
+Connection resolution is delegated entirely to ``snowflake-connector-python``:
+``config_manager.CONFIG_MANAGER`` owns the TOML files and ``connect(
+connection_name=...)`` owns the login. We do not parse the files or assemble
+connect() kwargs ourselves. See ``_config_from_connection`` below.
+
+Kept import-cheap: no httpx, no pydantic, and the connector is imported lazily
+(on first connection resolution), so ``import snowflake.sandbox`` stays fast.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import threading
+import warnings
+from contextlib import contextmanager
+from contextvars import ContextVar
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any, Final, Protocol, TypeAlias
+
+# Connection resolution and the connector-session registry / credential-renewal
+# machinery live in sibling leaf modules now, but are re-exported here so every
+# ``snowflake.sandbox.config.<name>`` import path (and the tests that patch these
+# on ``config``) keeps working unchanged. The ``as`` form is a deliberate explicit
+# re-export (mypy ``no_implicit_reexport`` under ``strict``). These modules import
+# back into ``config`` only inside function bodies, so this edge stays one-way.
+from snowflake.sandbox._connection_resolve import (
+    _config_from_connection as _config_from_connection,
+)
+from snowflake.sandbox._connection_resolve import (
+    _config_from_live_connection as _config_from_live_connection,
+)
+from snowflake.sandbox._connection_resolve import (
+    _connection_fields as _connection_fields,
+)
+from snowflake.sandbox._connection_resolve import (
+    _connector_config_manager as _connector_config_manager,
+)
+from snowflake.sandbox._connection_resolve import (
+    _default_connection_name as _default_connection_name,
+)
+from snowflake.sandbox._connection_resolve import (
+    _host_from_connection_fields as _host_from_connection_fields,
+)
+from snowflake.sandbox._session_registry import (
+    _close_connection as _close_connection,
+)
+from snowflake.sandbox._session_registry import (
+    _close_one_session as _close_one_session,
+)
+from snowflake.sandbox._session_registry import (
+    _close_session_registry as _close_session_registry,
+)
+from snowflake.sandbox._session_registry import (
+    _reconnect as _reconnect,
+)
+from snowflake.sandbox._session_registry import (
+    _renew_or_reconnect as _renew_or_reconnect,
+)
+from snowflake.sandbox._session_registry import (
+    _retire_connection as _retire_connection,
+)
+from snowflake.sandbox._session_registry import (
+    refresh_config as refresh_config,
+)
+from snowflake.sandbox._session_registry import (
+    refresh_credential as refresh_credential,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+    from pathlib import Path
+
+__all__ = [
+    "Config",
+    "ConnectionLike",
+    "current_config",
+    "close_connections",
+    "refresh_connection_config",
+    "resolve_config",
+    "using",
+]
+
+# ``enable_dev_mode`` is intentionally NOT in ``__all__`` and NOT re-exported at
+# the package level: it only arms the internal dev/regtest transport (inert, then
+# an ImportError, in a released wheel), so it is not part of the public surface.
+# It stays importable as ``snowflake.sandbox.config.enable_dev_mode`` for the
+# SDK's own dev harness (see tests/sandbox/test_config_security.py).
+
+# ``refresh_config`` / ``refresh_credential`` are intentionally NOT in ``__all__``:
+# they are transport-internal plumbing (the 401 self-heal hook), imported
+# explicitly by the transport, not user-facing API like the names above.
+
+# Sandbox API base path — the REST surface (/api/v2/sandbox/v1/) served by Snowflake
+# and the standalone sandbox-api service.
+DEFAULT_BASE_PATH = "/api/v2/sandbox/v1"
+DEFAULT_TIMEOUT_S = 120.0
+DEFAULT_MAX_CONNECTIONS = 100
+
+# Characters that must never appear in a host: a scheme separator, a path, a
+# query/fragment, credentials, or whitespace. See `_validate_host_shape`.
+_HOST_FORBIDDEN_CHARS = frozenset("/\\?#@ \t\r\n")
+
+
+def _validate_host_shape(host: str) -> None:
+    """Reject a host that is anything but a bare ``hostname[:port]``.
+
+    ``host="evil.com/api"`` / ``SNOWFLAKE_HOST=evil.com/api`` otherwise
+    yielded ``base_url == "https://evil.com/api"``, sending the account bearer
+    token to an attacker-chosen host and path. A scheme, path, query, fragment,
+    userinfo (``user@host``), whitespace, or control character is refused so the
+    token can only ever leave for a host the caller actually named.
+    """
+    if not host:
+        raise ValueError("host must not be empty")
+    if "://" in host:
+        raise ValueError(f"host must not include a scheme (got {host!r})")
+    if any(c in _HOST_FORBIDDEN_CHARS for c in host):
+        raise ValueError(
+            f"host must be a bare hostname[:port], not {host!r} "
+            "(no path, query, credentials, or whitespace)"
+        )
+    if any(ord(c) < 32 for c in host):
+        raise ValueError(f"host contains control characters: {host!r}")
+
+
+def _is_trusted_snowflake_host(host: str) -> bool:
+    """True for ``*.snowflakecomputing.com`` (PrivateLink subdomains included)."""
+    bare = host.split(":", 1)[0].rstrip(".").lower()
+    return bare == "snowflakecomputing.com" or bare.endswith(".snowflakecomputing.com")
+
+
+# Dev-mode gate. The regtest/dev transport (``SNOWFLAKE_CWS_DEV=1`` -> cleartext
+# ``http://`` bearer token, HTTP/2 off, ``trust_env=False``, request-body rewrite,
+# ``mint_testaccount_token`` over plaintext) must NOT be reachable by a stray
+# environment variable in a released install. It is honored only when code in the
+# process has explicitly opted in via ``enable_dev_mode()`` — something a customer
+# wheel never does, and an attacker who only controls the environment cannot do.
+_dev_mode_enabled = False
+
+
+def enable_dev_mode(enabled: bool = True) -> None:
+    """Opt this process in to the internal dev/regtest transport.
+
+    Required before ``SNOWFLAKE_CWS_DEV=1`` has any effect: without this in-code
+    call the env var is ignored (with a warning), so a released install cannot be
+    downgraded to the cleartext dev transport by the environment alone. Intended
+    for the SDK's own dev/test harness. Re-reads config on the next call.
+    """
+    global _dev_mode_enabled
+    _dev_mode_enabled = enabled
+    close_connections()
+
+
+@dataclass(frozen=True)
+class Config:
+    """Resolved SDK configuration.
+
+    ``pat`` is the bearer token. ``base_url`` is the fully-qualified host
+    (``https://...``); ``base_path`` is the API prefix joined with each
+    endpoint. ``verify`` controls TLS verification — always True unless the
+    caller explicitly passes ``verify=False``. It is NEVER inferred
+    from the host: doing so silently exposed the bearer PAT to a MITM on every
+    account whose name legitimately contains an underscore.
+    """
+
+    account: str | None = None
+    # repr=False: a Config lands in tracebacks, log lines, and notebook cell
+    # output, and none of those should carry the bearer token.
+    pat: str | None = field(default=None, repr=False)
+    host: str | None = None
+    base_path: str = DEFAULT_BASE_PATH
+    verify: bool = True
+    timeout_s: float = DEFAULT_TIMEOUT_S
+    max_connections: int = DEFAULT_MAX_CONNECTIONS
+    extra_headers: dict[str, str] = field(default_factory=dict)
+    # CWS dev mode — set via SNOWFLAKE_CWS_DEV=1 in the environment.
+    # Never set in production.
+    cws_dev: bool = False
+    cws_dial: str = ""  # host:port to dial directly (bypasses DNS)
+    cws_gs_host: str = ""  # Host header value for envoy routing
+    # connect() kwargs used to REOPEN the named connection this Config came from,
+    # or None when it was resolved from the environment. Kept so a later connector
+    # operation (a stage PUT) can re-authenticate the way the connection itself
+    # does, instead of re-deriving credentials from ``pat`` — which is a *session*
+    # token here, and is rejected when replayed as authenticator="oauth".
+    #
+    # These carry the connection NAME (plus login_timeout and an optional role),
+    # never a secret: the connector re-reads the credential from the TOML file on
+    # reconnect (see ``_config_from_connection``). repr=False is precautionary all
+    # the same, so a future field that did carry a secret cannot leak into a
+    # traceback/log; compare=False because they are derived, so two Configs naming
+    # the same connection stay equal.
+    connector_kwargs: dict[str, Any] | None = field(default=None, repr=False, compare=False)
+    # The live ``snowflake.connector`` connection this Config's session token was
+    # minted from, kept so the token can be RENEWED after it expires without a full
+    # re-login: the connector holds a longer-lived master token and renews the
+    # session off it in one round-trip (see ``refresh_config`` /
+    # ``SnowflakeRestful._renew_session``). ``None`` for an env/PAT Config (nothing
+    # to renew from). Excluded from repr (a connection object in a traceback is
+    # noise, and its rest token is a live secret) and from eq/hash (it is derived
+    # and unhashable), exactly like ``connector_kwargs`` above. For a connection the
+    # SDK opened it is the same object already retained in ``_session_registry``, so
+    # this reference does not extend its lifetime beyond ``close_connections``; for one the
+    # caller opened and handed us (the ``snow`` CLI plugin, via
+    # ``_config_from_live_connection``) it is NOT registered — the caller owns its
+    # lifetime and ``close_connections`` must not close it.
+    connection: Any | None = field(default=None, repr=False, compare=False)
+
+    @property
+    def base_url(self) -> str:
+        """Return the base URL — http in dev mode, https otherwise."""
+        if self.cws_dev and self.cws_dial:
+            return f"http://{self.cws_dial}"
+        host = self.host or (f"{self.account}.snowflakecomputing.com" if self.account else None)
+        if not host:
+            raise RuntimeError(
+                "snowflake.sandbox has no endpoint to talk to: set SNOWFLAKE_ACCOUNT or "
+                "SNOWFLAKE_HOST in the environment, name a connection in "
+                "~/.snowflake/connections.toml, or pass one explicitly — "
+                '`connection="my_connection"`, or '
+                "`connection=Config(account=..., pat=...)` for raw credentials."
+            )
+        # A legacy ACCOUNT_REGION identifier (e.g. SFCOGSOPS-SNOWHOUSE_AWS_US_WEST_2,
+        # as Snowhouse uses) carries underscores, which are not valid in a DNS/TLS
+        # hostname label -- the `*.snowflakecomputing.com` certificate only matches
+        # the hyphenated form, so the underscore host fails verification with a
+        # "Hostname mismatch". The connector maps `_`->`-` for the URL it dials;
+        # mirror that here for the REST endpoint. The `account` field itself is
+        # left untouched (it is reused verbatim for connector re-auth), and a host
+        # with no underscores is unaffected.
+        host = host.replace("_", "-")
+        # Guard every source (configure, env, a directly-built Config): a
+        # path-injected or scheme-bearing host must not become the base_url the
+        # bearer token rides on.
+        _validate_host_shape(host)
+        return f"https://{host}"
+
+    def resolve_pat(self) -> str | None:
+        """The token to authenticate with NOW — live from the connection if any.
+
+        When this Config was minted from a named connection, the connector holds
+        the live session token on ``connection.rest.token`` and renews it in place
+        (via its own traffic, the keep-alive heartbeat, or an explicit
+        ``_renew_session``). Reading it live here — rather than the ``pat`` snapshot
+        taken when the connection was resolved — means a renewed token is picked up
+        on the very next request, with no stale-snapshot window. ``pat`` remains the
+        fallback for an env/PAT Config that has no connection, and the source of
+        truth for the ``ver:`` scheme heuristic either way.
+        """
+        conn = self.connection
+        if conn is not None:
+            rest = getattr(conn, "rest", None)
+            token = getattr(rest, "token", None) if rest is not None else None
+            if token:
+                return str(token)
+        return self.pat
+
+
+class _ConnectorConnection(Protocol):
+    """Structural type for a live ``snowflake.connector`` connection.
+
+    Matched by having ``rest`` (whose ``token`` is the REST bearer we borrow).
+    """
+
+    rest: Any
+
+
+class _SnowparkSession(Protocol):
+    """Structural type for a Snowpark ``Session``, which wraps a connector connection.
+
+    Matched by exposing ``connection``. Users in Streamlit-in-Snowflake and stored
+    procedures hold a Session rather than a connection.
+    """
+
+    @property
+    def connection(self) -> Any: ...
+
+
+# What ``connection=`` accepts, named so callers and their type checkers can spell it.
+#
+# Structural rather than a union of concrete classes: two of the four shapes live in
+# optional dependencies (``snowflake.connector``, ``snowflake.snowpark``), and importing
+# either to write the annotation would make it mandatory and add import cost for
+# everyone. Protocols describe the shapes we actually use, so a real connection or
+# Session matches without any import — and unlike the `str | Any | None` this replaces,
+# a wrong argument is now rejected instead of silently accepted.
+ConnectionLike: TypeAlias = str | Config | _ConnectorConnection | _SnowparkSession
+
+
+_lock = threading.Lock()
+
+# Holds connector sessions minted for password/oauth connections so they are
+# not garbage-collected (which would invalidate their session tokens).
+# Released by `close_connections` via `_close_session_registry`.
+_session_registry: list[object] = []
+
+
+# --- scoped connection (``using()``) -----------------------------------------
+#
+# A ``using()`` block binds a resolved `Config` to the *current context* -- this
+# thread, or this asyncio task -- instead of to a process slot. It exists because
+# ``create(connection=...)`` can only serve the call that builds a sandbox: the
+# entry points that start from an id or a name (``connect()``, ``list_sandboxes()``,
+# ``destroy_sandbox()``, ``Job.from_id()``) resolve their config late, when the
+# request is made, and had no way to name a connection at all.
+#
+# A ContextVar cannot outlive its block and is not shared between threads or tasks, so
+# neither defect of the per-role slots this replaced applies to it: there is no slot to
+# collide on (#247's two-connections case) and nothing to leak into a later call.
+@dataclass
+class _Scope:
+    """The connection bound by an enclosing ``using()`` block.
+
+    ``role_cache`` memoises role-scoped Configs minted from this scope's own
+    connection, so ``using(connection=X)`` wrapping N calls that each pass
+    ``role=R`` pays one connector login, not N.
+
+    Deliberately holds no pool key: the transport layer derives it from the `Config`
+    (`_scope_key`) at acquisition time, so storing a copy here would be a second source
+    of truth to keep in step.
+    """
+
+    config: Config
+    role_cache: dict[str, Config] = field(default_factory=dict)
+
+
+_scoped: ContextVar[_Scope | None] = ContextVar("_snowflake_sandbox_scope", default=None)
+
+# Resolved named connections, keyed ``(name, ROLE)``. Guarded by ``_lock``.
+#
+# ``_config_from_connection`` is a connector LOGIN. Without memoising it, a per-call
+# ``connection=`` would log in on every single call -- ``get_sandbox_by_name(n,
+# connection="prod")`` in a loop is then one OAuth login per iteration. That is not just
+# slow: repeated logins in quick succession trip auth rate limiting, which showed up as
+# an ``OperationalError`` from the connector's auth plugin in this SDK's own live suite.
+#
+# Caching a Config means caching the live connector session it carries:
+# ``Config.resolve_pat()`` re-reads the token from that session, so a renewal is picked
+# up rather than pinned. Cleared by ``close_connections()`` (which also closes those sessions)
+# and by ``refresh_connection_config()`` (the on-disk TOML may now say something
+# different).
+#
+# Since the per-role config slots were removed this is the SDK's only config
+# store, and it is a pure memo: every entry is reproducible from ``(name, role)`` plus
+# the on-disk TOML, so dropping it costs a re-login and never changes an answer. That is
+# what makes it safe for `close_connections` to clear unconditionally.
+_resolution_cache: dict[tuple[str, str | None], Config] = {}
+
+
+def _resolve_named_connection(name: str, role: str | None = None) -> Config:
+    """Resolve a named connection into a `Config`, memoised per ``(name, role)``.
+
+    The login happens WITHOUT ``_lock`` held (it is blocking network I/O), then stores
+    first-writer-wins. A loser's session stays alive in ``_session_registry`` until
+    ``close_connections()``, so nothing is leaked.
+    """
+    key = (name, role.upper() if role else None)
+    with _lock:
+        hit = _resolution_cache.get(key)
+    if hit is not None:
+        return hit
+    cfg = _config_from_connection(name, role)
+    with _lock:
+        return _resolution_cache.setdefault(key, cfg)
+
+
+def _replace_cached_config(old: Config, new: Config) -> bool:
+    """Swap a re-minted `Config` in for the one it replaces, in the resolution memo.
+
+    The reactive reauth path (`refresh_credential`) reconnects the ambient config and
+    needs the result to be what the NEXT request resolves; otherwise every request after
+    an expired session pays its own reconnect and the memo keeps handing back the dead
+    one.
+
+    Matched on identity, not on the ``(name, role)`` key: the caller renewed a specific
+    `Config` object, and only that entry should move. Returns False when it is no longer
+    in the memo -- cleared mid-refresh, or never memoised because it came from the bare
+    environment -- which tells the caller its reconnect is an orphan to retire rather
+    than install.
+    """
+    with _lock:
+        for key, cur in _resolution_cache.items():
+            if cur is old:
+                _resolution_cache[key] = new
+                return True
+    return False
+
+
+def _credential_identity(cfg: Config) -> str | None:
+    """How this Config proves who it is, as a poolable identity.
+
+    The transport pool must never hand a block a transport built for *different*
+    credentials: a scoped transport bakes its Config in (``_config_override``), so a
+    collision here means every request in the second block authenticates as the first
+    block's principal. The three cases differ in whether the token can be renewed
+    behind a stable identity:
+
+    * **named connection** -- keyed on the NAME (plus role, added by the caller).
+      ``Config.resolve_pat()`` re-reads the token from the session the Config carries,
+      and a re-login produces an equivalent principal, so the token is deliberately
+      excluded: including it would fragment the pool on every renewal, which is what
+      pooling per connection exists to avoid.
+    * **live connection the caller opened** -- keyed on that object's identity. Two
+      distinct sessions may be two distinct users on the same account, so they must not
+      share, while re-entering a block with the *same* object should.
+    * **raw credentials** (``account=``/``pat=``, no session) -- keyed on a FINGERPRINT
+      of the token. There is nothing to re-read from, so the token is a static snapshot
+      and two different tokens are two different principals. Hashed, never the token
+      itself: a pool key can end up in a repr or a log line.
+    """
+    kw = cfg.connector_kwargs or {}
+    name = kw.get("connection_name")
+    if name:
+        return f"name:{name}"
+    if cfg.connection is not None:
+        return f"session:{id(cfg.connection):x}"
+    token = cfg.pat
+    if token:
+        return f"token:{hashlib.sha256(token.encode()).hexdigest()[:16]}"
+    return None
+
+
+def _scope_key(cfg: Config) -> str:
+    """Stable identity for a scoped Config, used to key the transport pool.
+
+    `Config` is frozen but NOT usable as a dict key (``extra_headers`` is a dict, so
+    hashing raises), and two ``using()`` blocks on the same connection should share one
+    transport rather than pay a second TLS handshake.
+
+    Covers the fields that decide *where* a request goes, plus the credential identity
+    from `_credential_identity` -- which is what keeps a block from inheriting another
+    block's principal.
+    """
+    kw = cfg.connector_kwargs or {}
+    return json.dumps(
+        [
+            cfg.account,
+            cfg.host,
+            cfg.base_path,
+            cfg.verify,
+            # Baked into the httpx client at construction (timeout / Limits), so two
+            # blocks on one connection that ask for DIFFERENT values must not share a
+            # transport — the second would silently run with the first's.
+            cfg.timeout_s,
+            cfg.max_connections,
+            # A credential-bound transport serves requests from the Config baked into
+            # it, so anything that reaches the WIRE belongs in this key. Normally these
+            # come from SNOWFLAKE_CWS_EXTRA_HEADERS and are identical process-wide, but
+            # a caller-built ``connection=Config(extra_headers=...)`` can differ per
+            # call, and sharing would send the other Config's headers.
+            sorted(cfg.extra_headers.items()),
+            cfg.cws_dev,
+            cfg.cws_dial,
+            cfg.cws_gs_host,
+            (kw.get("role") or "").upper() or None,
+            _credential_identity(cfg),
+        ],
+        separators=(",", ":"),
+    )
+
+
+def _in_scope() -> bool:
+    """True inside a ``using()`` block on this thread/task."""
+    return _scoped.get() is not None
+
+
+def _scoped_config(role: str | None = None) -> Config | None:
+    """The Config bound by an enclosing ``using()`` block, or ``None`` if there is none.
+
+    With ``role``, returns that role minted from the scope's *own* connection, so
+    ``using(connection="prod")`` composes with a per-call ``role=``. Raises
+    `SandboxError` when the two disagree, rather than silently preferring one -- an
+    unrequested role binding is the failure mode #247 is about.
+    """
+    scope = _scoped.get()
+    if scope is None:
+        return None
+    if role is None:
+        return scope.config
+    key = role.upper()
+    kw = scope.config.connector_kwargs or {}
+    have = (kw.get("role") or "").upper()
+    if have == key:
+        return scope.config
+    if have:
+        from snowflake.sandbox.exceptions import SandboxError
+
+        raise SandboxError(
+            f"role={role!r} conflicts with the enclosing using(role={kw.get('role')!r}). "
+            "Pass the role on one of them, not both."
+        )
+    cached = scope.role_cache.get(key)
+    if cached is not None:
+        return cached
+    name = kw.get("connection_name")
+    if not name:
+        from snowflake.sandbox.exceptions import SandboxError
+
+        raise SandboxError(
+            f"role={role!r} needs a named Snowflake connection to mint a role-scoped "
+            "session from, but the enclosing using(...) resolved raw credentials "
+            "(account/pat), which carry their own role. Name a connection on using(), "
+            "or drop role=."
+        )
+    minted = _resolve_named_connection(name, role)
+    # First-writer-wins: a concurrent task that beat us here already left a usable
+    # session, and the loser's is retained by ``_session_registry`` until
+    # ``close_connections()``.
+    return scope.role_cache.setdefault(key, minted)
+
+
+def _extra_headers_from_env() -> dict[str, str]:
+    """Parse ``SNOWFLAKE_CWS_EXTRA_HEADERS`` (a JSON object) into ``{str: str}``.
+
+    Returns ``{}`` when unset. A malformed value (invalid JSON, or valid JSON that
+    is not an object) is ignored WITH a ``RuntimeWarning`` rather than swallowed:
+    silently dropping every extra header left a caller relying on one with no signal
+    it was gone. Keys and values are coerced to ``str``.
+    """
+    raw = os.environ.get("SNOWFLAKE_CWS_EXTRA_HEADERS", "").strip()
+    if not raw:
+        return {}
+    try:
+        parsed = json.loads(raw)
+    except ValueError as exc:
+        warnings.warn(
+            f"SNOWFLAKE_CWS_EXTRA_HEADERS is not valid JSON ({exc}); ignoring it.",
+            RuntimeWarning,
+            stacklevel=2,
+        )
+        return {}
+    if not isinstance(parsed, dict):
+        warnings.warn(
+            "SNOWFLAKE_CWS_EXTRA_HEADERS must be a JSON object; ignoring it.",
+            RuntimeWarning,
+            stacklevel=2,
+        )
+        return {}
+    return {str(k): str(v) for k, v in parsed.items()}
+
+
+def _from_env() -> Config:
+    _cws_dev_requested = os.environ.get("SNOWFLAKE_CWS_DEV", "").lower() in ("1", "true")
+    # Honor the dev transport only when code opted in (see enable_dev_mode): a
+    # released install left the flag False, so the env var is a no-op there.
+    _cws_dev = _cws_dev_requested and _dev_mode_enabled
+    if _cws_dev_requested and not _dev_mode_enabled:
+        warnings.warn(
+            "SNOWFLAKE_CWS_DEV is set but dev mode is not enabled in this process; "
+            "ignoring it. The dev/regtest transport (cleartext http bearer token, "
+            "HTTP/2 off, trust_env disabled) is only used after an explicit "
+            "snowflake.sandbox.config.enable_dev_mode() call.",
+            RuntimeWarning,
+            stacklevel=2,
+        )
+    _gs_host = os.environ.get("GS_HOST", "testaccount.reg.local:8082")
+    _gs_resolve = os.environ.get("GS_HOST_RESOLVE", "").strip()
+    _cws_dial = f"{_gs_resolve}:8082" if _gs_resolve else _gs_host
+    return Config(
+        account=os.environ.get("SNOWFLAKE_ACCOUNT"),
+        pat=os.environ.get("SNOWFLAKE_PAT") or os.environ.get("SNOWFLAKE_TOKEN"),
+        host=os.environ.get("SNOWFLAKE_HOST"),
+        base_path=DEFAULT_BASE_PATH,
+        verify=True,
+        cws_dev=_cws_dev,
+        cws_dial=_cws_dial if _cws_dev else "",
+        cws_gs_host=_gs_host if _cws_dev else "",
+        extra_headers=_extra_headers_from_env(),
+    )
+
+
+def resolve_config(
+    *,
+    connection: ConnectionLike | None = None,
+    account: str | None = None,
+    pat: str | None = None,
+    token: str | None = None,
+    host: str | None = None,
+    role: str | None = None,
+    base_path: str | None = None,
+    verify: bool | None = None,
+    timeout_s: float | None = None,
+    max_connections: int | None = None,
+    connector_kwargs: dict[str, Any] | None = None,
+) -> Config:
+    """Resolve a `Config` from a connection + overrides, WITHOUT storing it anywhere.
+
+    The pure core every ``connection=`` argument and `using()` share, so the two cannot
+    drift: both take the returned `Config` to the transport pool (keyed on its credential
+    identity) and mutate no global state.
+
+    `connection` is the one way to name a connection, in three shapes: a NAME in
+    ``~/.snowflake/connections.toml``, a LIVE ``snowflake.connector`` connection the
+    caller already opened, or a `Config` carrying raw credentials. The remaining
+    arguments override fields on whichever of those resolved.
+
+    Args:
+        connection: A connection name, a live connector connection, or a `Config`.
+        account: Snowflake account identifier, when not resolved from ``connection``
+            or the environment.
+        pat: Programmatic access token used as the REST bearer credential.
+        token: Alias for ``pat`` — whichever is set is used; ``pat`` wins if both
+            are given.
+        host: REST host override. Applies to the REST surface only; the connector
+            keeps the host its connection logged in with (which may legitimately
+            differ, e.g. PrivateLink). A non-Snowflake host warns.
+        role: Role used to create sandboxes, applied when the session is minted;
+            requires a connection *name*, since the role is chosen at login.
+        base_path: API base path prefix for the REST endpoints.
+        verify: TLS certificate verification. ``False`` sends the bearer token
+            over an unverified channel and emits a ``RuntimeWarning`` — use only
+            against a trusted local endpoint, never in production.
+        timeout_s: Per-request HTTP timeout, in seconds.
+        max_connections: Size of the HTTP connection pool.
+        connector_kwargs: Extra keyword arguments forwarded to the Snowflake
+            connector when the SDK opens a connection for stage operations.
+
+    Returns:
+        The resolved `Config`. Nothing is stored; a named connection's login is
+        memoised so repeated resolution of the same name does not re-authenticate.
+    """
+    if role is not None and connection is None:
+        raise ValueError(
+            f"role={role!r} requires connection=: the role is applied when the session "
+            "is minted from a named password/oauth connection. Without one there is no "
+            "session to mint — the bearer token in the environment carries its own role."
+        )
+    if verify is False:
+        # Mandatory: disabling TLS verification sends the bearer PAT over an
+        # unverified channel. It must never be a silent, undocumented workaround.
+        warnings.warn(
+            "verify=False disables TLS verification: "
+            "the Snowflake bearer token will be sent over an unverified connection "
+            "and is exposed to a man-in-the-middle. Use it only against a trusted "
+            "local endpoint, never in production.",
+            RuntimeWarning,
+            stacklevel=2,
+        )
+    if host is not None:
+        # Reject a path-injected/scheme-bearing host up front (base_url also
+        # guards it), and warn when the token would leave for a non-Snowflake host.
+        _validate_host_shape(host)
+        if not _is_trusted_snowflake_host(host):
+            warnings.warn(
+                f"host={host!r} targets a host that is not "
+                "*.snowflakecomputing.com (nor a PrivateLink subdomain); the account "
+                "bearer token will be sent there. Confirm this is a trusted "
+                "Snowflake endpoint.",
+                RuntimeWarning,
+                stacklevel=2,
+            )
+    if connection is None:
+        base = _from_env()
+    elif isinstance(connection, str):
+        # Memoised: a per-call ``connection=`` must not cost a login per call.
+        base = _resolve_named_connection(connection, role)
+    elif isinstance(connection, Config):
+        # A `Config` the caller assembled themselves — the explicit raw-credential path
+        # (``account=``/``pat=``/``host=``, plus the client knobs), for a process with no
+        # ``connections.toml`` at all. This is what lets ``connection=`` be the single
+        # way to name a connection: a NAME, a live SESSION, or CREDENTIALS. Nothing is
+        # resolved or logged in here; the Config already is the answer.
+        if role is not None:
+            raise ValueError(
+                f"role={role!r} cannot be applied to a Config: a role is chosen at login "
+                "and this Config already carries its resolved identity. Pass "
+                "connection=<name> with role=, or set the role on the Config's own "
+                "connection."
+            )
+        base = connection
+    else:
+        # A live connection the caller opened (the snow CLI resolves the connection
+        # with its own machinery, then passes the object here). role= is rejected
+        # inside — the role is a login-time choice, and this session already exists.
+        base = _config_from_live_connection(connection, role)
+    chosen_pat = pat if pat is not None else token
+    resolved_host = host if host is not None else base.host
+    if verify is None:
+        verify = base.verify
+    return Config(
+        account=account if account is not None else base.account,
+        pat=chosen_pat if chosen_pat is not None else base.pat,
+        host=resolved_host,
+        base_path=base_path if base_path is not None else base.base_path,
+        verify=verify,
+        timeout_s=timeout_s if timeout_s is not None else base.timeout_s,
+        max_connections=(max_connections if max_connections is not None else base.max_connections),
+        cws_dev=base.cws_dev,
+        cws_dial=base.cws_dial,
+        cws_gs_host=base.cws_gs_host,
+        extra_headers=base.extra_headers,
+        # Carried, not rebuilt from the arguments above: these are what actually
+        # authenticated against this connection, and a stage operation reusing
+        # them is the point. An explicit host= override applies to the REST
+        # surface only — the connector keeps the host its connection logged in
+        # with, which may legitimately differ (PrivateLink, an account
+        # identifier the REST TLS path cannot use).
+        #
+        # An explicit connector_kwargs= wins: the `snow sandbox` plugin resolves the
+        # connection with the CLI's own machinery and passes the connection NAME
+        # through here, so a stage operation can still re-open it.
+        connector_kwargs=(
+            connector_kwargs if connector_kwargs is not None else base.connector_kwargs
+        ),
+        # Carry the live connection the base resolved (a named connection the SDK
+        # opened, or one the caller handed via connection=<obj>). Previously dropped
+        # here, which cost the explicit-credential path its token renewal and its
+        # stage-PUT reuse — both read off Config.connection. resolve_pat() reads the
+        # live rest.token from it, so an explicit host=/pat= override still applies to
+        # the REST surface while the connection stays the credential authority.
+        connection=base.connection,
+    )
+
+
+def configure(*_args: Any, **_kwargs: Any) -> Any:
+    """Removed; see `snowflake.sandbox.configure` for the migration message.
+
+    Shimmed here too because this was the function's home, and
+    ``from snowflake.sandbox.config import configure`` is the import a caller who reached
+    past the package export would have written.
+    """
+    from snowflake.sandbox import configure as _moved
+
+    return _moved(*_args, **_kwargs)
+
+
+def ensure_role_config(*_args: Any, **_kwargs: Any) -> Any:
+    """Removed along with the per-role config slots it populated.
+
+    Raising rather than absent for the same reason as `configure`: an ImportError with no
+    explanation is worse than a name that tells you what replaced it.
+    """
+    raise NotImplementedError(
+        "snowflake.sandbox.config.ensure_role_config() was removed along with the "
+        "per-role config slots it populated. A role is now resolved on demand: pass "
+        "role= alongside connection= on the call, or to using()."
+    )
+
+
+def current_config(role: str | None = None) -> Config:
+    """Resolve the AMBIENT SDK configuration -- the one a caller who named no
+    connection gets (account, host, token).
+
+    A reader, not a setter: it stores nothing beyond memoising the connection it
+    resolved, and calling it can never change what a later call resolves. Resolution
+    order, matching the ``snow`` CLI's:
+
+    1. a credential in the environment (``SNOWFLAKE_PAT`` / ``SNOWFLAKE_TOKEN``, or the
+       dev transport), which is how an in-sandbox process authenticates with no config
+       at all;
+    2. ``SNOWFLAKE_DEFAULT_CONNECTION_NAME``, else ``default_connection_name`` in
+       ``~/.snowflake/config.toml`` -- resolved through the connector and memoised;
+    3. the bare environment, which has no credential and so fails with an actionable
+       error when something actually tries to use it.
+
+    ``role`` mints that role from the resolved connection (memoised per
+    ``(name, role)``), so a role-keyed ambient transport carries the right token. It is
+    ignored on path 1: a bare token carries its own role and there is no session to
+    mint from. Callers for whom the role MUST have taken effect -- ``create(role=...)``,
+    where it becomes the sandbox's identity -- check that with `prime_role_config`
+    rather than assuming.
+
+    Deliberately NOT aware of an enclosing ``using()`` block. That block's connection
+    reaches requests by handing out a *different*, explicitly-bound transport
+    (`get_transport`); the ambient transport resolves through this function on every
+    request, so making it scope-aware would let a transport acquired outside a block
+    change accounts on entering one -- and its ``httpx`` client has already baked in the
+    first host it saw. Use the value ``using()`` yields to see a scope's config.
+
+    Example:
+        from snowflake.sandbox import current_config
+
+        cfg = current_config()
+        print(cfg.account, cfg.host)
+    """
+    env = _from_env()
+    if env.pat or env.cws_dev:
+        return env
+    name = os.environ.get("SNOWFLAKE_DEFAULT_CONNECTION_NAME") or _default_connection_name()
+    if name:
+        try:
+            return _resolve_named_connection(name, role)
+        except Exception as exc:
+            # The user pointed us at a connection — via SNOWFLAKE_DEFAULT_CONNECTION_NAME
+            # or the default entry in connections.toml — so a failure to resolve it is
+            # actionable and should be loud. Surfacing the real cause (a missing
+            # connector for an oauth/password connection, an absent token file, a
+            # typo'd name) is far more useful than swallowing it here and letting the
+            # empty env raise a generic, misleading "is not configured" downstream.
+            raise RuntimeError(
+                f"snowflake.sandbox could not resolve connection {name!r} from "
+                f"~/.snowflake/connections.toml: {exc}"
+            ) from exc
+    return env
+
+
+def effective_config(role: str | None = None) -> Config:
+    """The config for an operation that has NO transport and named no connection.
+
+    An enclosing ``using()`` block if there is one, else the ambient `current_config`.
+    This is what `get_transport` resolves, expressed for the few call sites that reach
+    Snowflake without going through a transport at all -- the stage PUT and the
+    diagnostics probe.
+
+    Those may honour the scope where the ambient TRANSPORT deliberately does not, and the
+    difference is lifetime. A pooled transport is long-lived and its ``httpx`` client
+    bakes in the first host it saw, so letting it follow a scope would make a handle
+    acquired outside a block start authenticating as the block's principal against the
+    old host. These call sites resolve a config and use it immediately for one operation,
+    so there is nothing to go stale -- and inside a block the scope is the RIGHT answer:
+    uploading a sandbox's code to the default account while the sandbox itself runs in
+    the block's account is the bug, not the fix.
+    """
+    return _scoped_config(role) or current_config(role)
+
+
+def prime_role_config(role: str) -> None:
+    """Resolve the ambient config at *role* now, and say whether the role took effect.
+
+    Two jobs, both about ``role=`` on an entry point that did not name a connection:
+
+    * **Resolve it off the hot path.** `current_config` performs a connector LOGIN on a
+      cache miss. Read from the transport's ``config`` property mid-request that would
+      run on the caller's event loop and stall every other coroutine, so entry points
+      call this first from a worker thread; afterwards the read is a memo hit.
+    * **Refuse to silently ignore the role.** A role can only be minted from a named
+      connection, so a role that did not take effect raises rather than letting the call
+      run under the default role.
+
+    Strict on EVERY path, which it did not used to be. The read/attach paths passed
+    ``required=False`` because ``role=`` there carried a second meaning -- the server-side
+    ``?role=`` filter (sandbox-api#236), valid under any credential including a bare env
+    token with nothing to mint from -- so an unmintable role was tolerated. ``role=`` now
+    means CREDENTIAL on every entry point and the flag is gone. The wire filter did not go
+    with it: it is still sent, demoted to an internal narrowing that AGREES with the
+    credential meaning (a sandbox is owned by the role that created it, so under a session
+    minted at X, ``?role=X`` returns exactly the set X can see). Dropping it and filtering
+    on the returned ``sb.role`` was the original plan and is measurably wrong: a
+    role-minted session still sees every role's sandboxes (verified live -- a PUBLIC
+    session listed 7 ENGINEER sandboxes), and this SDK does not follow pagination cursors,
+    so local filtering would silently return a fraction of one page.
+
+    Checks the role that was actually applied rather than whether a connection name was
+    resolvable: that is the property callers depend on, and it also catches a connection
+    whose own role silently disagreed with the one asked for.
+
+    A no-op inside a ``using()`` block, and that is load-bearing rather than an
+    optimisation: `current_config` is deliberately scope-blind, so without the guard this
+    would log into the AMBIENT account at the requested role -- a login against an account
+    the caller did not name, whose result is then thrown away because the scope's transport
+    is what serves the request -- and would raise "name a connection" at a caller who
+    already named one. A scope mints its own role via `_scoped_config`, which raises its
+    own error when the two roles conflict.
+    """
+    from snowflake.sandbox.exceptions import SandboxError
+
+    if _in_scope():
+        return
+    cfg = current_config(role=role)
+    applied = (cfg.connector_kwargs or {}).get("role") or ""
+    if applied.upper() != role.upper():
+        got = f"role {applied!r}" if applied else "raw credentials from the environment"
+        raise SandboxError(
+            f"role={role!r} needs a named Snowflake connection to mint a role-scoped "
+            f"session from, but this process resolved {got}. Name the connection on the "
+            f'call — connection="my_connection", role={role!r} — or wrap it in '
+            f'`using("my_connection", role={role!r})`, or drop role=.'
+        )
+
+
+@contextmanager
+def using(
+    connection: ConnectionLike | None = None,
+    *,
+    close: bool = False,
+    role: str | None = None,
+    account: str | None = None,
+    pat: str | None = None,
+    token: str | None = None,
+    host: str | None = None,
+    base_path: str | None = None,
+    verify: bool | None = None,
+    timeout_s: float | None = None,
+    max_connections: int | None = None,
+    connector_kwargs: dict[str, Any] | None = None,
+) -> Iterator[Config]:
+    """Run a block against one Snowflake connection, without touching global state.
+
+    Everything inside the block -- `Sandbox.create`, `Sandbox.connect`,
+    `list_sandboxes`, `destroy_sandbox`, `Job.from_id`, a `Session` reconnect --
+    uses this connection. Nothing outside it does. The binding lives in a
+    `contextvars.ContextVar`, so it cannot outlive the block and is not shared with
+    other threads or asyncio tasks: two of them can hold two different connections at
+    the same time.
+
+    Takes the same arguments as `resolve_config`: a ``connection`` name from
+    ``~/.snowflake/connections.toml``, a live ``snowflake.connector`` connection you
+    already opened, or raw ``account=``/``pat=`` credentials. Yields the resolved
+    `Config`.
+
+    Scope, precisely: it decides where a *newly acquired* transport comes from. A
+    `Sandbox` handle built **outside** the block keeps its own connection when used
+    inside it -- a handle never switches accounts underneath you. A per-call
+    ``role=`` composes, minted from this scope's connection (once, then memoised).
+    Repeating the SAME role on a call inside the block is a no-op; a DIFFERENT one
+    raises `SandboxError` rather than silently preferring either.
+
+    Transports are pooled per connection identity so repeated blocks skip the TLS
+    handshake, and are released by `shutdown` / `shutdown_sync` like every other
+    pooled transport -- not at block exit.
+
+    Example:
+        from snowflake.sandbox import Sandbox, list_sandboxes, using
+
+        with using("prod_snowhouse"):
+            for info in list_sandboxes():          # reads prod_snowhouse
+                print(info.name)
+            sb = Sandbox.connect("my-agent")       # attaches over prod_snowhouse
+
+    ``close=True`` releases the connection when the block exits, instead of leaving the
+    connector session and its sockets pooled for the next call. Use it for a one-off
+    connection a long-lived process will not touch again -- a maintenance pass over
+    another account, a per-request connection in a server -- where the default
+    (keep it warm, and let `close_connections` release everything at the end) would
+    accumulate live authenticated sessions:
+
+        with using("other_account", close=True):
+            destroy_sandbox(stale_id)
+        # the session is closed here, not at process exit
+
+    It only closes a connection the **SDK opened**. A live connection or Snowpark
+    ``Session`` you passed in stays yours -- ``close=True`` will not close it, because
+    the SDK never closes what it did not open, and a block is not a transfer of
+    ownership. Scoped transports and the resolution memo are dropped first either way,
+    since both hold the Config whose session is going away.
+    """
+    cfg = resolve_config(
+        connection=connection,
+        account=account,
+        pat=pat,
+        token=token,
+        host=host,
+        role=role,
+        base_path=base_path,
+        verify=verify,
+        timeout_s=timeout_s,
+        max_connections=max_connections,
+        connector_kwargs=connector_kwargs,
+    )
+    token_ = _scoped.set(_Scope(config=cfg))
+    try:
+        yield cfg
+    finally:
+        _scoped.reset(token_)
+        if close:
+            # Drop the transports bound to THIS scope BEFORE closing the session: they
+            # carry this Config, and one left pooled would authenticate from a session
+            # this call just closed.
+            #
+            # Narrow on purpose -- only this scope's key, not every scoped transport, and
+            # only this connection's memo entry, not the whole cache. The global forms
+            # (`close_connections`) are right for a teardown that releases everything;
+            # here a sibling `using()` block or a `connection=`-bound handle must not lose
+            # its pooled client. It would recover (clients are recreated lazily) at the
+            # cost of a TLS handshake and, for the memo, a fresh connector login -- but a
+            # scoped verb reaching outside its scope is the wrong default even when the
+            # cost is only latency.
+            from snowflake.sandbox._sync_transport import close_scoped_sync_transports_for
+            from snowflake.sandbox._transport import close_scoped_transports_for
+
+            key = _scope_key(cfg)
+            close_scoped_sync_transports_for(key)
+            close_scoped_transports_for(key)
+            # Prune the ONE memo entry this scope resolved, keyed exactly as
+            # `_resolve_named_connection` keys it: ``(name, role.upper() or None)``.
+            #
+            # It must be exactly one, because `_close_one_session` below closes exactly one
+            # session (``cfg.connection``). Pruning every entry for the NAME would drop a
+            # sibling ``using(name, role="B")``'s entry while leaving B's session open and
+            # unreferenced -- so the next ``using(name, role="B")`` mints a duplicate and
+            # the orphan leaks until `close_connections()`, the opposite of what close=True
+            # is for. A scope with no entry at all (raw credentials, a live connection, a
+            # Snowpark Session -- none of which `_resolve_named_connection` stores)
+            # correctly prunes nothing.
+            #
+            # NOT matched on identity the way `_replace_cached_config` does: that one is
+            # handed the memo's own object, whereas `resolve_config` returns a config
+            # DERIVED from the memoised one, so `is` never matches here and the prune would
+            # silently do nothing. Verified: the Config `using()` yields is not the object
+            # in the cache.
+            kw = cfg.connector_kwargs or {}
+            cache_name = kw.get("connection_name")
+            if cache_name:
+                cache_key = (str(cache_name), (kw.get("role") or "").upper() or None)
+                with _lock:
+                    _resolution_cache.pop(cache_key, None)
+            _close_one_session(cfg.connection)
+
+
+def close_connections() -> None:
+    """Close the connector sessions, clear the resolution cache, drop bound transports.
+
+    That list is the whole of what it does, and the name now says so. It was
+    ``reset_config()``, a leftover from the deleted ``configure()`` that described
+    something this function never did -- there is no config to reset -- and which read as
+    "put the SDK back to unconfigured" when it is really "release what is open".
+
+    The SDK's teardown. Each connection resolution mints and *retains* a live connector
+    session in `_session_registry` so its bearer token stays valid, so without this a
+    long-lived process accumulates live authenticated connections (and their sockets).
+
+    Clearing the resolution memo alongside them is what keeps the two consistent: a
+    cached `Config` holds the session being closed, and serving it again would
+    authenticate from a dead session. Nothing is lost, because the memo is reproducible
+    -- the next call re-resolves from ``connections.toml`` and logs in again. So this is
+    a release, NOT an un-configure: the SDK keeps working afterwards.
+
+    Also drops every explicitly-bound (``connection=`` / ``using()``) transport, for the
+    same reason: those carry their `Config`, which may hold a session this call just
+    closed, and leaving one pooled would authenticate from it on the next request. The
+    ambient transport is left alone -- it re-resolves through `current_config` on every
+    request, so it recovers by itself.
+    """
+    from snowflake.sandbox._sync_transport import reset_scoped_sync_transports
+    from snowflake.sandbox._transport import reset_scoped_transports
+
+    with _lock:
+        # The cached Configs hold the sessions the next line closes.
+        _resolution_cache.clear()
+    _close_session_registry()
+    reset_scoped_transports()
+    reset_scoped_sync_transports()
+
+
+# --- credential refresh ------------------------------------------------------
+#
+# The connector-session registry and the reactive renew/reconnect path live in
+# ``_session_registry`` (``_close_session_registry``, ``_renew_or_reconnect``,
+# ``_reconnect``, ``_close_connection``, ``_retire_connection``, ``refresh_config``,
+# ``refresh_credential``) — re-exported at the top of this module. Only the shared
+# state they mutate stays here: ``_lock`` / ``_resolution_cache`` (the resolved-connection
+# memo), the ``_session_registry`` list, and the ``_refresh_lock`` below.
+
+# Snowflake error codes that mean "re-authenticate": 390111 session gone,
+# 390112 session expired (renewable off the master token), 390114 master expired,
+# 390115 master invalid. The transport keys its reactive re-mint on these.
+REAUTH_GS_CODES: Final[frozenset[str]] = frozenset({"390111", "390112", "390114", "390115"})
+
+# Serializes reactive re-mints so a concurrent burst of reauth failures produces
+# exactly one renew/reconnect. Deliberately SEPARATE from ``_lock``: the connector
+# I/O runs while holding THIS lock, never ``_lock``, so config readers
+# (``current_config`` on the request hot path) are not blocked on the network.
+_refresh_lock = threading.Lock()
+
+
+# --- connection resolution ---------------------------------------------------
+#
+# The named-connection resolution machinery (``_config_from_connection``,
+# ``_config_from_live_connection``, ``_connection_fields``,
+# ``_host_from_connection_fields``, ``_default_connection_name``,
+# ``_connector_config_manager``) lives in ``_connection_resolve`` and is
+# re-exported at the top of this module. The two helpers that stay here —
+# ``_config_files`` and ``refresh_connection_config`` — are the home/TOML plumbing
+# those functions build on; ``_warn_pat_fallback`` (below) is the PAT-exchange
+# fallback warning they emit.
+
+
+def _config_files() -> tuple[Path, Path]:
+    """``(config.toml, connections.toml)`` for the current home, honouring
+    ``SNOWFLAKE_HOME`` the way the connector does (our old code used
+    ``Path.home()`` and ignored it)."""
+    from pathlib import Path
+
+    root = os.environ.get("SNOWFLAKE_HOME")
+    base = Path(root).expanduser() if root else Path.home() / ".snowflake"
+    return base / "config.toml", base / "connections.toml"
+
+
+def refresh_connection_config() -> None:
+    """Re-point the connector's ``CONFIG_MANAGER`` at the current home and re-read,
+    so a later ``connect(connection_name=...)`` resolves the same files
+    ``_config_from_connection`` did. Needed before the stage-PUT reconnect because
+    the manager is a process-global that caches its last read (and we pass a
+    connection *name*, not a file path, so config.toml connections resolve too).
+
+    This re-reads the on-disk TOML only; it does **not** re-authenticate or refresh a
+    token. A stale session token is not renewed here — the transport's reactive re-mint
+    (`refresh_credential`) does that, and `close_connections` forces a clean re-resolve.
+
+    Drops the memoised connection resolutions: their Configs were built from the TOML as
+    it read a moment ago, and the point of this call is that it may now say something
+    different. Sessions already handed out are left running -- a caller holding a handle
+    keeps the connection it was built with; only the next resolution sees the new
+    file."""
+    _connector_config_manager()
+    with _lock:
+        _resolution_cache.clear()
+
+
+def _warn_pat_fallback(name: str, exc: Exception) -> None:
+    warnings.warn(
+        f"connection {name!r}: could not exchange the PAT for a session token "
+        f"({type(exc).__name__}: {exc}); using the PAT directly. Snowflake "
+        "access from inside the sandbox (e.g. Cortex Code) may fail with "
+        "'Invalid OAuth access token'.",
+        RuntimeWarning,
+        stacklevel=2,
+    )