launchhelm 0.1.0__py3-none-any.whl

launchhelm/session.py

@@ -0,0 +1,2824 @@
+"""Logging session: project, run, participant, and scalar metrics.
+
+Contract: ``init`` is the public entry. Overflow is required and has no
+default. ``log`` admits scalars into the runtime queue. ``finish`` waits
+for a query-visible receipt. A session that never registers a capability
+or services a safe point does not claim commands.
+
+Failure: ``TypeError`` for a missing overflow, a nested metric, or a
+changed metric type. ``ValueError`` for an invalid name, axis, or config
+label. ``LaunchHelmError`` when project lookup is ambiguous or the server
+rejects a document.
+"""
+
+from __future__ import annotations
+
+import atexit
+import json
+import math
+import os
+import platform
+import re
+import shlex
+import shutil
+import socket
+import sqlite3
+import subprocess
+import sys
+import threading
+from collections.abc import Callable, Mapping, Sequence
+from concurrent.futures import ThreadPoolExecutor
+from decimal import Decimal
+from hashlib import sha256 as _sha256
+from pathlib import Path
+from typing import Any, Literal, TextIO, cast
+from uuid import uuid4
+
+from .client import Client, SessionClient
+from .commands import CommandFunction, adapt, command_capability
+from .env import load_env
+from .errors import LaunchHelmError
+from .models import Capability, Document, Scope, opaque_schema
+from .rich import (
+    _SUFFIX_MEDIA,
+    MEDIA_OBJECT_BYTES,
+    PENDING_PREFIX,
+    Audio,
+    Histogram,
+    Image,
+    MediaGrid,
+    PendingBlob,
+    RichValue,
+    Text,
+    Video,
+    _check_media_type,
+    _NativeMedia,
+    bin_values,
+    compile_columns,
+    compile_rows,
+    infer_columns,
+    is_media_item,
+    pending_item,
+)
+from .rich import (
+    media_url as _media_url_item,
+)
+from .runtime import CapabilityHandler, Runtime
+from .values import JSONObject, JSONValue, scalar
+
+OverflowPolicy = Literal["drop_new", "block", "raise"]
+DEFAULT_URL = "https://launchhelm.com"
+_AXIS = re.compile(r"^[a-z][a-z0-9_.:-]{0,127}$")
+_COORD = re.compile(r"^-?(0|[1-9][0-9]*)(\.[0-9]+)?$")
+_MAX_LABELS = 64
+_MAX_LABEL = 1024
+_JSON_LABEL = "json:"
+_MAX_PAGES = 100
+_STREAM_CREATES = 8
+_HISTOGRAM_STATS = frozenset({"underflow", "overflow", "total", "min", "max", "mean", "std"})
+
+
+class _BuiltTable(RichValue):
+    """A table value from pre-compiled columns and rows."""
+
+    renderer = "table"
+
+    def __init__(
+        self,
+        columns: list[tuple[str, str]],
+        rows: list[list[JSONValue]],
+        blobs: list[PendingBlob],
+    ) -> None:
+        self._columns = [{"name": name, "type": ctype} for name, ctype in columns]
+        self._rows = rows
+        self._blobs = blobs
+
+    def value(self) -> JSONObject:
+        return {
+            "columns": cast(JSONValue, self._columns),
+            "rows": cast(JSONValue, self._rows),
+        }
+
+    def blobs(self) -> list[PendingBlob]:
+        return list(self._blobs)
+
+
+def _as_rich_value(value: object) -> RichValue | None:
+    """Map a ``log`` metric value to its rich wrapper, or ``None``.
+
+    ``RichValue`` instances pass through; a non-empty sequence of media
+    values or media item mappings becomes a ``MediaGrid``. Plain strings
+    and objects keep their scalar stream types.
+    """
+    if isinstance(value, RichValue):
+        return value
+    if isinstance(value, Sequence) and not isinstance(value, str | bytes | bytearray):
+        items = list(value)
+        if items and all(
+            isinstance(item, _NativeMedia | RichValue) or is_media_item(item) for item in items
+        ):
+            if any(
+                isinstance(item, RichValue) and not isinstance(item, _NativeMedia) for item in items
+            ):
+                return None
+            return MediaGrid(items)
+    return None
+
+
+def _pending_hashes(node: object) -> list[str]:
+    """Collect ``pending:<hash>`` artifact ids from a built value."""
+    found: list[str] = []
+    if isinstance(node, Mapping):
+        for key, item in node.items():
+            if key == "id" and isinstance(item, str) and item.startswith(PENDING_PREFIX):
+                found.append(item[len(PENDING_PREFIX) :])
+            else:
+                found.extend(_pending_hashes(item))
+    elif isinstance(node, Sequence) and not isinstance(node, str | bytes | bytearray):
+        for item in node:
+            found.extend(_pending_hashes(item))
+    return found
+
+
+def _stream_renderer(document: Document) -> str:
+    presentation = document.spec.get("presentation")
+    if isinstance(presentation, Mapping):
+        renderer = presentation.get("renderer")
+        if isinstance(renderer, str):
+            return renderer
+    return ""
+
+
+class _LineCapture:
+    """Write through to the original stream and record each complete line.
+
+    A failed ``console`` record never propagates through ``write`` — the
+    stream keeps working (tracebacks stay intact) and the first failure is
+    reported by ``Run.finish`` instead.
+    """
+
+    def __init__(self, original: TextIO, run: Run, stream: str) -> None:
+        self.original = original
+        self._run = run
+        self._stream = stream
+        self._buffer = ""
+        self._inside = False
+        self._failed = False
+
+    def write(self, text: str) -> int:
+        self.original.write(text)
+        if self._inside or self._failed:
+            return len(text)
+        self._buffer += text
+        while "\n" in self._buffer:
+            line, self._buffer = self._buffer.split("\n", 1)
+            self._inside = True
+            try:
+                self._run.console(line, stream=self._stream)
+            except Exception as error:  # a dead tee must not break the stream
+                self._failed = True
+                self._run._console_failure(error)
+            finally:
+                self._inside = False
+        return len(text)
+
+    def flush(self) -> None:
+        self.original.flush()
+
+    def flush_line(self) -> None:
+        if not self._buffer:
+            return
+        line = self._buffer
+        self._buffer = ""
+        self._run.console(line, stream=self._stream)
+
+    def __getattr__(self, name: str) -> Any:  # noqa: ANN401 - delegates arbitrary stream attributes
+        return getattr(self.original, name)
+
+
+class Run:
+    """One attached participant and the streams it has declared.
+
+    Contract: ``log`` returns after memory admission. ``flush`` and
+    ``finish`` use the runtime durability rules. The step counter is
+    local to this process.
+
+    Failure: see ``log`` and ``finish``.
+    """
+
+    def __init__(
+        self,
+        runtime: Runtime,
+        *,
+        client: SessionClient,
+        name: str,
+        owned_client: SessionClient | None,
+        metadata_client: SessionClient | None = None,
+        owned_metadata: SessionClient | None = None,
+        checkpoint: Path,
+        restored: Mapping[str, JSONValue] | None = None,
+        next_step: int = 0,
+        reuse_streams: bool = False,
+        config: Mapping[str, JSONValue] | None = None,
+        summary: Mapping[str, JSONValue] | None = None,
+        summary_changed: bool = False,
+        group: str = "",
+        tags: tuple[str, ...] = (),
+        notes: str = "",
+        git: str = "",
+        host: str = "",
+        python: str = "",
+        argv: str = "",
+    ) -> None:
+        self.runtime = runtime
+        self.name = name
+        self.project_id = runtime.scope.project_id
+        self.run_id = runtime.scope.run_id
+        self.restored: Mapping[str, JSONValue] = dict(restored or {})
+        self.config: Mapping[str, JSONValue] = dict(config or {})
+        self.summary_values: dict[str, JSONValue] = dict(summary or {})
+        self.group = group
+        self.tags = tags
+        self.notes = notes
+        self.git = git
+        self.host = host
+        self.python = python
+        self.argv = argv
+        self._checkpoint = checkpoint
+        self._client = client
+        self._owned_client = owned_client
+        self._metadata = metadata_client if metadata_client is not None else client
+        self._owned_metadata = owned_metadata
+        self._streams: dict[str, tuple[Document, str, tuple[str, ...]]] = {}
+        self._next_step = next_step
+        self._closed = False
+        self._reuse_streams = reuse_streams
+        self._summary: dict[str, JSONValue] = dict(self.summary_values)
+        self._summary_changed = summary_changed
+        self._reductions: dict[str, str] = {}
+        self._reduced: dict[str, tuple[int, float]] = {}
+        self._summary_locked: set[str] = set()
+        self._seeded_mean: set[str] = set()
+        self.last_applied: dict[str, str] | None = None
+        self.last_result: JSONValue | None = None
+        self._console_line = 0
+        self._console_lock = threading.Lock()
+        self._console_stdout: _LineCapture | None = None
+        self._console_stderr: _LineCapture | None = None
+        self._console_error: Exception | None = None
+        self._media_blobs: dict[str, PendingBlob] = {}
+
+    def __enter__(self) -> Run:
+        """Return ``self``. ``__exit__`` calls ``finish``."""
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        """Finish the run. Does not suppress the block exception."""
+        self.finish()
+
+    def define(
+        self,
+        name: str,
+        kind: str = "number",
+        *axes: str,
+        unit: str = "",
+        summary: str = "",
+    ) -> None:
+        """Create the stream for ``name`` before the first point.
+
+        Contract: ``kind`` is ``number``, ``string``, or ``boolean``. ``step``
+        is always an axis. Extra names in ``axes`` are locked with it. A later
+        ``log`` that changes the kind or the axes fails before the step
+        counter moves.         ``summary`` is ``min``, ``max``, or ``mean`` for a
+        number metric. ``finish`` stores that reduction unless ``summary()``
+        set the same name.         ``min`` and ``max`` continue from the value already
+        stored on a resumed run. ``mean`` continues from the stored count.
+
+        Failure: ``TypeError`` for an empty name. ``ValueError`` for a kind
+        or axis the protocol rejects, or when the stream already has a
+        different kind or axes.
+        """
+        if not isinstance(name, str) or not name or len(name) > 256:
+            raise TypeError("metric name must be 1 to 256 characters")
+        if kind not in {"number", "string", "boolean"}:
+            raise ValueError("metric kind must be number, string, or boolean")
+        if not isinstance(unit, str) or len(unit) > 64:
+            raise ValueError("unit must be at most 64 characters")
+        if summary and summary not in {"min", "max", "mean"}:
+            raise ValueError("summary must be min, max, or mean")
+        if summary and kind != "number":
+            raise ValueError("summary applies to a number metric")
+        if summary:
+            self._reductions[name] = summary
+            if summary == "mean":
+                saved = self._saved_mean(name)
+                if saved is not None:
+                    self._reduced[name] = saved
+                    self._seeded_mean.add(name)
+        locked = ["step"]
+        for axis in axes:
+            if axis == "step" or not isinstance(axis, str) or not _AXIS.fullmatch(axis):
+                raise ValueError(f"invalid axis {axis!r}")
+            if axis not in locked:
+                locked.append(axis)
+        self._stream(name, kind, tuple(locked), unit=unit)
+
+    def log(  # noqa: PLR0912 - rich/scalar dispatch keeps the wire contract in one place
+        self,
+        metrics: Mapping[str, JSONValue | RichValue | Sequence[RichValue]],
+        *,
+        step: int | None = None,
+        **axes: int | float | str,
+    ) -> bool:
+        """Admit one point per metric at the same coordinates.
+
+        Contract: scalar values keep the existing stream kinds; a
+        ``RichValue`` (``Text``/``Table``/``Histogram``/``Image`` etc.) logs
+        its canonical object on a rendered stream and a non-empty sequence
+        of media values logs a media grid. An omitted ``step`` uses the
+        local counter, starting at 0.
+        An explicit ``step`` sets the counter. Returns ``False`` when any
+        point is dropped under ``drop_new``. Nested values are rejected.
+        Missing stream names in one call are created in one batch. A client
+        without ``create_documents`` creates them concurrently, up to eight
+        at a time. Each name is still its own stream.
+
+        Failure: ``TypeError`` for an empty name, a non-scalar, a boolean
+        step, or a metric whose JSON type changed. ``ValueError`` for an
+        axis or coordinate the protocol rejects, or a new axis on an
+        existing metric. Propagates runtime admission errors.
+        """
+        if self._closed:
+            raise RuntimeError("run is closed")
+        if not metrics:
+            return True
+        prepared: list[tuple[str, str, JSONValue, RichValue | None]] = []
+        for name, value in metrics.items():
+            if not isinstance(name, str) or not name or len(name) > 256:
+                raise TypeError("metric name must be 1 to 256 characters")
+            rich_value = _as_rich_value(value)
+            if rich_value is not None:
+                prepared.append((name, "object", rich_value.value(), rich_value))
+                continue
+            kind, encoded = _scalar(cast(JSONValue, value))
+            prepared.append((name, kind, encoded, None))
+        _, axis_names = self._coordinates(step, axes, advance=False)
+        for name, kind, _encoded, rich_value in prepared:
+            known = self._streams.get(name)
+            if known is None:
+                continue
+            document, known_kind, known_axes = known
+            if rich_value is not None:
+                if known_kind != "object":
+                    raise TypeError(f"metric {name!r} is {known_kind}, not a rich value")
+                stored = _stream_renderer(document)
+                if stored != rich_value.renderer:
+                    raise ValueError(
+                        f"metric {name!r} renders as {stored}, not {rich_value.renderer}"
+                    )
+            elif known_kind != kind:
+                raise TypeError(f"metric {name!r} is {known_kind}, not {kind}")
+            if known_axes != axis_names:
+                raise ValueError(f"metric {name!r} axes are fixed")
+        coordinates, axis_names = self._coordinates(step, axes, advance=True)
+        missing = [
+            (name, kind)
+            for name, kind, _encoded, rich_value in prepared
+            if rich_value is None and name not in self._streams
+        ]
+        self._open_streams(missing, axis_names)
+        admitted = True
+        for name, kind, encoded, rich_value in prepared:
+            if rich_value is not None:
+                document = self._rich_stream(name, rich_value.renderer, axis_names)
+                if not self._log_rich(document, rich_value, coordinates=coordinates):
+                    admitted = False
+                continue
+            document = self._stream(name, kind, axis_names)
+            if not self.runtime.log(document, encoded, coordinates=coordinates):
+                admitted = False
+                continue
+            self._note_reduction(name, encoded)
+        return admitted
+
+    def console(self, text: str, *, stream: str = "stdout") -> None:
+        """Record one output line without advancing the step counter.
+
+        Contract: ``text`` is one line, at most 1024 characters, stored on
+        the string metric ``console``. Coordinates are the current step, a
+        monotonic ``line``, and ``stream`` (``stdout`` or ``stderr``). A
+        later ``log`` still starts at the same step.
+
+        Failure: ``TypeError`` when ``text`` is not a string. ``ValueError``
+        for a stream other than ``stdout`` or ``stderr``, or a line longer
+        than 1024 characters.
+        """
+        if not isinstance(text, str):
+            raise TypeError("console line must be a string")
+        if stream not in {"stdout", "stderr"}:
+            raise ValueError("console stream must be stdout or stderr")
+        if len(text) > 1024:
+            raise ValueError("console line must be at most 1024 characters")
+        with self._console_lock:
+            line = self._console_line
+            self._console_line += 1
+        coordinates, axis_names = self._coordinates(
+            None,
+            {"line": line, "stream": 0 if stream == "stdout" else 1},
+            advance=False,
+        )
+        self._open_streams([("console", "string")], axis_names)
+        document = self._stream("console", "string", axis_names)
+        if not self.runtime.log(document, text, coordinates=coordinates):
+            raise LaunchHelmError("protocol", "console line was dropped")
+
+    def capture_console(self) -> None:
+        """Tee stdout and stderr into ``console`` until ``finish``.
+
+        Contract: each complete line is recorded and still written to the
+        original stream. A line emitted while a console point is being
+        recorded is not captured again. ``finish`` restores the original
+        streams and records a trailing partial line.
+
+        Failure: same as ``console``.
+        """
+        if self._console_stdout is not None:
+            return
+        self._console_stdout = _LineCapture(sys.stdout, self, "stdout")
+        self._console_stderr = _LineCapture(sys.stderr, self, "stderr")
+        sys.stdout = self._console_stdout
+        sys.stderr = self._console_stderr
+        atexit.register(self._restore_console)
+
+    def _restore_console(self) -> None:
+        """Return the original streams without recording; safe at interpreter exit."""
+        stdout = self._console_stdout
+        stderr = self._console_stderr
+        if stdout is not None and sys.stdout is stdout:
+            sys.stdout = stdout.original
+        if stderr is not None and sys.stderr is stderr:
+            sys.stderr = stderr.original
+        self._console_stdout = None
+        self._console_stderr = None
+
+    def _console_failure(self, error: Exception) -> None:
+        if self._console_error is None:
+            self._console_error = error
+
+    def _stop_console(self) -> None:
+        if self._console_stdout is None:
+            return
+        stdout = self._console_stdout
+        stderr = self._console_stderr
+        self._restore_console()
+        errors: list[Exception] = []
+        try:
+            stdout.flush_line()
+        except Exception as error:  # restore already done; collect
+            errors.append(error)
+        if stderr is not None:
+            try:
+                stderr.flush_line()
+            except Exception as error:
+                errors.append(error)
+        if self._console_error is not None:
+            raise self._console_error
+        if errors:
+            raise errors[0]
+
+    def flush(self, *, delivered: bool = True, timeout: float = 30.0) -> None:
+        """Wait for local durability, or for a query-visible receipt."""
+        self.runtime.flush(timeout=timeout, delivered=delivered)
+
+    def finish(self, *, close_run: bool = True, timeout: float = 30.0) -> None:
+        """End the session: flush, record the summary, and close the runtime.
+
+        Contract: idempotent. Console capture stops first so buffered lines
+        reach the spool, admission is then fenced so the flush drains a
+        fixed set, and admitted points are flushed until query-visible —
+        telemetry delivery is never skipped because a later step fails. The
+        summary and stored reductions are written to the run with the
+        original credential, not the adopted worker key. The
+        participant session is then ended on the server: with ``close_run``
+        (the default) the run closes once no participant still holds a live
+        session; ``close_run=False`` leaves the run open for a deliberate
+        resume. The heartbeat loop stops when the session ends. Every step
+        is attempted even when an earlier one fails. Does not execute queued
+        commands. Closes every client this session constructed.
+
+        Failure: the first step's error is raised after all steps were
+        attempted.
+        """
+        if self._closed:
+            return
+        self._closed = True
+        errors: list[BaseException] = []
+        for step in (
+            self._stop_console,
+            self.runtime.stop_accepting,
+            lambda: self.runtime.flush(timeout=timeout, delivered=True),
+            self._write_summary,
+            lambda: self._end_session(close_run),
+            lambda: self.runtime.close(timeout=timeout),
+        ):
+            try:
+                step()
+            except BaseException as error:  # report the first
+                errors.append(error)
+        for extra in (self._owned_metadata, self._owned_client):
+            if extra is not None:
+                try:
+                    extra.close()
+                except BaseException as error:
+                    errors.append(error)
+        if errors:
+            raise errors[0]
+
+    def _end_session(self, close_run: bool) -> None:
+        """End the participant session, closing the run when asked.
+
+        ``close_run=True`` asks the server to close the run once no
+        participant still holds a live session (``when_idle``); ``False``
+        always leaves it open (``never``). A client without ``end_session``
+        falls back to closing the run document directly.
+        """
+        policy = "when_idle" if close_run else "never"
+        ended = self.runtime.end_session(close_run=policy)
+        if ended is None and close_run:
+            self._close_run()
+
+    def on(self, safe_point: str, capability: Capability, handler: CapabilityHandler) -> Document:
+        """Register ``handler`` for ``safe_point`` and start background claim.
+
+        Contract: claim runs on the control thread. The training step does
+        not wait on the network. ``sync`` applies a command only when one
+        is already waiting locally.
+
+        Failure: ``ValueError`` when ``safe_point`` is not declared on the
+        capability. ``LaunchHelmError`` from registration.
+        """
+        if safe_point not in capability.safe_points:
+            raise ValueError(f"capability does not declare safe point {safe_point!r}")
+        return self.register(capability, handler)
+
+    def command(
+        self, safe_point: str, *, name: str = ""
+    ) -> Callable[[CommandFunction], CommandFunction]:
+        """Register a typed function as a command at ``safe_point``.
+
+        Contract: annotations ``int``, ``float``, ``str``, and ``bool``, a list
+        of those, and an optional annotation become the input form. A
+        ``context: CommandContext`` parameter is filled by
+        the session and is not a form field. The function name is the
+        capability name unless ``name`` is set. Several commands may share
+        one safe point. ``sync`` still runs at most one waiting command.
+
+        Failure: ``TypeError`` for an unsupported annotation.
+        ``LaunchHelmError`` from registration.
+        """
+
+        def decorate(function: CommandFunction) -> CommandFunction:
+            capability = command_capability(function, safe_point, name=name)
+            self.on(safe_point, capability, adapt(function))
+            return function
+
+        return decorate
+
+    def sync(self, safe_point: str, *, step: int | None = None, **axes: int | float | str) -> int:
+        """Apply at most one command already claimed for ``safe_point``.
+
+        Contract: returns ``1`` when a handler ran and ``0`` when the local
+        queue is empty. The handler's return value is ``last_result``, or
+        ``None`` when nothing ran. The first call for a point not declared
+        at connect advertises it on one heartbeat so a parked claim can
+        observe it; later calls do not call the network and do not
+        wait for a command to arrive.
+
+        Failure: same as ``safe_point``.
+        """
+        return self.safe_point(safe_point, step=step, **axes)
+
+    def register(self, capability: Capability, handler: CapabilityHandler) -> Document:
+        """Publish a capability. Starts command claim on this runtime."""
+        return self.runtime.register(capability, handler)
+
+    def pending(self, safe_point: str) -> bool:
+        """Return ``True`` when a command for ``safe_point`` waits locally.
+
+        Contract: reads the local claimed-command queue only; no network.
+        Distributed adapters use this to broadcast one flag before every
+        rank enters the collective handler.
+
+        Failure: none.
+        """
+        return self.runtime.pending(safe_point)
+
+    def safe_point(self, name: str, *, step: int | None = None, **axes: int | float | str) -> int:
+        """Service one command at ``name``. Starts command claim."""
+        coordinates, _ = self._coordinates(step, axes, advance=False)
+        applied = self.runtime.safe_point(name, coordinates=coordinates)
+        if applied:
+            self.last_applied = {item["axis"]: item["value"] for item in coordinates}
+            self.last_result = self.runtime.last_result
+        else:
+            self.last_result = None
+        return applied
+
+    def summary(self, metrics: Mapping[str, JSONValue]) -> None:
+        """Remember scalar end-of-run values. ``finish`` stores them on the run.
+
+        Contract: values are booleans, strings, or finite numbers. They are
+        one run label, ``launchhelm.summary``, not a time series. A later
+        call merges keys into the map. ``None`` removes that key. The encoded
+        label is at most 1024 characters.
+
+        Failure: ``RuntimeError`` after ``finish``. ``TypeError`` for a
+        nested value. ``ValueError`` for an empty name, a non-finite number,
+        or a map that does not fit in the label.
+        """
+        if self._closed:
+            raise RuntimeError("run is closed")
+        stored: dict[str, JSONValue] = dict(self._summary)
+        for key, value in metrics.items():
+            if not isinstance(key, str) or not key or len(key) > 256:
+                raise ValueError("summary name must be 1 to 256 characters")
+            if value is None:
+                stored.pop(key, None)
+                self._summary_locked.discard(key)
+                continue
+            self._summary_locked.add(key)
+            if isinstance(value, bool | str | int):
+                stored[key] = value
+            elif isinstance(value, float):
+                if not math.isfinite(value):
+                    raise ValueError("summary cannot be non-finite")
+                stored[key] = value
+            else:
+                raise TypeError("summary values must be scalars")
+        encoded = json.dumps(stored, allow_nan=False, separators=(",", ":"), sort_keys=True)
+        if len(encoded) > 1024:
+            raise ValueError("summary is longer than 1024 characters")
+        self._summary = stored
+        self._summary_changed = True
+        self.summary_values = dict(stored)
+
+    def _saved_mean(self, name: str) -> tuple[int, float] | None:
+        if not self.run_id:
+            return None
+        try:
+            found = self._run_document()
+        except LaunchHelmError:
+            return None
+        item = _reduction_item(found, name)
+        if item is None:
+            return None
+        count = item.get("count")
+        held = item.get("held")
+        if isinstance(count, bool) or not isinstance(count, int) or count < 1:
+            return None
+        if (
+            isinstance(held, bool)
+            or not isinstance(held, int | float)
+            or not math.isfinite(float(held))
+        ):
+            return None
+        return count, float(held)
+
+    def _note_reduction(self, name: str, encoded: JSONValue) -> None:
+        policy = self._reductions.get(name)
+        if policy is None or isinstance(encoded, bool) or not isinstance(encoded, int | float):
+            return
+        if isinstance(encoded, float) and not math.isfinite(encoded):
+            return
+        value = float(encoded)
+        count, held = self._reduced.get(name, (0, 0.0))
+        if policy == "min":
+            held = value if count == 0 else min(held, value)
+        elif policy == "max":
+            held = value if count == 0 else max(held, value)
+        else:
+            held += value
+        self._reduced[name] = (count + 1, held)
+
+    def _apply_reductions(self) -> None:
+        changed = False
+        for name, policy in self._reductions.items():
+            if name in self._summary_locked:
+                continue
+            stats = self._reduced.get(name)
+            if stats is None or stats[0] == 0:
+                continue
+            count, held = stats
+            value = held if policy != "mean" else held / count
+            stored = self._summary.get(name)
+            if (
+                policy in {"min", "max"}
+                and isinstance(stored, int | float)
+                and not isinstance(stored, bool)
+                and math.isfinite(float(stored))
+            ):
+                value = min(value, float(stored)) if policy == "min" else max(value, float(stored))
+            elif policy == "mean" and name in self._summary and name not in self._seeded_mean:
+                continue
+            self._summary[name] = value
+            changed = True
+        if changed:
+            self._summary_changed = True
+            self.summary_values = dict(self._summary)
+
+    def _write_summary(self) -> None:
+        self._apply_reductions()
+        if not self._summary and not self._summary_changed:
+            return
+        summary = json.dumps(self._summary, allow_nan=False, separators=(",", ":"), sort_keys=True)
+        reduction = {
+            name: {"count": count, "held": held}
+            for name, policy in self._reductions.items()
+            if policy == "mean"
+            for count, held in [self._reduced.get(name, (0, 0.0))]
+            if count
+        }
+
+        def apply(found: Document) -> JSONObject:
+            stored = found.spec.get("labels")
+            labels: dict[str, JSONValue] = dict(stored) if isinstance(stored, dict) else {}
+            labels["launchhelm.summary"] = summary
+            if reduction:
+                labels["launchhelm.reduction"] = json.dumps(
+                    reduction, allow_nan=False, separators=(",", ":"), sort_keys=True
+                )
+            spec = dict(found.spec)
+            spec["labels"] = labels
+            return spec
+
+        self._update_run(apply)
+
+    def _update_run(
+        self, mutate: Callable[[Document], JSONObject], *, retries: int = 5
+    ) -> Document:
+        """Re-read the run and apply ``mutate`` to its spec.
+
+        The write runs under the original credential and retries a bounded
+        number of revision conflicts so concurrent participants do not lose
+        their keys.
+        """
+        for attempt in range(retries):
+            found = self._run_document(self._metadata)
+            try:
+                return self._metadata.update_document(found, mutate(found))
+            except LaunchHelmError as error:
+                if error.code != "conflict" or attempt == retries - 1:
+                    raise
+        raise LaunchHelmError("conflict", "run document is contended")
+
+    def _close_run(self) -> None:
+        if not self.run_id:
+            return
+
+        def close(found: Document) -> JSONObject:
+            spec = dict(found.spec)
+            spec["state"] = "closed"
+            return spec
+
+        found = self._run_document(self._metadata)
+        if found.spec.get("state") == "closed":
+            return
+        self._metadata.update_document(found, close(found))
+
+    def _run_document(self, client: SessionClient | None = None) -> Document:
+        if not self.run_id:
+            raise LaunchHelmError("protocol", "run document is missing")
+        reader = client if client is not None else self._client
+        found = reader.get_document(self.run_id)
+        if found.kind != "run" or found.id != self.run_id:
+            raise LaunchHelmError("protocol", "run document is missing")
+        return found
+
+    def about(self, run: str = "") -> dict[str, JSONValue]:
+        """Return the stored name, state, group, notes, tags, and summary for ``run``.
+
+        Contract: ``run`` is a title or id in this project. ``summary`` is the
+        parsed ``launchhelm.summary`` object, or ``{}`` when that label is
+        absent. ``config`` is the label map with the reserved ``launchhelm.*``
+        keys removed. A ``parameters`` spec object carries the full config when
+        values do not fit in labels; older runs may hold a ``launchhelm.config``
+        artifact reference instead.
+        ``git``, ``host``, and ``argv`` are the recorded commit,
+        machine, and command. ``tags`` is a list of strings. This does not open the run.
+
+        Failure: ``ValueError`` when ``run`` is empty and this session has no run.
+        ``LaunchHelmError``
+        when ``run`` is not one run in this project or a stored label is malformed.
+        """
+        if not isinstance(run, str):
+            raise ValueError("run name is required")
+        if not run:
+            run = self.run_id or self.name
+        if not run:
+            raise ValueError("run name is required")
+        found = [
+            document
+            for document in self._project_runs()
+            if document.id == run or document.spec.get("name") == run
+        ]
+        unique = {document.id: document for document in found}
+        if len(unique) != 1:
+            raise LaunchHelmError("config", f"run {run!r} is not one run in this project")
+        document = next(iter(unique.values()))
+        raw_summary = _metadata_value(document, "launchhelm.summary")
+        summary: JSONValue = {}
+        if raw_summary:
+            parsed = json.loads(raw_summary)
+            if not isinstance(parsed, dict):
+                raise LaunchHelmError("protocol", "run summary is not an object")
+            summary = parsed
+        name = document.spec.get("name")
+        state = document.spec.get("state")
+        return {
+            "name": name if isinstance(name, str) else "",
+            "state": state if isinstance(state, str) else "",
+            "group": _metadata_value(document, "launchhelm.group"),
+            "notes": _metadata_value(document, "launchhelm.notes"),
+            "tags": list(_metadata_tags(document)),
+            "summary": summary,
+            "config": _resume_config(self._client, document),
+            "git": _metadata_value(document, "launchhelm.git"),
+            "host": _metadata_value(document, "launchhelm.host"),
+            "argv": _metadata_value(document, "launchhelm.argv"),
+        }
+
+    def runs(self) -> list[str]:
+        """Return the titles of runs in this project that share this group.
+
+        Contract: titles are unique and sorted. An empty group returns every
+        run in the project. A set group returns only runs whose
+        ``launchhelm.group`` label matches. This does not open those runs.
+
+        Failure: ``LaunchHelmError`` when a run page is malformed.
+        """
+        return [name for name, _state in self.statuses()]
+
+    def statuses(self) -> list[tuple[str, str]]:
+        """Return ``(title, state)`` for runs in this group, sorted by title.
+
+        Contract: the same group filter as ``runs``. ``state`` is the run
+        document state, or ``""`` when it is missing. A closed sibling stays
+        in the list so a sweep can skip it.
+
+        Failure: ``LaunchHelmError`` when a run page is malformed.
+        """
+        found: dict[str, str] = {}
+        for document in self._project_runs():
+            if self.group and _metadata_value(document, "launchhelm.group") != self.group:
+                continue
+            name = document.spec.get("name")
+            if isinstance(name, str) and name:
+                state = document.spec.get("state")
+                found[name] = state if isinstance(state, str) else ""
+        return sorted(found.items())
+
+    def _project_runs(self) -> list[Document]:
+        found: list[Document] = []
+        cursor = ""
+        for _ in range(_MAX_PAGES):
+            page = self._client.list_documents(
+                kind="run", project_id=self.project_id, cursor=cursor, limit=100
+            )
+            items = page.get("items") or []
+            if not isinstance(items, list):
+                raise LaunchHelmError("protocol", "run list is not a page")
+            for item in items:
+                if not isinstance(item, dict):
+                    raise LaunchHelmError("protocol", "run list entry is not a document")
+                document = Document.parse(item)
+                if document.kind == "run" and document.scope.project_id == self.project_id:
+                    found.append(document)
+            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 describe(
+        self,
+        *,
+        group: str | None = None,
+        tags: Sequence[str] | None = None,
+        notes: str | None = None,
+        name: str | None = None,
+    ) -> None:
+        """Update the run group, tags, notes, or title without touching config.
+
+        Contract: an omitted argument keeps the current value. An empty
+        group, tag list, or note removes that label. The title cannot be
+        empty. Config and the end-of-run summary stay on the run.
+
+        Failure: ``RuntimeError`` after ``finish``. ``ValueError`` for a
+        group, note, tag, or title that does not fit. ``TypeError`` when
+        tags are not strings.
+        """
+        if self._closed:
+            raise RuntimeError("run is closed")
+        if name is not None and (not isinstance(name, str) or not name or len(name) > 256):
+            raise ValueError("run name must be 1 to 256 characters")
+        next_group = self.group if group is None else group
+        next_tags = self.tags if tags is None else tags
+        next_notes = self.notes if notes is None else notes
+        staged: JSONObject = {}
+        _metadata(staged, next_group, next_tags, next_notes)
+        self.group = next_group
+        self.tags = tuple(next_tags)
+        self.notes = next_notes
+        if name is not None:
+            self.name = name
+        self._write_metadata()
+
+    def _write_metadata(self) -> None:
+        def apply(found: Document) -> JSONObject:
+            stored = found.spec.get("labels")
+            labels: dict[str, JSONValue] = dict(stored) if isinstance(stored, dict) else {}
+            for key, value in (
+                ("launchhelm.group", self.group),
+                ("launchhelm.notes", self.notes),
+            ):
+                if value:
+                    labels[key] = value
+                else:
+                    labels.pop(key, None)
+            if self.tags:
+                labels["launchhelm.tags"] = json.dumps(list(self.tags), separators=(",", ":"))
+            else:
+                labels.pop("launchhelm.tags", None)
+            spec = dict(found.spec)
+            spec["labels"] = labels
+            if self.name:
+                spec["name"] = self.name
+            return spec
+
+        self._update_run(apply)
+
+    def keep(self, state: Mapping[str, JSONValue]) -> None:
+        """Save trainer state so a later ``init(..., resume=)`` can continue.
+
+        Contract: ``state`` is JSON data owned by the trainer, such as the
+        learning rate, schedule boundaries, and layer weights. The file also
+        records the next log step and the run id. A crash after ``keep`` resumes from this
+        snapshot. Logs already admitted stay in the local spool until
+        ``finish`` uploads them.
+
+        Failure: ``TypeError`` when ``state`` is not JSON. ``OSError`` when
+        the checkpoint cannot be replaced.
+        """
+        payload = {
+            "step": self._next_step,
+            "participant_id": self.runtime.participant.id,
+            "state": state,
+        }
+        if self.run_id:
+            payload["run_id"] = self.run_id
+        if self._summary_changed:
+            payload["summary"] = self._summary
+        encoded = json.dumps(payload, allow_nan=False, separators=(",", ":"))
+        temporary = self._checkpoint.with_suffix(".tmp")
+        temporary.write_text(encoded, encoding="utf-8")
+        temporary.replace(self._checkpoint)
+
+    def artifact(
+        self,
+        path: str | Path,
+        *,
+        step: int | None = None,
+        name: str | None = None,
+        media_type: str = "application/octet-stream",
+        idempotency_key: str = "",
+        **axes: int | float | str,
+    ) -> Document:
+        """Upload one file as an artifact at these coordinates.
+
+        Contract: ``log`` stays scalar-only. A checkpoint, image, or histogram
+        file uses this call. An omitted ``step`` is the current counter and
+        does not advance it. Pass the same ``step`` just logged when the file
+        belongs to that point. ``name`` also records the artifact id as a
+        string metric at those coordinates and does not advance the counter.
+        The upload runs on this thread and does not
+        wait for telemetry already in the queue.
+
+        Failure: ``LaunchHelmError`` when the client cannot upload or the
+        result is not an artifact document. Coordinate errors match ``log``.
+        """
+        return self._artifact(
+            path,
+            step=step,
+            name=name,
+            media_type=media_type,
+            idempotency_key=idempotency_key,
+            axes=axes,
+        )
+
+    def _artifact(
+        self,
+        path: str | Path,
+        *,
+        step: int | None,
+        name: str | None,
+        media_type: str,
+        idempotency_key: str,
+        axes: Mapping[str, int | float | str],
+    ) -> Document:
+        upload = getattr(self.runtime.client, "upload_file", None)
+        if not callable(upload):
+            raise LaunchHelmError("protocol", "session client cannot upload artifacts")
+        if name is not None and (not isinstance(name, str) or not name or len(name) > 256):
+            raise TypeError("metric name must be 1 to 256 characters")
+        coordinates, axis_names = self._coordinates(step, axes, advance=False)
+        if name is not None:
+            known = self._streams.get(name)
+            if known is not None and known[1] != "string":
+                raise TypeError(f"metric {name!r} is {known[1]}, not string")
+            if known is not None and known[2] != axis_names:
+                raise ValueError(f"metric {name!r} axes are fixed")
+        points: list[JSONValue] = [dict(item) for item in coordinates]
+        provenance: JSONObject = {"inputs": [], "coordinates": points, "labels": {}}
+        document = upload(
+            path,
+            self.runtime.scope,
+            idempotency_key=idempotency_key or str(uuid4()),
+            media_type=media_type,
+            provenance=provenance,
+        )
+        if not isinstance(document, Document):
+            raise LaunchHelmError("protocol", "upload did not return an artifact document")
+        if name is not None:
+            self._open_streams([(name, "string")], axis_names)
+            stream = self._stream(name, "string", axis_names)
+            if not self.runtime.log(stream, document.id, coordinates=coordinates):
+                raise LaunchHelmError("protocol", "artifact reference was dropped")
+        return document
+
+    def fetch(self, name: str, *, run: str | None = None) -> bytes:  # noqa: PLR0912 - media/general artifact dispatch stays readable as one flow
+        """Download the newest artifact recorded under ``name``.
+
+        Contract: ``artifact(..., name=)`` stores the artifact id as a string
+        metric. This returns the file for the newest point of that metric.
+        ``run`` is another run in this project, the same way ``latest``
+        selects one. A later upload of the same name is the file a resumed
+        run receives.
+
+        Failure: ``ValueError`` for an empty name. ``LaunchHelmError`` when
+        the metric has no point, the value is not an artifact id, or the
+        client cannot download the file.
+        """
+        if not isinstance(name, str) or not name:
+            raise ValueError("metric name is required")
+        point = self.latest(name, run=run)
+        if point is None:
+            raise LaunchHelmError("protocol", "artifact metric has no point")
+        value = point.get("value")
+        if isinstance(value, Mapping):
+            items = value.get("items")
+            if isinstance(items, list):
+                artifact_id = ""
+                for item in items:
+                    if not isinstance(item, Mapping):
+                        continue
+                    source = item.get("source")
+                    if isinstance(source, Mapping):
+                        artifact = source.get("artifact")
+                        if isinstance(artifact, Mapping):
+                            candidate = artifact.get("id")
+                            if isinstance(candidate, str):
+                                artifact_id = candidate
+                                break
+                if artifact_id:
+                    download = getattr(self._client, "download_artifact", None)
+                    if not callable(download):
+                        raise LaunchHelmError(
+                            "protocol", "session client cannot download artifacts"
+                        )
+                    body = download(artifact_id)
+                    if not isinstance(body, bytes):
+                        raise LaunchHelmError("protocol", "artifact download is not bytes")
+                    return body
+            raise LaunchHelmError("protocol", "media stream has no native item")
+        if not isinstance(value, str) or not value:
+            raise LaunchHelmError("protocol", "artifact metric is not an id")
+        artifact_id = value
+        download = getattr(self._client, "download_artifact", None)
+        if not callable(download):
+            raise LaunchHelmError("protocol", "session client cannot download artifacts")
+        body = download(artifact_id)
+        if not isinstance(body, bytes):
+            raise LaunchHelmError("protocol", "artifact download is not bytes")
+        return body
+
+    def checkpoint(
+        self,
+        path: str | Path,
+        *,
+        step: int | None = None,
+        name: str = "checkpoint",
+        **axes: int | float | str,
+    ) -> Document:
+        """Upload a checkpoint file and record its id as a string metric.
+
+        Contract: this is ``artifact`` with the metric name ``checkpoint``.
+        ``fetch(name)`` returns the newest file. An omitted ``step`` is the
+        current counter and does not advance it.
+
+        Failure: same as ``artifact``.
+        """
+        return self._artifact(
+            path,
+            step=step,
+            name=name,
+            media_type="application/octet-stream",
+            idempotency_key="",
+            axes=axes,
+        )
+
+    def text(
+        self,
+        name: str,
+        text: str,
+        *,
+        format: str | None = None,
+        caption: str | None = None,
+        step: int | None = None,
+        **axes: int | float | str,
+    ) -> bool:
+        """Log one ``rich_text`` point on the ``text`` renderer stream.
+
+        Contract: creates or reuses the stream ``name`` with presentation
+        ``text``. An omitted ``step`` is the current counter and does not
+        advance it. Returns ``False`` when the point is dropped under
+        ``drop_new``.
+
+        Failure: ``TypeError`` for a bad name. ``ValueError`` for an
+        over-long text, unknown format, or a stream conflict.
+        """
+        return self._rich_log(Text(text, format=format, caption=caption), name, step, axes)
+
+    def image(
+        self,
+        name: str,
+        source: str | Path | bytes | object,
+        *,
+        media_type: str | None = None,
+        caption: str | None = None,
+        step: int | None = None,
+        **axes: int | float | str,
+    ) -> bool:
+        """Log one image item on the ``media`` renderer stream ``name``.
+
+        Contract: ``source`` is a path, bytes with ``media_type``, a PIL
+        image when Pillow is installed, or a NumPy array / torch tensor
+        (HW or HWC with 1/3/4 channels; uint8 or floats in [0, 1]) encoded
+        to PNG. The upload runs on a background thread and the point is
+        admitted once the ``media`` artifact exists; ``flush()`` waits
+        for that admission. An omitted ``step`` does not advance the
+        counter.
+
+        Failure: ``TypeError`` for a bad name or source kind.
+        ``ValueError`` for an uninferable or unallowlisted media type,
+        an empty or over-16 MiB payload, or a stream conflict.
+        """
+        return self._rich_log(
+            Image(source, media_type=media_type, caption=caption), name, step, axes
+        )
+
+    def audio(
+        self,
+        name: str,
+        source: str | Path | bytes,
+        *,
+        media_type: str | None = None,
+        caption: str | None = None,
+        step: int | None = None,
+        **axes: int | float | str,
+    ) -> bool:
+        """Log one audio clip on the ``media`` renderer stream ``name``.
+
+        Contract: matches ``image`` for path/bytes sources. The media
+        type comes from the suffix (``wav``, ``mp3``, ``ogg``, ``flac``,
+        ``weba``) or ``media_type`` and must be allowlisted.
+        """
+        return self._rich_log(
+            Audio(source, media_type=media_type, caption=caption), name, step, axes
+        )
+
+    def video(
+        self,
+        name: str,
+        source: str | Path | bytes,
+        *,
+        media_type: str | None = None,
+        caption: str | None = None,
+        step: int | None = None,
+        **axes: int | float | str,
+    ) -> bool:
+        """Log one video on the ``media`` renderer stream ``name``.
+
+        Contract: matches ``image`` for path/bytes sources; the suffixes
+        ``mp4`` and ``webm`` infer video types.
+        """
+        return self._rich_log(
+            Video(source, media_type=media_type, caption=caption), name, step, axes
+        )
+
+    def media(
+        self,
+        name: str,
+        items: Sequence[object],
+        *,
+        step: int | None = None,
+        **axes: int | float | str,
+    ) -> bool:
+        """Log a media grid on the ``media`` renderer stream ``name``.
+
+        Contract: ``items`` mix entries from ``upload_media``,
+        ``media_url``, and ``Image``/``Audio``/``Video`` values — up to
+        64 items. Native items upload in the background; external items
+        admit at once.
+        """
+        return self._rich_log(MediaGrid(list(items)), name, step, axes)
+
+    def upload_media(
+        self,
+        source: str | Path | bytes,
+        *,
+        media_type: str | None = None,
+        caption: str | None = None,
+    ) -> JSONObject:
+        """Stage local media bytes for a later ``media``/``log_table`` call.
+
+        Contract: returns a media item whose artifact reference is a
+        pending marker; the bytes are registered with this run and the
+        background uploader creates the ``media`` artifact (idempotent
+        on content hash and run — identical bytes share one artifact).
+        The point that uses the item is admitted after the upload.
+        Synchronous-from-caller shape is NOT the contract here — unlike
+        the TypeScript/Rust/C++ SDKs, the upload always happens off the
+        training thread.
+
+        Failure: ``ValueError`` for an uninferable/unallowlisted media
+        type, empty bytes, or over-16 MiB payloads.
+        """
+        if isinstance(source, str | Path):
+            path = Path(source)
+            resolved = media_type or _SUFFIX_MEDIA.get(path.suffix.lower())
+            if resolved is None:
+                raise ValueError(f"cannot infer media type from {path.suffix!r}; pass media_type")
+            data = path.read_bytes()
+        else:
+            resolved = media_type
+            data = bytes(source)
+        if resolved is None:
+            raise ValueError("bytes sources need an explicit media_type")
+        _check_media_type(resolved)
+        if not data or len(data) > MEDIA_OBJECT_BYTES:
+            raise ValueError("media must be 1 byte to 16 MiB")
+        blob = PendingBlob(_sha256(data).hexdigest(), resolved, data)
+        self._media_blobs[blob.hash] = blob
+        return pending_item(blob, caption)
+
+    def media_url(self, href: str, media_type: str, *, caption: str | None = None) -> JSONObject:
+        """Build an external media item; needs no upload."""
+        return _media_url_item(href, media_type, caption)
+
+    def rows(
+        self,
+        name: str,
+        records: Sequence[Mapping[str, JSONValue]],
+        *,
+        step: int | None = None,
+        **axes: int | float | str,
+    ) -> bool:
+        """Log scalar records as a ``rich_table`` point on ``name``.
+
+        Contract: columns are the sorted key set with inferred types —
+        ``integer`` only when every non-null value is an int, ``number``
+        for mixed numerics, ``boolean``/``string``/``media`` for those
+        cell kinds; mixed unrelated types are rejected. A missing key
+        logs null. An omitted ``step`` does not advance the counter.
+        """
+        if not isinstance(name, str) or not name or len(name) > 256:
+            raise TypeError("metric name must be 1 to 256 characters")
+        columns, body, blobs = infer_columns(records)
+        return self._log_table_value(name, columns, body, blobs, step, axes)
+
+    def log_table(
+        self,
+        name: str,
+        columns: Sequence[object],
+        rows: Sequence[Sequence[object]],
+        *,
+        step: int | None = None,
+        **axes: int | float | str,
+    ) -> bool:
+        """Log a ``rich_table`` point with explicit columns on ``name``.
+
+        Contract: named ``log_table`` because ``table`` is the existing
+        read method. ``columns`` are ``{"name", "type"}`` mappings or
+        ``(name, type)`` pairs; a ``media`` column takes media items from
+        ``upload_media``/``media_url`` or ``Image``/``Audio``/``Video``
+        values. Cells may be null.
+        """
+        if not isinstance(name, str) or not name or len(name) > 256:
+            raise TypeError("metric name must be 1 to 256 characters")
+        compiled = compile_columns(columns)
+        body, blobs = compile_rows(compiled, rows)
+        return self._log_table_value(name, compiled, body, blobs, step, axes)
+
+    def histogram(
+        self,
+        name: str,
+        values: Sequence[int | float],
+        *,
+        bins: int = 64,
+        step: int | None = None,
+        **axes: int | float | str,
+    ) -> bool:
+        """Log a binned ``rich_histogram`` point on ``name``.
+
+        Contract: equal-width bins from the minimum to the maximum with
+        the maximum in the last bin; equal samples use one bin; ``bins``
+        is 1 to 512 (default 64). Only finite values are accepted. An
+        omitted ``step`` does not advance the counter.
+        """
+        if not isinstance(name, str) or not name or len(name) > 256:
+            raise TypeError("metric name must be 1 to 256 characters")
+        edges, counts = bin_values(values, bins=bins)
+        return self._rich_log(Histogram.from_counts(edges, counts), name, step, axes)
+
+    def histogram_counts(
+        self,
+        name: str,
+        edges: Sequence[int | float],
+        counts: Sequence[int | float],
+        *,
+        step: int | None = None,
+        **axes: int | float | str,
+    ) -> bool:
+        """Log a ``rich_histogram`` point from explicit bins on ``name``.
+
+        Contract: ``edges`` are finite and strictly increasing and
+        ``counts`` holds one non-negative finite entry per bin. Optional
+        statistics pass as keyword arguments (``underflow``, ``overflow``,
+        ``total``, ``min``, ``max``, ``mean``, ``std``) and must be
+        finite — the named trio non-negative.
+        """
+        if not isinstance(name, str) or not name or len(name) > 256:
+            raise TypeError("metric name must be 1 to 256 characters")
+        stats = {
+            key: value
+            for key, value in axes.items()
+            if key in _HISTOGRAM_STATS and isinstance(value, int | float)
+        }
+        point_axes = {key: value for key, value in axes.items() if key not in _HISTOGRAM_STATS}
+        return self._rich_log(Histogram.from_counts(edges, counts, **stats), name, step, point_axes)
+
+    def _rich_log(
+        self,
+        value: RichValue,
+        name: str,
+        step: int | None,
+        axes: Mapping[str, int | float | str],
+    ) -> bool:
+        if not isinstance(name, str) or not name or len(name) > 256:
+            raise TypeError("metric name must be 1 to 256 characters")
+        if self._closed:
+            raise RuntimeError("run is closed")
+        coordinates, axis_names = self._coordinates(step, axes, advance=False)
+        document = self._rich_stream(name, value.renderer, axis_names)
+        return self._log_rich(document, value, coordinates=coordinates)
+
+    def _log_table_value(
+        self,
+        name: str,
+        columns: list[tuple[str, str]],
+        rows: list[list[JSONValue]],
+        blobs: list[PendingBlob],
+        step: int | None,
+        axes: Mapping[str, int | float | str],
+    ) -> bool:
+        table = _BuiltTable(columns, rows, blobs)
+        return self._rich_log(table, name, step, axes)
+
+    def _log_rich(
+        self,
+        document: Document,
+        value: RichValue,
+        *,
+        coordinates: list[dict[str, str]],
+    ) -> bool:
+        point_value = value.value()
+        blobs = self._pending_blobs(value, point_value)
+        if blobs:
+            return self.runtime.log_media(
+                document, point_value, coordinates=coordinates, blobs=blobs
+            )
+        return self.runtime.log(document, point_value, coordinates=coordinates)
+
+    def _pending_blobs(self, value: RichValue, point_value: JSONObject) -> list[PendingBlob]:
+        """Resolve every ``pending:<hash>`` artifact id inside a value."""
+        by_hash = {blob.hash: blob for blob in value.blobs()}
+        for hash in _pending_hashes(point_value):
+            if hash not in by_hash:
+                blob = self._media_blobs.get(hash)
+                if blob is None:
+                    raise ValueError("media item references an unknown pending upload")
+                by_hash[hash] = blob
+        return list(by_hash.values())
+
+    def _rich_stream(self, name: str, renderer: str, axes: tuple[str, ...]) -> Document:
+        existing = self._streams.get(name)
+        if existing is not None:
+            document, declared, declared_axes = existing
+            if declared != "object":
+                raise TypeError(f"metric {name!r} is {declared}, not a rich value")
+            stored = _stream_renderer(document)
+            if stored != renderer:
+                raise ValueError(f"metric {name!r} renders as {stored}, not {renderer}")
+            if declared_axes != axes:
+                raise ValueError(f"metric {name!r} axes are fixed")
+            return document
+        if self._reuse_streams:
+            found = self._find_stream(name)
+            if found is not None:
+                value_schema = found.spec.get("value_schema")
+                found_type = value_schema.get("type") if isinstance(value_schema, dict) else None
+                if found_type != "object":
+                    raise TypeError(f"metric {name!r} is {found_type}, not a rich value")
+                stored = _stream_renderer(found)
+                if stored != renderer:
+                    raise ValueError(f"metric {name!r} renders as {stored}, not {renderer}")
+                raw_axes = found.spec.get("axes")
+                if (
+                    not isinstance(raw_axes, list)
+                    or any(not isinstance(item, str) for item in raw_axes)
+                    or tuple(raw_axes) != axes
+                ):
+                    raise ValueError(f"metric {name!r} axes are fixed")
+                self._streams[name] = (found, "object", axes)
+                return found
+        spec: JSONObject = {
+            "name": name,
+            "participant_id": self.runtime.participant.id,
+            "value_schema": {"type": "object"},
+            "axes": list(axes),
+            "labels": {},
+            "presentation": {"renderer": renderer},
+        }
+        document = self._client.create_document("stream", self.runtime.scope, spec)
+        self._streams[name] = (document, "object", axes)
+        return document
+
+    def latest(
+        self, metric: str, *, run: str | None = None, **axes: int | float | str
+    ) -> dict[str, JSONValue] | None:
+        """Return the newest query-visible point for ``metric`` in this run.
+
+        Contract: streams that share the name are compared by ``observed_at``.
+        ``run`` is a title or id in this project; the point then comes from
+        that run. Keyword axes keep only points whose coordinates match those decimals,
+        then the newest ``observed_at`` among them is returned. The result is
+        ``{"value", "coordinates", "observed_at"}``. ``coordinates`` maps axis
+        name to decimal string. Returns ``None`` when the run has no matching
+        point. This does not read ``resume.json``.
+
+        Failure: ``ValueError`` for an empty name or an invalid axis.
+        ``LaunchHelmError`` when the client cannot query or a page is malformed.
+        """
+        if not isinstance(metric, str) or not metric:
+            raise ValueError("metric name is required")
+        if axes or run is not None:
+            filters: dict[str, Any] = dict(axes)
+            series = self.history(metric, run=run, **filters)
+            if not series:
+                return None
+            return max(series, key=lambda point: str(point["observed_at"]))
+        query = getattr(self.runtime.client, "query", None)
+        if not callable(query):
+            raise LaunchHelmError("protocol", "session client cannot query telemetry")
+        newest: dict[str, JSONValue] | None = None
+        newest_at = ""
+        for document in self._streams_named(metric):
+            point = _newest_point(query, document.id)
+            if point is None:
+                continue
+            observed = point["observed_at"]
+            if newest is not None and str(observed) <= newest_at:
+                continue
+            newest = point
+            newest_at = str(observed)
+        return newest
+
+    def history(
+        self,
+        metric: str,
+        *,
+        limit: int = 1000,
+        step_from: int | None = None,
+        step_to: int | None = None,
+        run: str | None = None,
+        **axes: int | float | str,
+    ) -> list[dict[str, JSONValue]]:
+        """Return query-visible points for ``metric``, oldest step first.
+
+        Contract: each item has the same ``value``, ``coordinates``, and
+        ``observed_at`` fields as ``latest``. Streams that share the name are
+        merged, including an earlier participant on this run. ``run`` is a
+        title or id in this project; the series then comes from that run
+        instead of this one. Keyword axes
+        keep only points whose coordinates match those decimals. ``step_from``
+        and ``step_to`` are an inclusive step window. Order is the
+        integer ``step`` coordinate, then ``observed_at``. Each server page is
+        1000 points. A full page is followed from its newest ``observed_at``,
+        so a step past the first page is still visible. A full page whose
+        points share one ``observed_at`` continues after that page's
+        ``epoch`` and ``sequence``. Axis and step filters
+        run after those pages. Without a step window, the newest ``limit``
+        points are returned, oldest step first within that tail, so the end
+        of a long run stays visible. A step window returns the oldest
+        ``limit`` matches inside it. ``limit`` is from 1 to 10000 and defaults to
+        1000. This does
+        not read ``resume.json``.
+
+        Failure: ``ValueError`` for an empty name, a limit outside that range,
+        or an invalid axis. ``LaunchHelmError`` when the client cannot query,
+        ``run`` does not match one run in this project, or a point is malformed.
+        """
+        if not isinstance(metric, str) or not metric:
+            raise ValueError("metric name is required")
+        if isinstance(limit, bool) or not isinstance(limit, int) or limit < 1 or limit > 10000:
+            raise ValueError("history limit must be from 1 to 10000")
+        for bound in (step_from, step_to):
+            if bound is not None and (isinstance(bound, bool) or not isinstance(bound, int)):
+                raise TypeError("step must be an integer")
+        if step_from is not None and step_to is not None and step_from > step_to:
+            raise ValueError("step_from is after step_to")
+        wanted = {name: _coordinate(value) for name, value in axes.items()}
+        for name in wanted:
+            if name == "step" or not _AXIS.fullmatch(name):
+                raise ValueError(f"invalid axis {name!r}")
+        query = getattr(self.runtime.client, "query", None)
+        if not callable(query):
+            raise LaunchHelmError("protocol", "session client cannot query telemetry")
+        series: list[dict[str, JSONValue]] = []
+        run_id = self._run_named(run) if run is not None else None
+        for document in self._streams_named(metric, run_id=run_id):
+            for viewed in self._history_pages(query, document.id):
+                coordinates = viewed["coordinates"]
+                if (
+                    isinstance(coordinates, dict)
+                    and all(coordinates.get(name) == value for name, value in wanted.items())
+                    and _step_in(viewed, step_from, step_to)
+                ):
+                    series.append(viewed)
+        series = _newer_coordinates(series)
+        series.sort(key=_history_key)
+        if step_from is None and step_to is None:
+            return series[-limit:]
+        return series[:limit]
+
+    def table(
+        self,
+        *metrics: str,
+        run: str | None = None,
+        axis: str = "step",
+        limit: int = 1000,
+    ) -> list[dict[str, JSONValue]]:
+        """Join query-visible series on one coordinate.
+
+        Contract: each row has that coordinate and the metric names that logged
+        a value there. A coordinate that omitted a metric does not invent a
+        value. Rows are oldest coordinate first. ``axis`` defaults to ``step``.
+        ``run`` is the same selector as ``history``.
+
+        Failure: ``ValueError`` when no metric is named or a name is empty.
+        ``LaunchHelmError`` when ``history`` cannot read a series.
+        """
+        if not metrics:
+            raise ValueError("metric name is required")
+        if not isinstance(axis, str) or not axis:
+            raise ValueError("axis name is required")
+        rows: dict[str, dict[str, JSONValue]] = {}
+        for name in metrics:
+            if not isinstance(name, str) or not name:
+                raise ValueError("metric name is required")
+            for point in self.history(name, run=run, limit=limit):
+                coordinates = point.get("coordinates")
+                key = coordinates.get(axis) if isinstance(coordinates, dict) else None
+                if not isinstance(key, str) or not key:
+                    continue
+                row = rows.setdefault(key, {axis: key})
+                row[name] = point["value"]
+
+        def order(key: str) -> tuple[int, int | str]:
+            try:
+                return (0, int(key))
+            except ValueError:
+                return (1, key)
+
+        return [rows[key] for key in sorted(rows, key=order)]
+
+    def compare(
+        self, metric: str, *runs: str, axis: str = "step", limit: int = 1000
+    ) -> list[dict[str, JSONValue]]:
+        """Join one metric across runs on the ``step`` coordinate.
+
+        Contract: each row has ``step`` and a column for every named run that
+        logged the metric there. A run that skipped the step has no column.
+        ``runs`` entries are titles or ids, the same selector as ``history``.
+        An empty name is this run, and its column is this run's title.
+        ``axis`` defaults to ``step``. Rows are oldest coordinate first.
+
+        Failure: ``ValueError`` when fewer than two runs are named.
+        ``LaunchHelmError`` when a run is not one run in this project.
+        """
+        if len(runs) < 2:
+            raise ValueError("compare needs two runs")
+        if not isinstance(axis, str) or not axis:
+            raise ValueError("axis name is required")
+        rows: dict[str, dict[str, JSONValue]] = {}
+        for name in runs:
+            if not isinstance(name, str):
+                raise ValueError("run name is required")
+            label = name or self.name
+            if not label:
+                raise ValueError("run name is required")
+            for point in self.history(metric, run=name or None, limit=limit):
+                coordinates = point.get("coordinates")
+                key = coordinates.get(axis) if isinstance(coordinates, dict) else None
+                if not isinstance(key, str) or not key:
+                    continue
+                row = rows.setdefault(key, {axis: key})
+                row[label] = point["value"]
+
+        def order(step: str) -> tuple[int, int | str]:
+            try:
+                return (0, int(step))
+            except ValueError:
+                return (1, step)
+
+        return [rows[step] for step in sorted(rows, key=order)]
+
+    def _history_pages(
+        self, query: Callable[..., JSONObject], stream_id: str
+    ) -> list[dict[str, JSONValue]]:
+        start = "1970-01-01T00:00:00Z"
+        end = "2261-01-01T00:00:00Z"
+        after_epoch = ""
+        after_sequence = ""
+        seen: set[tuple[str, tuple[tuple[str, JSONValue], ...], str, str, str]] = set()
+        collected: list[dict[str, JSONValue]] = []
+        for _ in range(_MAX_PAGES):
+            page = query(
+                stream_id,
+                start=start,
+                end=end,
+                limit=1000,
+                order="asc",
+                after_epoch=after_epoch,
+                after_sequence=after_sequence,
+            )
+            items = page.get("items") if isinstance(page, dict) else None
+            if not isinstance(items, list):
+                raise LaunchHelmError("protocol", "telemetry page is not a list")
+            if not items:
+                break
+            added = 0
+            last_at = start
+            last_epoch = after_epoch
+            last_sequence = after_sequence
+            for point in items:
+                viewed = _view_point(point)
+                coordinates = viewed["coordinates"]
+                pairs = tuple(sorted(coordinates.items())) if isinstance(coordinates, dict) else ()
+                identity = (
+                    str(viewed["observed_at"]),
+                    pairs,
+                    str(viewed["value"]),
+                    str(viewed.get("epoch") or ""),
+                    str(viewed.get("sequence") or ""),
+                )
+                if identity in seen:
+                    continue
+                seen.add(identity)
+                collected.append(viewed)
+                added += 1
+                observed = viewed["observed_at"]
+                if isinstance(observed, str):
+                    last_at = observed
+                if isinstance(point, dict):
+                    epoch = point.get("epoch")
+                    sequence = point.get("sequence")
+                    if isinstance(epoch, str) and epoch:
+                        last_epoch = epoch
+                    if isinstance(sequence, str) and sequence:
+                        last_sequence = sequence
+            full = len(items) >= 1000 or (isinstance(page, dict) and page.get("complete") is False)
+            cursor = (
+                bool(last_epoch)
+                and bool(last_sequence)
+                and (last_sequence != after_sequence or last_epoch != after_epoch)
+            )
+            advanced = last_at > start or cursor
+            if not full or added == 0 or not advanced:
+                break
+            start = last_at
+            after_epoch = last_epoch if cursor else ""
+            after_sequence = last_sequence if cursor else ""
+        return collected
+
+    def metrics(self, *, run: str | None = None) -> list[str]:
+        """Return the metric names already stored on this run, in order.
+
+        Contract: each name is a stream on the run, including a stream from
+        an earlier participant. ``run`` is a title or id in this project; the
+        names then come from that run. The list is unique and sorted. This
+        does not read ``resume.json``.
+
+        Failure: ``LaunchHelmError`` when a stream page is malformed or
+        ``run`` does not match one run in this project.
+        """
+        names: set[str] = set()
+        cursor = ""
+        run_id = self._run_named(run) if run is not None else self.runtime.scope.run_id
+        for _ in range(_MAX_PAGES):
+            page = self._client.list_documents(
+                kind="stream",
+                project_id=self.project_id,
+                run_id=run_id,
+                cursor=cursor,
+                limit=100,
+            )
+            items = page.get("items") or []
+            if not isinstance(items, list):
+                raise LaunchHelmError("protocol", "stream list is not a page")
+            for item in items:
+                if not isinstance(item, dict):
+                    raise LaunchHelmError("protocol", "stream list entry is not a document")
+                document = Document.parse(item)
+                name = document.spec.get("name")
+                if document.kind == "stream" and isinstance(name, str) and name:
+                    names.add(name)
+            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 sorted(names)
+
+    def metric(self, name: str, *, run: str | None = None) -> dict[str, JSONValue] | None:
+        """Return the stored kind and axes for ``name``.
+
+        Contract: ``{"kind", "axes", "unit"}`` from the stream on this run.
+        ``run`` is a title or id in this project; the description then comes
+        from that run. ``kind`` is ``number``, ``string``, or ``boolean``.
+        ``axes`` is the coordinate names, including ``step``. Returns ``None``
+        when the run has no stream of that name. This does not read ``resume.json``.
+
+        Failure: ``ValueError`` when ``name`` is empty. ``LaunchHelmError``
+        when a stream page is malformed or ``run`` does not match one run.
+        """
+        if not isinstance(name, str) or not name:
+            raise ValueError("metric name is required")
+        run_id = self._run_named(run) if run is not None else None
+        for document in self._streams_named(name, run_id=run_id):
+            schema = document.spec.get("value_schema")
+            kind = schema.get("type") if isinstance(schema, dict) else None
+            axes = document.spec.get("axes")
+            if not isinstance(kind, str) or not isinstance(axes, list):
+                continue
+            stored_unit = document.spec.get("unit")
+            return {
+                "kind": kind,
+                "axes": [item for item in axes if isinstance(item, str)],
+                "unit": stored_unit if isinstance(stored_unit, str) else "",
+            }
+        return None
+
+    def _run_named(self, run: str) -> str:
+        if not isinstance(run, str) or not run:
+            raise ValueError("run name is required")
+        matches: list[str] = []
+        cursor = ""
+        for _ in range(_MAX_PAGES):
+            page = self._client.list_documents(
+                kind="run", project_id=self.project_id, cursor=cursor, limit=100
+            )
+            items = page.get("items") or []
+            if not isinstance(items, list):
+                raise LaunchHelmError("protocol", "run list is not a page")
+            for item in items:
+                if not isinstance(item, dict):
+                    raise LaunchHelmError("protocol", "run list entry is not a document")
+                document = Document.parse(item)
+                if document.kind != "run" or document.scope.project_id != self.project_id:
+                    continue
+                if document.id == run or document.spec.get("name") == run:
+                    matches.append(document.id)
+            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
+        unique = list(dict.fromkeys(matches))
+        if len(unique) != 1:
+            raise LaunchHelmError("config", f"run {run!r} is not one run in this project")
+        return unique[0]
+
+    def _streams_named(self, metric: str, *, run_id: str | None = None) -> list[Document]:
+        found: list[Document] = []
+        cursor = ""
+        run_id = self.runtime.scope.run_id if run_id is None else run_id
+        for _ in range(_MAX_PAGES):
+            page = self._client.list_documents(
+                kind="stream",
+                project_id=self.project_id,
+                run_id=run_id,
+                cursor=cursor,
+                limit=100,
+            )
+            items = page.get("items") or []
+            if not isinstance(items, list):
+                raise LaunchHelmError("protocol", "stream list is not a page")
+            for item in items:
+                if not isinstance(item, dict):
+                    raise LaunchHelmError("protocol", "stream list entry is not a document")
+                document = Document.parse(item)
+                if document.kind == "stream" and document.spec.get("name") == metric:
+                    found.append(document)
+            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 _coordinates(
+        self, step: int | None, axes: Mapping[str, int | float | str], *, advance: bool
+    ) -> tuple[list[dict[str, str]], tuple[str, ...]]:
+        if step is None:
+            current = self._next_step
+        else:
+            if isinstance(step, bool) or not isinstance(step, int):
+                raise TypeError("step must be an integer")
+            current = step
+        values: dict[str, str] = {"step": str(current)}
+        for name, value in axes.items():
+            if name == "step" or not _AXIS.fullmatch(name):
+                raise ValueError(f"invalid axis {name!r}")
+            values[name] = _coordinate(value)
+        if advance:
+            self._next_step = max(self._next_step, current + 1)
+        names = tuple(values)
+        return [{"axis": name, "value": values[name]} for name in names], names
+
+    def _open_streams(self, missing: list[tuple[str, str]], axes: tuple[str, ...]) -> None:
+        if len(missing) < 2:
+            return
+        create_many = getattr(self._client, "create_documents", None)
+        if create_many is not None:
+            documents = create_many(
+                [
+                    (
+                        "stream",
+                        self.runtime.scope,
+                        {
+                            "name": name,
+                            "participant_id": self.runtime.participant.id,
+                            "value_schema": {"type": kind},
+                            "axes": list(axes),
+                            "labels": {},
+                        },
+                    )
+                    for name, kind in missing
+                ]
+            )
+            if len(documents) != len(missing):
+                raise LaunchHelmError("protocol", "stream batch length does not match")
+            for (name, kind), document in zip(missing, documents, strict=True):
+                self._streams[name] = (document, kind, axes)
+            return
+
+        def create(item: tuple[str, str]) -> tuple[str, str, Document]:
+            name, kind = item
+            document = self._client.create_document(
+                "stream",
+                self.runtime.scope,
+                {
+                    "name": name,
+                    "participant_id": self.runtime.participant.id,
+                    "value_schema": {"type": kind},
+                    "axes": list(axes),
+                    "labels": {},
+                },
+            )
+            return name, kind, document
+
+        workers = min(_STREAM_CREATES, len(missing))
+        with ThreadPoolExecutor(max_workers=workers) as pool:
+            opened = list(pool.map(create, missing))
+        for name, kind, document in opened:
+            self._streams[name] = (document, kind, axes)
+
+    def _stream(self, name: str, kind: str, axes: tuple[str, ...], unit: str = "") -> Document:
+        existing = self._streams.get(name)
+        if existing is not None:
+            document, declared, declared_axes = existing
+            stored_unit = (
+                document.spec.get("unit") if isinstance(document.spec.get("unit"), str) else ""
+            )
+            if unit and stored_unit and stored_unit != unit:
+                raise ValueError(f"metric {name!r} unit is fixed")
+            if declared != kind:
+                raise TypeError(f"metric {name!r} is {declared}, not {kind}")
+            if declared_axes != axes:
+                raise ValueError(f"metric {name!r} axes are fixed")
+            return document
+        if self._reuse_streams:
+            found = self._find_stream(name)
+            if found is not None:
+                value_schema = found.spec.get("value_schema")
+                found_type = value_schema.get("type") if isinstance(value_schema, dict) else None
+                raw_axes = found.spec.get("axes")
+                if not isinstance(found_type, str) or found_type != kind:
+                    raise TypeError(f"metric {name!r} is {found_type}, not {kind}")
+                if (
+                    not isinstance(raw_axes, list)
+                    or any(not isinstance(item, str) for item in raw_axes)
+                    or tuple(raw_axes) != axes
+                ):
+                    raise ValueError(f"metric {name!r} axes are fixed")
+                self._streams[name] = (found, kind, axes)
+                return found
+        schema: JSONObject = {"type": kind}
+        labels: JSONObject = {}
+        spec: JSONObject = {
+            "name": name,
+            "participant_id": self.runtime.participant.id,
+            "value_schema": schema,
+            "axes": list(axes),
+            "labels": labels,
+        }
+        if unit:
+            spec["unit"] = unit
+        document = self._client.create_document(
+            "stream",
+            self.runtime.scope,
+            spec,
+        )
+        self._streams[name] = (document, kind, axes)
+        return document
+
+    def _find_stream(self, name: str) -> Document | None:
+        participant_id = self.runtime.participant.id
+        run_id = self.runtime.scope.run_id
+        cursor = ""
+        for _ in range(_MAX_PAGES):
+            page = self._client.list_documents(
+                kind="stream",
+                project_id=self.project_id,
+                run_id=run_id,
+                cursor=cursor,
+                limit=100,
+            )
+            items = page.get("items") or []
+            if not isinstance(items, list):
+                raise LaunchHelmError("protocol", "stream list is not a page")
+            for item in items:
+                if not isinstance(item, dict):
+                    raise LaunchHelmError("protocol", "stream list entry is not a document")
+                document = Document.parse(item)
+                if document.kind != "stream" or document.spec.get("name") != name:
+                    continue
+                if document.spec.get("participant_id") == participant_id:
+                    return document
+            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 None
+
+
+def init(
+    project: str,
+    *,
+    overflow: OverflowPolicy = "block",
+    name: str = "",
+    config: Mapping[str, JSONValue] | None = None,
+    group: str = "",
+    tags: Sequence[str] = (),
+    notes: str = "",
+    organization: str = "",
+    client: SessionClient | None = None,
+    state_dir: str | Path | None = None,
+    media_spool_bytes: int = 256 << 20,
+    resume: str = "",
+    project_id: str = "",
+    participant_name: str = "",
+    participant_role: str = "logger",
+    participant_labels: Mapping[str, str] | None = None,
+) -> Run:
+    """Open a logging run.
+
+    Contract: the default overflow is ``block``. Admitted points are written
+    to the local spool and are not dropped while the run is open. An existing
+    project with this exact name is reused. A new run is created unless
+    ``resume`` names an existing run id or run title in that project. The
+    ``keep`` writes trainer state, the next log step, and the participant id
+    to ``resume.json``. ``init`` with ``resume`` loads that snapshot and
+    reopens the same participant, so later points use the same streams and
+    the existing spool can finish uploading. A resume with no checkpoint
+    reopens a participant directory that still has unacknowledged points,
+    so those points upload. Otherwise it creates a new participant.
+    When ``client`` is omitted, the API origin is ``LAUNCHHELM_URL`` or
+    ``https://launchhelm.com``. ``LAUNCHHELM_API_KEY`` is the credential.
+    ``LAUNCHHELM_ORGANIZATION`` is required only when the key belongs to more
+    than one organization. ``LAUNCHHELM_PROJECT`` or ``project_id`` opens that
+    project directly. A project-scoped key cannot scan the organization
+    catalog, so the credential the app issues sets ``LAUNCHHELM_PROJECT``.
+    Unset keys are filled from ``.env`` files from the working directory up
+    to the filesystem root. Shell variables win over files. ``participant_name``
+    names the new participant instead of the ``logger-<pid>`` default,
+    ``participant_role`` overrides its role, and ``participant_labels``
+    merges labels into its spec; all apply only when a participant is
+    created, so a resumed run keeps its stored identity.
+
+    Failure: ``ValueError`` for an empty project name, a bad overflow, or a
+    config that cannot be a label. ``LaunchHelmError`` when the key is
+    missing, the organization is ambiguous, or two projects share the name.
+    """
+    load_env()
+    if overflow not in {"drop_new", "block", "raise"}:
+        raise ValueError("overflow must be drop_new, block, or raise")
+    if not project or len(project) > 256:
+        raise ValueError("project name must be 1 to 256 characters")
+    owns_client = client is None
+    if client is None:
+        client = _init_client(organization)
+    owned_metadata: SessionClient | None = None
+    try:
+        run_name, supplied, labels = _run_labels(name, config, group, tags, notes)
+        found = _init_project(client, project, project_id, owns_client, resume)
+        opened, run_name = _open_init_run(
+            client, found, resume, run_name, labels, supplied, state_dir
+        )
+        directory = Path.cwd() / ".launchhelm" / opened.id if state_dir is None else Path(state_dir)
+        directory.mkdir(parents=True, exist_ok=True)
+        checkpoint = directory / "resume.json"
+        participant, next_step, restored, saved_summary, reused = _init_participant(
+            client,
+            found,
+            opened,
+            resume,
+            directory,
+            checkpoint,
+            participant_name,
+            participant_role,
+            participant_labels,
+        )
+        # The worker key only publishes this participant's catalog; run-level
+        # writes (summary, metadata, state) keep the original credential on a
+        # client held in memory only.
+        bound = _bind_worker(client, participant)
+        metadata: SessionClient = client
+        if bound:
+            with_key = getattr(client, "with_key", None)
+            if callable(with_key):
+                derived = with_key()
+                if derived is not client:
+                    owned_metadata = derived
+                    metadata = derived
+        runtime = Runtime(
+            client,
+            participant.id,
+            state_dir=directory / "participants" / participant.id,
+            overflow=overflow,
+            media_spool_bytes=media_spool_bytes,
+            serve_commands=False,
+        )
+    except BaseException:
+        if owned_metadata is not None:
+            owned_metadata.close()
+        if owns_client:
+            client.close()
+        raise
+    return Run(
+        runtime,
+        client=client,
+        name=run_name,
+        owned_client=client if owns_client else None,
+        metadata_client=metadata,
+        owned_metadata=owned_metadata,
+        checkpoint=checkpoint,
+        restored=restored,
+        next_step=next_step,
+        reuse_streams=reused,
+        config=_resume_config(client, opened) if resume else supplied,
+        summary=(
+            saved_summary
+            if saved_summary is not None
+            else (_summary_from_run(opened) if resume else None)
+        ),
+        summary_changed=saved_summary is not None,
+        group=_metadata_value(opened, "launchhelm.group"),
+        tags=_metadata_tags(opened),
+        notes=_metadata_value(opened, "launchhelm.notes"),
+        git=_metadata_value(opened, "launchhelm.git"),
+        host=_metadata_value(opened, "launchhelm.host"),
+        python=_metadata_value(opened, "launchhelm.python"),
+        argv=_metadata_value(opened, "launchhelm.argv"),
+    )
+
+
+def _init_client(organization: str) -> Client:
+    url = _api_url()
+    key = _env("LAUNCHHELM_API_KEY")
+    selected = organization or os.environ.get("LAUNCHHELM_ORGANIZATION", "")
+    if not selected:
+        selected = _only_organization(url, key)
+    return Client(url, key, selected)
+
+
+def _run_labels(
+    name: str,
+    config: Mapping[str, JSONValue] | None,
+    group: str,
+    tags: Sequence[str],
+    notes: str,
+) -> tuple[str, dict[str, JSONValue], JSONObject]:
+    run_name = name or f"run-{uuid4().hex[:12]}"
+    if len(run_name) > 256:
+        raise ValueError("run name must be at most 256 characters")
+    supplied = dict(config or {})
+    labels = _labels(supplied)
+    _metadata(labels, group, tags, notes)
+    _provenance(labels)
+    return run_name, supplied, labels
+
+
+def _init_project(
+    client: SessionClient, project: str, project_id: str, owns_client: bool, resume: str
+) -> Document:
+    selected = project_id
+    if not selected and owns_client:
+        selected = os.environ.get("LAUNCHHELM_PROJECT", "")
+    found = _open_project(client, project, selected)
+    if found is None:
+        if resume:
+            raise LaunchHelmError("not_found", f"project {project!r} does not exist")
+        found = client.create_document(
+            "project",
+            Scope(client.organization_id),
+            {"name": project, "labels": {}},
+        )
+    return found
+
+
+def _open_init_run(
+    client: SessionClient,
+    found: Document,
+    resume: str,
+    run_name: str,
+    labels: JSONObject,
+    supplied: dict[str, JSONValue],
+    state_dir: str | Path | None,
+) -> tuple[Document, str]:
+    saved_run = ""
+    if resume and state_dir is not None:
+        preview = Path(state_dir) / "resume.json"
+        if preview.is_file():
+            saved_run = _read_checkpoint(preview)[4]
+    if resume and saved_run:
+        opened = client.get_document(saved_run)
+        if opened.kind != "run" or opened.scope.project_id != found.id:
+            raise LaunchHelmError("not_found", f"open run {saved_run!r} was not found")
+        if opened.spec.get("state") != "open":
+            raise LaunchHelmError("conflict", f"run {saved_run!r} is not open")
+        return opened, str(opened.spec.get("name") or resume)
+    if resume:
+        opened = _run(client, found.id, resume)
+        return opened, str(opened.spec.get("name") or resume)
+    opened = client.create_document(
+        "run",
+        Scope(client.organization_id, found.id),
+        {
+            "name": run_name,
+            "state": "open",
+            "configuration": opaque_schema(),
+            "labels": labels,
+            **({"parameters": supplied} if supplied else {}),
+        },
+    )
+    return opened, run_name
+
+
+def _init_participant(
+    client: SessionClient,
+    found: Document,
+    opened: Document,
+    resume: str,
+    directory: Path,
+    checkpoint: Path,
+    participant_name: str,
+    participant_role: str,
+    participant_labels: Mapping[str, str] | None,
+) -> tuple[Document, int, dict[str, JSONValue], dict[str, JSONValue] | None, bool]:
+    next_step, restored, saved_participant, saved_summary, _saved_run = _read_checkpoint(checkpoint)
+    if resume and not checkpoint.is_file():
+        next_step, restored = _server_cursor(client, opened.scope.project_id, opened.id)
+        if not saved_participant:
+            saved_participant = _pending_participant(directory)
+    participant = _saved_participant(client, opened, saved_participant) if resume else None
+    reused = participant is not None
+    if participant is None:
+        labels: JSONObject = {}
+        if participant_labels:
+            labels.update(participant_labels)
+        participant = client.create_document(
+            "participant",
+            Scope(client.organization_id, found.id, opened.id),
+            {
+                "name": participant_name or f"logger-{os.getpid()}",
+                "role": participant_role,
+                "labels": labels,
+            },
+        )
+    return participant, next_step, restored, saved_summary, reused
+
+
+def _bind_worker(client: SessionClient, participant: Document) -> bool:
+    """Mint the participant-bound worker key and adopt it on ``client``.
+
+    Returns ``True`` when a worker credential was adopted; the caller then
+    keeps a second client on the original credential for run-level writes.
+    """
+    create = getattr(client, "create_key", None)
+    if create is None:
+        return False
+    created = create(participant)
+    token = created.get("token") if isinstance(created, dict) else ""
+    adopt = getattr(client, "adopt", None)
+    if isinstance(token, str) and token and adopt is not None:
+        adopt(token)
+        return True
+    return False
+
+
+def _only_organization(url: str, key: str) -> str:
+    probe = Client(url, key, "00000000-0000-4000-8000-000000000000")
+    try:
+        found = probe.list_my_organizations()
+    finally:
+        probe.close()
+    return _select_organization("", found)
+
+
+def _select_organization(explicit: str, found: list[tuple[str, str]]) -> str:
+    if explicit:
+        return explicit
+    if len(found) == 1:
+        return found[0][0]
+    if not found:
+        raise LaunchHelmError("config", "this key is not a member of an organization")
+    shown = ", ".join(name or identity for identity, name in found[:8])
+    raise LaunchHelmError(
+        "config",
+        f"set LAUNCHHELM_ORGANIZATION; this key is in more than one organization ({shown})",
+    )
+
+
+def _api_url() -> str:
+    return os.environ.get("LAUNCHHELM_URL") or DEFAULT_URL
+
+
+def _env(name: str) -> str:
+    value = os.environ.get(name, "")
+    if not value:
+        raise LaunchHelmError("config", f"{name} is required")
+    return value
+
+
+def _metadata(labels: JSONObject, group: str, tags: Sequence[str], notes: str) -> None:
+    if not isinstance(group, str) or len(group) > 256:
+        raise ValueError("group must be at most 256 characters")
+    if not isinstance(notes, str) or len(notes) > _MAX_LABEL:
+        raise ValueError("notes must be at most 1024 characters")
+    if not isinstance(tags, Sequence) or isinstance(tags, str):
+        raise TypeError("tags must be a sequence of strings")
+    cleaned = []
+    for tag in tags:
+        if not isinstance(tag, str) or not tag or len(tag) > 64:
+            raise ValueError("each tag must be 1 to 64 characters")
+        cleaned.append(tag)
+    encoded = json.dumps(cleaned, separators=(",", ":"))
+    if len(encoded) > _MAX_LABEL:
+        raise ValueError("tags must fit in 1024 characters")
+    if group:
+        labels["launchhelm.group"] = group
+    if cleaned:
+        labels["launchhelm.tags"] = encoded
+    if notes:
+        labels["launchhelm.notes"] = notes
+
+
+def _provenance(labels: JSONObject) -> None:
+    """Record the code and machine that opened the run.
+
+    Contract: ``launchhelm.python``, ``launchhelm.host``, and ``launchhelm.argv``
+    are always set. ``argv`` is the process command, at most 1024 characters.
+    ``launchhelm.git`` is the current commit when this directory is a git
+    checkout. A missing git command or a non-repository leaves that label
+    unset. These labels are not config.
+
+    Failure: none. Capture never blocks ``init``.
+    """
+    labels["launchhelm.python"] = platform.python_version()
+    command = shlex.join(sys.argv)
+    if command:
+        labels["launchhelm.argv"] = command[:_MAX_LABEL]
+    host = socket.gethostname()
+    if host:
+        labels["launchhelm.host"] = host[:256]
+    git = shutil.which("git")
+    if git is None:
+        return
+    try:
+        completed = subprocess.run(  # noqa: S603 - fixed argv, resolved binary
+            [git, "rev-parse", "HEAD"],
+            check=False,
+            capture_output=True,
+            text=True,
+            timeout=2,
+        )
+    except (OSError, subprocess.TimeoutExpired):
+        return
+    revision = completed.stdout.strip()
+    if completed.returncode == 0 and re.fullmatch(r"[0-9a-fA-F]{7,64}", revision):
+        labels["launchhelm.git"] = revision.lower()
+
+
+def _metadata_value(document: Document, key: str) -> str:
+    labels = document.spec.get("labels")
+    if not isinstance(labels, dict):
+        return ""
+    value = labels.get(key)
+    return value if isinstance(value, str) else ""
+
+
+def _metadata_tags(document: Document) -> tuple[str, ...]:
+    raw = _metadata_value(document, "launchhelm.tags")
+    if not raw:
+        return ()
+    parsed = json.loads(raw)
+    if not isinstance(parsed, list) or any(not isinstance(item, str) for item in parsed):
+        raise LaunchHelmError("protocol", "run tags are not a list of strings")
+    return tuple(parsed)
+
+
+def _labels(config: Mapping[str, JSONValue]) -> JSONObject:
+    if len(config) > _MAX_LABELS:
+        raise ValueError("config has more than 64 labels")
+    labels: JSONObject = {}
+    for key, value in config.items():
+        if not isinstance(key, str) or not key:
+            raise ValueError("config label name is empty")
+        if isinstance(value, bool):
+            text = "true" if value else "false"
+        elif isinstance(value, int):
+            text = str(value)
+        elif isinstance(value, float):
+            if not math.isfinite(value):
+                raise ValueError("config label cannot be non-finite")
+            text = format(value, ".16g")
+        elif isinstance(value, str):
+            text = value
+        elif isinstance(value, dict | list):
+            encoded = _JSON_LABEL + json.dumps(value, allow_nan=False, separators=(",", ":"))
+            if len(encoded) > _MAX_LABEL:
+                continue
+            text = encoded
+        else:
+            raise ValueError("config labels must be scalars, objects, or lists")
+        if len(text) > _MAX_LABEL:
+            continue
+        labels[key] = text
+    return labels
+
+
+def _reduction_item(run: Document, name: str) -> dict[str, JSONValue] | None:
+    labels = run.spec.get("labels")
+    raw = labels.get("launchhelm.reduction") if isinstance(labels, dict) else None
+    if not isinstance(raw, str) or not raw:
+        return None
+    parsed = json.loads(raw)
+    item = parsed.get(name) if isinstance(parsed, dict) else None
+    return item if isinstance(item, dict) else None
+
+
+def _summary_from_run(run: Document) -> dict[str, JSONValue]:
+    labels = run.spec.get("labels")
+    if not isinstance(labels, dict):
+        return {}
+    raw = labels.get("launchhelm.summary")
+    if not isinstance(raw, str) or not raw:
+        return {}
+    parsed = json.loads(raw)
+    if not isinstance(parsed, dict):
+        raise LaunchHelmError("config", "summary label is not an object")
+    return parsed
+
+
+def _resume_config(client: SessionClient, run: Document) -> dict[str, JSONValue]:
+    parameters = run.spec.get("parameters")
+    if isinstance(parameters, dict):
+        return dict(parameters)
+    labels = run.spec.get("labels")
+    if isinstance(labels, dict):
+        artifact_id = labels.get("launchhelm.config")
+        if isinstance(artifact_id, str) and artifact_id:
+            download = getattr(client, "download_artifact", None)
+            if not callable(download):
+                raise LaunchHelmError("protocol", "session client cannot download config")
+            body = download(artifact_id)
+            if not isinstance(body, bytes | str):
+                raise LaunchHelmError("protocol", "config artifact is not text")
+            parsed = json.loads(body)
+            if not isinstance(parsed, dict):
+                raise LaunchHelmError("config", "config artifact is not an object")
+            return parsed
+    return _config_from_labels(labels)
+
+
+def _config_from_labels(labels: object) -> dict[str, JSONValue]:
+    if not isinstance(labels, dict):
+        return {}
+    config: dict[str, JSONValue] = {}
+    for key, value in labels.items():
+        if not isinstance(key, str) or not isinstance(value, str):
+            continue
+        if key in {
+            "launchhelm.summary",
+            "launchhelm.config",
+            "launchhelm.group",
+            "launchhelm.tags",
+            "launchhelm.notes",
+            "launchhelm.git",
+            "launchhelm.host",
+            "launchhelm.python",
+            "launchhelm.argv",
+        }:
+            continue
+        if value.startswith(_JSON_LABEL):
+            parsed = json.loads(value[len(_JSON_LABEL) :])
+            if not isinstance(parsed, dict | list):
+                raise LaunchHelmError("config", f"config label {key!r} is not an object or list")
+            config[key] = parsed
+        else:
+            config[key] = value
+    return config
+
+
+def _open_project(client: SessionClient, name: str, project_id: str) -> Document | None:
+    if not project_id:
+        return _project(client, name)
+    document = client.get_document(project_id)
+    if document.kind != "project":
+        raise LaunchHelmError("not_found", f"project {project_id!r} does not exist")
+    if document.spec.get("name") != name:
+        raise LaunchHelmError("conflict", f"project {project_id!r} is not named {name!r}")
+    return document
+
+
+def _project(client: SessionClient, name: str) -> Document | None:
+    cursor = ""
+    matches: list[Document] = []
+    for _ in range(_MAX_PAGES):
+        page = client.list_documents(kind="project", cursor=cursor, limit=100)
+        items = page.get("items") or []
+        if not isinstance(items, list):
+            raise LaunchHelmError("protocol", "project list is not a page")
+        for item in items:
+            if not isinstance(item, dict):
+                raise LaunchHelmError("protocol", "project list entry is not a document")
+            document = Document.parse(item)
+            if document.kind == "project" and document.spec.get("name") == name:
+                matches.append(document)
+        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
+    if len(matches) > 1:
+        raise LaunchHelmError("conflict", f"more than one project is named {name!r}")
+    return matches[0] if matches else None
+
+
+def _scalar(value: JSONValue) -> tuple[str, JSONValue]:
+    if isinstance(value, bool):
+        return "boolean", value
+    if isinstance(value, str):
+        return "string", value
+    if isinstance(value, int | float):
+        return "number", scalar(value)
+    raise TypeError("metric value must be a boolean, string, or number")
+
+
+def _coordinate(value: int | float | str) -> str:
+    if isinstance(value, bool) or not isinstance(value, int | float | str):
+        raise TypeError("coordinate must be an integer, finite float, or decimal string")
+    if isinstance(value, float):
+        if not math.isfinite(value):
+            raise ValueError("coordinate cannot be non-finite")
+        text = format(Decimal(str(value)), "f")
+        if "." in text:
+            text = text.rstrip("0").rstrip(".")
+        if text.startswith("."):
+            text = "0" + text
+        elif text.startswith("-."):
+            text = "-0" + text[1:]
+        if text in {"", "-"}:
+            text = "0"
+    elif isinstance(value, int):
+        text = str(value)
+    else:
+        text = value
+    if not _COORD.fullmatch(text):
+        raise ValueError(f"coordinate {text!r} is not a decimal")
+    return text
+
+
+def _run(client: SessionClient, project_id: str, token: str) -> Document:
+    cursor = ""
+    matches: list[Document] = []
+    for _ in range(_MAX_PAGES):
+        page = client.list_documents(kind="run", project_id=project_id, cursor=cursor, limit=100)
+        items = page.get("items") or []
+        if not isinstance(items, list):
+            raise LaunchHelmError("protocol", "run list is not a page")
+        for item in items:
+            if not isinstance(item, dict):
+                raise LaunchHelmError("protocol", "run list entry is not a document")
+            document = Document.parse(item)
+            if document.kind != "run":
+                continue
+            if document.id == token or document.spec.get("name") == token:
+                matches.append(document)
+        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
+    if not matches:
+        raise LaunchHelmError("not_found", f"open run {token!r} was not found")
+    if len(matches) > 1:
+        raise LaunchHelmError("conflict", f"more than one run is named {token!r}")
+    opened = matches[0]
+    if opened.spec.get("state") != "open":
+        raise LaunchHelmError("conflict", f"run {token!r} is not open")
+    return opened
+
+
+def _pending_participant(directory: Path) -> str:
+    root = directory / "participants"
+    if not root.is_dir():
+        return ""
+    chosen = ""
+    newest = -1.0
+    for child in root.iterdir():
+        database = child / "state.sqlite3"
+        if not database.is_file():
+            continue
+        try:
+            connection = sqlite3.connect(f"file:{database}?mode=ro", uri=True)
+            try:
+                row = connection.execute("SELECT COUNT(*) FROM points").fetchone()
+                pending = int(row[0]) if row else 0
+                try:
+                    row = connection.execute("SELECT COUNT(*) FROM media_points").fetchone()
+                    pending += int(row[0]) if row else 0
+                except sqlite3.Error:
+                    # Spool files written before media support lack the table.
+                    pass
+            finally:
+                connection.close()
+        except sqlite3.Error:
+            continue
+        if pending == 0:
+            continue
+        modified = database.stat().st_mtime
+        if modified >= newest:
+            newest = modified
+            chosen = child.name
+    return chosen
+
+
+def _saved_participant(
+    client: SessionClient, run: Document, participant_id: str
+) -> Document | None:
+    if not participant_id:
+        return None
+    try:
+        document = client.get_document(participant_id)
+    except (LaunchHelmError, KeyError):
+        return None
+    if document.kind != "participant" or document.scope.run_id != run.id:
+        return None
+    return document
+
+
+def _view_point(point: JSONValue) -> dict[str, JSONValue]:
+    if not isinstance(point, dict):
+        raise LaunchHelmError("protocol", "telemetry point is not an object")
+    observed = point.get("observed_at")
+    if not isinstance(observed, str):
+        raise LaunchHelmError("protocol", "telemetry point has no observed_at")
+    coordinates = point.get("coordinates")
+    if not isinstance(coordinates, list):
+        raise LaunchHelmError("protocol", "telemetry point has no coordinates")
+    axes: dict[str, JSONValue] = {}
+    for item in coordinates:
+        if not isinstance(item, dict):
+            raise LaunchHelmError("protocol", "telemetry coordinate is not an object")
+        axis = item.get("axis")
+        value = item.get("value")
+        if not isinstance(axis, str) or not isinstance(value, str):
+            raise LaunchHelmError("protocol", "telemetry coordinate is invalid")
+        axes[axis] = value
+    viewed: dict[str, JSONValue] = {
+        "value": point.get("value"),
+        "coordinates": axes,
+        "observed_at": observed,
+    }
+    for key in ("epoch", "sequence"):
+        raw = point.get(key)
+        if isinstance(raw, str) and raw:
+            viewed[key] = raw
+    return viewed
+
+
+def _newer_coordinates(
+    series: list[dict[str, JSONValue]],
+) -> list[dict[str, JSONValue]]:
+    chosen: dict[tuple[tuple[str, JSONValue], ...], dict[str, JSONValue]] = {}
+    order: list[tuple[tuple[str, JSONValue], ...]] = []
+    for point in series:
+        coordinates = point["coordinates"]
+        key = tuple(sorted(coordinates.items())) if isinstance(coordinates, dict) else ()
+        sequence = point.get("sequence")
+        if isinstance(sequence, str) and sequence:
+            key = (*key, ("sequence", sequence))
+        previous = chosen.get(key)
+        if previous is None:
+            order.append(key)
+            chosen[key] = point
+        elif str(point["observed_at"]) >= str(previous["observed_at"]):
+            chosen[key] = point
+    return [chosen[key] for key in order]
+
+
+def _step_in(point: dict[str, JSONValue], start: int | None, end: int | None) -> bool:
+    if start is None and end is None:
+        return True
+    coordinates = point["coordinates"]
+    step = coordinates.get("step") if isinstance(coordinates, dict) else None
+    if not isinstance(step, str) or not step.lstrip("-").isdigit():
+        return False
+    value = int(step)
+    if start is not None and value < start:
+        return False
+    return not (end is not None and value > end)
+
+
+def _newest_point(query: Callable[..., JSONValue], stream_id: str) -> dict[str, JSONValue] | None:
+    page = query(
+        stream_id,
+        start="1970-01-01T00:00:00Z",
+        end="2261-01-01T00:00:00Z",
+        limit=1,
+        order="desc",
+    )
+    items = page.get("items") if isinstance(page, dict) else None
+    if not isinstance(items, list) or not items:
+        return None
+    point = items[0]
+    if not isinstance(point, dict):
+        raise LaunchHelmError("protocol", "telemetry point is not an object")
+    observed = point.get("observed_at")
+    if not isinstance(observed, str):
+        raise LaunchHelmError("protocol", "telemetry point has no observed_at")
+    coordinates = point.get("coordinates")
+    if not isinstance(coordinates, list):
+        raise LaunchHelmError("protocol", "telemetry point has no coordinates")
+    axes: dict[str, JSONValue] = {}
+    for item in coordinates:
+        if not isinstance(item, dict):
+            raise LaunchHelmError("protocol", "telemetry coordinate is not an object")
+        axis = item.get("axis")
+        value = item.get("value")
+        if not isinstance(axis, str) or not isinstance(value, str):
+            raise LaunchHelmError("protocol", "telemetry coordinate is invalid")
+        axes[axis] = value
+    return {"value": point.get("value"), "coordinates": axes, "observed_at": observed}
+
+
+def _history_key(point: dict[str, JSONValue]) -> tuple[int, str]:
+    coordinates = point["coordinates"]
+    step = coordinates.get("step") if isinstance(coordinates, dict) else None
+    rank = 2**63 - 1
+    if isinstance(step, str) and step.lstrip("-").isdigit():
+        rank = int(step)
+    observed = point["observed_at"]
+    return rank, observed if isinstance(observed, str) else ""
+
+
+def _server_cursor(
+    client: SessionClient, project_id: str, run_id: str
+) -> tuple[int, dict[str, JSONValue]]:
+    query = getattr(client, "query", None)
+    if not callable(query):
+        return 0, {}
+    highest = -1
+    newest_at = ""
+    coordinates: dict[str, JSONValue] = {}
+    cursor = ""
+    for _ in range(_MAX_PAGES):
+        page = client.list_documents(
+            kind="stream",
+            project_id=project_id,
+            run_id=run_id,
+            cursor=cursor,
+            limit=100,
+        )
+        items = page.get("items") or []
+        if not isinstance(items, list):
+            return 0, {}
+        for item in items:
+            if not isinstance(item, dict):
+                continue
+            document = Document.parse(item)
+            if document.kind != "stream":
+                continue
+            try:
+                points = query(
+                    document.id,
+                    start="1970-01-01T00:00:00Z",
+                    end="2261-01-01T00:00:00Z",
+                    limit=1,
+                    order="desc",
+                )
+            except (LaunchHelmError, TypeError, ValueError):
+                continue
+            listed = points.get("items") if isinstance(points, dict) else None
+            if not isinstance(listed, list) or not listed:
+                continue
+            viewed = _view_point(listed[0])
+            axes = viewed["coordinates"]
+            step = axes.get("step") if isinstance(axes, dict) else None
+            if isinstance(step, str) and step.lstrip("-").isdigit():
+                highest = max(highest, int(step))
+            observed = viewed["observed_at"]
+            if isinstance(observed, str) and observed > newest_at and isinstance(axes, dict):
+                newest_at = observed
+                coordinates = dict(axes)
+        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 0 if highest < 0 else highest + 1, coordinates
+
+
+def _read_checkpoint(
+    path: Path,
+) -> tuple[int, dict[str, JSONValue], str, dict[str, JSONValue] | None, str]:
+    if not path.is_file():
+        return 0, {}, "", None, ""
+    body = json.loads(path.read_text(encoding="utf-8"))
+    if not isinstance(body, dict):
+        raise LaunchHelmError("config", "resume checkpoint is not an object")
+    step = body.get("step", 0)
+    state = body.get("state", {})
+    participant_id = body.get("participant_id", "")
+    if isinstance(step, bool) or not isinstance(step, int) or step < 0:
+        raise LaunchHelmError("config", "resume checkpoint step is invalid")
+    if not isinstance(state, dict):
+        raise LaunchHelmError("config", "resume checkpoint state is invalid")
+    if not isinstance(participant_id, str):
+        raise LaunchHelmError("config", "resume checkpoint participant is invalid")
+    run_id = body.get("run_id", "")
+    if not isinstance(run_id, str):
+        raise LaunchHelmError("config", "resume checkpoint run is invalid")
+    restored: dict[str, JSONValue] = {}
+    for key, value in state.items():
+        if not isinstance(key, str):
+            raise LaunchHelmError("config", "resume checkpoint state key is invalid")
+        restored[key] = value
+    saved_summary: dict[str, JSONValue] | None = None
+    if "summary" in body:
+        summary = body["summary"]
+        if not isinstance(summary, dict):
+            raise LaunchHelmError("config", "resume checkpoint summary is invalid")
+        saved_summary = {}
+        for key, value in summary.items():
+            if not isinstance(key, str):
+                raise LaunchHelmError("config", "resume checkpoint summary key is invalid")
+            saved_summary[key] = value
+    return step, restored, participant_id, saved_summary, run_id