simulo 0.26.0__py3-none-any.whl

simulo/_client/asset_pins.py

@@ -0,0 +1,187 @@
+"""Submit-time asset pin resolution — the ``simulo run`` half of registry-asset pinning.
+
+Collects every registry-asset ref an app declared (its App-level mounts, surfaced
+as the manifest's ``resources``), resolves them to exact versions against the
+control plane in one batch, prints the ``Resolved assets:`` block, applies the
+``--frozen`` / ``--strict-assets`` gates and the deprecated / not-validated
+warnings, and returns the ``[{ref, digest}]`` pins to attach to the job-create
+call as the top-level ``assets`` field.
+
+**Package-hash invariance.** Pins are a property of THIS submission, never of the
+package: they ride the job-create wire body (a sibling of ``args``), never enter
+``args`` or the manifest, so a package's content-addressed ``package_id`` can never
+change based on which versions its unpinned refs resolved to. Exactly the
+viewstream / seed rule (``app.py`` ambient signals).
+
+The heavy logic (resolution, gating, rendering) lives here rather than in
+``app.py`` so the submit seam stays lean and this is unit-testable in isolation.
+"""
+
+from __future__ import annotations
+
+import sys
+from typing import Any, Dict, List, Mapping, Optional, Sequence, TextIO
+
+from simulo._client.runtime_display import display_runtime
+from simulo._client.submit_api import AssetPinError, SubmitApiClient
+from simulo.interfaces.platform.asset_catalog import DEFAULT_ASSET_RUNTIME, ResolvedAssetPin, parse_asset_ref
+
+#: Re-exported from ``simulo.interfaces.platform.asset_catalog`` (current code and tests
+#: "Runtime-string seam", 2026-07-17 — hoisted there so the CLIENT's resolve
+#: request and the VALIDATOR's finalize call can never send different runtime
+#: strings). Kept as a module attribute here too — existing call sites
+#: (``app.py``, tests) import it from this module.
+__all__ = ["DEFAULT_ASSET_RUNTIME", "collect_asset_refs", "resolve_and_pin_assets"]
+
+
+def collect_asset_refs(manifest: Mapping[str, Any]) -> List[str]:
+    """Return the de-duplicated registry-asset refs an app declared, in first-seen
+    order.
+
+    The refs are the ``uri`` of every ``resources`` entry the manifest carries —
+    i.e. every App-level mount that is a :class:`simulo.Asset` (``Volume`` mounts
+    live in ``volumes``, not here; ``Asset.usd(...)`` / ``.urdf(...)`` model specs
+    are not mounts at all). Order-preserving de-dup so the printed block and the
+    resolve batch are stable and never resolve the same ref twice.
+    """
+    seen: Dict[str, None] = {}
+    for resource in manifest.get("resources") or []:
+        uri = resource.get("uri") if isinstance(resource, dict) else resource
+        if isinstance(uri, str) and uri and uri not in seen:
+            seen[uri] = None
+    return list(seen)
+
+
+def _short_digest(digest: str) -> str:
+    """``sha256:9c41…`` — the algo prefix + the first 4 hex chars + an ellipsis.
+    A digest with no recognisable hex tail is
+    rendered verbatim (defensive; the wire form is always ``sha256:<hex>``)."""
+    prefix, _, hexpart = digest.partition(":")
+    if hexpart:
+        return f"{prefix}:{hexpart[:4]}…"
+    return digest
+
+
+def _is_unpinned(ref: str) -> bool:
+    """``True`` if *ref* names no explicit ``:v<N>`` (resolved to latest at submit).
+
+    Parses through the ONE shared grammar so ``--frozen``'s notion of "pinned"
+    can never drift from what the catalog considers a version. A ref that does not
+    even parse is treated as unpinned here — it will fail the resolve with a clear
+    miss regardless, and ``--frozen`` should not be the thing that accepts it.
+    """
+    try:
+        return parse_asset_ref(ref).version is None
+    except ValueError:
+        return True
+
+
+def _resolved_publisher(canonical_ref: str) -> Optional[str]:
+    """The owning-catalog publisher of a resolved canonical ref, or ``None`` if it
+    cannot be parsed (defensive — a resolved ref is always canonical)."""
+    try:
+        return parse_asset_ref(canonical_ref).publisher
+    except ValueError:
+        return None
+
+
+def _render_resolved_block(refs: Sequence[str], resolved: Mapping[str, ResolvedAssetPin]) -> str:
+    """The ``Resolved assets:`` block — the authored (short) ref →
+    resolved version + short digest, columns aligned, in the order the refs were
+    declared. When the ref OMITTED its publisher (the caller's own org), the
+    owning org is named as a trailing ``(org: <slug>)`` label so the human always
+    sees which catalog a bare ref resolved in — the short-form + org-label
+    display, layered on the canonical pin that is actually recorded."""
+    lines = ["Resolved assets:"]
+    width = max((len(ref) for ref in refs), default=0)
+    for ref in refs:
+        pin = resolved[ref]
+        row = f"  {ref.ljust(width)}  ->  v{pin.version}  ({_short_digest(pin.digest)})"
+        try:
+            authored_omits_publisher = parse_asset_ref(ref).publisher is None
+        except ValueError:
+            authored_omits_publisher = False
+        if authored_omits_publisher:
+            org = _resolved_publisher(pin.canonical_ref)
+            if org is not None:
+                row += f"  (org: {org})"
+        lines.append(row)
+    return "\n".join(lines)
+
+
+def resolve_and_pin_assets(
+    client: SubmitApiClient,
+    refs: Sequence[str],
+    *,
+    runtime: str = DEFAULT_ASSET_RUNTIME,
+    frozen: bool = False,
+    strict: bool = False,
+    stream: Optional[TextIO] = None,
+) -> List[Dict[str, str]]:
+    """Resolve *refs* to exact pins, print the resolution, gate, and return
+    ``[{ref, digest}]`` for the job-create ``assets`` field.
+
+    Ordering mirrors the promise "failures happen in seconds": the
+    ``--frozen`` unpinned check runs BEFORE any network call, then a single batch
+    resolve, then the missing / deprecated / not-validated checks — all before the
+    package is uploaded (the caller sequences this ahead of upload).
+
+    * ``frozen`` — any unpinned ref fails immediately (CI / release explicitness).
+    * ``strict`` — the deprecated and not-validated-on-runtime WARNINGS become
+      errors.
+
+    Raises :class:`AssetPinError` (a ``SubmitApiError`` the CLI already renders as
+    a clean one-liner) on any frozen / missing / strict failure. Returns ``[]``
+    when *refs* is empty (no resolve call is made). The pins carry each version's
+    CANONICAL ref (publisher explicit, version pinned) — so the control plane
+    records the EXACT version this submit resolved, never re-resolving "latest" in
+    the submit transaction (a TOCTOU a new publish between resolve and submit would
+    otherwise open).
+    """
+    stream = stream if stream is not None else sys.stderr
+    refs = list(refs)
+    if not refs:
+        return []
+
+    if frozen:
+        unpinned = [ref for ref in refs if _is_unpinned(ref)]
+        if unpinned:
+            raise AssetPinError(
+                "--frozen requires every asset to be pinned to an exact version, but these are unpinned:\n"
+                + "".join(f"    {ref}\n" for ref in unpinned)
+                + "Pin each to a specific version (e.g. `robot/forklift:v3`) — `simulo asset inspect <ref>` "
+                "lists the versions — or drop --frozen."
+            )
+
+    response = client.resolve_assets(refs, runtime)
+    resolved, missing = response.resolved, response.missing
+
+    if missing:
+        raise AssetPinError(
+            "these assets could not be resolved (they don't exist, or you don't have access to them):\n"
+            + "".join(f"    {ref}: {miss.message}\n" for ref, miss in missing.items())
+            + "Check the ref and your active org — `simulo asset list` shows what you can use."
+        )
+
+    print(_render_resolved_block(refs, resolved), file=stream)
+
+    warnings: List[str] = []
+    for ref in refs:
+        pin = resolved[ref]
+        if pin.deprecated:
+            warnings.append(f"{pin.canonical_ref} is deprecated; a newer version may be available.")
+        if not pin.validated_on_runtime:
+            warnings.append(f"{pin.canonical_ref} has never validated on runtime {display_runtime(runtime)!r}.")
+
+    if warnings:
+        if strict:
+            raise AssetPinError(
+                "--strict-assets: these asset warnings are treated as errors:\n"
+                + "".join(f"    {warning}\n" for warning in warnings)
+                + "Revalidate the asset (`simulo asset validate <ref> --runtime "
+                + f"{runtime}`), pin a validated version, or drop --strict-assets."
+            )
+        for warning in warnings:
+            print(f"warning: {warning}", file=stream)
+
+    return [{"ref": resolved[ref].canonical_ref, "digest": resolved[ref].digest} for ref in refs]

