launchhelm 0.1.0__py3-none-any.whl

launchhelm/client.py

@@ -0,0 +1,1660 @@
+"""Synchronous HTTP client for the LaunchHelm v1 API.
+
+Contract: HTTPS is required outside loopback. Request bodies that are already
+encoded bytes are sent unchanged so telemetry fingerprints stay stable.
+Responses larger than 8 MiB are rejected. Redirects are not followed.
+
+Failure: ``LaunchHelmError`` for transport uncertainty (retryable), HTTP
+problem documents, and invalid JSON. ``ValueError`` for a malformed base URL
+or organization id.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import uuid
+from collections.abc import Sequence
+from datetime import UTC, datetime, timedelta
+from pathlib import Path
+from typing import Protocol
+from urllib.parse import urlparse
+
+import httpx
+
+from ._version import __version__
+from .errors import LaunchHelmError
+from .models import (
+    AckInput,
+    AckResult,
+    AnalysisClaimInput,
+    AnalysisLeaseInput,
+    AnalysisReport,
+    AnalysisRunInput,
+    DeliveryClaimInput,
+    DeliveryPage,
+    Document,
+    ExportInput,
+    InvitationInput,
+    InvitationResendInput,
+    NotificationDispatchResult,
+    NotificationInput,
+    NotificationReadInput,
+    PublicDocument,
+    PublicDocumentPage,
+    PublicViewInput,
+    PublicViewPublication,
+    PublicViewToken,
+    PublicViewUpdate,
+    Query,
+    QueryResult,
+    RetentionHoldInput,
+    RetentionPlan,
+    RetentionRestoreInput,
+    Scope,
+    UsageInput,
+    UsageReport,
+)
+from .store import TelemetryBatch
+from .transport import AbortableTransport
+from .values import (
+    JSONObject,
+    JSONValue,
+    as_json_value,
+    encode,
+    json_object,
+    string_object,
+)
+
+MAX_RESPONSE_BYTES = 8 << 20
+UPLOAD_TIMEOUT_SECONDS = 120
+MIN_PART_SIZE = 5 << 20
+MAX_PART_SIZE = 64 << 20
+MAX_PARTS = 10000
+
+
+class RuntimeClient(Protocol):
+    """Subset of ``Client`` required by ``Runtime``.
+
+    Contract: implementations must allow concurrent calls from the runtime's
+    control thread, uploader thread, and caller thread. ``httpx.Client``
+    satisfies this; test doubles must not share mutable response buffers
+    without their own locking.
+
+    Failure: methods raise ``LaunchHelmError`` using the same codes as
+    ``Client``.
+    """
+
+    base_url: str
+    organization_id: str
+
+    def get_document(self, document_id: str, *, revision: str = "") -> Document:
+        """See ``Client.get_document``."""
+
+    def connect(
+        self,
+        participant_id: str,
+        instance_id: str,
+        *,
+        safe_points: tuple[str, ...] = (),
+        attempt_id: str = "",
+    ) -> JSONObject:
+        """See ``Client.connect``."""
+
+    def heartbeat(
+        self, participant_id: str, epoch: str, *, safe_points: tuple[str, ...] = ()
+    ) -> JSONObject:
+        """See ``Client.heartbeat``."""
+
+    def claim(self, participant_id: str, epoch: str, *, wait_ms: int = 0) -> JSONObject | None:
+        """See ``Client.claim``."""
+
+    def create_document(self, kind: str, scope: Scope, spec: JSONObject) -> Document:
+        """See ``Client.create_document``."""
+
+    def list_documents(
+        self,
+        *,
+        kind: str = "",
+        project_id: str = "",
+        run_id: str = "",
+        cursor: str = "",
+        limit: int = 100,
+    ) -> JSONObject:
+        """See ``Client.list_documents``."""
+
+    def query(
+        self,
+        stream_id: str,
+        *,
+        start: str,
+        end: str,
+        limit: int = 1000,
+        order: str = "",
+        after_epoch: str = "",
+        after_sequence: str = "",
+    ) -> JSONObject:
+        """See ``Client.query``."""
+
+    def get_command(self, command_id: str) -> JSONObject:
+        """See ``Client.get_command``."""
+
+    def begin(self, command: JSONObject) -> JSONObject:
+        """See ``Client.begin``."""
+
+    def report(self, command: JSONObject, result: JSONObject) -> JSONObject:
+        """See ``Client.report``."""
+
+    def renew(self, command: JSONObject) -> None:
+        """See ``Client.renew``."""
+
+    def ingest(self, batch: TelemetryBatch) -> JSONObject:
+        """See ``Client.ingest``."""
+
+    def abort(self) -> None:
+        """See ``Client.abort``."""
+
+
+class SessionClient(RuntimeClient, Protocol):
+    """Subset of ``Client`` required by ``init`` and ``Run``.
+
+    Contract: adds the document administration calls a session uses beyond
+    the runtime surface. Capability-dependent calls (``create_key``,
+    ``upload_file``, ``download_artifact``) stay optional and are probed
+    with ``getattr``.
+
+    Failure: methods raise ``LaunchHelmError`` using the same codes as
+    ``Client``.
+    """
+
+    def update_document(self, document: Document, spec: JSONObject) -> Document:
+        """See ``Client.update_document``."""
+
+    def close(self) -> None:
+        """See ``Client.close``."""
+
+
+class Client:
+    """Authenticated LaunchHelm HTTP client.
+
+    Contract: every JSON request body is ``encode``d unless the caller passes
+    already-encoded bytes (telemetry ingest). The process must not put
+    credentials in ``base_url``.
+
+    Failure: see module docstring.
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        api_key: str,
+        organization_id: str,
+        *,
+        transport: httpx.BaseTransport | None = None,
+        timeout: float = 30,
+    ) -> None:
+        parsed = urlparse(base_url)
+        if parsed.username or parsed.password or parsed.query or parsed.fragment:
+            raise ValueError("base URL must not contain credentials, query, or fragment")
+        if parsed.scheme != "https" and not (
+            parsed.scheme == "http" and parsed.hostname in {"localhost", "127.0.0.1", "::1"}
+        ):
+            raise ValueError("HTTPS is required outside loopback")
+        uuid.UUID(organization_id)
+        self.base_url = base_url.rstrip("/")
+        self.organization_id = organization_id
+        self._api_key = api_key
+        self._timeout = timeout
+        self._transport: httpx.BaseTransport = (
+            transport if transport is not None else AbortableTransport()
+        )
+        self.http = httpx.Client(
+            base_url=self.base_url,
+            timeout=timeout,
+            follow_redirects=False,
+            transport=self._transport,
+            headers={
+                "Authorization": f"Bearer {api_key}",
+                "X-LaunchHelm-Protocol": "1.0",
+                "User-Agent": f"launchhelm-python/{__version__}",
+            },
+        )
+        self._prefix = f"/v1/organizations/{organization_id}"
+
+    def close(self) -> None:
+        """Close the underlying HTTP pool.
+
+        Contract: idle connections are released; further requests raise from
+        httpx. A request blocked in another thread is not interrupted; use
+        ``abort`` for that.
+
+        Failure: none.
+        """
+        self.http.close()
+
+    def abort(self) -> None:
+        """Fail in-flight requests immediately, then close the pool.
+
+        Contract: with the default transport, a parked long-poll claim in
+        another thread raises ``LaunchHelmError("transport")`` within
+        milliseconds; ``Runtime.close`` relies on this so shutdown does not
+        wait out the claim. A caller-supplied transport that lacks ``abort``
+        is only closed.
+
+        Failure: none.
+        """
+        abort = getattr(self._transport, "abort", None)
+        if callable(abort):
+            abort()
+        self.close()
+
+    def __enter__(self) -> Client:
+        """Return ``self`` for ``with Client(...)`` usage.
+
+        Contract: ``__exit__`` closes the pool.
+
+        Failure: none.
+        """
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        """Close the client, ignoring the block exception.
+
+        Contract: does not suppress exceptions from the ``with`` body.
+
+        Failure: none.
+        """
+        self.close()
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        data: JSONValue | bytes | None = None,
+        *,
+        idempotency_key: str | None = None,
+        params: dict[str, JSONValue] | None = None,
+        timeout: float | None = None,
+        bearer: str | None = None,
+    ) -> JSONValue:
+        """Send one HTTP request and parse a JSON response.
+
+        Contract: ``data`` bytes are sent unchanged; other values are passed
+        through ``encode``. Problem-document errors become ``LaunchHelmError``.
+        ``timeout`` overrides the client default for this request only.
+        ``bearer`` replaces the client API key on this request.
+
+        Failure: ``ValueError`` for a non-relative path. ``LaunchHelmError``
+        for transport, oversize responses, invalid JSON, or HTTP errors.
+        """
+        if not path.startswith("/") or path.startswith("//"):
+            raise ValueError("API path must be relative to the configured server")
+        headers = {"Content-Type": "application/json"}
+        if bearer is not None:
+            headers["Authorization"] = f"Bearer {bearer}"
+        if idempotency_key:
+            headers["Idempotency-Key"] = idempotency_key
+        content = data if isinstance(data, bytes) else (encode(data) if data is not None else None)
+        query = _query_params(params)
+        stream_timeout = timeout if timeout is not None else self.http.timeout
+        try:
+            with self.http.stream(
+                method,
+                path,
+                content=content,
+                headers=headers,
+                params=query,
+                timeout=stream_timeout,
+            ) as response:
+                chunks = bytearray()
+                for chunk in response.iter_bytes():
+                    chunks.extend(chunk)
+                    if len(chunks) > MAX_RESPONSE_BYTES:
+                        raise LaunchHelmError("response_too_large", "Use a smaller page")
+                try:
+                    parsed: object = json.loads(chunks)
+                except (ValueError, UnicodeError):
+                    if response.status_code >= 300:
+                        # A proxy or load balancer answered (for example a 502
+                        # page while the API restarts). Classify by status so
+                        # a deploy is retried like any other 5xx.
+                        raise LaunchHelmError(
+                            "http_error",
+                            f"HTTP {response.status_code} without a problem document",
+                            status=response.status_code,
+                            retryable=response.status_code >= 500 or response.status_code == 429,
+                        ) from None
+                    raise LaunchHelmError(
+                        "invalid_response",
+                        "Server returned invalid JSON",
+                        status=response.status_code,
+                    ) from None
+                result = _json_value(parsed)
+                if response.status_code >= 300:
+                    problem = result.get("error") if isinstance(result, dict) else None
+                    details = problem if isinstance(problem, dict) else {}
+                    code = details.get("code")
+                    message = details.get("message")
+                    retryable_flag = details.get("retryable", False)
+                    raise LaunchHelmError(
+                        code if isinstance(code, str) else "http_error",
+                        message if isinstance(message, str) else "Request failed",
+                        status=response.status_code,
+                        retryable=(retryable_flag if isinstance(retryable_flag, bool) else False)
+                        or response.status_code >= 500,
+                    )
+                return result
+        except httpx.HTTPError:
+            raise LaunchHelmError(
+                "transport", "Request delivery or outcome is uncertain", retryable=True
+            ) from None
+
+    def create_document(self, kind: str, scope: Scope, spec: JSONObject) -> Document:
+        """Create a resource in ``scope``.
+
+        Contract: ``scope.organization_id`` must match this client.
+
+        Failure: ``ValueError`` on organization mismatch. ``LaunchHelmError``
+        from the server.
+        """
+        if scope.organization_id != self.organization_id:
+            raise ValueError("organization scope mismatch")
+        return Document.parse(
+            json_object(
+                self.request(
+                    "POST",
+                    self._prefix + "/documents",
+                    {
+                        "kind": kind,
+                        "scope": string_object(scope.wire()),
+                        "spec": spec,
+                    },
+                ),
+                what="document",
+            )
+        )
+
+    def create_documents(self, documents: list[tuple[str, Scope, JSONObject]]) -> list[Document]:
+        """Create every document in one request.
+
+        Contract: the server commits the batch together. ``documents`` holds
+        one to 1024 ``(kind, scope, spec)`` triples. Every scope uses this
+        client's organization.
+
+        Failure: ``ValueError`` on an empty batch, a batch over 1024, or an
+        organization mismatch. ``LaunchHelmError`` from the server. A rejected
+        batch creates nothing.
+        """
+        if not documents or len(documents) > 1024:
+            raise ValueError("document batch must contain 1 to 1024 documents")
+        body: list[JSONValue] = []
+        for kind, scope, spec in documents:
+            if scope.organization_id != self.organization_id:
+                raise ValueError("organization scope mismatch")
+            body.append(
+                {
+                    "kind": kind,
+                    "scope": string_object(scope.wire()),
+                    "spec": spec,
+                }
+            )
+        result = json_object(
+            self.request("POST", self._prefix + "/document-batches", {"documents": body}),
+            what="document batch",
+        )
+        opened = result.get("documents")
+        if not isinstance(opened, list) or len(opened) != len(documents):
+            raise LaunchHelmError("protocol", "document batch length does not match")
+        return [Document.parse(json_object(item, what="document")) for item in opened]
+
+    def create_key(self, participant: Document) -> JSONObject:
+        """Mint a worker key bound to ``participant`` and its run.
+
+        Contract: the key can connect, write telemetry, and read or create
+        documents in that run. It expires in seven days. The token is returned
+        once.
+
+        Failure: ``ValueError`` on organization mismatch. ``LaunchHelmError``
+        from the server.
+        """
+        scope = participant.scope
+        if scope.organization_id != self.organization_id:
+            raise ValueError("organization scope mismatch")
+        expires = (datetime.now(UTC) + timedelta(days=7)).strftime("%Y-%m-%dT%H:%M:%SZ")
+        return json_object(
+            self.request(
+                "POST",
+                self._prefix + "/keys",
+                {
+                    "name": "logger",
+                    "participant_id": participant.id,
+                    "expires_at": expires,
+                    "grants": [
+                        {
+                            "effect": "allow",
+                            "scope": string_object(scope.wire()),
+                            "actions": [
+                                "participant.connect",
+                                "telemetry.write",
+                                "document.create",
+                                "document.read",
+                                "document.list",
+                                "document.update",
+                                "artifact.write",
+                                "artifact.download",
+                                "command.claim",
+                                "command.report",
+                            ],
+                            "kinds": ["*"],
+                            "resources": ["*"],
+                            "bounds": {},
+                        }
+                    ],
+                },
+            ),
+            what="key",
+        )
+
+    def adopt(self, token: str) -> None:
+        """Use ``token`` for later requests from this client."""
+        self.http.headers["Authorization"] = f"Bearer {token}"
+
+    def with_key(self) -> Client:
+        """Return a client on this origin using the construction credential.
+
+        Contract: the credential this client was built with is reused — not a
+        token later installed by ``adopt``. The derived client owns its own
+        connection pool; the caller closes it. The credential stays in
+        memory only.
+
+        Failure: same as construction.
+        """
+        return Client(
+            self.base_url,
+            self._api_key,
+            self.organization_id,
+            timeout=self._timeout,
+        )
+
+    def end_session(
+        self, participant_id: str, epoch: str, *, close_run: str = "never"
+    ) -> JSONObject:
+        """End the participant's live session epoch.
+
+        Contract: ``close_run`` is ``never`` or ``when_idle``. With
+        ``when_idle`` the run document closes when no other participant still
+        holds a live session epoch. Re-ending an already finished epoch
+        succeeds. The response carries the finished ``session`` epoch record
+        and ``run_closed``.
+
+        Failure: ``ValueError`` for a malformed id or unknown policy.
+        ``LaunchHelmError`` ``conflict`` when ``epoch`` is not the live
+        epoch, ``forbidden`` for a credential not bound to the participant.
+        """
+        uuid.UUID(participant_id)
+        if close_run not in {"never", "when_idle"}:
+            raise ValueError("close_run must be never or when_idle")
+        return json_object(
+            self.request(
+                "POST",
+                self._prefix + f"/participants/{participant_id}/session/end",
+                {"epoch": epoch, "close_run": close_run},
+            ),
+            what="session end",
+        )
+
+    def get_document(self, document_id: str, *, revision: str = "") -> Document:
+        """Fetch a resource by id, optionally at a historical revision.
+
+        Contract: ``document_id`` must be a UUID.
+
+        Failure: ``ValueError`` from ``uuid.UUID``. ``LaunchHelmError`` from
+        the server.
+        """
+        uuid.UUID(document_id)
+        return Document.parse(
+            json_object(
+                self.request(
+                    "GET",
+                    self._prefix + f"/documents/{document_id}",
+                    params={"revision": revision} if revision else None,
+                ),
+                what="document",
+            )
+        )
+
+    def update_document(self, document: Document, spec: JSONObject) -> Document:
+        """Patch ``document`` expecting its current revision.
+
+        Contract: uses ``expected_revision`` for optimistic concurrency.
+
+        Failure: ``LaunchHelmError`` with ``conflict`` if the revision moved.
+        """
+        return Document.parse(
+            json_object(
+                self.request(
+                    "PATCH",
+                    self._prefix + f"/documents/{document.id}",
+                    {"expected_revision": document.revision, "spec": spec},
+                ),
+                what="document",
+            )
+        )
+
+    def list_documents(
+        self,
+        *,
+        kind: str = "",
+        project_id: str = "",
+        run_id: str = "",
+        cursor: str = "",
+        limit: int = 100,
+    ) -> JSONObject:
+        """List resources with the given filters.
+
+        Contract: empty filters are sent as empty strings; the server treats
+        them as unconstrained.
+
+        Failure: ``LaunchHelmError`` from the server.
+        """
+        return json_object(
+            self.request(
+                "GET",
+                self._prefix + "/documents",
+                params={
+                    "kind": kind,
+                    "project_id": project_id,
+                    "run_id": run_id,
+                    "cursor": cursor,
+                    "limit": limit,
+                },
+            ),
+            what="document list",
+        )
+
+    def submit_command(self, request: JSONObject, *, idempotency_key: str) -> JSONObject:
+        """Submit a command with a caller-chosen idempotency key.
+
+        Contract: repeating the same key and fingerprint returns the original
+        command; a different fingerprint with the same key is a conflict.
+
+        Failure: ``LaunchHelmError`` from the server.
+        """
+        return json_object(
+            self.request(
+                "POST",
+                self._prefix + "/commands",
+                request,
+                idempotency_key=idempotency_key,
+            ),
+            what="command",
+        )
+
+    def get_command(self, command_id: str) -> JSONObject:
+        """Fetch a command by id.
+
+        Contract: ``command_id`` must be a UUID.
+
+        Failure: ``ValueError`` from ``uuid.UUID``. ``LaunchHelmError`` from
+        the server.
+        """
+        uuid.UUID(command_id)
+        return json_object(
+            self.request("GET", self._prefix + f"/commands/{command_id}"),
+            what="command",
+        )
+
+    def decide_command(self, command: JSONObject, action: str) -> JSONObject:
+        """Approve or cancel ``command`` using its fingerprint.
+
+        Contract: ``action`` is ``approve`` or ``cancel``.
+
+        Failure: ``ValueError`` for an unknown action. ``LaunchHelmError``
+        from the server.
+        """
+        if action not in {"approve", "cancel"}:
+            raise ValueError("invalid command decision")
+        return json_object(
+            self.request(
+                "POST",
+                self._prefix + f"/commands/{command['id']}/{action}",
+                {"fingerprint": command["fingerprint"]},
+            ),
+            what="command",
+        )
+
+    def events(self, *, cursor: str = "0", limit: int = 100) -> JSONObject:
+        """Read a page of organization events.
+
+        Contract: ``cursor`` ``0`` starts at the beginning of the log.
+
+        Failure: ``LaunchHelmError`` from the server.
+        """
+        return json_object(
+            self.request(
+                "GET",
+                self._prefix + "/events",
+                params={"cursor": cursor, "limit": limit},
+            ),
+            what="events",
+        )
+
+    def claim_deliveries(
+        self,
+        subscription_id: str,
+        input_: DeliveryClaimInput | None = None,
+    ) -> DeliveryPage:
+        """Lease one ordered delivery batch from an event subscription.
+
+        Contract: unacknowledged deliveries are at-least-once. The returned
+        lease id and cursor must be passed to ``ack_deliveries`` after durable
+        consumer handling.
+
+        Failure: ``ValueError`` for a malformed id. ``LaunchHelmError`` from
+        the server.
+        """
+        uuid.UUID(subscription_id)
+        return DeliveryPage.parse(
+            json_object(
+                self.request(
+                    "POST",
+                    self._prefix + f"/event-subscriptions/{subscription_id}/claim",
+                    (input_ or DeliveryClaimInput()).wire(),
+                ),
+                what="delivery_page",
+            )
+        )
+
+    def ack_deliveries(
+        self,
+        subscription_id: str,
+        input_: AckInput,
+    ) -> AckResult:
+        """Cumulatively acknowledge deliveries held by one lease."""
+        uuid.UUID(subscription_id)
+        return AckResult.parse(
+            json_object(
+                self.request(
+                    "POST",
+                    self._prefix + f"/event-subscriptions/{subscription_id}/ack",
+                    input_.wire(),
+                ),
+                what="ack_result",
+            )
+        )
+
+    def dispatch_notification(self, input_: NotificationInput) -> NotificationDispatchResult:
+        """Queue, deduplicate, or preference-suppress one notification."""
+        return NotificationDispatchResult.parse(
+            json_object(
+                self.request("POST", self._prefix + "/notifications", input_.wire()),
+                what="notification_dispatch_result",
+            )
+        )
+
+    def list_notifications(
+        self,
+        *,
+        account_id: str = "",
+        state: str = "",
+        cursor: str = "",
+        limit: int = 50,
+    ) -> JSONObject:
+        """Return one inbox page, optionally filtered by account and state."""
+        return json_object(
+            self.request(
+                "GET",
+                self._prefix + "/notifications",
+                params={
+                    "account_id": account_id,
+                    "state": state,
+                    "cursor": cursor,
+                    "limit": limit,
+                },
+            ),
+            what="notification_page",
+        )
+
+    def read_notification(
+        self,
+        notification_id: str,
+        input_: NotificationReadInput | None = None,
+    ) -> Document:
+        """Mark a notification read, optionally guarded by revision."""
+        uuid.UUID(notification_id)
+        return Document.parse(
+            json_object(
+                self.request(
+                    "POST",
+                    self._prefix + f"/notifications/{notification_id}/read",
+                    (input_ or NotificationReadInput()).wire(),
+                ),
+                what="document",
+            )
+        )
+
+    def publish_public_view(self, input_: PublicViewInput) -> PublicViewPublication:
+        """Preview or store a public view.
+
+        Contract: ``confirm`` false returns the projection and writes nothing.
+        ``input_.scope.organization_id`` must match this client.
+
+        Failure: ``ValueError`` on organization mismatch. ``LaunchHelmError``
+        from the server.
+        """
+        if input_.scope.organization_id != self.organization_id:
+            raise ValueError("organization scope mismatch")
+        return PublicViewPublication.parse(
+            json_object(
+                self.request("POST", self._prefix + "/public-views", input_.wire()),
+                what="public_view_publication",
+            )
+        )
+
+    def update_public_view(
+        self, document_id: str, input_: PublicViewUpdate
+    ) -> PublicViewPublication:
+        """Revise a public view.
+
+        Contract: ``document_id`` is a UUID. Snapshot views cannot gain
+        resources, paths, or surfaces.
+
+        Failure: ``ValueError`` from ``uuid.UUID``. ``LaunchHelmError`` from
+        the server.
+        """
+        uuid.UUID(document_id)
+        return PublicViewPublication.parse(
+            json_object(
+                self.request(
+                    "PATCH",
+                    self._prefix + f"/public-views/{document_id}",
+                    input_.wire(),
+                ),
+                what="public_view_publication",
+            )
+        )
+
+    def mint_public_view_token(self, document_id: str) -> PublicViewToken:
+        """Mint a one-time public-view bearer token.
+
+        Contract: the returned token is the only copy. ``document_id`` is a UUID.
+
+        Failure: ``ValueError`` from ``uuid.UUID``. ``LaunchHelmError`` from
+        the server.
+        """
+        uuid.UUID(document_id)
+        return PublicViewToken.parse(
+            json_object(
+                self.request("POST", self._prefix + f"/public-views/{document_id}/tokens"),
+                what="public_view_token",
+            )
+        )
+
+    def revoke_public_view(self, document_id: str) -> Document:
+        """Disable a public view and revoke its live tokens.
+
+        Contract: ``document_id`` is a UUID. A second call is idempotent.
+
+        Failure: ``ValueError`` from ``uuid.UUID``. ``LaunchHelmError`` from
+        the server.
+        """
+        uuid.UUID(document_id)
+        return Document.parse(
+            json_object(
+                self.request("POST", self._prefix + f"/public-views/{document_id}/revoke"),
+                what="document",
+            )
+        )
+
+    def list_public_documents(self, token: str) -> PublicDocumentPage:
+        """List the documents a public token may read.
+
+        Contract: ``token`` is sent as the bearer credential for this call
+        only. The client's API key is not used.
+
+        Failure: ``ValueError`` when ``token`` is empty. ``LaunchHelmError``
+        from the server.
+        """
+        self._require_public_token(token)
+        return PublicDocumentPage.parse(
+            json_object(
+                self.request("GET", "/v1/public/documents", bearer=token),
+                what="public_document_page",
+            )
+        )
+
+    def read_public_document(self, token: str, document_id: str) -> PublicDocument:
+        """Read one published document.
+
+        Contract: ``token`` authenticates this call. ``document_id`` is a UUID.
+
+        Failure: ``ValueError`` for an empty token or a non-UUID id.
+        ``LaunchHelmError`` from the server.
+        """
+        self._require_public_token(token)
+        uuid.UUID(document_id)
+        return PublicDocument.parse(
+            json_object(
+                self.request("GET", f"/v1/public/documents/{document_id}", bearer=token),
+                what="public_document",
+            )
+        )
+
+    def run_public_query(self, token: str, query: Query) -> QueryResult:
+        """Evaluate a query inside the public view's published series.
+
+        Contract: ``token`` authenticates this call. Select sources are bound
+        to the view's organization by the server.
+
+        Failure: ``ValueError`` when ``token`` is empty. ``LaunchHelmError``
+        from the server.
+        """
+        self._require_public_token(token)
+        return QueryResult.parse(
+            json_object(
+                self.request("POST", "/v1/public/queries", query.wire(), bearer=token),
+                what="query_result",
+            )
+        )
+
+    def read_public_artifact(self, token: str, document_id: str) -> PublicDocument:
+        """Read one published artifact document.
+
+        Contract: ``token`` authenticates this call. ``document_id`` is a UUID.
+
+        Failure: ``ValueError`` for an empty token or a non-UUID id.
+        ``LaunchHelmError`` from the server.
+        """
+        self._require_public_token(token)
+        uuid.UUID(document_id)
+        return PublicDocument.parse(
+            json_object(
+                self.request("GET", f"/v1/public/artifacts/{document_id}", bearer=token),
+                what="public_document",
+            )
+        )
+
+    def download_artifact(self, document_id: str) -> bytes:
+        """Download an artifact's bytes.
+
+        Contract: ``GET .../download`` returns a URL. This method follows it
+        and returns the body.
+
+        Failure: ``ValueError`` from ``uuid.UUID``. ``LaunchHelmError`` when
+        the download document has no URL, the signed target is insecure, or
+        the fetch fails.
+        """
+        uuid.UUID(document_id)
+        body = json_object(
+            self.request("GET", self._prefix + f"/artifacts/{document_id}/download"),
+            what="download",
+        )
+        url = body.get("url")
+        if not isinstance(url, str) or not url:
+            raise LaunchHelmError("protocol", "artifact download has no url")
+        _check_download_url(url)
+        try:
+            # The signed object request must not inherit API auth or cookies.
+            response = self.http.send(httpx.Request("GET", url), auth=None, follow_redirects=False)
+            response.raise_for_status()
+        except httpx.HTTPError as error:
+            raise LaunchHelmError("transport", "artifact download failed") from error
+        return response.content
+
+    def download_public_artifact(self, token: str, document_id: str) -> str:
+        """Return a short-lived download URL for a published ready artifact.
+
+        Contract: ``token`` authenticates this call. ``document_id`` is a UUID.
+
+        Failure: ``ValueError`` for an empty token or a non-UUID id.
+        ``LaunchHelmError`` when the server omits a URL or rejects the call.
+        """
+        self._require_public_token(token)
+        uuid.UUID(document_id)
+        signed = json_object(
+            self.request(
+                "GET",
+                f"/v1/public/artifacts/{document_id}/download",
+                bearer=token,
+            ),
+            what="url",
+        )
+        url = signed.get("url")
+        if not isinstance(url, str) or url == "":
+            raise LaunchHelmError("invalid_response", "Download response is missing a URL")
+        return url
+
+    def create_invitation(self, input_: InvitationInput) -> Document:
+        """Create a pending invitation for one verified email address."""
+        return Document.parse(
+            json_object(
+                self.request("POST", self._prefix + "/invitations", input_.wire()),
+                what="document",
+            )
+        )
+
+    def list_invitations(self, *, cursor: str = "", limit: int = 50) -> JSONObject:
+        """Return one page of organization invitations."""
+        return json_object(
+            self.request(
+                "GET",
+                self._prefix + "/invitations",
+                params={"cursor": cursor, "limit": limit},
+            ),
+            what="invitation_page",
+        )
+
+    def resend_invitation(self, document_id: str, input_: InvitationResendInput) -> Document:
+        """Record another send and extend a pending invitation."""
+        uuid.UUID(document_id)
+        return Document.parse(
+            json_object(
+                self.request(
+                    "POST",
+                    self._prefix + f"/invitations/{document_id}/resend",
+                    input_.wire(),
+                ),
+                what="document",
+            )
+        )
+
+    def revoke_invitation(self, document_id: str) -> Document:
+        """Revoke a pending invitation."""
+        uuid.UUID(document_id)
+        return Document.parse(
+            json_object(
+                self.request("POST", self._prefix + f"/invitations/{document_id}/revoke", {}),
+                what="document",
+            )
+        )
+
+    def accept_invitation(self, document_id: str) -> Document:
+        """Accept an invitation addressed to this account's verified email."""
+        uuid.UUID(document_id)
+        return Document.parse(
+            json_object(
+                self.request("POST", self._prefix + f"/invitations/{document_id}/accept", {}),
+                what="document",
+            )
+        )
+
+    def decline_invitation(self, document_id: str) -> Document:
+        """Decline an invitation addressed to this account's verified email."""
+        uuid.UUID(document_id)
+        return Document.parse(
+            json_object(
+                self.request("POST", self._prefix + f"/invitations/{document_id}/decline", {}),
+                what="document",
+            )
+        )
+
+    def list_my_invitations(self) -> JSONObject:
+        """Return pending invitations addressed to the caller's verified email."""
+        return json_object(self.request("GET", "/v1/invitations"), what="invitation_inbox")
+
+    def dispatch_analysis(self, input_: AnalysisRunInput, *, idempotency_key: str) -> Document:
+        """Queue one analysis run. The same key and input return the original run."""
+        return Document.parse(
+            json_object(
+                self.request(
+                    "POST",
+                    self._prefix + "/analysis-runs",
+                    input_.wire(),
+                    idempotency_key=idempotency_key,
+                ),
+                what="document",
+            )
+        )
+
+    def claim_analysis(self, document_id: str, input_: AnalysisClaimInput) -> Document:
+        """Lease a queued analysis run for this connected worker."""
+        uuid.UUID(document_id)
+        return Document.parse(
+            json_object(
+                self.request(
+                    "POST",
+                    self._prefix + f"/analysis-runs/{document_id}/claim",
+                    input_.wire(),
+                ),
+                what="document",
+            )
+        )
+
+    def start_analysis(self, document_id: str, input_: AnalysisLeaseInput) -> Document:
+        """Move a leased analysis run from dispatched to running."""
+        uuid.UUID(document_id)
+        return Document.parse(
+            json_object(
+                self.request(
+                    "POST",
+                    self._prefix + f"/analysis-runs/{document_id}/start",
+                    input_.wire(),
+                ),
+                what="document",
+            )
+        )
+
+    def report_analysis(self, document_id: str, input_: AnalysisReport) -> Document:
+        """Record a terminal result for the analysis run this worker holds."""
+        uuid.UUID(document_id)
+        return Document.parse(
+            json_object(
+                self.request(
+                    "POST",
+                    self._prefix + f"/analysis-runs/{document_id}/report",
+                    input_.wire(),
+                ),
+                what="document",
+            )
+        )
+
+    def cancel_analysis(self, document_id: str) -> Document:
+        """Cancel a live analysis run and release its unacked work item."""
+        uuid.UUID(document_id)
+        return Document.parse(
+            json_object(
+                self.request("POST", self._prefix + f"/analysis-runs/{document_id}/cancel", {}),
+                what="document",
+            )
+        )
+
+    def record_usage(self, input_: UsageInput) -> Document:
+        """Record one usage measurement. The idempotency key is a body field."""
+        return Document.parse(
+            json_object(
+                self.request("POST", self._prefix + "/usage", input_.wire()),
+                what="document",
+            )
+        )
+
+    def report_usage(self, *, start: str = "", end: str = "") -> UsageReport:
+        """Sum the usage ledger over an optional half-open window."""
+        params: dict[str, JSONValue] = {}
+        if start:
+            params["from"] = start
+        if end:
+            params["to"] = end
+        return UsageReport.parse(
+            json_object(
+                self.request("GET", self._prefix + "/usage", params=params or None),
+                what="usage_report",
+            )
+        )
+
+    def create_export(self, input_: ExportInput, *, idempotency_key: str) -> Document:
+        """Queue one pinned export. The same key and input return the original export."""
+        return Document.parse(
+            json_object(
+                self.request(
+                    "POST",
+                    self._prefix + "/exports",
+                    input_.wire(),
+                    idempotency_key=idempotency_key,
+                ),
+                what="document",
+            )
+        )
+
+    def cancel_export(self, document_id: str) -> Document:
+        """Stop a queued or running export before its artifact is published."""
+        uuid.UUID(document_id)
+        return Document.parse(
+            json_object(
+                self.request("POST", self._prefix + f"/exports/{document_id}/cancel"),
+                what="document",
+            )
+        )
+
+    def plan_retention(self, policy_id: str) -> RetentionPlan:
+        """Dry-run one retention policy without hiding documents."""
+        uuid.UUID(policy_id)
+        return RetentionPlan.parse(
+            json_object(
+                self.request(
+                    "POST",
+                    self._prefix + f"/retention-policies/{policy_id}/plan",
+                ),
+                what="retention_plan",
+            )
+        )
+
+    def create_retention_hold(self, input_: RetentionHoldInput) -> Document:
+        """Pin one document so retention will not hide it."""
+        return Document.parse(
+            json_object(
+                self.request("POST", self._prefix + "/retention-holds", input_.wire()),
+                what="document",
+            )
+        )
+
+    def release_retention_hold(self, document_id: str) -> Document:
+        """Release a hold so the pinned document can be deleted again."""
+        uuid.UUID(document_id)
+        return Document.parse(
+            json_object(
+                self.request(
+                    "POST",
+                    self._prefix + f"/retention-holds/{document_id}/release",
+                ),
+                what="document",
+            )
+        )
+
+    def restore_retention(self, input_: RetentionRestoreInput) -> Document:
+        """Return a hidden document to the catalog before its bytes are purged."""
+        return Document.parse(
+            json_object(
+                self.request("POST", self._prefix + "/retention-restores", input_.wire()),
+                what="document",
+            )
+        )
+
+    def _require_public_token(self, token: str) -> None:
+        if token == "":
+            raise ValueError("public view token is required")
+
+    def query(
+        self,
+        stream_id: str,
+        *,
+        start: str,
+        end: str,
+        limit: int = 1000,
+        order: str = "",
+        after_epoch: str = "",
+        after_sequence: str = "",
+    ) -> JSONObject:
+        """Query telemetry points in ``[start, end]``.
+
+        Contract: ``stream_id`` must be a UUID. ``order="desc"`` returns the
+        newest points first. ``after_epoch`` and ``after_sequence`` together
+        skip rows at ``start`` that are not strictly after that point, so a
+        page whose points share one timestamp can continue. This is not an
+        analytical query engine; the server enforces bounded pages.
+
+        Failure: ``ValueError`` from ``uuid.UUID``. ``LaunchHelmError`` from
+        the server.
+        """
+        uuid.UUID(stream_id)
+        params: dict[str, JSONValue] = {"from": start, "to": end, "limit": limit}
+        if order:
+            params["order"] = order
+        if after_epoch and after_sequence:
+            params["after_epoch"] = after_epoch
+            params["after_sequence"] = after_sequence
+        return json_object(
+            self.request(
+                "GET",
+                self._prefix + f"/streams/{stream_id}/points",
+                params=params,
+            ),
+            what="points",
+        )
+
+    def read_samples(
+        self,
+        stream_id: str,
+        *,
+        axis: JSONObject | None = None,
+        select: JSONObject,
+    ) -> JSONObject:
+        """Read bounded samples of one stream for a rich renderer.
+
+        Contract: mirrors ``POST /telemetry/samples`` — ``axis`` is an
+        ``axis_spec`` object (defaults to the ``step`` coordinate axis)
+        and ``select`` a ``samples_select`` object such as
+        ``{"mode": "latest", "limit": 16}``, ``{"mode": "at",
+        "values": ["10"]}``, ``{"mode": "spread", "limit": 64,
+        "window": {...}}``, or ``{"mode": "index", "limit": 256}``.
+        Returns the ``samples_result`` object: ``points`` carry ``x`` and
+        the stored ``value`` (omitted for ``index``), ``complete`` is
+        false when the response was truncated, and ``media`` maps media
+        artifact ids to authorized download entries.
+
+        Failure: ``ValueError`` from ``uuid.UUID``. ``LaunchHelmError``
+        from the server.
+        """
+        uuid.UUID(stream_id)
+        payload: JSONObject = {
+            "stream_id": stream_id,
+            "axis": axis or {"kind": "coordinate", "name": "step"},
+            "select": select,
+        }
+        return json_object(
+            self.request(
+                "POST",
+                self._prefix + "/telemetry/samples",
+                payload,
+            ),
+            what="samples",
+        )
+
+    def run_query(self, organization_id: str, query: Query) -> QueryResult:
+        """Evaluate an ad-hoc telemetry query.
+
+        Contract: ``organization_id`` must match this client. ``query`` is
+        sent as its wire document.
+
+        Failure: ``ValueError`` from ``uuid.UUID`` or an organization
+        mismatch. ``LaunchHelmError`` from the server.
+        """
+        self._require_organization(organization_id)
+        return QueryResult.parse(
+            json_object(
+                self.request(
+                    "POST",
+                    f"/v1/organizations/{organization_id}/telemetry/queries",
+                    query.wire(),
+                ),
+                what="query_result",
+            )
+        )
+
+    def run_saved_query(
+        self, organization_id: str, query_id: str, *, revision: str | None = None
+    ) -> QueryResult:
+        """Evaluate a stored query document, optionally at ``revision``.
+
+        Contract: ``organization_id`` must match this client. ``query_id``
+        must be a UUID. Empty ``revision`` selects the current document.
+
+        Failure: ``ValueError`` from ``uuid.UUID`` or an organization
+        mismatch. ``LaunchHelmError`` from the server.
+        """
+        self._require_organization(organization_id)
+        uuid.UUID(query_id)
+        body: JSONObject = {}
+        if revision:
+            body["revision"] = revision
+        return QueryResult.parse(
+            json_object(
+                self.request(
+                    "POST",
+                    f"/v1/organizations/{organization_id}/queries/{query_id}/run",
+                    body,
+                ),
+                what="query_result",
+            )
+        )
+
+    def list_my_organizations(self) -> list[tuple[str, str]]:
+        """Return ``(id, name)`` for every organization this key can see.
+
+        Contract: ``GET /v1/organizations`` is account-scoped. The client's
+        organization id is not part of the request. Pages follow
+        ``next_cursor`` until the server ends the list.
+
+        Failure: ``LaunchHelmError`` from the server or a malformed page.
+        """
+        cursor = ""
+        found: list[tuple[str, str]] = []
+        for _ in range(100):
+            page = json_object(
+                self.request(
+                    "GET",
+                    "/v1/organizations",
+                    params={"cursor": cursor, "limit": 100},
+                ),
+                what="organization list",
+            )
+            items = page.get("items") or []
+            if not isinstance(items, list):
+                raise LaunchHelmError("protocol", "organization list is not a page")
+            for item in items:
+                if not isinstance(item, dict):
+                    raise LaunchHelmError("protocol", "organization list entry is invalid")
+                identity = item.get("id")
+                if not isinstance(identity, str):
+                    raise LaunchHelmError("protocol", "organization list entry is invalid")
+                name = item.get("name")
+                found.append((identity, name if isinstance(name, str) else ""))
+            next_cursor = page.get("next_cursor") or ""
+            if not isinstance(next_cursor, str) or not next_cursor or next_cursor == cursor:
+                break
+            cursor = next_cursor
+        return found
+
+    def _require_organization(self, organization_id: str) -> None:
+        uuid.UUID(organization_id)
+        if organization_id != self.organization_id:
+            raise ValueError("organization scope mismatch")
+
+    def connect(
+        self,
+        participant_id: str,
+        instance_id: str,
+        *,
+        safe_points: tuple[str, ...] = (),
+        attempt_id: str = "",
+    ) -> JSONObject:
+        """Open an execution session for ``participant_id``.
+
+        Contract: ``instance_id`` identifies this process. The returned
+        ``epoch`` is the session fence token. ``safe_points`` is the full set
+        of cooperative names this runtime services; Claim returns only commands
+        whose ``safe_point`` is empty or in this set. ``attempt_id`` binds
+        emitted provenance to the active attempt. Repeating Connect with the
+        same instance and attempt does not fence in-flight commands and grows
+        the serviced safe-point set.
+
+        Failure: ``LaunchHelmError`` from the server.
+        """
+        body: JSONObject = {
+            "instance_id": instance_id,
+            "safe_points": list(safe_points),
+        }
+        if attempt_id:
+            body["attempt_id"] = attempt_id
+        return json_object(
+            self.request(
+                "POST",
+                self._prefix + f"/participants/{participant_id}/sessions",
+                body,
+            ),
+            what="session",
+        )
+
+    def heartbeat(
+        self,
+        participant_id: str,
+        epoch: str,
+        *,
+        safe_points: tuple[str, ...] = (),
+    ) -> JSONObject:
+        """Renew the execution session identified by ``epoch``.
+
+        Contract: a conflict means this runtime is fenced. Optional
+        ``safe_points`` are unioned into the session (same validation and cap
+        as Connect) without fencing. Connect still declares the initial set.
+
+        Failure: ``LaunchHelmError``; ``conflict`` is the fence signal.
+        """
+        body: JSONObject = {"epoch": epoch}
+        if safe_points:
+            body["safe_points"] = list(safe_points)
+        return json_object(
+            self.request(
+                "POST",
+                self._prefix + f"/participants/{participant_id}/heartbeat",
+                body,
+            ),
+            what="session",
+        )
+
+    def claim(self, participant_id: str, epoch: str, *, wait_ms: int = 0) -> JSONObject | None:
+        """Claim the next command for this participant and epoch.
+
+        Contract: returns ``None`` when the queue is empty. ``wait_ms`` is a
+        bounded server-side long poll (0 is immediate). The HTTP timeout is
+        set above ``wait_ms`` so a parked claim is not aborted by the client.
+
+        Failure: ``LaunchHelmError`` from the server.
+        """
+        body: JSONObject = {"epoch": epoch}
+        timeout: float | None = None
+        if wait_ms > 0:
+            body["wait_ms"] = wait_ms
+            timeout = wait_ms / 1000 + 6
+        payload = json_object(
+            self.request(
+                "POST",
+                self._prefix + f"/participants/{participant_id}/commands",
+                body,
+                timeout=timeout,
+            ),
+            what="claim",
+        )
+        command = payload.get("command")
+        if command is None:
+            return None
+        return json_object(command, what="command")
+
+    def begin(self, command: JSONObject) -> JSONObject:
+        """Mark ``command`` as applying under its lease.
+
+        Contract: must be called after local journal phase ``starting`` and
+        before the handler. A definitive rejection is not retried as success.
+
+        Failure: ``LaunchHelmError`` from the server.
+        """
+        request = json_object(command.get("request") or {}, what="command request")
+        return json_object(
+            self.request(
+                "POST",
+                self._prefix + f"/commands/{command['id']}/begin",
+                {"lease_id": command["lease_id"], "epoch": request["epoch"]},
+            ),
+            what="command",
+        )
+
+    def report(self, command: JSONObject, result: JSONObject) -> JSONObject:
+        """Publish a command result (applied, rejected, or outcome_unknown).
+
+        Contract: unknown effects stay unknown; this method does not re-run
+        the handler.
+
+        Failure: ``LaunchHelmError`` from the server. A conflict on a
+        rejected result is reconciled by the runtime.
+        """
+        return json_object(
+            self.request("POST", self._prefix + f"/commands/{command['id']}/result", result),
+            what="command",
+        )
+
+    def renew(self, command: JSONObject) -> None:
+        """Renew the lease of an in-flight command.
+
+        Contract: a conflict means the lease is already terminal.
+
+        Failure: ``LaunchHelmError`` from the server.
+        """
+        request = json_object(command.get("request") or {}, what="command request")
+        self.request(
+            "POST",
+            self._prefix + f"/commands/{command['id']}/heartbeat",
+            {"lease_id": command["lease_id"], "epoch": request["epoch"]},
+        )
+
+    def ingest(self, batch: TelemetryBatch) -> JSONObject:
+        """Submit a durable telemetry batch.
+
+        Contract: sends ``batch.payload`` unchanged so the wire document is
+        byte-identical to the spooled batch.
+
+        Failure: ``LaunchHelmError`` from the server. Durability checking is
+        the runtime's responsibility.
+        """
+        return json_object(
+            self.request("POST", self._prefix + "/telemetry", batch.payload),
+            what="receipt",
+        )
+
+    def ingest_many(self, batches: Sequence[TelemetryBatch]) -> JSONObject:
+        """Submit grouped telemetry batches in one request.
+
+        Contract: each ``batch.payload`` is embedded unchanged so every wire
+        batch document stays byte-identical to its spooled record. The
+        response carries one receipt per submitted batch, keyed by
+        ``batch_id``.
+
+        Failure: ``ValueError`` when ``batches`` is empty.
+        ``LaunchHelmError`` from the server — including ``not_found`` when
+        the server predates grouped ingest. Per-batch durability checking is
+        the runtime's responsibility.
+        """
+        if not batches:
+            raise ValueError("ingest_many requires at least one batch")
+        payload = (
+            b'{"protocol":"1.0","batches":[' + b",".join(batch.payload for batch in batches) + b"]}"
+        )
+        return json_object(
+            self.request("POST", self._prefix + "/telemetry/batches", payload),
+            what="ingestion envelope",
+        )
+
+    def upload_file(
+        self,
+        path: str | Path,
+        scope: Scope,
+        *,
+        idempotency_key: str,
+        media_type: str = "application/octet-stream",
+        part_size: int = 16 << 20,
+        provenance: JSONObject | None = None,
+        purpose: str = "general",
+    ) -> Document:
+        """Upload a local file as an artifact via signed multipart PUT.
+
+        Contract: the source file must not change during the upload (size,
+        mtime, inode). Object-store URLs must be HTTPS outside loopback.
+        Repeating ``idempotency_key`` resumes or returns the existing
+        artifact.
+
+        Failure: ``ValueError`` for an impossible part budget. ``LaunchHelmError``
+        for insecure URLs, transport uncertainty, a missing ETag, or a
+        mutated source file.
+        """
+        source = Path(path)
+        if part_size < MIN_PART_SIZE or part_size > MAX_PART_SIZE:
+            raise ValueError("part_size must be between 5 and 64 MiB")
+        with source.open("rb") as stream:
+            initial = source.stat()
+            size = initial.st_size
+            if size < 1 or (size + part_size - 1) // part_size > MAX_PARTS:
+                raise ValueError("file does not fit the configured multipart budget")
+            digest = hashlib.file_digest(stream, "sha256").hexdigest()
+            stream.seek(0)
+            payload: JSONObject = {
+                "scope": string_object(scope.wire()),
+                "name": source.name,
+                "media_type": media_type,
+                "size": str(size),
+                "sha256": digest,
+                "provenance": provenance or {"inputs": [], "coordinates": [], "labels": {}},
+                "purpose": purpose,
+            }
+            artifact = Document.parse(
+                json_object(
+                    self.request(
+                        "POST",
+                        self._prefix + "/artifacts",
+                        payload,
+                        idempotency_key=idempotency_key,
+                    ),
+                    what="artifact",
+                )
+            )
+            state = artifact.spec.get("state")
+            if state in {"ready", "verifying"}:
+                return artifact
+            parts: list[JSONValue] = []
+            with httpx.Client(timeout=UPLOAD_TIMEOUT_SECONDS, follow_redirects=False) as uploads:
+                number = 0
+                while chunk := stream.read(part_size):
+                    number += 1
+                    signed = json_object(
+                        self.request(
+                            "POST",
+                            self._prefix + f"/artifacts/{artifact.id}/parts",
+                            {
+                                "number": number,
+                                "size": str(len(chunk)),
+                                "sha256": hashlib.sha256(chunk).hexdigest(),
+                            },
+                        ),
+                        what="signed part",
+                    )
+                    url = signed.get("url")
+                    if not isinstance(url, str):
+                        raise LaunchHelmError("invalid_response", "Signed upload is missing a URL")
+                    target = urlparse(url)
+                    if target.scheme != "https" and target.hostname not in {
+                        "localhost",
+                        "127.0.0.1",
+                        "::1",
+                    }:
+                        raise LaunchHelmError("insecure_upload", "Object upload requires HTTPS")
+                    headers_field = signed.get("headers")
+                    upload_headers = (
+                        {str(k): str(v) for k, v in headers_field.items()}
+                        if isinstance(headers_field, dict)
+                        else {}
+                    )
+                    try:
+                        response = uploads.put(url, content=chunk, headers=upload_headers)
+                    except httpx.HTTPError:
+                        raise LaunchHelmError(
+                            "upload_uncertain",
+                            "Retry with the same artifact idempotency key",
+                            retryable=True,
+                        ) from None
+                    if response.status_code >= 300 or "etag" not in response.headers:
+                        raise LaunchHelmError(
+                            "upload_failed",
+                            "Object store did not acknowledge the part",
+                            retryable=True,
+                        )
+                    part: JSONObject = {
+                        "number": number,
+                        "etag": response.headers["etag"],
+                    }
+                    parts.append(part)
+            final = source.stat()
+            if (initial.st_size, initial.st_mtime_ns, initial.st_ino) != (
+                final.st_size,
+                final.st_mtime_ns,
+                final.st_ino,
+            ):
+                raise LaunchHelmError("source_changed", "Artifact source changed during upload")
+            complete: JSONObject = {"parts": parts}
+            return Document.parse(
+                json_object(
+                    self.request(
+                        "POST",
+                        self._prefix + f"/artifacts/{artifact.id}/complete",
+                        complete,
+                    ),
+                    what="artifact",
+                )
+            )
+
+
+def _query_params(params: dict[str, JSONValue] | None) -> dict[str, str | int] | None:
+    if params is None:
+        return None
+    query: dict[str, str | int] = {}
+    for key, value in params.items():
+        if isinstance(value, bool) or value is None:
+            query[key] = json.dumps(value)
+        elif isinstance(value, str | int):
+            query[key] = value
+        else:
+            query[key] = json.dumps(value)
+    return query
+
+
+def _check_download_url(url: str) -> None:
+    try:
+        parsed = urlparse(url)
+        host = parsed.hostname
+        # Touching port validates its range and syntax.
+        _ = parsed.port
+        userinfo = parsed.username is not None or parsed.password is not None
+    except ValueError:
+        raise LaunchHelmError(
+            "insecure_download", "Object download requires HTTPS without credentials"
+        ) from None
+    secure = parsed.scheme == "https" or (
+        parsed.scheme == "http" and host in {"localhost", "127.0.0.1", "::1"}
+    )
+    if not secure or not host or userinfo:
+        raise LaunchHelmError(
+            "insecure_download", "Object download requires HTTPS without credentials"
+        )
+
+
+def _json_value(value: object) -> JSONValue:
+    try:
+        return as_json_value(value)
+    except TypeError:
+        raise LaunchHelmError("invalid_response", "Server returned a non-JSON value") from None