simulo 0.26.0__py3-none-any.whl

simulo/_client/preflight_render.py

@@ -0,0 +1,200 @@
+"""Shared preflight finding rendering — ``simulo prepare`` (``cli.py``)
+and ``simulo run``'s preflight phase (``app.py``) render
+the identical wire finding format (:class:`simulo.interfaces.platform.
+manifest.PreflightFinding`) through this ONE module rather than each keeping
+its own copy of the per-code text and the control-character defense — two
+independent copies is exactly how a code's rendering (or the sanitizer)
+drifts between the two commands. For the same reason, the outcome-level
+rendering (fail-open notice, the ``✗``/``⚠`` finding loops) also lives here —
+see :func:`render_preflight_skip_notice` / :func:`render_preflight_findings`
+— rather than as two copies in ``cli.py`` and ``app.py``.
+
+The finding ``code`` strings below are the server's own vocabulary
+(``simulo_control_plane.preflight.constants``) — deliberately NOT part of
+the ``simulo-interfaces`` contract, which pins only ``FINDING_CLASSIFICATIONS``
+(``blocking``/``advisory``): codes are an APPEND-ONLY server vocabulary a
+client can never fully enumerate ahead of time, so a code this module
+doesn't recognise (including one invented after this client shipped) still
+renders — generically, via :func:`render_preflight_finding_text`'s fallback
+— never a failure to render. Mirrored here as bare string literals rather
+than imported for that reason.
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:  # typing-only; avoids a module-scope dependency on the HTTP client
+    from simulo._client.preflight_api import PreflightOutcome
+    from simulo.interfaces.platform.manifest import PreflightFinding
+
+PIP_VERSION_CONFLICT_CODE = "pip_version_conflict"
+RUNTIME_MANIFEST_UNAVAILABLE_CODE = "runtime_manifest_unavailable"
+UNKNOWN_RUNTIME_CODE = "unknown_runtime"
+PACKAGE_TOO_LARGE_CODE = "package_too_large"
+JOB_TIMEOUT_INVALID_CODE = "job_timeout_invalid"
+RESERVED_RUNTIME_ENV_CODE = "reserved_runtime_env_keys"
+NO_ACTIVE_WORKER_CODE = "no_active_worker"
+
+#: The blocking finding for a manifest that names a runtime this platform
+#: has never reported. Its own finding TEXT still renders through the
+#: generic ``details["message"]`` fallback below — the server owns that
+#: sentence and this change leaves it untouched — but ``app.py`` needs this
+#: code as a value to switch on (not string-matching a rendered message)
+#: for the separate, generic "Pass --skip-preflight" follow-on hint it
+#: prints after a blocking finding: see :func:`app._skip_preflight_hint`.
+RUNTIME_NOT_AVAILABLE_CODE = "runtime_not_available"
+
+#: C0 (0x00-0x1F minus TAB/LF, which legitimate multi-line detail text may
+#: use) and C1 (0x7F-0x9F, including DEL) control characters. Used to strip
+#: ESC/CR/OSC-framing bytes out of server-supplied finding text before it
+#: ever reaches a terminal — see :func:`sanitize_server_text`.
+_CONTROL_CHARS_RE = re.compile(r"[\x00-\x08\x0b-\x1f\x7f-\x9f]")
+
+
+def sanitize_server_text(text: str) -> str:
+    """Strip C0/C1 control characters from server-supplied text.
+
+    Findings (``code``/``details["message"]``/``package``/``keys`` etc.) and
+    the fail-open ``notice`` are all server-supplied strings the CLI prints
+    straight to a terminal. A compromised control plane — or a user pointed
+    at an attacker-run ``SIMULO_API_URL`` — could embed ANSI/OSC
+    sequences: e.g. ``"\\x1b[2K\\x1b[1G\\u2713 ..."`` (erase-line + cursor-
+    home, then a fake checkmark) would repaint the line this CLI just wrote
+    with ``✗`` as if it were a clean pass — the exit code stays honest (1),
+    but the user reads the opposite of the truth, exactly the outcome
+    preflight exists to prevent. Dropping the bare ESC/CR/OSC-framing bytes
+    breaks any such sequence back into inert literal text; TAB and LF are
+    kept so a legitimate multi-line message still reads sensibly.
+    """
+    return _CONTROL_CHARS_RE.sub("", text)
+
+
+def render_preflight_finding_text(code: str, details: dict[str, Any]) -> tuple[str, list[str]]:
+    """One finding -> ``(title, extra detail lines)``. Never raises.
+
+    The top-level shape validation each caller's parser performs (``code``
+    is a str, ``details`` is a dict) does not know each code's expected
+    ``details`` field types, so a structurally-valid-but-unexpected payload
+    (e.g. a future server bug, or a code this module recognises whose
+    ``details`` shape has since drifted) could otherwise raise here (a
+    non-string ``keys`` list failing ``", ".join``, for instance). The NFR
+    "users never see a stack trace" applies to this render step too, so any
+    failure degrades to the same generic fallback an unrecognised CODE gets.
+
+    Every returned string is passed through :func:`sanitize_server_text`
+    here — the single choke point every finding's rendered text passes
+    through on its way out, regardless of which branch (present or future)
+    produced it — rather than at each individual call site inside
+    :func:`_render_finding_text_unsafe`, which is exactly the kind
+    of place a newly-added branch could forget it.
+    """
+    try:
+        title, lines = _render_finding_text_unsafe(code, details)
+    except Exception:  # noqa: BLE001 - rendering must never crash the caller
+        message = details.get("message") if isinstance(details, dict) else None
+        if isinstance(message, str) and message:
+            title, lines = message, []
+        else:
+            title, lines = code, []
+    return sanitize_server_text(title), [sanitize_server_text(line) for line in lines]
+
+
+def _render_finding_text_unsafe(code: str, details: dict[str, Any]) -> tuple[str, list[str]]:
+    """One finding -> ``(title, extra detail lines)``; may raise on an
+    unexpected ``details`` shape — see :func:`render_preflight_finding_text`,
+    which wraps this and never lets that happen.
+
+    The server ships only ``code``/``classification``/``details`` — never
+    English — so this is where the CLI owns
+    the copy. An unrecognised code still renders: via ``details["message"]``
+    when present (every seed-checkpoint finding carries one — see
+    ``simulo_control_plane.preflight.service._seed_findings``), else the
+    bare code string.
+    """
+    if code == PIP_VERSION_CONFLICT_CODE:
+        package = details.get("package", "?")
+        requested = details.get("requested", "")
+        platform_version = details.get("platform", "?")
+        title = (
+            f"{package}{requested} cannot be satisfied — the platform runtime has "
+            f"{package}=={platform_version} installed"
+        )
+        lines = []
+        if details.get("manifest_freshness") == "stale":
+            lines.append("(the platform's reported package inventory is stale — informational only)")
+        return title, lines
+    if code == RUNTIME_MANIFEST_UNAVAILABLE_CODE:
+        return "no runtime package inventory is available yet — pip version checks were skipped", []
+    if code == UNKNOWN_RUNTIME_CODE:
+        return (
+            f"unknown runtime {details.get('runtime_id')!r} — this job will run on the "
+            f"platform default ({details.get('default_runtime_id')!r})",
+            [],
+        )
+    if code == PACKAGE_TOO_LARGE_CODE:
+        return (
+            f"the package would be {details.get('archive_size')} bytes, over the platform's "
+            f"{details.get('max_package_bytes')}-byte limit",
+            [],
+        )
+    if code == JOB_TIMEOUT_INVALID_CODE:
+        return (
+            f"job {details.get('job')!r} declares an invalid timeout ({details.get('timeout')!r}) — "
+            "it must be a positive whole number of seconds",
+            [],
+        )
+    if code == RESERVED_RUNTIME_ENV_CODE:
+        keys = details.get("keys") or []
+        return f"runtime_env sets reserved key(s) the platform ignores at execution: {', '.join(keys)}", []
+    if code == NO_ACTIVE_WORKER_CODE:
+        return "no active compute worker observed right now — the job would queue until capacity is available", []
+    message = details.get("message")
+    if isinstance(message, str) and message:
+        return message, []
+    return code, []
+
+
+def render_preflight_skip_notice(outcome: PreflightOutcome) -> None:
+    """Fail-open path: print ``outcome.notice`` to stderr, sanitized like
+    every other server-supplied string this module renders.
+
+    Shared by ``simulo prepare`` (``cli.py``) and ``simulo run``'s preflight
+    phase (``app.py``, PR-A6) so the fail-open message reads identically from
+    both commands — see the module docstring for why the two never keep
+    their own copy of this rendering.
+    """
+    notice = sanitize_server_text(outcome.notice) if outcome.notice else outcome.notice
+    print(f"note: {notice}", file=sys.stderr)
+
+
+def render_preflight_findings(outcome: PreflightOutcome) -> tuple[list[PreflightFinding], list[PreflightFinding]]:
+    """Print every finding in a NON-skipped *outcome* — ``✗`` for
+    ``blocking``, ``⚠`` for ``advisory``, each with its indented detail
+    lines — and return ``(blocking, advisory)`` so the caller decides what
+    happens next.
+
+    Only the print-and-classify step is shared: ``simulo prepare``
+    (``cli.py``) turns a non-empty ``blocking`` list into a process exit
+    code, ``simulo run``'s preflight phase (``app.py``) turns it into a
+    raised ``PreflightBlockedError`` instead — that "what happens on a
+    blocking finding" behavior differs by design and stays in each caller.
+
+    Must only be called when ``outcome.skipped`` is False — see
+    :func:`render_preflight_skip_notice` for the fail-open branch.
+    """
+    blocking = [finding for finding in outcome.findings if finding.classification == "blocking"]
+    advisory = [finding for finding in outcome.findings if finding.classification == "advisory"]
+    for finding in blocking:
+        title, detail_lines = render_preflight_finding_text(finding.code, finding.details)
+        print(f"✗ {title}")
+        for line in detail_lines:
+            print(f"    {line}")
+    for finding in advisory:
+        title, detail_lines = render_preflight_finding_text(finding.code, finding.details)
+        print(f"⚠ {title}")
+        for line in detail_lines:
+            print(f"    {line}")
+    return blocking, advisory

simulo/_client/registry.py

@@ -0,0 +1,98 @@
+"""Process-global registry of declared ``App`` instances.
+
+Each ``App`` self-registers on construction. ``find_app`` resolves the single
+app for a discovery import — either by scanning an imported module's globals
+(the precise, contamination-free path used by ``discovery.discover``) or by
+falling back to the process-wide registry.
+
+The registry holds plain objects (typed against ``AppProtocol``) so this module
+depends only on the contract layer and never imports the concrete ``App`` at
+module scope — that would create an import cycle (``app`` imports ``registry``).
+``find_app`` therefore lazy-imports the concrete ``App`` class and identifies
+app instances by that **concrete type**, never by the structural
+``AppProtocol``: under ``@runtime_checkable`` on Python 3.11, a Protocol
+``isinstance`` check is satisfied by ``hasattr`` alone, so a discovery import
+stub (which answers *every* attribute) would otherwise be mis-counted as an App.
+"""
+
+from pathlib import Path
+from types import ModuleType
+from typing import Optional
+
+from simulo.interfaces.exceptions import ContractViolationError, ResourceNotFoundError
+from simulo.interfaces.platform.app import AppProtocol
+
+_REGISTRY: list[AppProtocol] = []
+
+
+def register(app: AppProtocol) -> None:
+    """Record a freshly-constructed app (idempotent on identity)."""
+    if not any(existing is app for existing in _REGISTRY):
+        _REGISTRY.append(app)
+
+
+def clear() -> None:
+    """Drop all registered apps. Intended for tests."""
+    _REGISTRY.clear()
+
+
+def find_app(module: Optional[ModuleType] = None, name: Optional[str] = None) -> AppProtocol:
+    """Resolve the single ``App`` to package.
+
+    When ``module`` is given, scan that module's globals (deterministic per file);
+    otherwise scan the process-wide registry. ``name`` optionally disambiguates.
+    Raises if zero or more than one candidate remains.
+
+    Candidates are identified by the **concrete ``App`` class** — never by the
+    structural ``AppProtocol`` — so a discovery import stub left bound in the
+    module's globals (e.g. ``torch`` after ``with runtime.imports(): import
+    torch``) is never mistaken for an App. The stub never self-registers, so the
+    registry fallback is inherently stub-free; the concrete-type filter on the
+    module-globals path closes the same gap there.
+    """
+    # Lazy import to avoid the registry -> app import cycle (``app`` imports
+    # ``registry`` at module scope to self-register on construction).
+    from simulo._client.app import App
+
+    if module is not None:
+        candidates: list[AppProtocol] = [
+            value for value in vars(module).values() if isinstance(value, App) and not isinstance(value, ModuleType)
+        ]
+    else:
+        candidates = [app for app in _REGISTRY if isinstance(app, App)]
+
+    if name is not None:
+        candidates = [app for app in candidates if app.name == name]
+
+    # Deduplicate by identity — the same app object may appear in both a module
+    # global and the registry, or under several aliases.
+    unique: list[AppProtocol] = []
+    for app in candidates:
+        if not any(existing is app for existing in unique):
+            unique.append(app)
+
+    if not unique:
+        if module is not None:
+            # Prefer the user's own file name over the synthetic
+            # ``_simulo_user_<stem>`` module name a discovery import runs
+            # under (``discovery._load_module_from_path``) — ``__file__`` is
+            # set by ``importlib.util.module_from_spec`` whenever the spec
+            # carries a location (it always does on that path), so this is
+            # available without any extra plumbing. Falls back to the module
+            # name for a module with no ``__file__`` (e.g. a hand-built
+            # ``ModuleType`` in a test, or the process-wide registry scan).
+            file_name = getattr(module, "__file__", None)
+            where = f"file {Path(file_name).name!r}" if file_name else f"module {module.__name__!r}"
+        else:
+            where = "the app registry"
+        suffix = f" named {name!r}" if name is not None else ""
+        raise ResourceNotFoundError(f"No simulo.App{suffix} found in {where}.")
+    if len(unique) > 1:
+        # ``str(...)`` is defensive: every candidate is now a concrete ``App``
+        # with a ``str`` name, but never sort/format-compare a non-``str`` name.
+        found = ", ".join(sorted(str(app.name) for app in unique))
+        raise ContractViolationError(
+            f"Ambiguous: found {len(unique)} simulo.App instances ({found}). "
+            "Define exactly one App per packaged file, or pass an explicit name."
+        )
+    return unique[0]

simulo/_client/runtime.py

@@ -0,0 +1,185 @@
+"""``Runtime`` — a Simulo-curated runtime (implements ``RuntimeProtocol``).
+
+Simulo owns the runtime: every job executes in a prebuilt, Simulo-managed
+environment that ships everything a robotics training job needs — the
+simulation engine, GPU stack, and the scientific-Python toolchain. You never
+bring your own image or registry; you *pick* a Simulo runtime (today there is
+one, :data:`DEFAULT_RUNTIME`, and it is the default — the common path writes
+nothing) and may layer a guarded set of extras on top: :meth:`Runtime.env`
+merges environment variables into the job's execution environment, and
+:meth:`Runtime.pip_install` declares additional **public-PyPI** packages the
+Simulo image builder installs on top of the base runtime. There is no
+private-registry, URL, VCS, or local-path install surface — a package the
+base runtime already provides cannot be overridden (see
+``simulo.interfaces.platform.is_platform_pinned``).
+
+Locally this class is a lean metadata recorder: ``from_registry`` names the
+Simulo runtime, ``env`` accumulates environment overrides, ``pip_install``
+records ordered public-PyPI dependency layers, ``torch_jit`` is a no-op
+marker at submit (and real ``torch.jit.script`` on the worker), and
+``imports`` is the remote-only-import boundary (Rule #3) — a real
+``nullcontext`` in execution mode, a stub-installing context manager in
+discovery mode. Nothing is ever installed on your machine at submit.
+"""
+
+import copy
+import importlib
+from contextlib import AbstractContextManager, nullcontext
+from typing import Any, Callable, Mapping, TypeVar, cast
+
+from simulo._client.discovery import stub_import_context
+from simulo._client.mode import DISCOVERY, EXECUTION, current_mode
+from simulo.interfaces.platform import canonical_pypi_name
+
+F = TypeVar("F", bound=Callable[..., object])
+
+
+def _reject_non_pypi_spec(spec: str) -> None:
+    """Raise ``SystemExit`` if *spec* is not a plain public-PyPI requirement.
+
+    Delegates the actual grammar check to
+    ``simulo.interfaces.platform.canonical_pypi_name`` — the SAME positive
+    allowlist ``is_platform_pinned`` fails closed on — rather than
+    duplicating a rule in this package too (review round 2, critic MINOR: a
+    duplicated rule is how one copy gets hardened and the other doesn't).
+    Here the reject happens at CALL time with a message naming the actual
+    problem (not a misleading "platform-pinned" one at submit time).
+    """
+    if canonical_pypi_name(spec) is None:
+        raise SystemExit(f"pip_install accepts PyPI package specs only — not URLs, paths, or VCS refs: {spec}")
+
+
+class Runtime:
+    """A Simulo-curated runtime a job executes in. Torch-free metadata recorder.
+
+    You normally never construct one: every :class:`simulo.App` defaults to
+    :data:`DEFAULT_RUNTIME`. Pick a Simulo runtime by name and layer your own
+    environment variables and public-PyPI packages on top::
+
+        runtime = (
+            simulo.Runtime.from_registry("simulo/gpu-rl:2026.06")
+            .pip_install("wandb==0.17.0")
+            .env({"WANDB_PROJECT": "cartpole"})
+        )
+        app = simulo.App("cartpole", runtime=runtime)
+
+    Nothing is installed on your machine — the runtime is Simulo-built and
+    lives in the cloud; submit only records which runtime the app picked plus
+    the declared env/dependency layers, and the cloud materialises them at
+    execution time.
+    """
+
+    def __init__(self, runtime_id: str) -> None:
+        self._runtime_id = runtime_id
+        self._env: dict[str, str] = {}
+        self._remote_imports: list[str] = []
+        self._torch_jit_marks: list[str] = []
+        self._pip_layers: list[dict[str, Any]] = []
+
+    @classmethod
+    def from_registry(cls, image: str) -> "Runtime":
+        """Pick a Simulo runtime by name (e.g. ``"simulo/gpu-rl:2026.06"``)."""
+        return cls(runtime_id=image)
+
+    @property
+    def runtime_id(self) -> str:
+        """The Simulo runtime name passed to :meth:`from_registry`."""
+        return self._runtime_id
+
+    @property
+    def runtime_env(self) -> Mapping[str, str]:
+        """The accumulated :meth:`env` overrides (a copy)."""
+        return dict(self._env)
+
+    @property
+    def pip_dependencies(self) -> list[dict[str, Any]]:
+        """Ordered public-PyPI dependency layers (defensive deep copy).
+
+        Each layer is ``{"packages": [...], "pre": bool}`` — one entry per
+        :meth:`pip_install` call, in call order. The Simulo image builder
+        installs these on top of the base runtime; submit only records them.
+        """
+        return copy.deepcopy(self._pip_layers)
+
+    def env(self, variables: Mapping[str, str]) -> "Runtime":
+        """Merge environment variables into the job's execution environment.
+
+        Later calls win on key conflicts. Returns ``self`` for chaining.
+        Guarded: runner/worker-owned keys
+        (``simulo.interfaces.platform.RESERVED_RUNTIME_ENV_KEYS`` /
+        ``RESERVED_RUNTIME_ENV_PREFIXES``) are never honoured at execution —
+        enforcement lives at the runner/worker, which also sanitises the pip
+        environment so no variable declared here can redirect the image
+        builder's package installs.
+        """
+        self._env.update(variables)
+        return self
+
+    def pip_install(self, *packages: str, pre: bool = False) -> "Runtime":
+        """Declare public-PyPI packages to add on top of the Simulo runtime.
+
+        Each *package* is a plain PyPI requirement — ``name``, optionally
+        with extras and a version specifier (``"wandb==0.17.0"``,
+        ``"transformers[torch]>=4.40"``). URLs, VCS refs
+        (``git+...``), local paths, and PEP 508 direct references
+        (``name @ url``) are rejected: the Simulo image builder installs from
+        public PyPI only. ``pre=True`` allows pre-release versions for this
+        layer.
+
+        Each call appends an **ordered layer**; the builder installs the
+        layers in order on top of the base runtime. Submit only *records* the
+        layers — nothing is installed locally. A package the base runtime
+        already provides (torch, numpy, the CUDA wheels, the ``simulo``
+        distributions — ``simulo.interfaces.platform.PLATFORM_PINNED_PACKAGES``)
+        cannot be re-declared here; submit fails fast if one is.
+
+        Called with no *packages* (``pip_install()``), this is a no-op — no
+        layer is recorded — rather than appending a vacuous empty layer for
+        every downstream consumer (the manifest, the worker) to special-case.
+
+        Returns ``self`` for chaining.
+        """
+        for spec in packages:
+            _reject_non_pypi_spec(spec)
+        if packages:
+            self._pip_layers.append({"packages": list(packages), "pre": pre})
+        return self
+
+    def torch_jit(self, fn: F) -> F:
+        """Record the function's qualname; JIT-compile only on the worker.
+
+        In discovery (submit) this is a no-op marker — it records the qualname and
+        returns ``fn`` unchanged, so no ``torch`` import happens locally. In
+        execution mode (the backend runner, which has the heavy runtime) it
+        replaces ``@torch.jit.script``: ``torch`` is imported lazily inside the
+        method so module load stays lean.
+        """
+        self._torch_jit_marks.append(fn.__qualname__)
+        if current_mode() == EXECUTION:
+            # Lazy import via importlib (only the worker has torch). importlib keeps
+            # module load lean AND avoids a static ``import torch`` that a torch-free
+            # type-check would flag.
+            script = getattr(importlib.import_module("torch.jit"), "script")
+            return cast(F, script(fn))
+        return fn
+
+    def imports(self) -> AbstractContextManager[None]:
+        """Remote-only-import boundary.
+
+        In execution mode this is a plain ``nullcontext`` (the imports really
+        happen). In discovery mode it installs a stub import finder that records
+        the deferred top-level imports without resolving them — how heavy
+        libraries (``torch`` and friends) stay off your machine at submit.
+        """
+        if current_mode() == DISCOVERY:
+            return stub_import_context(self._remote_imports)
+        return nullcontext()
+
+
+#: The Simulo runtime every :class:`simulo.App` executes in unless it picks a
+#: different one. Simulo-owned and prebuilt — it ships the full simulation +
+#: GPU training stack, so the common path declares no runtime at all. Shared
+#: across every App that omits ``runtime=``: an app that wants its own
+#: ``env()`` / ``pip_install()`` layers should construct its own Runtime via
+#: :meth:`Runtime.from_registry` rather than mutating this shared default.
+DEFAULT_RUNTIME = Runtime.from_registry("simulo/gpu-rl:2026.06")

simulo/_client/runtime_display.py

@@ -0,0 +1,90 @@
+"""The ONE place a validation record's ``runtime`` field is turned into
+copy a user should see (W7 operator directive: "the user must never see
+the engine — it's an implementation detail").
+
+The wire/DB value (``"isaac"`` today — control-plane's
+``DEFAULT_ASSET_VALIDATION_RUNTIME``, mirrored here via interfaces'
+``DEFAULT_ASSET_RUNTIME`` so the two can never drift) is never renamed — only
+how the CLI prints it changes. Every
+human-readable print/echo site that renders a validation record's
+``runtime`` field, or echoes a user-supplied ``--runtime`` value back as
+prose, routes through :func:`display_runtime` so a future engine swap (or a
+second runtime) is a one-line change here — never a grep-and-replace across
+``cli.py`` / ``asset_pins.py``.
+
+Also maps the ``runtime`` FIELD inside ``--json`` / ``--report`` structured
+output (:func:`with_display_runtime` for a validation record or a report
+document, :func:`with_display_validations` for a version's ``validations``
+list). A user reads and STORES that JSON, so the engine alias must not appear
+there either — the field carries the neutral label exactly like the human
+lines, so the two agree. (This closes the gap the earlier human-print scrub
+left: the machine-readable surfaces were still shipping raw ``"isaac"``.)
+
+Deliberately NOT mapped: the ``--runtime <alias>`` flag value itself (the real
+argument sent to ``client.revalidate(...)`` / ``resolve_assets(...)``) and
+copy-pasteable command hints (e.g. "revalidate with `--runtime isaac`") — both
+carry the actual wire value a user or script passes back, not a display label.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+from simulo.interfaces.platform.asset_catalog import DEFAULT_ASSET_RUNTIME
+
+#: What the user sees instead of the engine's internal alias.
+_ENGINE_DISPLAY_LABEL = "Simulo Cloud"
+
+
+def display_runtime(value: Any) -> str:
+    """Map a wire ``runtime`` value to what the user should see.
+
+    The platform's engine alias (``DEFAULT_ASSET_RUNTIME``, currently
+    ``"isaac"``, matched case-insensitively) becomes ``"Simulo Cloud"``.
+    Any other value (an unrecognized or future runtime alias) passes
+    through title-cased — a defensive default, never a raw unmapped
+    internal name. ``None``/empty renders as ``""``.
+    """
+    text = "" if value is None else str(value)
+    if text.strip().lower() == DEFAULT_ASSET_RUNTIME.lower():
+        return _ENGINE_DISPLAY_LABEL
+    return text.title()
+
+
+def with_display_runtime(record: Any) -> Any:
+    """Return a copy of a validation record / report document with its
+    ``"runtime"`` field mapped through :func:`display_runtime`.
+
+    Called at the ``--json`` / ``--report`` emission sites so a record a user
+    reads or stores shows the neutral label, never the raw engine alias. A
+    no-op passthrough for a non-mapping (defensive — ``None``, a missing
+    report) or a record with no ``"runtime"`` key (or a ``None`` one). The
+    input is never mutated. Idempotent: a record already carrying
+    ``"Simulo Cloud"`` is returned unchanged (``display_runtime`` passes the
+    neutral label straight through)."""
+    if not isinstance(record, Mapping):
+        return record
+    mapped = dict(record)
+    if mapped.get("runtime") is not None:
+        mapped["runtime"] = display_runtime(mapped["runtime"])
+    return mapped
+
+
+def with_display_validations(version: Any) -> Any:
+    """Return a copy of a version-detail dict whose ``validations`` records
+    each have their ``"runtime"`` mapped for display (see
+    :func:`with_display_runtime`).
+
+    ``inspect --json`` dumps a whole version document, whose
+    ``validations[*].runtime`` are the raw wire aliases; this is the one place
+    that maps them. A missing or non-list ``validations`` passes through
+    untouched, and the rest of the version dict is copied shallowly and never
+    mutated."""
+    if not isinstance(version, Mapping):
+        return version
+    mapped = dict(version)
+    validations = mapped.get("validations")
+    if isinstance(validations, list):
+        mapped["validations"] = [with_display_runtime(record) for record in validations]
+    return mapped

simulo/_client/seed_ref.py

@@ -0,0 +1,76 @@
+"""The client's parse of a ``seed_from_job_id`` wire value (``--from``).
+
+ONE definition, used by every client-side caller that needs to understand a
+``--from`` value: the CLI's pre-flight syntax check (the thin client's CLI module)
+and the test suite's fake control plane (``tests/conftest.py``). Nothing here
+resolves a ref — existence, prefix resolution, terminal status and output
+availability are the control plane's org-scoped call, answered in the submit
+request itself.
+
+**This must stay byte-for-byte equivalent to the server's rule** — the control
+plane's ``simulo_control_plane.jobs.constants.parse_seed_job_ref``, which
+``jobs/service.py`` calls to resolve a seed source. A divergence is silent in
+the worst way: the client accepts a value the server rejects (the user pays a
+full package build + archive upload for a typo the client claimed to catch
+locally), or rejects one the server would have accepted.
+
+That equivalence is not a comment — it is asserted, over an exhaustive table
+of cases, by ``tests/integration/test_contract_mirror.py`` at the repo root,
+which loads the control plane's rule from its actual source file and runs both
+implementations against the same inputs. The grammar both sides implement is
+pinned in the contract package as
+:data:`simulo.interfaces.platform.submit.SEED_JOB_REF_GRAMMAR`.
+
+The rule (server order, exactly):
+
+* ``":"`` is not in the job-ref alphabet (UUID text or an id prefix), so its
+  presence is an unambiguous suffix signal. No ``":"`` → the whole value is
+  the ref and ``kind`` defaults to ``MODEL_KINDS[0]`` (``"best"``).
+* Otherwise split on the LAST ``":"`` and reject — never silently fall back —
+  when either side is empty or the kind is unrecognized. ``":latest"`` is NOT
+  a bare ref named ``latest``; ``"8b52:"`` is NOT an implicit ``:best``.
+  "Never a silent fall-back" is this wave's whole point.
+* ``kind`` is stripped and lowercased before the membership test, so
+  ``"8b52:BEST"`` is accepted (the server accepts it; a client that rejected
+  it would be gratuitously stricter than the wire).
+"""
+
+from __future__ import annotations
+
+from simulo.interfaces.platform.submit import MAX_SEED_REF_CHARS, MODEL_KINDS
+
+__all__ = ["MAX_SEED_REF_CHARS", "SeedJobRefError", "parse_seed_job_ref"]
+
+
+class SeedJobRefError(ValueError):
+    """A ``--from`` value that violates the pinned seed-job-ref grammar.
+
+    Carries the server's own ``seed_artifact_invalid`` semantics: the control
+    plane answers 422 with that code for every value this raises on.
+    """
+
+
+def parse_seed_job_ref(raw: str) -> tuple[str, str]:
+    """Split a ``seed_from_job_id`` wire value into ``(job_ref, kind)``.
+
+    Raises :class:`SeedJobRefError` on any value the control plane answers
+    ``422 seed_artifact_invalid`` for. Does NOT enforce
+    :data:`MAX_SEED_REF_CHARS` — length is a separate, schema-level bound on
+    the server (Pydantic ``max_length``), and keeping it out of the parse is
+    what lets this function stay exactly equal to the server's parse.
+    """
+    if ":" in raw:
+        ref, _, suffix = raw.rpartition(":")
+        kind = suffix.strip().lower()
+        if not ref or not kind:
+            raise SeedJobRefError(
+                "expects <job-ref> or <job-ref>:best / <job-ref>:latest — a job reference "
+                "and, optionally, a non-empty output kind after ':'."
+            )
+        if kind not in MODEL_KINDS:
+            kinds = " or ".join(f"':{name}'" for name in MODEL_KINDS)
+            raise SeedJobRefError(f"unknown output suffix ':{suffix}' — use {kinds} (default: ':{MODEL_KINDS[0]}').")
+        return ref, kind
+    if not raw:
+        raise SeedJobRefError("the job reference is empty.")
+    return raw, MODEL_KINDS[0]