simulo/_client/builtin_aliases.py

@@ -0,0 +1,107 @@
+"""``builtin://`` → global-catalog alias table + submit-time deprecation scan.
+
+The legacy ``builtin://<name>`` scheme (``simulo.Asset.usd("builtin://cartpole")``)
+is being absorbed into the global catalog under ``simulo/robot/<name>``. While
+the shim keeps ``builtin://`` refs working, ``simulo run`` prints a
+one-line deprecation notice at submit for every ``builtin://<name>`` whose catalog
+equivalent has been seeded — pointing the user at the ``simulo/robot/...`` idiom.
+
+Two pieces:
+
+* :data:`BUILTIN_ASSET_ALIASES` — the ``<builtin-name> -> <catalog-ref>`` table.
+  **PR-13 populated this table for real**, from a live GPU seeding run
+  (``scripts/seed-global-catalog.py``, run against a real control plane + a
+  real worker on the local 3090): every entry below is a builtin whose USD
+  closure localized AND whose real cloud validation (settle + actuation
+  probes) actually PASSED. A ``BUILTIN_ROBOT_CONFIGS`` name that isn't here
+  (``cartpole``, ``franka``, ``humanoid``, ``unitree_go2``, ``ur10`` as of
+  PR-13) genuinely has NOT been seeded — it failed real validation or could
+  not be localized into a self-contained package — so the scan below finds
+  nothing for it and NO notice is printed; that ``builtin://`` ref still
+  resolves through the legacy path. Do not add entries here by hand: a name
+  belongs in this table only once ``scripts/seed-global-catalog.py`` has
+  actually published + validated its ``simulo/robot/<name>`` catalog entry
+  (the script's own ``update_alias_table`` appends here, additively, keyed
+  on the SAME name it published under — see that script for the current
+  seed report), or the notice would send users to a ref that 404s.
+
+* :func:`scan_source_for_builtin_aliases` — a textual scan of the packaged source
+  files at submit, returning every ``(builtin_name, catalog_ref)`` pair whose
+  ``builtin_name`` both appears in a ``builtin://`` literal in the source AND has
+  a table entry. Purely lexical (a substring/regex scan, not an import or an AST
+  walk) so it stays torch-free and cannot execute user code.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Dict, List, Tuple
+
+#: ``<builtin-name>`` → the canonical ``simulo/robot/<name>`` catalog ref it maps
+#: to. Populated by ``scripts/seed-global-catalog.py`` (see the module
+#: docstring) — additively, one entry per REAL-validated seeded builtin. The
+#: deprecation notice fires ONLY for a name present in this table.
+BUILTIN_ASSET_ALIASES: Dict[str, str] = {
+    "anymal": "simulo/robot/anymal-c",
+    "anymal_c": "simulo/robot/anymal-c",
+    "h1": "simulo/robot/unitree-h1",
+    "jetbot": "simulo/robot/jetbot",
+    "pick_and_place": "simulo/robot/pick-and-place",
+    "unitree_h1": "simulo/robot/unitree-h1",
+}
+
+#: Matches a ``builtin://<name>`` literal in source text. ``<name>`` is a
+#: Python-identifier-shaped ``BUILTIN_ROBOT_CONFIGS`` key (lowercase letters,
+#: digits, underscores — e.g. ``pick_and_place``, ``unitree_h1``, ``anymal_c``)
+#: — DELIBERATELY WIDER than the catalog's own hyphen-only
+#: ``ASSET_SLUG_PATTERN``: this regex captures the AUTHORED ``builtin://``
+#: literal (a registry key), never a catalog ref itself (critic MAJOR, fix
+#: loop 1 — the original ``[a-z0-9-]`` alphabet silently truncated
+#: ``builtin://pick_and_place`` at the first underscore, capturing only
+#: ``"pick"``, which is never a table key, so the notice for every seeded
+#: underscore-named builtin silently never fired). The scan only ACTS on
+#: names that are also in :data:`BUILTIN_ASSET_ALIASES`, so a stray match on
+#: some other alphabet is harmless (it will not be in the table).
+_BUILTIN_URI_RE = re.compile(r"builtin://([a-z0-9][a-z0-9_-]*)")
+
+
+def scan_source_for_builtin_aliases(package_path: Path) -> List[Tuple[str, str]]:
+    """Return ``(builtin_name, catalog_ref)`` for every seeded ``builtin://`` use
+    in the packaged ``.py`` sources under *package_path*.
+
+    Short-circuits to ``[]`` when :data:`BUILTIN_ASSET_ALIASES` is empty (a
+    genuinely-empty table happens only in a checkout where the seeding script
+    has never run — the shipped table is populated, see the module
+    docstring), so submit pays no scan cost in that case. The
+    scan is lexical and best-effort: an unreadable file is skipped, never fatal —
+    a deprecation notice must never break a submit. Results are de-duplicated and
+    ordered by builtin name for a stable, testable notice.
+    """
+    if not BUILTIN_ASSET_ALIASES:
+        return []
+    found: Dict[str, str] = {}
+    for py_file in sorted(package_path.rglob("*.py")):
+        try:
+            text = py_file.read_text(encoding="utf-8", errors="replace")
+        except OSError:
+            continue  # unreadable file: skip, never fail a submit over the scan
+        for match in _BUILTIN_URI_RE.finditer(text):
+            name = match.group(1)
+            catalog_ref = BUILTIN_ASSET_ALIASES.get(name)
+            if catalog_ref is not None:
+                found[name] = catalog_ref
+    return [(name, found[name]) for name in sorted(found)]
+
+
+def format_builtin_deprecation_notice(matches: List[Tuple[str, str]]) -> str:
+    """Render the one-block deprecation notice for :func:`scan_source_for_builtin_aliases`'s
+    matches. Assumes a non-empty *matches* — callers guard on it."""
+    lines = [
+        "warning: the builtin:// asset scheme is deprecated and will be removed. "
+        "Move to the catalog ref (same asset, one grammar):",
+    ]
+    width = max(len(f"builtin://{name}") for name, _ in matches)
+    for name, catalog_ref in matches:
+        lines.append(f"    {f'builtin://{name}'.ljust(width)}  ->  {catalog_ref}")
+    return "\n".join(lines)

simulo/_client/bundle.py

@@ -0,0 +1,254 @@
+"""Build a v1 manifest from a live ``App`` and write the package (submit).
+
+Shared by ``simulo run`` (the CLI) and ``JobFunction.spawn`` — the *submit* path:
+discover the app's metadata and write the package (manifest + source bundle) to
+disk. The manifest builder reads only the public ``App`` surface, so it works in
+discovery mode (where submit runs). ``ensure_bundle`` memoises the written package
+per *submission* — ``(app, job_name, args)`` — so re-submitting the same job with
+the same args reuses the package, while a second spawn with a different job or
+different args writes a distinct package (no clobber).
+
+Submit NEVER executes a job and NEVER invokes the backend — it only writes the
+package. This module imports no heavy library; it stays on the torch-free side of
+the seam, and the ``simulo-backend`` runner (the sole executor) consumes the
+package it writes.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Optional, Sequence
+
+from simulo._client.asset import Asset
+from simulo._client.packaging import canonical_args, package, read_bundle_package_id
+from simulo._client.volume import Volume
+from simulo.interfaces.platform import is_platform_pinned
+from simulo.interfaces.platform.manifest import Manifest
+
+if TYPE_CHECKING:  # typing-only; avoids any import cycle with app.py at runtime
+    from simulo._client.app import App, JobSpec
+
+#: Default location for spawn-built bundles, relative to the project root. Pruned
+#: from packaging by the ``.simulo`` directory exclude, so it never self-includes.
+DEFAULT_OUT_SUBPATH = (".simulo", "packages")
+
+# Memoise the built bundle per *submission* (per process). Keyed on
+# ``(id(app), job_name, canonical_json(args))`` — an App lives for the whole run,
+# so identity reuse is not a concern, and keying on the job + args means multiple
+# spawns in one entrypoint (different job or different args) each write their own
+# package instead of the first one being reused for all.
+#
+# Each entry stores ``(bundle_dir, package_id)`` — the package_id the bundle
+# was written for when THIS process cached it — not just the path. The local
+# bundle directory name is a short, non-injective digest prefix (see
+# ``packaging.bundle_dir_name``), so a directory existing at the cached path is
+# NOT proof it still holds this submission's content: another submission whose
+# id happens to share the same short prefix could have called ``package()``
+# again for a DIFFERENT id and overwritten it (``package()`` unconditionally
+# rmtree+rewrites whatever it finds there). ``ensure_bundle`` re-verifies the
+# manifest on every cache hit before trusting it (see below) — turning a
+# prefix collision into a redundant rebuild, never a silently wrong package.
+#: Cache key's 4th element is the sorted, de-duplicated URIs of every
+#: ambiently-CAPTURED asset visible at this ``ensure_bundle`` call (construction-
+#: capture — see ``asset.py``) — included so a LATER spawn() in the same process,
+#: after the entrypoint has constructed MORE assets since an earlier spawn() with
+#: the identical ``(app, job_name, args)``, is never served a stale cached bundle
+#: whose ``resources`` predates those constructions (``package_id`` itself never
+#: changes with the asset set — see the package-hash-invariance rule — so the
+#: `package_id` re-check below cannot by itself catch this staleness).
+_BUNDLE_CACHE: dict[tuple[int, str, str, tuple[str, ...]], tuple[Path, str]] = {}
+
+
+def _mount_ref(mount: object) -> dict[str, Any]:
+    """Serialise a mount (Volume/Asset) to a manifest reference."""
+    if isinstance(mount, Volume):
+        return {"type": "volume", "name": mount.name, "create_if_missing": mount.create_if_missing}
+    if isinstance(mount, Asset):
+        return {"type": "asset", "uri": mount.uri, "read_only": mount.is_read_only}
+    return {"type": "unknown", "repr": repr(mount)}
+
+
+def _callback_entry(callback: object) -> dict[str, Any]:
+    """Serialise one job callback to its manifest entry.
+
+    Duck-typed on ``manifest_entry()`` so ``simulo.callbacks`` classes carry
+    their full config into the manifest. Foreign ``JobCallbackProtocol``
+    implementations (which have no ``manifest_entry``) fall back to a
+    config-less ``{"type": <ClassName>, "config": {}}`` record.
+    """
+    entry = getattr(callback, "manifest_entry", None)
+    if callable(entry):
+        result = entry()
+        if isinstance(result, dict):
+            return result
+    return {"type": type(callback).__name__, "config": {}}
+
+
+def _job_entry(spec: "JobSpec") -> dict[str, Any]:
+    return {
+        "module": spec.module,
+        "qualname": spec.qualname,
+        "resources": spec.resources,
+        "timeout": spec.timeout,
+        "retries": spec.retries,
+        "resume": spec.resume.value,
+        # List of {"type", "config"} dicts (was a list of class-name strings —
+        # the backend runner tolerates both shapes; manifest_version stays 1).
+        "callbacks": [_callback_entry(callback) for callback in spec.callbacks],
+        "mounts": {key: _mount_ref(mount) for key, mount in spec.mounts.items()},
+    }
+
+
+def build_manifest(
+    app: "App",
+    app_file: Path,
+    project_root: Path,
+    *,
+    args: Optional[dict[str, Any]] = None,
+    extra_assets: Sequence[Asset] = (),
+) -> Manifest:
+    """Build the v1 manifest from a live app's metadata (digest stamped later).
+
+    ``args`` records the keyword arguments the submitted job will be executed with
+    (the values passed to ``spawn``/``submit``). The backend runner merges these
+    over any ``--args-json`` it is given, so a submitted package carries the exact
+    invocation the user asked for.
+
+    ``extra_assets`` (construction-capture — ``asset.current_captured_assets()``)
+    are unioned into ``resources`` alongside the App's own ``mounts=``-declared
+    Assets, deduplicated by ``uri`` — an :class:`Asset` constructed but never
+    mounted (e.g. only referenced via ``Robot(asset=forklift)``) still needs a
+    ``resources`` entry so BOTH the submit-time resolve batch (``asset_pins.
+    collect_asset_refs`` reads ``resources``) and the local ``run-package`` mount
+    setup (``runner._setup_mounts``, also keyed off ``resources``) see it — an
+    unmounted handle must never resolve to a silent zero-pin submit.
+
+    **Submit-time denylist gate:** every package name declared via the
+    runtime's ``pip_install()`` is checked against
+    ``simulo.interfaces.platform.is_platform_pinned`` — a layer naming a
+    package the Simulo base runtime already provides (torch, numpy, the CUDA
+    wheels, the ``simulo`` distributions) fails the whole submit here with a
+    ``SystemExit`` listing the offenders, before any package is written or
+    uploaded. Fast-fail by design: a shadowing layer version once broke the
+    runtime's compiled camera-sensor bindings in ways undiagnosable from the
+    job's own traceback, so this raises — it never skips-and-warns.
+    """
+    rel = app_file.resolve().relative_to(project_root)
+    module = ".".join(rel.with_suffix("").parts)
+    entrypoints = app.entrypoint_names
+    entrypoint_name = entrypoints[0] if entrypoints else None
+
+    volumes: dict[str, Any] = {}
+    resource_by_uri: dict[str, dict[str, Any]] = {}
+    for mount in app.mounts.values():
+        if isinstance(mount, Volume):
+            volumes[mount.name] = {"create_if_missing": mount.create_if_missing}
+        elif isinstance(mount, Asset):
+            resource_by_uri[mount.uri] = {"uri": mount.uri, "read_only": mount.is_read_only}
+    for asset in extra_assets:
+        resource_by_uri.setdefault(asset.uri, {"uri": asset.uri, "read_only": asset.is_read_only})
+    resources: list[Any] = list(resource_by_uri.values())
+
+    runtime = app.runtime
+    pip_dependencies = [dict(layer) for layer in getattr(runtime, "pip_dependencies", [])]
+    pinned = list(
+        dict.fromkeys(  # de-duplicate across layers, preserving declaration order
+            spec for layer in pip_dependencies for spec in layer.get("packages", []) if is_platform_pinned(str(spec))
+        )
+    )
+    if pinned:
+        raise SystemExit(
+            "Cannot pip_install these — the Simulo base runtime already provides them: "
+            f"{', '.join(pinned)}. Remove them; the base image includes them."
+        )
+    return Manifest(
+        source_digest="",  # stamped by package()
+        runtime_id=str(getattr(runtime, "runtime_id", "")),
+        # The sub-key DELIBERATELY keeps its pre-0.15 wire spelling even though
+        # the decorator it records is now ``@app.entrypoint``. Renaming it
+        # changes the manifest bytes — and therefore ``archive_sha256`` — while
+        # ``package_id`` (sha256 over source_digest + job + args only) holds
+        # still. package_id-same + archive-different is EXACTLY the server's
+        # ``package_conflict`` 409 (jobs/service.py), so a rename here
+        # hard-blocks every 0.14.x user resubmitting an UNCHANGED
+        # entrypoint-less file (an entrypoint-bearing file dodges it only
+        # because editing the decorator moves source_digest). The key is an
+        # opaque serialization detail nothing reads (the backend runner reads
+        # only ``entrypoint.module``); manifest-shape migration is Plan A's
+        # (#540 — register-conflict handling). Pinned by
+        # test_manifest_wire_stability.py.
+        entrypoint={"file": rel.as_posix(), "module": module, "local_entrypoint": entrypoint_name},
+        runtime_env=dict(getattr(runtime, "runtime_env", {})),
+        jobs={name: _job_entry(spec) for name, spec in app.jobs.items()},
+        resources=resources,
+        volumes=volumes,
+        pip_dependencies=pip_dependencies,
+        args=dict(args or {}),
+    )
+
+
+def ensure_bundle(
+    app: "App",
+    app_file: Path,
+    project_root: Path,
+    *,
+    job_name: str = "",
+    args: Optional[dict[str, Any]] = None,
+    out_dir: Optional[Path] = None,
+    extra_assets: Sequence[Asset] = (),
+) -> Path:
+    """Write the package for one submission (memoised); return its path.
+
+    This is the *submit* primitive: the manifest is built from the live app object
+    (no second discovery import) with the submitted job's ``args`` recorded, and
+    the source tree is written to ``<out>/<bundle_dir_name(package_id)>/`` — the
+    per-submission directory keyed on source + ``job_name`` + ``args`` (named by
+    the id's short, filesystem-safe form; see ``packaging.bundle_dir_name``).
+    Memoised per submission (``(id(app), job_name, canonical_json(args), sorted
+    extra_assets uris)``) so re-submitting the same job with the same args AND the
+    same captured-asset set reuses the package, while a different job, different
+    args, or a DIFFERENT captured-asset set (more constructions since an earlier
+    spawn() in the same process — see ``asset.current_captured_assets()``) writes a
+    distinct package rather than serving a bundle whose ``resources`` predates a
+    since-constructed handle.
+
+    A cache HIT is re-verified, not trusted blindly: the short bundle directory
+    name is not injective (Windows MAX_PATH trade-off — see
+    ``packaging.bundle_dir_name``), so before returning a cached path this reads
+    the manifest actually on disk there and confirms its ``package_id`` still
+    matches what THIS cache entry was written for. A mismatch — some other
+    submission's id collided on the same short prefix and ``package()``
+    overwrote the directory — is treated as a MISS: the package is rebuilt
+    (deterministically restoring the correct content for this exact
+    submission), never served as a silently wrong package.
+    """
+    extra_asset_uris = tuple(sorted({asset.uri for asset in extra_assets}))
+    cache_key = (id(app), job_name, canonical_args(args), extra_asset_uris)
+    cached = _BUNDLE_CACHE.get(cache_key)
+    if cached is not None:
+        cached_dir, cached_package_id = cached
+        if cached_dir.is_dir() and read_bundle_package_id(cached_dir) == cached_package_id:
+            return cached_dir
+    if out_dir is None:
+        out_dir = project_root.joinpath(*DEFAULT_OUT_SUBPATH)
+    manifest = build_manifest(app, app_file, project_root, args=args, extra_assets=extra_assets)
+    bundle = package(app_file, out_dir=out_dir, project_root=project_root, manifest=manifest, job_name=job_name)
+    bundle_package_id = read_bundle_package_id(bundle)
+    if bundle_package_id is None:
+        # Internal invariant, not a user-facing input error: package() always
+        # stamps package_id into the manifest it writes (see packaging.py). A
+        # bare `assert` here would be stripped under `python -O`, silently
+        # caching a bundle keyed on a package_id we never actually confirmed
+        # (critic finding, PR #363 round-2 re-review, 2026-07-12) — use a
+        # real, always-live exception instead.
+        raise RuntimeError(
+            f"Internal error: package() wrote a bundle at {bundle} with no package_id in its manifest. "
+            "This should never happen — please report it."
+        )
+    _BUNDLE_CACHE[cache_key] = (bundle, bundle_package_id)
+    return bundle
+
+
+def clear_bundle_cache() -> None:
+    """Drop the per-process bundle cache. Intended for tests."""
+    _BUNDLE_CACHE.clear()

