simulo-interfaces 0.5.0__tar.gz → 0.6.0__tar.gz

{simulo_interfaces-0.5.0/src/simulo_interfaces.egg-info → simulo_interfaces-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simulo-interfaces
-Version: 0.5.0
+Version: 0.6.0
 Summary: Type contracts for the Simulo SDK. Installed automatically as a dependency of the simulo package.
 Author-email: Simulo Team <team@simulo.ai>
 License: BSD-3-Clause

{simulo_interfaces-0.5.0 → simulo_interfaces-0.6.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "simulo-interfaces"
-version = "0.5.0"
+version = "0.6.0"
 description = "Type contracts for the Simulo SDK. Installed automatically as a dependency of the simulo package."
 readme = "PYPI.md"
 requires-python = ">=3.11"

{simulo_interfaces-0.5.0 → simulo_interfaces-0.6.0}/src/simulo/interfaces/platform/__init__.py

@@ -109,6 +109,7 @@ from simulo.interfaces.platform.submit import (
     MODEL_KINDS,
     PACKAGE_ARCHIVE_ROUTE_TEMPLATE,
     PACKAGES_ROUTE,
+    PLATFORM_PINNED_PACKAGES,
     RESERVED_RUNTIME_ENV_KEYS,
     RESERVED_RUNTIME_ENV_PREFIXES,
     SEED_JOB_REF_GRAMMAR,
@@ -125,6 +126,8 @@ from simulo.interfaces.platform.submit import (
     WORKER_LEASE_HEADER,
     ModelRecord,
     RecordingRecord,
+    canonical_pypi_name,
+    is_platform_pinned,
 )
 from simulo.interfaces.platform.volume import VolumeProtocol
 
@@ -181,6 +184,9 @@ __all__ = [
     "RecordingRecord",
     "RESERVED_RUNTIME_ENV_KEYS",
     "RESERVED_RUNTIME_ENV_PREFIXES",
+    "PLATFORM_PINNED_PACKAGES",
+    "is_platform_pinned",
+    "canonical_pypi_name",
     # explicit-run-intent plan: submit-time seed source (additive)
     "SEED_SOURCE_FIELDS",
     "SEED_SOURCE_CONFLICT_CODE",

{simulo_interfaces-0.5.0 → simulo_interfaces-0.6.0}/src/simulo/interfaces/platform/asset_catalog.py

@@ -256,7 +256,7 @@ GLOBAL_ASSET_PUBLISHER = "simulo"
 #: optional group being absent, 3+ chars matches via the group, but exactly 2
 #: chars can match neither — incoherent for users. Fixed here to ``{0,61}``,
 #: which accepts every length 1–63 contiguously; see the PR-1 resolutions in
-#: ``context/implementation-plans/usd-asset-catalogs/api-contract-freeze.md``.)
+#: ``context/implementation-plans/archive/usd-asset-catalogs/api-contract-freeze.md``.)
 #: Pinned here (rather than imported) because ``simulo-interfaces`` has zero
 #: dependencies on the control plane — the value is copied deliberately and this
 #: docstring is the drift anchor.

{simulo_interfaces-0.5.0 → simulo_interfaces-0.6.0}/src/simulo/interfaces/platform/enums.py

@@ -72,13 +72,12 @@ class ResourceKind(StrEnum):
     """A configuration bundle."""
 
     WORLD = "world"
-    """A world asset from the USD Asset Catalogs feature — an environment /
-    facility / terrain / scene robots operate in. The catalog's ``world`` kind
-    (see ``ASSET_KINDS`` in ``platform/asset_catalog.py``) and the legacy
-    ``ENVIRONMENT`` resource-mount term denote the same concept; ``WORLD`` is the
-    catalog vocabulary (§2 of the USD Asset Catalogs proposal — "world", not
-    "environment", which is overloaded). Both members are wire-stable and
-    retained (append-only); neither replaces the other."""
+    """A catalog world — a facility, terrain, or scene robots operate in.
+
+    ``WORLD`` is the current catalog term. The older ``ENVIRONMENT`` resource
+    mount term denotes the same concept; both values remain wire-stable and
+    neither replaces the other.
+    """
 
 
 class ArtifactKind(StrEnum):

{simulo_interfaces-0.5.0 → simulo_interfaces-0.6.0}/src/simulo/interfaces/platform/runtime.py

@@ -1,14 +1,14 @@
 """``RuntimeProtocol`` — Simulo-curated runtime contract (Part B, Rule #4).
 
 Runtimes are Simulo-owned, prebuilt execution environments. The contract is
-deliberately tiny: pick a curated runtime by name, and defer heavy imports
-behind ``imports()``. There is no dependency-declaration, user-environment,
-or image-customisation surface — the platform runtime ships everything a job
-needs.
+deliberately narrow: pick a curated runtime by name, merge in a guarded set
+of user environment variables via ``env()``, and defer heavy imports behind
+``imports()``. There is no dependency-declaration or image-customisation
+surface — the platform runtime ships everything a job needs.
 """
 
 from contextlib import AbstractContextManager
-from typing import Protocol, runtime_checkable
+from typing import Mapping, Protocol, runtime_checkable
 
 
 @runtime_checkable
@@ -17,6 +17,12 @@ class RuntimeProtocol(Protocol):
 
     Simulo owns and builds every runtime; ``from_registry`` picks one of the
     curated runtimes by name (there is no bring-your-own-image path).
+    ``env()`` merges caller-supplied environment variables into the job's
+    execution environment (later calls win on key conflicts) — guarded: a
+    runner/worker-owned key (see
+    ``simulo.interfaces.platform.submit.RESERVED_RUNTIME_ENV_KEYS`` /
+    ``RESERVED_RUNTIME_ENV_PREFIXES``) is never honoured; enforcement lives at
+    the runner/worker, not in this implementation-free Protocol.
     ``imports()`` is the real remote-only-import boundary (Rule #3): locally it
     records deferred import intent; in the cloud it resolves the real imports.
     Heavy imports (torch and friends) live ONLY inside this context manager.
@@ -24,4 +30,5 @@ class RuntimeProtocol(Protocol):
 
     @classmethod
     def from_registry(cls, image: str) -> "RuntimeProtocol": ...
+    def env(self, variables: Mapping[str, str]) -> "RuntimeProtocol": ...
     def imports(self) -> AbstractContextManager[None]: ...

{simulo_interfaces-0.5.0 → simulo_interfaces-0.6.0}/src/simulo/interfaces/platform/submit.py

@@ -124,7 +124,7 @@ platform-standard shape: ``{"error": {"code": ..., "message": ..., "request_id":
   terminal status, artifact kind) is server-side business logic layered on
   top of this wire shape, not defined by this module — see the
   explicit-run-intent plan's "Server validation" section
-  (``context/implementation-plans/explicit-run-intent-plan.md``).
+  (``context/implementation-plans/archive/explicit-run-intent-plan.md``).
 
 ## Client-facing: recordings
 
@@ -325,6 +325,7 @@ models; the list is empty, never an error.
   recordings upload.
 """
 
+import re
 from dataclasses import dataclass
 from typing import Optional
 
@@ -723,3 +724,269 @@ RESERVED_RUNTIME_ENV_KEYS = frozenset(
 #: ``SIMULO_CHECKPOINT_KEEP_LAST`` / ``SIMULO_RESUME``) does not match any of
 #: these prefixes and remains legitimate user-supplied job env.
 RESERVED_RUNTIME_ENV_PREFIXES = ("SIMULO_WORKER_", "SIMULO_INTERNAL_", "SIMULO_VOLUME_", "SIMULO_ASSET_")
+
+
+# --------------------------------------------------------------------------
+# Platform-pinned packages
+# --------------------------------------------------------------------------
+#
+# The governing principle: anything already in the base runtime image is
+# denied — a user ``pip_install()`` (restored in a later PR of this wave) may
+# ADD packages the base lacks, but may never OVERRIDE one the base already
+# provides. If a job's layer resolves a different version of a package the
+# base already ships, whichever version resolution order wins can silently
+# break the runtime in ways that never surface in the job's own code. The
+# canonical case (#285): a job's ``pip_install("numpy")`` pulled numpy 2.x,
+# shadowing the platform's numpy-1.x install and breaking the runtime's
+# compiled camera-sensor bindings — the job never imported numpy directly,
+# so the failure was undiagnosable from the job's own traceback. This is the
+# same class of hazard :data:`RESERVED_RUNTIME_ENV_KEYS` guards against for
+# environment variables, applied to pip package names instead: a job must
+# never be able to shadow a platform-pinned dependency.
+#
+# :data:`PLATFORM_PINNED_PACKAGES` is the CLIENT-SIDE FAST-FAIL SUBSET, not
+# the full "anything already in base" set — it names the known-critical base
+# packages we can enumerate statically (the torch family, numpy, the
+# nvidia/CUDA wheels, the platform's own SDK distributions) so
+# ``pip_install()`` (later PR) can reject an obviously-doomed layer at
+# submit time, before a job ever reaches the cloud. It is deliberately
+# curated-but-generous, not exhaustive: the AUTHORITATIVE enforcement lives
+# in ``simulo-backend`` (later PR), which checks each user-requested package
+# against the worker's actual base-env installed set at install time —
+# that check is complete by construction (it reads the real base env, it
+# doesn't hand-maintain a mirror of it) and is what closes the gap this
+# static frozenset cannot.
+#
+# Engine/runtime-native libraries (e.g. an ``isaacsim`` / ``isaaclab`` /
+# ``omni.*``-shaped dependency) are image-baked into the base runtime, not
+# resolved via ``pip`` into site-packages at job time — there is no pip
+# package name a user's ``pip_install()`` could collide with for those, so
+# they are deliberately NOT listed here. The nvidia/CUDA wheels are the
+# opposite case: torch's CUDA build pulls them in via a normal ``pip``
+# dependency into site-packages (the ``nvidia-*-cu12`` family + ``triton``),
+# so a job absolutely could shadow one — they belong in this set. Only
+# packages a job could actually reach through a real ``pip install <name>``
+# belong here, including the platform's own SDK distributions (a job pinning
+# its own ``simulo``/``simulo-interfaces``/``simulo-backend`` version could
+# silently desync the client and runtime contract versions).
+PLATFORM_PINNED_PACKAGES = frozenset(
+    {
+        "torch",
+        "torchvision",
+        "torchaudio",
+        "numpy",
+        "simulo",
+        "simulo-interfaces",
+        "simulo-backend",
+        "triton",
+        "nvidia-cuda-runtime-cu12",
+        "nvidia-cuda-nvrtc-cu12",
+        "nvidia-cuda-cupti-cu12",
+        "nvidia-cudnn-cu12",
+        "nvidia-cublas-cu12",
+        "nvidia-cufft-cu12",
+        "nvidia-curand-cu12",
+        "nvidia-cusolver-cu12",
+        "nvidia-cusparse-cu12",
+        "nvidia-nccl-cu12",
+        "nvidia-nvtx-cu12",
+        "nvidia-nvjitlink-cu12",
+    }
+)
+
+#: Matches the CUDA-wheel naming shape torch's CUDA build actually pulls into
+#: site-packages — ``nvidia-<lib>-cu<major>`` (``nvidia-cublas-cu12``,
+#: ``nvidia-cusolver-cu13``, ...) — matched in addition to the exact names
+#: enumerated in :data:`PLATFORM_PINNED_PACKAGES` above. CUDA major-version
+#: bumps mint new package names (``-cu12`` becomes ``-cu13`` and so on), so a
+#: shape match keeps every CUDA runtime wheel denied even as the exact-name
+#: list drifts behind a new CUDA release. Deliberately NOT a broad ``nvidia-``
+#: prefix: that wrongly caught legitimate nvidia *helper* packages that do not
+#: shadow anything in the base runtime (``nvidia-ml-py``,
+#: ``nvidia-dali-cuda120`` — note ``-cuda120`` is not the ``-cu<major>``
+#: runtime-wheel suffix), which a job may genuinely want to add.
+_NVIDIA_CUDA_WHEEL_PATTERN = re.compile(r"^nvidia-.+-cu\d+$")
+
+# --------------------------------------------------------------------------
+# Plain-PyPI requirement validation (shared: is_platform_pinned below AND the
+# thin client's Runtime.pip_install() both call canonical_pypi_name — see its
+# docstring for why this is a POSITIVE allowlist, not a denylist)
+# --------------------------------------------------------------------------
+#
+# Review round 2 (security MEDIUM + critic MAJOR) replaced an earlier
+# character/prefix DENYLIST here. A denylist only catches the forms its
+# author enumerated; this one leaked on every form it didn't:
+#
+# * ``"numpy(>=1.0)"`` — a parenthesized version spec (legal PEP 508) split
+#   its bare name as ``"numpy("`` under the old boundary-character split,
+#   missing :data:`PLATFORM_PINNED_PACKAGES` entirely (security MEDIUM).
+# * ``"evil-1.0-py3-none-any.whl"`` / ``"pkg.tar.gz"`` — a bare archive
+#   filename contains none of the old denylist's banned characters (no
+#   ``@``/``/``/``:``/``\\``, no ``git+``/``./``/``../`` prefix) and sailed
+#   through as a "clean" package name; the worker would then do a LOCAL
+#   wheel/sdist install — pip runs ``setup.py``/build hooks for those,
+#   arbitrary code execution (critic MAJOR).
+# * ``"."``, ``"-e"``, ``"--no-index"``, ``"--pre"`` — a bare directory or a
+#   leading-dash pip OPTION likewise contains none of the banned characters;
+#   pip would either install the current directory (running ``setup.py``) or
+#   have an option string injected into its own argv (critic MAJOR).
+#
+# :func:`canonical_pypi_name` fixes the class of bug, not just these three
+# instances: it is a POSITIVE grammar match for "plain, index-resolved PEP
+# 508 requirement, no direct reference" — anything that does not match,
+# including forms nobody has thought of yet, is rejected by construction.
+# This is also the ONE place both consumers call: ``is_platform_pinned``
+# below and ``simulo._client.runtime.Runtime.pip_install`` (thin client) —
+# duplicating the rule in both packages is how one gets hardened here and
+# missed there (critic MINOR, review round 2).
+
+#: PEP 503-shaped bare identifier: one or more alphanumeric runs separated by
+#: single ``.``/``_``/``-`` runs; first and last character always
+#: alphanumeric (so a bare ``.``/``..`` never matches). Written as
+#: alternating alnum-run/separator-run groups — not the more obvious
+#: ``[A-Za-z0-9]([A-Za-z0-9._-]*[A-Za-z0-9])?`` — specifically to avoid that
+#: form's ambiguous internal split (two adjacent classes sharing alnum
+#: characters), which is a classic catastrophic-backtracking shape; this
+#: form has none (each alternative consumes a disjoint character class).
+_PEP503_NAME = r"[A-Za-z0-9]+(?:[._-]+[A-Za-z0-9]+)*"
+_EXTRAS = rf"\[\s*{_PEP503_NAME}(?:\s*,\s*{_PEP503_NAME})*\s*\]"
+_VERSION_CMP = r"(?:===|==|!=|<=|>=|~=|<|>)"
+_VERSION_TOKEN = r"[A-Za-z0-9_.*+!-]+"
+_VERSION_CLAUSE = rf"{_VERSION_CMP}\s*{_VERSION_TOKEN}"
+_VERSION_CLAUSES = rf"{_VERSION_CLAUSE}(?:\s*,\s*{_VERSION_CLAUSE})*"
+#: A version spec may optionally be wrapped in parens (``"numpy(>=1.0)"``) —
+#: PEP 508 permits this form; it is the exact shape the old denylist's
+#: name-boundary split missed (see the module note above).
+_VERSION_SPEC = rf"(?:\(\s*{_VERSION_CLAUSES}\s*\)|{_VERSION_CLAUSES})"
+#: Environment-marker body after ``;``. Not a full PEP 508 marker-grammar
+#: parse (boolean ``and``/``or``, string-literal quoting rules) — a safe
+#: CHARACTER allowlist is sufficient here: ``@`` ``/`` ``\\`` are not in this
+#: class, so a marker can never smuggle a direct reference or a path — any
+#: attempt fails the OVERALL match, same as everywhere else in this grammar.
+_MARKER_BODY = r"[A-Za-z0-9_.,()'\" <>=!~-]+"
+_MARKER = rf";\s*{_MARKER_BODY}"
+
+#: The full grammar: ``name[extras](version-spec)?(; marker)?``, anchored
+#: start-to-end (via :func:`canonical_pypi_name`'s ``.match`` against the
+#: WHOLE stripped string) — nothing may follow that this grammar doesn't
+#: account for.
+_PLAIN_PYPI_SPEC = re.compile(
+    rf"^\s*(?P<name>{_PEP503_NAME})"
+    rf"(?:\s*(?P<extras>{_EXTRAS}))?"
+    rf"(?:\s*(?P<version>{_VERSION_SPEC}))?"
+    rf"(?:\s*{_MARKER})?"
+    r"\s*$"
+)
+
+#: Archive-file suffixes pip installs directly from a local/downloaded file
+#: without touching the index. Checked explicitly (case-insensitive) because
+#: a bare archive filename is otherwise a SYNTACTICALLY valid PEP 503 name —
+#: ``"evil-1.0-py3-none-any.whl"`` matches :data:`_PLAIN_PYPI_SPEC` letter
+#: for letter (hyphens and dots are legal name characters) — so the grammar
+#: match alone cannot reject it; this suffix check is the other half of
+#: closing that gap (a bare ``packaging.Requirement`` parse has the identical
+#: gap: ``Requirement("evil.whl")`` also parses as a plain name).
+#:
+#: Review round 3 (critic MAJOR / security HIGH): the round-2 tuple named
+#: only 6 suffixes — a subset of pip's real recognized-archive set
+#: (``pip._internal.utils.filetypes.ARCHIVE_EXTENSIONS`` /
+#: ``TAR_EXTENSIONS`` + ``ZIP_EXTENSIONS`` + ``.whl``). ``"evil-1.0.tar"``,
+#: ``"pkg.tbz"``, ``"pkg.tar.xz"``, ``"pkg.txz"``, ``"pkg.tlz"``,
+#: ``"pkg.tar.lz"``, and ``"pkg.tar.lzma"`` (``.tar`` especially — a
+#: mainstream sdist format) all had none of the 6 listed suffixes, so they
+#: read as a clean canonical name and passed BOTH :func:`is_platform_pinned`
+#: and the thin client's ``pip_install`` reject — pip installs each of these
+#: as a local sdist and runs its ``setup.py``. This tuple is now pip's
+#: COMPLETE 12-extension archive set, hardcoded (never `import pip` here —
+#: this package stays torch-free/dependency-light) plus ``.egg`` kept as a
+#: harmless extra (not one of pip's 12, but also not a legitimate bare PyPI
+#: name suffix).
+_ARCHIVE_SUFFIXES = (
+    ".zip",
+    ".whl",
+    ".tar.bz2",
+    ".tbz",
+    ".tar.gz",
+    ".tgz",
+    ".tar",
+    ".tar.xz",
+    ".txz",
+    ".tlz",
+    ".tar.lz",
+    ".tar.lzma",
+    ".egg",
+)
+
+
+def canonical_pypi_name(spec: str) -> Optional[str]:
+    """Return the canonical (PEP 503-normalised) bare name if *spec* is a
+    well-formed, plain-PyPI-installable requirement; ``None`` otherwise.
+
+    A spec is valid ONLY if it matches ``name[extras](version-spec)?(;
+    marker)?`` in full, with no direct-reference syntax — this is a POSITIVE
+    allowlist (see the module note above for why a denylist is the wrong
+    shape for this check). ``None`` covers every non-plain-PyPI form: a
+    direct reference (``name @ url``; any ``@``/``/``/``\\`` anywhere in the
+    spec fails the grammar), a VCS ref (``git+...`` — the ``+`` after
+    ``git`` is not a legal name character, so this also fails the grammar), a
+    local path (bare ``.``/``..``, or anything containing a path separator),
+    a bare archive filename (:data:`_ARCHIVE_SUFFIXES`), or a leading-dash
+    pip option (``-e``, ``--no-index``, ``-r``).
+
+    Callers MUST treat ``None`` as "reject" — never as "safe" or "not
+    pinned": see :func:`is_platform_pinned` (fails closed, returns ``True``)
+    and ``simulo._client.runtime.Runtime.pip_install`` (raises
+    ``SystemExit``) — the ONE validator both packages call (no duplicated
+    rule to drift out of sync).
+    """
+    stripped = spec.strip()
+    if not stripped or stripped in (".", ".."):
+        return None
+    if stripped.startswith("-"):
+        return None
+    if stripped.lower().endswith(_ARCHIVE_SUFFIXES):
+        return None
+    match = _PLAIN_PYPI_SPEC.match(stripped)
+    if match is None:
+        return None
+    return re.sub(r"[-_.]+", "-", match.group("name").lower())
+
+
+def is_platform_pinned(pkg_name: str) -> bool:
+    """Return ``True`` if ``pkg_name`` must be denied as platform-pinned.
+
+    Reduces *pkg_name* to its canonical bare name via
+    :func:`canonical_pypi_name` and denies (returns ``True``) if:
+
+    * *pkg_name* is not a well-formed, plain-PyPI requirement at all — a
+      direct reference, VCS ref, local path, archive filename, or pip
+      option. :func:`canonical_pypi_name` returns ``None`` for all of these;
+      this function fails CLOSED on ``None`` (denies) rather than treating
+      an unparseable spec as "not pinned" — an unverifiable spec could
+      install arbitrary content under a pinned package's name.
+    * the canonical name matches the CUDA-wheel shape (see
+      :data:`_NVIDIA_CUDA_WHEEL_PATTERN`): ``nvidia-<lib>-cu<N>`` is denied
+      for any CUDA major ``<N>``, while nvidia helper packages outside that
+      shape (``nvidia-ml-py``, ``nvidia-dali-cuda120``) are allowed.
+    * the canonical name is an exact (not prefix) member of
+      :data:`PLATFORM_PINNED_PACKAGES` — ``"torchmetrics"`` and
+      ``"simulo-console"`` do NOT match ``"torch"`` / ``"simulo"``.
+
+    Matching is case-insensitive and tolerant of the forms a real
+    ``pip_install()`` call can pass — extras, version specifiers (bare or
+    parenthesized), and environment markers are all stripped by
+    :func:`canonical_pypi_name` before comparison, so ``"Torch"``,
+    ``"torch(==2.1)"``, ``"simulo_interfaces"``, and
+    ``"Simulo-Interfaces==0.5.0"`` all match their canonical entry.
+
+    This function is the client-side fast-fail check only (see the module
+    note above) — a package that passes it may still collide with the base
+    image; the backend's install-time check against the real base-env
+    install set is authoritative.
+    """
+    normalized = canonical_pypi_name(pkg_name)
+    if normalized is None:
+        return True
+    if _NVIDIA_CUDA_WHEEL_PATTERN.match(normalized):
+        return True
+    return normalized in PLATFORM_PINNED_PACKAGES

{simulo_interfaces-0.5.0 → simulo_interfaces-0.6.0/src/simulo_interfaces.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simulo-interfaces
-Version: 0.5.0
+Version: 0.6.0
 Summary: Type contracts for the Simulo SDK. Installed automatically as a dependency of the simulo package.
 Author-email: Simulo Team <team@simulo.ai>
 License: BSD-3-Clause