cmpnd 0.44.0__tar.gz → 0.46.0__tar.gz

{cmpnd-0.44.0 → cmpnd-0.46.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cmpnd
-Version: 0.44.0
+Version: 0.46.0
 Summary: DSPy observability and deployment SDK for cmpnd
 Project-URL: Homepage, https://cmpnd.ai
 Author-email: cmpnd <hello@cmpnd.ai>

{cmpnd-0.44.0 → cmpnd-0.46.0}/cmpnd/__init__.py

@@ -15,6 +15,8 @@ Usage:
 import importlib.metadata
 from typing import TYPE_CHECKING
 
+from cmpnd_ingest.client_floor import UpgradeRequiredWarning
+
 from . import authored, programs, traces
 from ._http import ApiError
 from .callback import CmpndCallback, trace_id
@@ -46,7 +48,7 @@ from .deployment_runs import (
 )
 from .execution import DeployedProgram, RetryableProviderError, deployment_run_id, execute
 from .exporter import flush_exporter, shutdown_exporter
-from .lm_configuration import configure_lm
+from .lm_configuration import SystemOne, configure_lm
 from .mcp_servers import (
     Bearer,
     McpToolReference,
@@ -80,6 +82,7 @@ __all__ = [
     # Configuration
     "configure",
     "configure_lm",
+    "SystemOne",
     "get_config",
     "require_config",
     # Main callback
@@ -110,6 +113,8 @@ __all__ = [
     "program",
     "authored",
     "ApiError",
+    # Raised once when the server no longer supports this release
+    "UpgradeRequiredWarning",
     # Types
     "SpanType",
     "TraceStatus",

{cmpnd-0.44.0 → cmpnd-0.46.0}/cmpnd/_authored_import.py

@@ -118,16 +118,14 @@ def _program_facts(
 ) -> dict[str, Any]:
     """Everything the deployment create call reads off the imported program."""
 
-    from . import configuration, deployment, identity, mcp_servers, packaging
+    from . import _http, configuration, deployment, identity, mcp_servers, packaging
     from .authored import ProgramFacts
 
     references = deployment._mcp_tool_references(program)
     pinned: dict[tuple[str, str], Any] = {}
     if references:
-        import httpx
-
         config = configuration.require_config()
-        with httpx.Client(timeout=30) as client:
+        with _http.new_client(timeout=30) as client:
             pinned = deployment._resolve_mcp_tool_references(client, config, references)
     tool_references = [
         {

{cmpnd-0.44.0 → cmpnd-0.46.0}/cmpnd/_http.py

@@ -13,8 +13,10 @@ from __future__ import annotations
 import os
 import re
 from typing import Any
+from urllib.parse import urlsplit
 
 import httpx
+from cmpnd_ingest import client_floor
 
 
 class ApiError(Exception):
@@ -76,6 +78,48 @@ def server_detail(response: httpx.Response) -> str:
     return (response.text or "").strip()[:2000]
 
 
+def new_client(**kwargs: Any) -> httpx.Client:
+    """An ``httpx.Client`` that warns when the server no longer supports this
+    release (:mod:`cmpnd_ingest.client_floor`).
+
+    Every client the SDK builds comes from here, so every answer the platform
+    sends gets the check. A caller's own ``event_hooks`` run after it.
+    """
+    hooks = client_floor.event_hooks()
+    for event, callers in (kwargs.pop("event_hooks", None) or {}).items():
+        hooks.setdefault(event, []).extend(callers)
+    return httpx.Client(event_hooks=hooks, **kwargs)
+
+
+_DEFAULT_PORTS = {"http": 80, "https": 443}
+
+
+def _origin(url: str) -> tuple[str, str, int] | None:
+    """A URL's (scheme, host, port), or None when it cannot be read as one."""
+    try:
+        parts = urlsplit(url)
+        port = parts.port
+    except ValueError:
+        return None
+    scheme = parts.scheme.lower()
+    if scheme not in _DEFAULT_PORTS or not parts.hostname:
+        return None
+    return scheme, parts.hostname.lower(), port if port is not None else _DEFAULT_PORTS[scheme]
+
+
+def upload_auth_headers(upload_url: str, endpoint: str, api_key: str) -> dict[str, str]:
+    """The authentication header for a PUT to an ``upload_url`` serve advertised.
+
+    Serve authenticates its upload routes with the API key. The SDK sends the URL
+    as given, so the key goes only to a URL on the configured endpoint's origin:
+    the same scheme, host and port. Any other origin gets no key.
+    """
+    own = _origin(endpoint)
+    if not api_key or own is None or _origin(upload_url) != own:
+        return {}
+    return {"X-API-Key": api_key}
+
+
 class ApiClient:
     """Thin HTTP client for the cmpnd backend API."""
 
@@ -150,7 +194,7 @@ class ApiClient:
         url = f"{self._endpoint}{path}"
         timeout = self.configured_timeout()
         try:
-            with httpx.Client(
+            with new_client(
                 headers={"X-API-Key": self._api_key, "Content-Type": "application/json"},
                 timeout=timeout,
             ) as client:

{cmpnd-0.44.0 → cmpnd-0.46.0}/cmpnd/callback.py

@@ -383,6 +383,10 @@ def _lm15_cache_hit(entry: Any, response: Any) -> bool | None:
 
 def _usage_dialect(instance: Any, usage: Any) -> str | None:
     """Name the response surface only when its shape establishes one."""
+    # A decision client (DSPy's `TypeSafe`) speaks System One. Its usage names chat's token
+    # fields, so the shape alone would misname it. DSPy dispatches on the same flag.
+    if getattr(instance, "supports_decision_requests", False) is True:
+        return "system_one"
     model_type = _text_field(instance, "model_type")
     if model_type == "responses":
         return "responses"
@@ -1489,7 +1493,8 @@ class _LMMixin(_CallbackBase):
             observation.usage_dialect = _usage_dialect(instance, usage)
             if observation.usage_dialect in {"chat_completions", "responses"}:
                 observation.prompt_inclusion = "includes_cache_reads"
-            elif observation.usage_dialect == "converse":
+            elif observation.usage_dialect in {"converse", "system_one"}:
+                # System One serves nothing from a cache, so its prompt is all fresh input.
                 observation.prompt_inclusion = "excludes_cache_reads"
 
             if usage_reported and usage is not None:

{cmpnd-0.44.0 → cmpnd-0.46.0}/cmpnd/dataset_sync.py

@@ -10,9 +10,7 @@ from __future__ import annotations
 import logging
 from typing import Any
 
-import httpx
-
-from . import configuration, identity, models
+from . import _http, configuration, identity, models
 
 logger = logging.getLogger(__name__)
 
@@ -37,7 +35,7 @@ def check_dataset_exists(dataset_hash: str) -> bool:
     url = f"{config.endpoint}/api/v1/datasets/check/{dataset_hash}"
 
     try:
-        with httpx.Client(timeout=5.0) as client:
+        with _http.new_client(timeout=5.0) as client:
             response = client.get(
                 url,
                 headers={"Authorization": f"Bearer {config.api_key}"},

{cmpnd-0.44.0 → cmpnd-0.46.0}/cmpnd/datasets.py

@@ -8,9 +8,7 @@ from __future__ import annotations
 
 from typing import Any
 
-import httpx
-
-from . import configuration
+from . import _http, configuration
 
 
 class DatasetNotFoundError(Exception):
@@ -114,7 +112,7 @@ def _fetch_dataset(
         params["version"] = str(version)
 
     # Make request to backend
-    with httpx.Client(timeout=30.0) as client:
+    with _http.new_client(timeout=30.0) as client:
         response = client.get(
             url,
             params=params,

{cmpnd-0.44.0 → cmpnd-0.46.0}/cmpnd/deployment.py

@@ -17,7 +17,18 @@ from typing import Any
 
 import httpx
 
-from . import authored, configuration, deployment_metadata, execution, identity, mcp_servers, models, packaging, retry
+from . import (
+    _http,
+    authored,
+    configuration,
+    deployment_metadata,
+    execution,
+    identity,
+    mcp_servers,
+    models,
+    packaging,
+    retry,
+)
 
 logger = logging.getLogger(__name__)
 
@@ -427,7 +438,7 @@ def deploy(module, metric=None, timeout=300, metadata=None, *, program_id=None):
     references = _mcp_tool_references(module)
     pinned_mcp_tools: dict[tuple[str, str], Any] = {}
     if references:
-        with httpx.Client(timeout=httpx.Timeout(_TIMEOUT_SECONDS, connect=_CONNECT_TIMEOUT_SECONDS)) as client:
+        with _http.new_client(timeout=httpx.Timeout(_TIMEOUT_SECONDS, connect=_CONNECT_TIMEOUT_SECONDS)) as client:
             pinned_mcp_tools = _resolve_mcp_tool_references(client, config, references)
 
     # Package the module
@@ -539,7 +550,7 @@ def _deploy_prepared(
     """Create, upload, and poll one fully prepared source bundle."""
     headers = {"X-API-Key": config.api_key, "Content-Type": "application/json"}
 
-    with httpx.Client(timeout=httpx.Timeout(_TIMEOUT_SECONDS, connect=_CONNECT_TIMEOUT_SECONDS)) as client:
+    with _http.new_client(timeout=httpx.Timeout(_TIMEOUT_SECONDS, connect=_CONNECT_TIMEOUT_SECONDS)) as client:
         created = _send_retrying(
             lambda: client.post(
                 f"{config.endpoint}/api/v1/deployments",
@@ -568,12 +579,13 @@ def _deploy_prepared(
             )
         for warning in answer.get("warnings") or []:
             logger.warning("deploy: %s", warning)
+        upload_url = answer["upload_url"]
+        upload_headers = {
+            "Content-Type": "application/zip",
+            **_http.upload_auth_headers(upload_url, config.endpoint, config.api_key),
+        }
         uploaded = _send_retrying(
-            lambda: client.put(
-                answer["upload_url"],
-                content=zip_bytes,
-                headers={"Content-Type": "application/zip"},
-            ),
+            lambda: client.put(upload_url, content=zip_bytes, headers=upload_headers),
             "upload deployment ZIP",
             may_resend_with_no_answer=lambda _: True,
             may_resend_after_answer=_repeatable_answer,

{cmpnd-0.44.0 → cmpnd-0.46.0}/cmpnd/deployment_runs.py

@@ -327,7 +327,7 @@ class _RunClient:
         self.retry_after = 0.0
 
     def __enter__(self) -> _RunClient:
-        self.client = httpx.Client(headers={"X-API-Key": self.api_key})
+        self.client = _http.new_client(headers={"X-API-Key": self.api_key})
         return self
 
     def __exit__(self, *_: object) -> None:

{cmpnd-0.44.0 → cmpnd-0.46.0}/cmpnd/lm_configuration.py

@@ -9,11 +9,25 @@ class LMConfigurationError(ValueError):
     """A hosted binding declaration cannot be resolved consistently."""
 
 
-class LMCapabilities(TypedDict):
-    """Explicit adapter hints for a hosted model, independent of its provider."""
+class LMCapabilities(TypedDict, total=False):
+    """Explicit adapter hints for a hosted model, independent of its provider.
+
+    ``dialect`` is present only for a System One binding, which :class:`SystemOne`
+    writes. Absent, the binding is a chat model.
+    """
 
     supported_params: list[str]
     supports_response_schema: bool
+    dialect: str
+
+
+# The wire protocol a binding's model speaks, named for the protocol and never for a
+# provider or a client library: a chat model answers chat completions, and a System One
+# model (TypeSafe's System One protocol, which other providers serve too) answers a set
+# of questions about a state.
+CHAT_COMPLETIONS = "chat_completions"
+SYSTEM_ONE = "system_one"
+_DIALECTS = frozenset({CHAT_COMPLETIONS, SYSTEM_ONE})
 
 
 def _validate_lm_capabilities(value: object) -> dict[str, LMCapabilities]:
@@ -27,7 +41,7 @@ def _validate_lm_capabilities(value: object) -> dict[str, LMCapabilities]:
             )
         if not isinstance(declaration, dict):
             raise LMConfigurationError(f"lm_capabilities[{binding!r}] must be a capability declaration")
-        unknown = declaration.keys() - {"supported_params", "supports_response_schema"}
+        unknown = declaration.keys() - {"supported_params", "supports_response_schema", "dialect"}
         if unknown:
             raise LMConfigurationError(f"lm_capabilities[{binding!r}] has unknown fields: {sorted(unknown, key=str)}")
         params = declaration.get("supported_params", [])
@@ -38,11 +52,24 @@ def _validate_lm_capabilities(value: object) -> dict[str, LMCapabilities]:
         schema = declaration.get("supports_response_schema", False)
         if not isinstance(schema, bool):
             raise LMConfigurationError(f"lm_capabilities[{binding!r}].supports_response_schema must be a boolean")
+        dialect = declaration.get("dialect", CHAT_COMPLETIONS)
+        if dialect not in _DIALECTS:
+            raise LMConfigurationError(
+                f"lm_capabilities[{binding!r}].dialect must be one of {sorted(_DIALECTS)} (got {dialect!r})"
+            )
+        if dialect == SYSTEM_ONE and (params or schema):
+            raise LMConfigurationError(
+                f"lm_capabilities[{binding!r}] is a System One binding, which takes no sampling "
+                "parameters and no response schema"
+            )
         if schema and "response_format" not in params:
             raise LMConfigurationError(
                 f"lm_capabilities[{binding!r}] requires response_format in supported_params for schema output"
             )
-        result[binding] = {"supported_params": list(dict.fromkeys(params)), "supports_response_schema": schema}
+        hints: LMCapabilities = {"supported_params": list(dict.fromkeys(params)), "supports_response_schema": schema}
+        if dialect == SYSTEM_ONE:
+            hints["dialect"] = SYSTEM_ONE
+        result[binding] = hints
     return result
 
 
@@ -122,6 +149,11 @@ def configure_lm(
             )
         _merge(_names, _name(lm), hints)
         return
+    _declare(lm, hints)
+
+
+def _declare(lm: Any, hints: dict[str, Any]) -> None:
+    """Attach a declaration to one LM object, shared by every binding made from it."""
     model = _model(lm)
     declared = _object_declaration(lm)
     if declared is not None and declared != (model, hints):
@@ -131,6 +163,38 @@ def configure_lm(
         _objects.append(lm)
 
 
+class SystemOne:
+    """A System One decision model, for a run's ``lms``.
+
+    A System One model answers a set of questions about a state instead of continuing a
+    conversation: TypeSafe's Jev, or another endpoint serving the same schema. A hosted
+    judge built on ``dspy.experimental.TypeSafe`` runs against the run's System One
+    binding without naming a key or a URL::
+
+        cmpnd.optimize(..., lms={"judge": cmpnd.SystemOne("typesafe/jev-latest")})
+
+    ``model`` is a platform model id: the prefix names the organization's sealed
+    credential, and the rest is the model at that credential's endpoint. Writing the
+    binding this way is the only thing that makes it a System One binding; a model name
+    on its own never does.
+    """
+
+    def __init__(self, model: object):
+        if not isinstance(model, str) or not model.strip():
+            raise ValueError(f"cmpnd.SystemOne needs a model id such as 'typesafe/jev-latest' (got {model!r})")
+        credential, _, name = model.strip().partition("/")
+        if not credential or not name:
+            raise ValueError(
+                f"cmpnd.SystemOne({model!r}) names no credential: write the model as "
+                "'<credential>/<model>', for example 'typesafe/jev-latest'"
+            )
+        self.model = model.strip()
+        _declare(self, {"supported_params": [], "supports_response_schema": False, "dialect": SYSTEM_ONE})
+
+    def __repr__(self) -> str:
+        return f"cmpnd.SystemOne({self.model!r})"
+
+
 def restore(declarations: object) -> None:
     """Load model-pinned declarations from a packaged artifact."""
     if not isinstance(declarations, dict):

{cmpnd-0.44.0 → cmpnd-0.46.0}/cmpnd/mcp_servers.py

@@ -669,15 +669,14 @@ def _registered_tools(url: str, timeout_s: float) -> list[PinnedTool] | None | o
     the registry route, so notebook use keeps its existing direct connection.
     ``None`` means the configured registry answered and does not know this server.
     """
-    from . import configuration
+    from . import _http, configuration
 
     config = configuration.get_config()
     if config is None:
         return _NO_PLATFORM_REGISTRY
-    import httpx
 
     headers = {"X-API-Key": config.api_key}
-    with httpx.Client(timeout=timeout_s) as client:
+    with _http.new_client(timeout=timeout_s) as client:
         listing = client.get(f"{config.endpoint}/api/v1/org/tool-servers", headers=headers)
         if listing.status_code == 404:
             return _NO_PLATFORM_REGISTRY

{cmpnd-0.44.0 → cmpnd-0.46.0}/cmpnd/optimization.py

@@ -462,6 +462,23 @@ def _lms_config(config: dict[str, Any], lms: Any) -> None:
         if isinstance(lm, str):
             declared[name] = {"model": lm}
             continue
+        from .lm_configuration import SystemOne
+
+        if isinstance(lm, SystemOne):
+            # A System One model takes no sampling, and its declaration (which says it
+            # is one) travels in the bundle rather than on the wire.
+            declared[name] = {"model": lm.model}
+            continue
+        if getattr(lm, "supports_decision_requests", False):
+            # dspy.experimental.TypeSafe, or a client like it: it carries a key and a URL
+            # rather than the name of a sealed credential, so the platform has nothing to
+            # resolve. Duck-typed so this module never imports dspy at scope.
+            raise ValueError(
+                f"{subject} is a {type(lm).__name__} client, which names a key and a URL rather "
+                f"than a credential. Bind the model with cmpnd.SystemOne, for example "
+                f"lms={{{name!r}: cmpnd.SystemOne('typesafe/jev-latest')}}; a judge that builds "
+                f"its own {type(lm).__name__} runs against that binding when hosted"
+            )
         model = _lm_model(lm, subject)
         _refuse_credential_on(lm, model, subject)
         entry: dict[str, Any] = {"model": model}
@@ -991,7 +1008,7 @@ def _run_steps(
     current_deployment_id = deployment_id
     non_improving = 0
 
-    with httpx.Client(timeout=_HTTP_TIMEOUT_SECONDS) as client:
+    with _http.new_client(timeout=_HTTP_TIMEOUT_SECONDS) as client:
         for step in range(max_steps):
             data = "upload" if step == 0 else "reuse"
             step_config = dict(config)
@@ -1014,7 +1031,7 @@ def _run_steps(
             optimization_id = initiated["optimization_id"]
 
             if data == "upload":
-                _upload_bundle(client, initiated, bundle)
+                _upload_bundle(client, initiated, bundle, endpoint=cfg.endpoint, api_key=cfg.api_key)
 
             status = _poll_until_terminal(
                 client,
@@ -1226,7 +1243,7 @@ def _refuse_conflicting_members(
     headers = {"X-API-Key": cfg.api_key}
     conflicting: list[str] = []
     try:
-        with httpx.Client(timeout=_HTTP_TIMEOUT_SECONDS) as client:
+        with _http.new_client(timeout=_HTTP_TIMEOUT_SECONDS) as client:
             listing = client.get(f"{cfg.endpoint}/api/v1/deployments/{deployment_id}/source", headers=headers)
             if not listing.is_success:
                 return
@@ -1397,26 +1414,21 @@ def _initiate_step(
     )
 
 
-def _upload_bundle(client: httpx.Client, initiated: dict[str, Any], bundle: bytes) -> None:
+def _upload_bundle(
+    client: httpx.Client, initiated: dict[str, Any], bundle: bytes, *, endpoint: str, api_key: str
+) -> None:
     """Upload the optimization bundle to the slot the initiate step returned.
 
-    Two postures, one path — keyed on ``upload_fields`` exactly as the deploy
-    upload is:
-
-    - **Presigned POST** (the deploy Lambda stack): ``upload_fields`` is a
-      non-empty form the destination key is pinned by; the bundle rides as the
-      ``file`` part of a multipart POST.
-    - **PUT** (the on-prem worker-sandbox): no form fields — the URL *is* the
-      slot. The bundle is the raw PUT body.
-
-    serve normalizes the awaiting_data response so both keys are always present
-    (``upload_method`` defaulting to PUT, ``upload_fields`` to ``{}``), so the
-    branch here is just "are there presigned fields to post."
+    Serve answers an ``awaiting_data`` initiate with ``upload_url``, ``upload_method:
+    "PUT"`` and empty ``upload_fields``, and the bundle goes out as the raw PUT body.
+    Serve authenticates that route with the API key, which rides the PUT only when
+    ``upload_url`` is on ``endpoint``'s origin (``_http.upload_auth_headers``). A
+    non-empty ``upload_fields`` is a presigned form, which no current server sends.
+    The bundle then rides as the ``file`` part of a multipart POST.
 
-    Both postures write to a slot the destination key is already pinned to, so
-    re-sending the same bytes overwrites the same object — this call is
-    idempotent by construction, and rides through a transient answer *and* a
-    transport blip alike.
+    The slot pins its destination, so re-sending the same bytes writes the same
+    object. That makes this call idempotent, so it rides through a transient answer
+    and a transport blip alike.
     """
     upload_url = initiated.get("upload_url")
     if not upload_url:
@@ -1424,6 +1436,7 @@ def _upload_bundle(client: httpx.Client, initiated: dict[str, Any], bundle: byte
     upload_fields = initiated.get("upload_fields")
     method = (initiated.get("upload_method") or ("POST" if upload_fields else "PUT")).upper()
     what = "upload optimization bundle"
+    auth = _http.upload_auth_headers(upload_url, endpoint, api_key)
 
     if upload_fields:
         resp = _request(
@@ -1431,6 +1444,7 @@ def _upload_bundle(client: httpx.Client, initiated: dict[str, Any], bundle: byte
                 upload_url,
                 data=dict(upload_fields),
                 files={"file": ("data.zip", bundle, "application/zip")},
+                headers=auth,
             ),
             what,
         )
@@ -1440,7 +1454,7 @@ def _upload_bundle(client: httpx.Client, initiated: dict[str, Any], bundle: byte
                 method,
                 upload_url,
                 content=bundle,
-                headers={"Content-Type": "application/zip"},
+                headers={"Content-Type": "application/zip", **auth},
             ),
             what,
         )

{cmpnd-0.44.0 → cmpnd-0.46.0}/docs/cli.md

@@ -32,6 +32,16 @@ retries, because a second send would create a second program.
 `cmpnd.programs.create(name=...)` makes the same call from Python and returns
 the row.
 
+## When the server no longer supports your release
+
+Every answer from the platform names the oldest `cmpnd` release it supports.
+When yours is older, the CLI and the SDK warn once per process and name the
+upgrade, `pip install -U cmpnd`. The server still answers, so an older release
+keeps working wherever nothing it relies on has changed. To stay on an older
+release without the warning, set `CMPND_NO_UPGRADE_WARNING=1`. In code,
+`warnings.filterwarnings("ignore", category=cmpnd.UpgradeRequiredWarning)`
+does the same.
+
 ## Deploy flow (Docker-style)
 
 These commands print human-readable output by default. Each takes `--json` for

{cmpnd-0.44.0 → cmpnd-0.46.0}/docs/sdk-instrumentation.md

@@ -73,6 +73,27 @@ endpoint accept JSON schemas. Undeclared bindings keep prompt-only JSON. These
 hints do not add a format the provider cannot accept or change local DSPy's
 capability lookup.
 
+### System One judges
+
+A System One model answers a set of questions about a state instead of continuing
+a conversation. TypeSafe's Jev is one, and other endpoints serve the same schema.
+Declare one for a run with `cmpnd.SystemOne`:
+
+```python
+cmpnd.optimize(..., lms={"judge": cmpnd.SystemOne("typesafe/jev-latest")})
+```
+
+The prefix names the organization's sealed credential and the rest names the
+model at that credential's endpoint. Writing the binding this way is the only
+thing that makes it a System One binding; a model name never does. The binding
+carries no sampling, and its declaration travels in the bundle like any other.
+
+Hosted, a judge built on `dspy.experimental.TypeSafe` runs unchanged. The kernel
+replaces `TypeSafe` with a client that spends the run's System One binding, so
+the judge's own model, key and base URL are not used. With several System One
+bindings, the judge picks one through `lms[name]`. A `TypeSafe` object passed in
+`lms` is refused, because it names a key and a URL rather than a credential.
+
 ## The callback
 
 `python-sdk/cmpnd/callback.py` implements `CmpndCallback`, which satisfies `dspy.utils.callback.BaseCallback` without inheriting it — `callback.py` must import on the standard library alone (`tests/test_import_weight.py`), so it cannot import dspy to get a base class. DSPy calls its hook methods synchronously on whatever thread is executing the module. The callback owns no long-lived state beyond a per-call span builder map; everything trace/span related flows through context vars (see next section).
@@ -285,6 +306,10 @@ Two callers implement the waiting:
 - **`exporter_http._send_json_retrying`** waits on the shutdown event rather than sleeping, so a backoff can't hold the process open at exit (and the post-shutdown drain gets no retries at all, deliberately).
 - **`optimization._request`** clips every wait by the caller's `timeout` deadline, which stays the outer bound of `optimize()`. See [the optimize loop](#the-optimize-loop-and-transient-tolerance) below.
 
+### The server says when this release is too old
+
+Every API answer names the oldest cmpnd release the server supports, in the `X-Cmpnd-Minimum-Client-Version` header. `cmpnd_ingest/client_floor.py` reads it in an httpx response hook. When the installed `cmpnd` is older, it raises an `UpgradeRequiredWarning` once per process that names both versions and the command `pip install -U cmpnd`. The server refuses nothing for a client's version, so a call below the floor still goes through, and the warning appears beside whatever it does. Every client the SDK builds comes from `cmpnd._http.new_client`, which installs the hook, and the exporter installs it in `_client_kwargs`. `tests/test_client_floor.py` fails on an `httpx.Client` built any other way in `cmpnd/`. An install of `cmpnd_ingest` without `cmpnd` has no version to compare and says nothing. `CMPND_NO_UPGRADE_WARNING=1` silences the warning for a user who stays on an older release on purpose, and the warning names that switch. `cmpnd.UpgradeRequiredWarning` is public, so a `warnings` filter silences it in code.
+
 ### The optimize loop and transient tolerance
 
 `optimization._poll_until_terminal` is what a caller blocks on for the length of a run, so one transient answer or one reset connection must not destroy a healthy run. It rides through transient answers on the shared budget, resetting after each successful poll, and never extends past the caller's `timeout` (default 600s per step) — a backoff wait is clipped by the deadline rather than overshooting it.
@@ -333,6 +358,11 @@ done.
 | `PUT upload_url` (the ZIP) | retried — the slot pins the key and the bytes are fixed, so a re-send overwrites the same object | retried, for the same reason |
 | `GET /api/v1/deployments/{id}` (poll) | retried on the next tick — a read is repeatable | retried on the next tick |
 
+Serve authenticates its upload routes with the API key. The deploy upload and
+the optimization bundle upload send `X-API-Key` when `upload_url` has the
+configured endpoint's scheme, host and port (`_http.upload_auth_headers`). A URL
+on any other origin gets no key.
+
 After the poll reports ready, the SDK reads
 `GET /api/v1/deployments/{id}/signature`. This bounded read returns persisted
 artifact metadata and never asks a worker or analytics store. A failed metadata