simulo/_client/cancel_api.py

@@ -0,0 +1,104 @@
+"""HTTP client for the job cancel endpoint (stdlib only, torch-free).
+
+Wire contract (job-cancel-and-demo-apps plan; the control
+plane's half of this route is built by a parallel effort, so this client codes
+directly against the plan's PINNED contract rather than waiting on it):
+``POST /v1/jobs/{job_id}/cancel`` (Cognito bearer, org-scoped).
+
+* 200 ``{"job_id": ..., "status": "cancelled"}`` — a QUEUED job is cancelled
+  immediately (it can never be claimed by a worker after this).
+* 202 ``{"job_id": ..., "status": "running", "cancel_requested": true}`` — a
+  RUNNING job has cancellation requested; the worker confirms termination
+  within one heartbeat interval. Idempotent — a repeat cancel of an
+  already-cancel-requested running job returns the same 202 shape again.
+* 409 ``job_not_running`` — the job is already in a terminal state
+  (completed/failed/cancelled); the response message carries the actual
+  status, but the caller (the thin client's CLI module) does not surface it
+  verbatim — it reuses the same friendly "has ended" copy ``simulo view``
+  uses for the identical situation.
+* 404 ``job_not_found`` — unknown or cross-org job id (anti-enumeration;
+  never 403). This is the cancel route's ONLY pinned 404 code — mirrors
+  ``view_session_api.py``'s contract, and the caller relies on that the same
+  way: any OTHER 404 code means the ``/cancel`` route itself isn't deployed
+  in this environment (e.g. prod before this feature ships there), not that
+  the job is missing — see ``cli._CANCEL_UNAVAILABLE_MESSAGE``.
+
+Error responses use the standard ``{"error": {"code", "message", "request_id"}}``
+envelope, parsed by ``http.py`` exactly like every other client in this
+package.
+
+The route path is a LOCAL constant here rather than imported from
+``simulo.interfaces.platform.runs`` — deliberately, the same reconciliation
+call ``view_session_api.py`` made: the control-plane cancel route is being
+built by a parallel PR and may land independently of this one, so this client
+codes directly against the plan's pinned path/response shape rather than
+sharing a file with that PR (avoiding a merge conflict). Reconcile into a
+shared ``simulo.interfaces.platform`` constant in a follow-up once that PR has
+merged, if a shared module materializes for it.
+
+Shares request plumbing (structured-error parsing, the https-when-token
+guard, the foreign-host bearer rule) with ``jobs_api.py``/``view_session_api.py``
+via ``http.py`` — one request path, not reimplemented a fourth time.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from simulo._client import http
+
+#: ``POST`` — request cancellation of a queued or running job. ``.format(job_id=...)``.
+CANCEL_ROUTE_TEMPLATE = "/v1/jobs/{job_id}/cancel"
+
+_REQUEST_TIMEOUT_S = 10.0  # every outbound call has an explicit timeout (NFR)
+_UNAVAILABLE_HINT = "Check SIMULO_API_URL / SIMULO_ENV, and that you are logged in (`simulo login`)."
+
+#: Required fields of a well-formed cancel response (see module docstring).
+_REQUIRED_FIELDS = ("job_id", "status")
+
+# Backward-compatible-style aliases — same convention as jobs_api.py /
+# view_session_api.py: these are literally ``http.HttpError``/``http.HttpHTTPError``
+# (not new subclasses), so callers that already catch ``JobsApiError`` (also
+# ``http.HttpError``) catch these too without any extra wiring.
+CancelApiError = http.HttpError
+CancelApiHTTPError = http.HttpHTTPError
+
+
+class CancelApiClient:
+    """Client for ``POST /v1/jobs/{job_id}/cancel``."""
+
+    def __init__(self, base_url: str, *, token: Optional[str] = None) -> None:
+        if not base_url.startswith(("http://", "https://")):
+            raise CancelApiError(f"API base URL must be an http(s) URL, got {base_url!r}.")
+        self._base_url = base_url.rstrip("/")
+        self._token = token
+
+    @property
+    def base_url(self) -> str:
+        return self._base_url
+
+    def cancel_job(self, job_id: str) -> dict[str, Any]:
+        """Request cancellation of *job_id*; returns the parsed 200/202 body.
+
+        Raises :class:`CancelApiHTTPError` on any non-2xx response — the
+        caller (the thin client's CLI module) classifies by ``exc.code``, never by
+        ``exc.status`` alone (both ``job_not_running`` and the route-missing
+        degradation share statuses with other codes, exactly like
+        ``ViewSessionApiClient.create_view_session``'s callers already do).
+        """
+        path = CANCEL_ROUTE_TEMPLATE.format(job_id=http.quote_path_segment(job_id))
+        payload = http.request_json(
+            "POST",
+            self._base_url + path,
+            token=self._token,
+            api_base_url=self._base_url,
+            json_body={},
+            timeout=_REQUEST_TIMEOUT_S,
+            unavailable_hint=_UNAVAILABLE_HINT,
+        )
+        if not isinstance(payload, dict):
+            raise CancelApiError("Malformed cancel response: expected a JSON object.")
+        missing = [field for field in _REQUIRED_FIELDS if field not in payload]
+        if missing:
+            raise CancelApiError(f"Malformed cancel response: missing field(s) {missing}.")
+        return payload