simulo 0.26.0__py3-none-any.whl

simulo/_client/app.py

@@ -0,0 +1,1308 @@
+"""``App`` / ``JobFunction`` / ``JobHandle`` — the ``@app.job`` surface.
+
+``App`` implements ``AppProtocol`` and self-registers on construction so submit can
+discover it. ``@app.job`` records job metadata (it never runs the body at
+decoration time) and returns a ``JobFunction`` proxy that is a superset of
+``JobFunctionProtocol``.
+
+**Submit, not execute.** ``spawn`` and ``submit`` are the *submit* surface: they
+write the package (manifest + source bundle) to disk via ``bundle.ensure_bundle``,
+recording this job's name + kwargs into the manifest, and return without training.
+``spawn`` returns a :class:`JobHandle` exposing ``.package_path`` / ``.job_id``;
+``submit`` returns a ``JobId``. Neither invokes the backend — execution is owned
+entirely by the ``simulo-backend`` runner (``simulo-backend run-package``), the
+sole executor. The thin client imports no part of ``simulo.backend``.
+
+**One user command.** ``simulo run app.py [--flags]`` is the canonical — and only —
+submit command: it runs the registered ``@app.entrypoint`` (or, without one, maps
+the flags onto the job's own signature), whose ``spawn`` call ends at exactly one
+submit. A direct ``python app.py`` never submits — ``@app.entrypoint`` detects the
+``__main__`` run, prints the exact equivalent ``simulo run`` command to stderr, and
+exits 2. An entrypoint-less file gets the SAME message and exit code from a
+same-copy at-exit guard (see :func:`_print_nothing_submitted_hint`).
+"""
+
+import atexit
+import contextlib
+import functools
+import hashlib
+import json
+import os
+import shlex
+import sys
+import types
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Callable, Iterator, Mapping, Optional, Sequence, TypeVar, Union, overload
+
+from simulo._client import config, credentials, registry
+from simulo._client._runner import JobFailedError, JobHandle, JobResultUnavailable
+from simulo._client.runtime import DEFAULT_RUNTIME
+from simulo.interfaces.ids import JobId, parse_job_public_id
+from simulo.interfaces.platform import JobCallbackProtocol
+from simulo.interfaces.platform.app import Mount
+from simulo.interfaces.platform.enums import ResumePolicy, SystemType
+from simulo.interfaces.platform.systems import SYSTEM_SPECS
+
+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
+
+F = TypeVar("F", bound=Callable[..., object])
+
+__all__ = ["App", "JobFunction", "JobHandle", "JobFailedError", "JobResultUnavailable", "JobSpec"]
+
+# ---------------------------------------------------------------------------
+# Spawn recorder — lets `simulo run` see every JobHandle an entrypoint's
+# spawn()/submit() calls produced, without threading a return value through
+# arbitrary user code. Used to decide the default post-run behavior (follow a
+# single cloud job's logs; print attach hints for zero/many).
+# ---------------------------------------------------------------------------
+
+_SPAWN_RECORDER: Optional[list["JobHandle"]] = None
+
+# True once ANY spawn()/submit() was ATTEMPTED in this process, recorder scope
+# or not — set on ENTRY to ``spawn()`` (intent to submit), never on success.
+# Read by the at-exit "nothing was submitted" guard. Intent, not success, is
+# deliberate: a cloud submit that dies AFTER ``create_job`` was sent (e.g. a
+# read timeout on the response) may have left a job RUNNING AND BILLING —
+# telling that user "Nothing was submitted" (and exiting 2) invites a re-run
+# that duplicates the GPU job. A failed attempt already printed its own
+# traceback; the guard has nothing truthful to add.
+_ANY_SPAWN_ATTEMPTED = False
+
+# True once any ``@app.job``-wrapped function was CALLED in-process — the
+# documented "run the body locally, exactly as if undecorated" mode. A direct
+# ``python app.py`` that called a job did real, intentional work; it is not a
+# silent no-op and must keep exit code 0.
+_ANY_JOB_INVOKED = False
+
+
+def _record_spawn(handle: "JobHandle") -> None:
+    if _SPAWN_RECORDER is not None:
+        _SPAWN_RECORDER.append(handle)
+
+
+@contextlib.contextmanager
+def spawn_recorder() -> Iterator[list["JobHandle"]]:
+    """Collect every :class:`JobHandle` produced by ``spawn()`` in this scope."""
+    global _SPAWN_RECORDER
+    previous = _SPAWN_RECORDER
+    handles: list[JobHandle] = []
+    _SPAWN_RECORDER = handles
+    try:
+        yield handles
+    finally:
+        _SPAWN_RECORDER = previous
+
+
+# ---------------------------------------------------------------------------
+# Viewstream ambient signal — `simulo run --viewstream` scopes this for the
+# duration of one submit so a cloud `spawn()` deep inside the user's
+# @app.entrypoint (which `simulo run` does not call directly) can
+# attach it to the job-create call. Deliberately NOT a `spawn()`/`submit()`
+# kwarg: those kwargs feed the job's `args`, whose canonical form is the
+# `package_id` sha256 — a streaming flag must never change the package hash
+# (the live-visualization plan's wire-contract rule). Mirrors the
+# `spawn_recorder` pattern above for the same "can't thread a return value
+# through arbitrary user code" reason.
+# ---------------------------------------------------------------------------
+
+_VIEWSTREAM_REQUESTED = False
+
+
+@contextlib.contextmanager
+def viewstream_requested(enabled: bool) -> Iterator[None]:
+    """Scope ``--viewstream`` for one ``simulo run`` submit call."""
+    global _VIEWSTREAM_REQUESTED
+    previous = _VIEWSTREAM_REQUESTED
+    _VIEWSTREAM_REQUESTED = enabled
+    try:
+        yield
+    finally:
+        _VIEWSTREAM_REQUESTED = previous
+
+
+# ---------------------------------------------------------------------------
+# Seed ambient signal — `simulo run --from <job-ref>[:best|:latest]` scopes the
+# seed reference for one submit (explicit-run-intent plan), exactly like the
+# viewstream signal above and for the same two reasons: the actual `spawn()`
+# happens deep inside the user's @app.entrypoint, and the seed is a
+# SUBMIT-time job property that must never enter `args` (whose canonical form
+# feeds the `package_id` sha256) or the package manifest. It rides the
+# `POST /v1/jobs` body as a top-level sibling of `args`, passed through
+# verbatim — the control plane resolves the ref (org-scoped, prefixes and
+# `:best`/`:latest` included) in the same request.
+# ---------------------------------------------------------------------------
+
+_SEED_FROM_REF: Optional[str] = None
+
+
+class SeedRequiresCloudError(RuntimeError):
+    """``--from`` was passed but the submit resolved to the local-disk path.
+
+    A local-disk submit only writes a package — no control plane exists to
+    resolve the seed reference or hand the checkpoint to a worker, so the
+    resulting run would silently be FRESH instead of seeded (the same
+    wrong-result hazard the loud-degradation check guards on the cloud
+    path). Refused loudly instead of ignored.
+    """
+
+
+@contextlib.contextmanager
+def seed_from_requested(seed_ref: Optional[str]) -> Iterator[None]:
+    """Scope ``--from``'s seed reference for one ``simulo run`` submit call."""
+    global _SEED_FROM_REF
+    previous = _SEED_FROM_REF
+    _SEED_FROM_REF = seed_ref
+    try:
+        yield
+    finally:
+        _SEED_FROM_REF = previous
+
+
+# ---------------------------------------------------------------------------
+# Asset-pin ambient signals — `simulo run --frozen` / `--strict-assets` scope
+# these for one submit, exactly like `--viewstream` / `--from` above and for the
+# same "the spawn() is deep inside the user's @app.entrypoint" reason. They
+# govern submit-time asset pin RESOLUTION, which — like viewstream/seed —
+# happens only on the cloud path (a local-disk submit has no control plane to
+# resolve against) and NEVER touches `args` or the manifest, so they can't move
+# `package_id`'s sha256.
+# ---------------------------------------------------------------------------
+
+_FROZEN_ASSETS_REQUESTED = False
+_STRICT_ASSETS_REQUESTED = False
+
+
+@contextlib.contextmanager
+def frozen_assets_requested(enabled: bool) -> Iterator[None]:
+    """Scope ``--frozen`` (fail on any unpinned asset ref) for one submit call."""
+    global _FROZEN_ASSETS_REQUESTED
+    previous = _FROZEN_ASSETS_REQUESTED
+    _FROZEN_ASSETS_REQUESTED = enabled
+    try:
+        yield
+    finally:
+        _FROZEN_ASSETS_REQUESTED = previous
+
+
+@contextlib.contextmanager
+def strict_assets_requested(enabled: bool) -> Iterator[None]:
+    """Scope ``--strict-assets`` (asset warnings become errors) for one submit call."""
+    global _STRICT_ASSETS_REQUESTED
+    previous = _STRICT_ASSETS_REQUESTED
+    _STRICT_ASSETS_REQUESTED = enabled
+    try:
+        yield
+    finally:
+        _STRICT_ASSETS_REQUESTED = previous
+
+
+# ---------------------------------------------------------------------------
+# Preflight ambient signal — `simulo run --skip-preflight` (PR-A6, Plan A)
+# scopes the escape hatch for one submit call, exactly like the flags above
+# and for the same "the cloud spawn() is deep inside the user's
+# @app.entrypoint" reason. Cloud-submit only: a local-disk submit never had
+# a preflight call to skip in the first place (no control plane target, and
+# `simulo run`'s OFFLINE default must stay a pure disk write with zero
+# network calls — see the module's "Submit, not execute" docstring rule).
+# ---------------------------------------------------------------------------
+
+_SKIP_PREFLIGHT_REQUESTED = False
+
+
+@contextlib.contextmanager
+def skip_preflight_requested(enabled: bool) -> Iterator[None]:
+    """Scope ``--skip-preflight`` for one ``simulo run`` submit call.
+
+    When True, ``_spawn_cloud`` makes NO preflight HTTP request at all for
+    this submission — bypassing the PHASE, not "call it and ignore the
+    answer". This is the documented escape hatch, so a ``blocking`` finding
+    can never become an unbypassable wall: a control plane a user cannot reach, or is
+    deliberately avoiding, must never be able to block this flag from
+    working.
+    """
+    global _SKIP_PREFLIGHT_REQUESTED
+    previous = _SKIP_PREFLIGHT_REQUESTED
+    _SKIP_PREFLIGHT_REQUESTED = enabled
+    try:
+        yield
+    finally:
+        _SKIP_PREFLIGHT_REQUESTED = previous
+
+
+class PreflightBlockedError(RuntimeError):
+    """A ``simulo run`` submit was refused by a ``blocking`` preflight finding.
+
+    Raised from ``_spawn_cloud`` AFTER the finding text is already printed
+    (mirrors ``simulo prepare``'s rendering) and BEFORE any other network
+    call for this submission: no asset-pin resolution, no package
+    registration, no archive upload, no job creation. ``--skip-preflight``
+    (:func:`skip_preflight_requested`) is the escape hatch that makes this
+    unreachable for a submission that wants to bypass the check entirely.
+    """
+
+
+def _require_no_seed_for_local_submit(reason: str) -> None:
+    """Refuse a local-disk submit that carries an ambient ``--from`` seed."""
+    if _SEED_FROM_REF is None:
+        return
+    raise SeedRequiresCloudError(
+        f"--from {_SEED_FROM_REF!r} needs a cloud control plane to resolve the checkpoint, but "
+        f"{reason} — a local-disk submit only writes the package and cannot continue from another "
+        "job's checkpoint, so the run would silently start fresh instead. Log in first "
+        "(`simulo login`) or point SIMULO_API_URL/SIMULO_ENV at a control plane (and unset "
+        "SIMULO_SUBMIT=local), or drop --from for a fresh local run."
+    )
+
+
+@dataclass
+class JobSpec:
+    """Recorded metadata for one ``@app.job``-decorated function."""
+
+    name: str
+    module: str
+    qualname: str
+    fn: Callable[..., object]
+    resources: dict[str, Any] = field(default_factory=dict)
+    timeout: Optional[int] = None
+    retries: int = 0
+    resume: ResumePolicy = ResumePolicy.AUTO
+    callbacks: tuple[JobCallbackProtocol, ...] = ()
+    mounts: dict[str, Mount] = field(default_factory=dict)
+
+
+def _app_source_location(module_name: str) -> tuple[Path, Path]:
+    """Resolve the on-disk app file (and its directory) for a job's module.
+
+    The app is defined in the same file as its jobs, so the job's ``__module__``
+    locates the source to package. Raises clearly if the module has no ``__file__``
+    (e.g. an interactively-defined app, which cannot be submitted as a package).
+    """
+    module = sys.modules.get(module_name)
+    file = getattr(module, "__file__", None)
+    if not file:
+        raise RuntimeError(
+            f"Cannot locate the source file for module {module_name!r} to package. "
+            "submit()/spawn() require the app to be defined in a .py file."
+        )
+    app_file = Path(file).resolve()
+    return app_file, app_file.parent
+
+
+def _cloud_mode_active(creds: Optional[dict[str, Any]]) -> bool:
+    """Cloud submit is active when credentials exist or the target is named explicitly.
+
+    Callers MUST check ``is_submit_forced_local`` (the client config module)
+    themselves BEFORE resolving ``creds`` — see :func:`_spawn_local` below.
+    That check is deliberately NOT repeated here: by the time this function is
+    called, ``SIMULO_SUBMIT=local`` has already short-circuited to the
+    local-disk path, so this function only ever runs when a credentials
+    read/refresh was already appropriate to attempt.
+    """
+    if config.has_explicit_cloud_env():
+        return True
+    return creds is not None
+
+
+def _spawn_local(job_name: str, package_path: Path) -> JobHandle:
+    """The local-disk submit path: a locally-derived job id, no network call."""
+    job_id = JobId(f"submitted-{job_name}-{package_path.name}")
+    return JobHandle(job_id, package_path, job_name)
+
+
+def _skip_preflight_hint(blocking: "Sequence[PreflightFinding]") -> str:
+    """The follow-on sentence :func:`_handle_preflight_outcome` appends after
+    its blocking-finding count, chosen from the WHOLE batch rather than one
+    finding at a time.
+
+    For most blocking codes this is the plain hint every prior release has
+    printed: the flag still bypasses the whole preflight phase, and nothing
+    here makes a finding unbypassable — ``skip_preflight_requested``'s
+    docstring rule ("a blocking finding can never become an unbypassable
+    wall") is unchanged.
+
+    ``runtime_not_available`` is the one exception, and only the ADVICE
+    changes, not the flag's behavior. The generic hint's two stated reasons
+    to bypass are "preflight is wrong about your app" and "the platform is
+    unreachable" — this finding is neither: it fires only when the
+    requested runtime id is absent from an ESTABLISHED inventory (at least
+    one worker has actually reported a runtime, so the known set describes
+    the fleet rather than merely restating the default); when nothing has
+    ever reported, that same absence is the advisory ``unknown_runtime``
+    instead (see ``preflight/service.py``'s ``_runtime_availability_finding``).
+    That established-inventory fact is real regardless of workload — the
+    same trigger fires for an unavailable GPU runtime as for an unavailable
+    CPU one. Bypassing it does not route around a wrong opinion, it
+    re-enables the exact silent substitution onto the platform's GPU-backed
+    default runtime that this finding exists to prevent, so the generic
+    hint is replaced with one naming that substitution WITHOUT inventing a
+    rate, an estimate, or any claim about what the workload itself needs —
+    there is no rate card (``PreflightResponse.estimate`` is reserved and
+    always ``null``; see ``preflight/schemas.py``/``routes.py``). Keyed on
+    ``finding.code`` (the server's own vocabulary — see
+    ``preflight_render.py``'s module docstring), never on message text.
+
+    ``--skip-preflight`` bypasses the entire preflight call, not one finding
+    in isolation (see ``skip_preflight_requested``), so if ANY finding in
+    *blocking* is ``runtime_not_available``, the qualified sentence governs
+    the whole raise even when an ordinary, safely-bypassable finding is also
+    blocking alongside it — bypassing would still re-enable that finding's
+    harm too.
+    """
+    from simulo._client.preflight_render import RUNTIME_NOT_AVAILABLE_CODE
+
+    if any(finding.code == RUNTIME_NOT_AVAILABLE_CODE for finding in blocking):
+        return (
+            "--skip-preflight would submit anyway, but not onto the runtime you asked for — this "
+            "platform doesn't offer it, so the job would run on the platform's default runtime "
+            "instead, which is GPU-backed."
+        )
+    return "Pass --skip-preflight to submit anyway (not recommended)."
+
+
+def _handle_preflight_outcome(outcome: "PreflightOutcome", *, job_name: str) -> None:
+    """Print + decide for one preflight answer inside ``_spawn_cloud``.
+
+    Fail-open (``outcome.skipped``): print the notice to stderr exactly like
+    ``simulo prepare`` does, then return — the submit proceeds as if
+    preflight had not run at all (see ``preflight_api``'s module docstring;
+    preflight failing HARD instead of failing open must never gain a second
+    instance on this path).
+
+    A well-formed response renders EVERY finding to stdout — ``✗`` for
+    ``blocking``, ``⚠`` for ``advisory`` — using the exact same per-code copy,
+    control-character sanitization, and outcome-level rendering ``simulo
+    prepare`` uses (``preflight_render.py``'s ``render_preflight_skip_notice``/
+    ``render_preflight_findings``), so the two commands read identically for
+    the same finding rather than each keeping its own copy of that loop.
+    Advisory findings (including the ``no_active_worker`` finding — the actual fix
+    for "submit accepts a job with zero workers and the client silently
+    follows an empty stream") print and the submit proceeds regardless. Any
+    ``blocking`` finding raises :class:`PreflightBlockedError` with a short
+    stderr summary — the detailed ``✗`` lines are already on stdout by the
+    time this raises, so the exception message is a summary + the
+    ``--skip-preflight`` hint (:func:`_skip_preflight_hint`), not a
+    duplicate render.
+    """
+    from simulo._client.preflight_render import render_preflight_findings, render_preflight_skip_notice
+
+    if outcome.skipped:
+        render_preflight_skip_notice(outcome)
+        return
+    blocking, _advisory = render_preflight_findings(outcome)
+    if not blocking:
+        return
+    raise PreflightBlockedError(
+        f"{len(blocking)} preflight issue(s) blocked job {job_name!r} — nothing was uploaded and no "
+        f"job was created. {_skip_preflight_hint(blocking)}"
+    )
+
+
+def _spawn_cloud(
+    job_name: str,
+    package_path: Path,
+    creds: Optional[dict[str, Any]],
+    *,
+    viewstream: bool = False,
+    seed_from: Optional[str] = None,
+    frozen_assets: bool = False,
+    strict_assets: bool = False,
+    skip_preflight: bool = False,
+    app_name: Optional[str] = None,
+) -> JobHandle:
+    """Tar the bundle, preflight it, upload it, create the job, and return a
+    cloud JobHandle.
+
+    ``app_name`` (live-view wave) is the submitting ``App``'s
+    declared name, forwarded as an OPTIONAL top-level sibling of ``args`` on
+    the job-create call only (the same package-hash-invariance rule as
+    ``viewstream``/``seed_from`` below) so the platform's live viewer can
+    show WHAT is being watched. Best-effort display metadata: an older
+    control plane ignores it, and omitting it changes nothing about the run.
+
+    ``viewstream`` rides ONLY the job-create call, as an optional top-level
+    body field (never inside ``args``, which feeds the ``package_id`` sha256
+    — see the live-visualization plan's wire-contract rule): a package's
+    content-addressed identity must never change based on whether this
+    particular execution asked for a live stream.
+
+    The requested GPU system tier (system-tier-catalog-1362, M50-persistence)
+    is NOT a parameter here — it is read from the already-parsed manifest's
+    ``jobs[job_name]["resources"]["system"]`` (the wire value
+    ``@app.job(system=...)`` already validated and recorded at decoration
+    time) and forwarded to ``create_job`` below as an optional top-level
+    sibling of ``args``, for the identical package-hash-invariance reason as
+    ``viewstream``.
+
+    ``seed_from`` (``simulo run --from``, explicit-run-intent plan) follows
+    the identical rule: the seed reference is a SUBMIT-time job property,
+    never a package property — it rides the job-create call only, verbatim
+    (the control plane resolves prefixes and ``:best``/``:latest``). When the
+    server honors it, the resolved provenance is announced on stderr without
+    exposing its machine UUID; when an older server ignores it, ``create_job``
+    raises rather than let a fresh run masquerade as a seeded one.
+
+    ``skip_preflight`` (``simulo run --skip-preflight``) bypasses the
+    preflight phase below entirely — no HTTP request is made — rather than
+    calling it and discarding the answer.
+
+    **Preflight** runs FIRST — before asset-pin
+    resolution, before ``create_package``, before ``upload_archive``, before
+    ``create_job`` — so a ``blocking`` finding uploads nothing and submits
+    nothing: a :class:`PreflightBlockedError` unwinds this call before any of
+    those network calls happen. ``job_name``/``archive_size`` are both known
+    here (unlike ``simulo prepare``, which checks a whole app with neither),
+    so this call is more precise than prepare's: the server's timeout check
+    scopes to just this job, and the archive-size check runs for real. The
+    already-built ``archive_bytes`` (local disk only — no network yet) feed
+    ``archive_size`` at zero extra cost. ``assets`` is deliberately NOT
+    passed: ``PreflightApiClient.evaluate`` accepts it for wire-tuple
+    parity, but resolving pins requires its own network round trip that
+    normally happens further down this function, and the control plane's
+    ``evaluate_preflight`` does not read ``body.assets`` in any check today
+    (verified against ``simulo_control_plane.preflight.service`` — no
+    finding consumes it) — running that resolve early would buy nothing and
+    would cost the fail-open contract an extra failure mode to reason about.
+    ``viewstream`` is passed for the same tuple-parity reason even though no
+    check consumes it either: it costs nothing (already a plain bool, no
+    resolution needed).
+
+    Registry-asset pins follow the SAME sibling-of-``args`` rule. Every
+    ``Asset.from_registry`` ref the app mounted is resolved to an exact
+    version in one batch BEFORE the package is uploaded — so a bad/missing/
+    unpinned ref fails in seconds rather than after the upload — the
+    ``Resolved assets:`` block is printed, ``--frozen`` / ``--strict-assets``
+    are enforced, and the resolved ``[{ref, digest}]`` pins ride the
+    job-create call's top-level ``assets`` field, never ``args``.
+    """
+    from simulo._client.asset_pins import DEFAULT_ASSET_RUNTIME, collect_asset_refs, resolve_and_pin_assets
+    from simulo._client.packaging import MANIFEST_FILENAME, ensure_tar
+    from simulo._client.preflight_api import PreflightApiClient
+    from simulo._client.submit_api import SubmitApiClient, SubmitApiError
+    from simulo.interfaces.platform.manifest import Manifest
+
+    manifest_text = (package_path / MANIFEST_FILENAME).read_text(encoding="utf-8")
+    manifest = json.loads(manifest_text)
+    # The manifest's package_id is the wire identity (``sha256:<hex>``) and is
+    # the ONLY source of truth for it — every manifest ``package()`` writes
+    # carries one (see packaging.py). The local directory name is NOT a valid
+    # fallback: it is a short, non-invertible, filesystem-safe form of the id
+    # (see ``packaging.bundle_dir_name`` — truncated for Windows MAX_PATH),
+    # so guessing an id back from it would either be impossible (can't invert
+    # a truncated hash) or, worse, silently put a WRONG/incomplete id on the
+    # wire. An id-less manifest means a bundle written by a client older than
+    # this fix, or a corrupted/foreign directory — fail loudly and tell the
+    # caller how to recover, never guess.
+    package_id = manifest.get("package_id")
+    if not package_id:
+        raise RuntimeError(
+            f"Package at {package_path} has no package_id in its manifest (it predates this client "
+            "version, or its manifest is missing/corrupted). Re-run `simulo run` (or call .spawn() "
+            "again) to rebuild it before submitting to the cloud."
+        )
+    package_id = str(package_id)
+    source_digest = str(manifest.get("source_digest", ""))
+    args = dict(manifest.get("args") or {})
+    # The requested GPU system tier (system-tier-catalog-1362, M50-persistence)
+    # — already validated at `@app.job(system=...)` decoration time and
+    # recorded on THIS job's own manifest entry as `resources["system"]`
+    # (the tier's wire value, e.g. "tier1"; see `decorate()`'s
+    # `resources["system"] = system.value`). Read from the already-parsed
+    # manifest rather than threaded in as a new parameter, since the value
+    # already lives there, keyed by this same `job_name`.
+    job_entry = manifest.get("jobs", {}).get(job_name) or {}
+    system = (job_entry.get("resources") or {}).get("system")
+
+    tar_path = ensure_tar(package_path)
+    archive_bytes = tar_path.read_bytes()
+    archive_sha256 = "sha256:" + hashlib.sha256(archive_bytes).hexdigest()
+
+    base_url = config.resolve_base_url(creds)
+    token = creds["access_token"] if creds else os.environ.get("SIMULO_API_TOKEN")
+
+    if not skip_preflight:
+        # This manifest was just written, moments ago, by THIS process's own
+        # `manifest.to_json()` (see `bundle.py`) — never foreign or
+        # cross-version bytes — so `Manifest.from_json` re-parsing it here
+        # can never hit the TypeError-on-unknown-key hazard PR-A1's security
+        # review flagged for UNTRUSTED input; this input is our own.
+        outcome = PreflightApiClient(base_url, token=token).evaluate(
+            Manifest.from_json(manifest_text),
+            job_name=job_name,
+            archive_size=len(archive_bytes),
+            seed_from_job_id=seed_from,
+            viewstream=viewstream,
+        )
+        _handle_preflight_outcome(outcome, job_name=job_name)
+
+    client = SubmitApiClient(base_url, token=token)
+
+    # Resolve every mounted registry-asset ref to an exact pin FIRST — before the
+    # package is uploaded — so a missing/unpinned/unvalidated ref fails in seconds.
+    # Returns the top-level `assets: [{ref, digest}]` for create_job; `[]`
+    # when the app mounts no registry assets (no resolve call is made then).
+    asset_pins = resolve_and_pin_assets(
+        client,
+        collect_asset_refs(manifest),
+        runtime=DEFAULT_ASSET_RUNTIME,
+        frozen=frozen_assets,
+        strict=strict_assets,
+    )
+
+    client.create_package(
+        package_id=package_id,
+        source_digest=source_digest,
+        job_name=job_name,
+        archive_sha256=archive_sha256,
+        archive_size=len(archive_bytes),
+    )
+    client.upload_archive(package_id, archive_bytes)
+    record = client.create_job(
+        package_id=package_id,
+        job_name=job_name,
+        args=args,
+        viewstream=viewstream,
+        seed_from_job_id=seed_from,
+        assets=asset_pins,
+        app_name=app_name,
+        system=system,
+    )
+
+    raw_public_id = record.get("public_id")
+    try:
+        if not isinstance(raw_public_id, str):
+            raise TypeError("public_id is not a string")
+        public_id = parse_job_public_id(raw_public_id)
+    except (TypeError, ValueError):
+        # A current public cloud response must carry the human-facing Job ID.
+        # The machine UUID is intentionally not used as display fallback: the
+        # job may already have been created, so give a neutral recovery path.
+        raise SubmitApiError(
+            "The platform created the job but did not return a usable Job ID. "
+            "Run `simulo jobs` to find the submission before retrying."
+        ) from None
+
+    if seed_from is not None:
+        # create_job has already guaranteed the seed dict is present (the
+        # loud-degradation guard) — this line is the human confirmation that
+        # the ref resolved to the intended source job. Seed provenance still
+        # carries machine UUIDs only, so keep this confirmation neutral rather
+        # than leaking a UUID while that response contract catches up.
+        seed = record.get("seed") or {}
+        print(
+            f"Continuing from selected job ({seed.get('name')}, {seed.get('kind')} checkpoint)",
+            file=sys.stderr,
+        )
+
+    return JobHandle(
+        JobId(str(record["job_id"])),
+        package_path,
+        job_name,
+        public_id=public_id,
+        cloud=True,
+        base_url=base_url,
+        token=token,
+    )
+
+
+class JobFunction:
+    """What ``@app.job`` returns: the original function, wrapped for submission.
+
+    Calling it runs the body in-process, exactly as if it were undecorated (that
+    is also how the platform invokes it on a worker). :meth:`spawn` and
+    :meth:`submit` package and submit it instead. You never construct one
+    yourself — decorate a function and use it from your ``@app.entrypoint``.
+    """
+
+    def __init__(self, app: "App", spec: JobSpec) -> None:
+        self._app = app
+        self._spec = spec
+        functools.update_wrapper(self, spec.fn)
+
+    @property
+    def spec(self) -> JobSpec:
+        return self._spec
+
+    def __call__(self, *args: object, **kwargs: object) -> object:
+        """Run the original job body in-process (execution mode)."""
+        global _ANY_JOB_INVOKED
+        _ANY_JOB_INVOKED = True
+        return self._spec.fn(*args, **kwargs)
+
+    def spawn(self, **kwargs: Any) -> JobHandle:
+        """Submit this job to the Simulo cloud (once logged in), or write it locally.
+
+        Submitting writes the manifest + source bundle (memoised once per app),
+        recording this job's name and ``kwargs`` into the manifest so the job can
+        be run later with ``fn(**kwargs)``.
+
+        **Cloud mode** — credentials exist (``simulo login``), or
+        ``SIMULO_API_URL``/``SIMULO_ENV`` names a target (and ``SIMULO_SUBMIT`` is
+        not ``local``): the package is tarred, uploaded, and a job is created on
+        the Simulo cloud. The returned :class:`JobHandle` carries the
+        SERVER-assigned ``job_id`` and ``.get()`` streams the real result.
+
+        **Local-disk mode** (the default with no cloud signal present): NEVER
+        trains and never runs the job — the handle exposes only
+        ``.package_path`` / ``.job_id`` (a locally-derived id), and ``.get()``
+        raises, pointing you at ``simulo login`` to submit to the cloud instead.
+
+        Positional arguments are rejected: a job body receives only the keyword
+        arguments recorded in the manifest.
+        """
+        # Intent-to-submit is recorded FIRST — before any packaging or network
+        # I/O — so a submit that fails partway (or times out AFTER the server
+        # accepted the job) can never be mislabelled "Nothing was submitted"
+        # by the at-exit guard. See _ANY_SPAWN_ATTEMPTED.
+        global _ANY_SPAWN_ATTEMPTED
+        _ANY_SPAWN_ATTEMPTED = True
+        # Lazy import keeps app.py free of a module-scope dependency on the
+        # packager (and any import cycle); spawn is a runtime call.
+        from simulo._client.asset import current_captured_assets
+        from simulo._client.bundle import ensure_bundle
+
+        app_file, project_root = _app_source_location(self._spec.module)
+        # Construction-capture (authored-ref mount invariant): every Asset
+        # constructed so far in the active `simulo run` capture scope (armed
+        # around the whole discovery import + entrypoint run — see cli.py) is
+        # unioned into this bundle's `resources`, even when never explicitly
+        # mounted via App(mounts=...) — an unmounted registry handle
+        # (`forklift = simulo.Asset.from_registry(...)`, used only via
+        # `Robot(asset=forklift)`) must still get resolved and pinned.
+        package_path = ensure_bundle(
+            self._app,
+            app_file,
+            project_root,
+            job_name=self._spec.name,
+            args=dict(kwargs),
+            extra_assets=current_captured_assets(),
+        )
+
+        # SIMULO_SUBMIT=local is checked FIRST, before touching credentials at
+        # all — the escape hatch must short-circuit even when the saved token
+        # is expired (which would otherwise trigger a network refresh, or
+        # fail outright if the refresh token itself is no longer valid). A
+        # local-disk submit must never depend on the network succeeding.
+        if config.is_submit_forced_local():
+            _require_no_seed_for_local_submit("SIMULO_SUBMIT=local forces a local-disk submit")
+            handle: JobHandle = _spawn_local(self._spec.name, package_path)
+        else:
+            creds = credentials.try_get_valid_credentials()
+            if _cloud_mode_active(creds):
+                handle = _spawn_cloud(
+                    self._spec.name,
+                    package_path,
+                    creds,
+                    viewstream=_VIEWSTREAM_REQUESTED,
+                    seed_from=_SEED_FROM_REF,
+                    frozen_assets=_FROZEN_ASSETS_REQUESTED,
+                    strict_assets=_STRICT_ASSETS_REQUESTED,
+                    skip_preflight=_SKIP_PREFLIGHT_REQUESTED,
+                    app_name=self._app.name,
+                )
+            else:
+                _require_no_seed_for_local_submit("no cloud target is configured")
+                handle = _spawn_local(self._spec.name, package_path)
+        _record_spawn(handle)
+        return handle
+
+    def submit(self, *args: object, **kwargs: object) -> JobId:
+        """Submit this job (keyword args only): write the package, return its id.
+
+        Like :meth:`spawn` but returns just the ``JobId`` (``JobFunctionProtocol``).
+        It writes the package and never executes; nothing is dispatched.
+        """
+        if args:
+            raise TypeError("JobFunction.submit() accepts keyword arguments only.")
+        return self.spawn(**kwargs).job_id
+
+
+def _cli_redirect_message(job_names: Sequence[str] = ()) -> str:
+    """The ONE stderr message for a direct ``python app.py`` run — both guard paths.
+
+    Names the exact equivalent ``simulo run`` command: ``sys.argv[0]`` is the app
+    file as the user typed it and ``sys.argv[1:]`` are their flags verbatim
+    (``shlex.join`` quotes anything that needs it), so the printed command is
+    copy-pasteable as-is.
+
+    The decoration-time redirect (``@app.entrypoint``) and the at-exit guard for
+    entrypoint-less files both print exactly this copy — one mistake, one
+    message, one exit code (2). ``job_names`` is passed only by the at-exit
+    guard when the file declares MORE THAN ONE job: a bare ``simulo run`` errors
+    there, so the suggested command gains ``--job NAME`` and the valid names are
+    listed (in declaration order — for staged apps that is the intended run
+    order).
+    """
+    command = shlex.join(["simulo", "run", *sys.argv])
+    job_lines = ""
+    if len(job_names) > 1:
+        command += " --job NAME"
+        job_lines = f"\nJobs in {sys.argv[0]} (in declaration order): {', '.join(job_names)}.\n"
+    return (
+        "Simulo apps are submitted with the Simulo CLI, not `python`:\n"
+        "\n"
+        f"    {command}\n"
+        f"{job_lines}"
+        "\n"
+        "Nothing was submitted."
+    )
+
+
+# Arm the "nothing was submitted" nudge at most once per process — only the first
+# App declared by a directly-run script registers the at-exit hook.
+_NOTHING_SUBMITTED_HINT_ARMED = False
+
+
+def _direct_run_frame_globals() -> Optional[dict[str, Any]]:
+    """The running script's module globals when this is a direct ``python app.py``, else None.
+
+    The app literal is written at module scope in the user's file, so the first
+    frame *outside this module* that constructs the App is that file's module
+    body. A direct ``python app.py`` runs it as ``__main__`` with a real
+    ``__file__``; ``simulo run`` and the backend runner import the file under its
+    own module name (never ``__main__``), and ``python -c`` / typed REPL and
+    notebook cells have no ``__file__`` — none of which arm the hint. Walking
+    out of this module (rather than counting frames) keeps it correct
+    regardless of internal call depth.
+
+    NOTE this check alone cannot distinguish ``python app.py`` from a HOST
+    process running the file under the ``__main__`` name — ``runpy.run_path``,
+    IPython's ``%run``, and similar harnesses set BOTH ``__name__ ==
+    "__main__"`` and a real ``__file__`` while executing it. The decoration-time
+    redirect is safe there anyway (it raises ``SystemExit``, which hosts catch);
+    the at-exit guard — which must never ``os._exit`` a host process — does its
+    own host discrimination (see :func:`_arm_nothing_submitted_hint` and
+    :func:`_print_nothing_submitted_hint`).
+    """
+    frame: Optional[types.FrameType] = sys._getframe(1)
+    while frame is not None and frame.f_globals.get("__name__") == __name__:
+        frame = frame.f_back
+    if frame is None:  # pragma: no cover - no caller outside this module
+        return None
+    g = frame.f_globals
+    if g.get("__name__") == "__main__" and g.get("__file__"):
+        return g
+    return None
+
+
+def _is_direct_script_run() -> bool:
+    """True when ``App(...)`` is being evaluated under the ``__main__`` name."""
+    return _direct_run_frame_globals() is not None
+
+
+# True once the direct run's exit is ALREADY EXPLAINED by something other than
+# a silent no-op: an unhandled exception (recorded by the wrapped
+# ``sys.excepthook`` — which CPython calls for every uncaught non-SystemExit
+# exception, including KeyboardInterrupt) or an explicit ``sys.exit(...)``
+# (recorded by the wrapped ``sys.exit``, any code including 0). Either way the
+# at-exit guard must stay silent and MUST NOT override the process's real exit
+# code — a caller has to be able to tell "wrong invocation" (2) from "your app
+# crashed" (its own code) from "your app chose to exit" (its own code).
+#
+# Coverage is precise, not total. COVERED: any ``sys.exit(...)`` RESOLVED AT
+# CALL TIME (the overwhelmingly common spelling), and any uncaught
+# non-SystemExit exception reaching the excepthook chain in place at arm time.
+# NOT covered — all verified empirically on CPython 3.11, all pinned or
+# documented, none detectable without process-global mutation:
+#
+# * a literal ``raise SystemExit(n)`` at module scope, any ``n`` — CPython
+#   special-cases SystemExit in ``_PyErr_PrintEx`` (the excepthook is never
+#   called for it) and ``sys.exit`` is bypassed, so no supported hook observes
+#   it before atexit runs, and the pending exit code is invisible to Python by
+#   then (pinned residuals: redirect + exit 2, destroying a chosen nonzero
+#   code);
+# * a reference to ``sys.exit`` captured BEFORE ``App(...)`` armed the wrapper
+#   (``from sys import exit`` / ``_saved = sys.exit``) — the call bypasses the
+#   wrapper;
+# * a third-party ``sys.excepthook`` installed AFTER arming that does not
+#   chain to the previous hook — it replaces our recorder outright.
+#
+# Covering the literal raise would require replacing ``builtins.SystemExit``
+# process-wide (rejected: making ``except SystemExit`` resolve to a subclass
+# silently stops it catching C-level real SystemExit raises — a worse,
+# less-debuggable breakage than these residuals). Consequence: such a run is
+# indistinguishable from a clean did-nothing exit and gets the redirect +
+# exit 2.
+_EXPLICIT_EXIT_OR_FAILURE = False
+
+
+def _arm_direct_run_exit_tracking() -> None:
+    """Wrap ``sys.excepthook`` and ``sys.exit`` to record a non-no-op exit.
+
+    Armed only for a directly-run ``python app.py`` (never under ``simulo
+    run``, the worker, or pytest imports). Both wrappers delegate to the
+    previous hook/function unchanged — behavior-neutral, record-only.
+    """
+    previous_excepthook = sys.excepthook
+
+    def _recording_excepthook(exc_type: Any, exc: Any, tb: Any) -> Any:
+        global _EXPLICIT_EXIT_OR_FAILURE
+        _EXPLICIT_EXIT_OR_FAILURE = True
+        return previous_excepthook(exc_type, exc, tb)
+
+    sys.excepthook = _recording_excepthook
+
+    previous_exit = sys.exit
+
+    # ``functools.wraps`` keeps the observable surface close to the builtin
+    # (``__name__``/``__qualname__``/``__module__``/``__doc__``, and
+    # ``__wrapped__`` pointing at the real ``sys.exit``); the positional-only
+    # marker keeps ``sys.exit(code=5)`` a ``TypeError`` exactly as on the
+    # builtin, so the wrapper never ACCEPTS a spelling the real function
+    # rejects.
+    @functools.wraps(previous_exit)
+    def _recording_exit(code: Any = None, /) -> Any:
+        global _EXPLICIT_EXIT_OR_FAILURE
+        _EXPLICIT_EXIT_OR_FAILURE = True
+        return previous_exit(code)
+
+    sys.exit = _recording_exit
+
+
+# The ``__main__`` MODULE OBJECT the guard was armed for. Host discrimination
+# is by module IDENTITY, not by ``__file__``: CPython's
+# ``PyRun_SimpleFileObject`` DELETES ``__main__.__file__`` after the script
+# body completes (measured — it is already None by atexit time even for a
+# genuine ``python app.py``), so a file-path comparison cannot tell a genuine
+# run from a host at exit. Identity can: ``runpy.run_path`` / IPython ``%run``
+# install a TEMPORARY module at ``sys.modules["__main__"]`` while the app body
+# (and therefore arming) runs, and restore the host's own ``__main__`` before
+# the host exits — so at atexit the identity no longer matches and the guard
+# stays silent. Under a genuine ``python app.py`` the module object is the
+# same one for the whole process life. (Holding a strong reference here also
+# keeps the comparison meaningful — the temp module cannot be recycled into a
+# false identity match.)
+_ARMED_MAIN_MODULE: Optional[Any] = None
+
+
+def _print_nothing_submitted_hint(app: "App") -> None:
+    """At interpreter exit, redirect a direct run that did NOTHING AT ALL.
+
+    A present ``@app.entrypoint`` redirects the ``__main__`` run to the CLI (and
+    exits 2) at DECORATION time, mid-import, long before this fires — that early
+    ``SystemExit`` is what stops a file ending in ``if __name__ == "__main__":
+    main()`` from ever reaching ``main()`` and submitting. An entrypoint-less
+    file has no decoration to intercept, so this at-exit guard covers it with
+    the SAME copy (:func:`_cli_redirect_message`, job-count-aware) and the SAME
+    exit code — one mistake, one message, either way.
+
+    It fires ONLY when every one of these holds:
+
+    * **this process's ``__main__`` is still the very module the guard was
+      armed in** (identity, not ``__file__`` — see ``_ARMED_MAIN_MODULE`` for
+      why a file comparison cannot work at atexit): a HOST that ran the file
+      under the ``__main__`` name (``runpy.run_path``, IPython's ``%run``,
+      embedding harnesses) swaps its own ``__main__`` back before it exits, so
+      at atexit the identity no longer matches and the guard stays silent — it
+      must never ``os._exit`` a host process that merely ran the app to
+      completion;
+    * jobs are declared and no entrypoint is registered;
+    * no submit was ATTEMPTED (``_ANY_SPAWN_ATTEMPTED`` — intent, not success:
+      a submit that died mid-flight may have left a cloud job running, and its
+      own traceback already explained the exit);
+    * no job body was invoked in-process (``_ANY_JOB_INVOKED`` — calling
+      ``work(x=7)`` locally is documented, deliberate work, not a no-op);
+    * the run neither crashed nor explicitly exited
+      (``_EXPLICIT_EXIT_OR_FAILURE`` — a real failure's exit code must never
+      be replaced by 2, and ``sys.exit(0)`` after local analysis is a choice,
+      not a mistake).
+
+    Exit code: raising ``SystemExit`` inside an ``atexit`` callback is IGNORED
+    by CPython ("Exception ignored in atexit callback"; the process still exits
+    0), so after printing the guard uses ``os._exit(2)``. That skips the rest
+    of interpreter finalization, so it first does the flushing finalization
+    would have done — ``logging.shutdown()`` (flushes+closes logging handlers;
+    a ``MemoryHandler``'s buffer is lost without it, and logging's own atexit
+    hook was registered at import time, BEFORE ours, so LIFO order means
+    ``os._exit`` would otherwise skip it) and explicit ``sys.stdout``/
+    ``sys.stderr`` flushes — inside a ``try`` whose ``finally`` holds the
+    ``os._exit(2)``: a user handler whose ``flush`` raises (or an
+    already-closed stream) must not downgrade the exit to 0 by blowing up
+    before the exit call.
+
+    Honest residuals: a user file handle left open at exit — referenced or
+    not — is not flushed here, and any atexit handler registered before
+    ``App(...)`` (i.e. at import time) is skipped. And "did nothing" means
+    "never touched a job or submit": a run that did real UNRELATED local work
+    (printing, writing files) without touching any job still gets the redirect
+    and exit 2 — that is the intended message for a jobs-declaring file, but
+    it IS a behavior change from the pre-0.15 exit-0 nudge for such scripts.
+    ``os._exit`` is nonetheless required: with a plain ``SystemExit`` here the
+    did-nothing case would exit 0, and the unified exit code is the contract.
+    """
+    if _ARMED_MAIN_MODULE is None or sys.modules.get("__main__") is not _ARMED_MAIN_MODULE:
+        return  # a host process ran the app; its exit is not ours to take
+    if app.entrypoint_names or not app.jobs or _ANY_SPAWN_ATTEMPTED or _ANY_JOB_INVOKED or _EXPLICIT_EXIT_OR_FAILURE:
+        return
+    import logging
+
+    print(_cli_redirect_message(job_names=list(app.jobs)), file=sys.stderr)
+    try:
+        logging.shutdown()
+        sys.stdout.flush()
+        sys.stderr.flush()
+    finally:
+        os._exit(2)
+
+
+def _arm_nothing_submitted_hint(app: "App") -> None:
+    """Register the at-exit no-op redirect once, for a directly-run script only.
+
+    Requires the constructing frame's globals to BE the current ``__main__``
+    module's ``__dict__`` — the extra identity check keeps a harness that
+    merely ``exec``s the file with ``{"__name__": "__main__", "__file__":
+    ...}`` globals (without installing a module) from ever arming the
+    ``os._exit`` path in ITS process. ``runpy``-style hosts DO pass this check
+    (they install a real temporary ``__main__``), and are excluded at exit by
+    the module-identity comparison instead (see ``_ARMED_MAIN_MODULE``).
+    """
+    global _NOTHING_SUBMITTED_HINT_ARMED, _ARMED_MAIN_MODULE
+    if _NOTHING_SUBMITTED_HINT_ARMED:
+        return
+    frame_globals = _direct_run_frame_globals()
+    if frame_globals is None:
+        return
+    main_module = sys.modules.get("__main__")
+    if main_module is None or frame_globals is not getattr(main_module, "__dict__", None):
+        return
+    _NOTHING_SUBMITTED_HINT_ARMED = True
+    _ARMED_MAIN_MODULE = main_module
+    _arm_direct_run_exit_tracking()
+    atexit.register(_print_nothing_submitted_hint, app)
+
+
+class App:
+    """The user-facing job container — declare it once, at module scope.
+
+    An app names your project and (optionally) mounts assets/volumes into
+    every job. Its jobs execute in a Simulo-curated runtime — the platform's
+    default runtime unless the app picks a
+    different Simulo runtime via ``runtime=``. Decorate functions with
+    :meth:`job` to make them submittable — ``simulo run app.py [--flags]``
+    submits the sole job with the flags mapped onto its own signature (``--job
+    NAME`` chooses among several). Optionally decorate one function with
+    :meth:`entrypoint` to orchestrate what ``simulo run app.py`` does instead::
+
+        import simulo
+
+        app = simulo.App("cartpole")
+
+        @app.job(system=simulo.SystemType.TIER_1)
+        def train(iterations: int = 1000):
+            ...
+
+        @app.entrypoint
+        def main(iterations: int = 1000):
+            train.spawn(iterations=iterations)
+
+    Args:
+        name: Non-empty app name, recorded in the package manifest.
+        runtime: Optionally pick a different Simulo runtime for this app's
+            jobs (``simulo.Runtime.from_registry("simulo/gpu-rl:2026.06")``).
+            Omitted means the platform default.
+        mounts: Optional mapping of mount name to :class:`simulo.Asset` /
+            :class:`simulo.Volume`, shared by every job of this app.
+
+    Raises:
+        ValueError: if ``name`` is empty or whitespace-only.
+    """
+
+    def __init__(
+        self,
+        name: str,
+        *,
+        runtime: Optional[object] = None,
+        mounts: Optional[Mapping[str, Mount]] = None,
+    ) -> None:
+        if not name or not name.strip():
+            raise ValueError("App name must be a non-empty string.")
+        self._name = name
+        self._runtime = runtime if runtime is not None else DEFAULT_RUNTIME
+        self._mounts: dict[str, Mount] = dict(mounts or {})
+        self._jobs: dict[str, JobSpec] = {}
+        self._entrypoints: dict[str, Callable[..., object]] = {}
+        registry.register(self)
+        # If this is a directly-run ``python app.py`` with jobs but no
+        # ``@app.entrypoint``, redirect at exit instead of silently no-op'ing
+        # (same copy + exit code as the decoration-time redirect).
+        _arm_nothing_submitted_hint(self)
+
+    @property
+    def name(self) -> str:
+        """The app's name, as passed at construction."""
+        return self._name
+
+    @property
+    def runtime(self) -> Any:
+        """The Simulo runtime this app's jobs execute in (the default unless picked)."""
+        return self._runtime
+
+    @property
+    def mounts(self) -> Mapping[str, Mount]:
+        """The assets/volumes mounted into every job of this app, by mount name (a copy)."""
+        return dict(self._mounts)
+
+    @property
+    def jobs(self) -> Mapping[str, JobSpec]:
+        """The registered job specs, by job name (a copy)."""
+        return dict(self._jobs)
+
+    @property
+    def entrypoint_names(self) -> tuple[str, ...]:
+        """Names of the functions registered with ``@app.entrypoint``."""
+        return tuple(self._entrypoints)
+
+    @overload
+    def job(self, fn: F) -> JobFunction: ...
+
+    @overload
+    def job(
+        self,
+        *,
+        callbacks: Sequence[JobCallbackProtocol] = ...,
+        resume: ResumePolicy = ...,
+        system: Optional[SystemType] = ...,
+        timeout: Optional[int] = ...,
+        retries: int = ...,
+        **extra: Any,
+    ) -> Callable[[F], JobFunction]: ...
+
+    def job(
+        self,
+        fn: Optional[F] = None,
+        *,
+        callbacks: Sequence[JobCallbackProtocol] = (),
+        resume: ResumePolicy = ResumePolicy.AUTO,
+        system: Optional[SystemType] = None,
+        timeout: Optional[int] = None,
+        retries: int = 0,
+        **extra: Any,
+    ) -> Union[JobFunction, Callable[[F], JobFunction]]:
+        """Register a function as a job of this app. Records metadata; never runs the body.
+
+        Usable bare (``@app.job``) or with options
+        (``@app.job(system=simulo.SystemType.TIER_1)``).
+        Returns a :class:`JobFunction` wrapping the original function — calling
+        it still runs the body in-process; ``.spawn()`` / ``.submit()`` submit it
+        to the platform instead.
+
+        Args:
+            fn: The function being decorated (bare-decorator form only — never
+                pass it alongside keyword options).
+            callbacks: Lifecycle callbacks from :mod:`simulo.callbacks` (e.g.
+                ``ResumableCheckpoint``), recorded into the package manifest and
+                honored at execution.
+            resume: How the job resumes from a discovered checkpoint
+                (:class:`~simulo.interfaces.platform.enums.ResumePolicy`,
+                default ``AUTO``).
+            system: The GPU system tier to request, as a
+                :class:`simulo.SystemType` member (e.g.
+                ``simulo.SystemType.TIER_1``), recorded in the job's resource
+                spec as ``resources["system"]`` (the tier's wire value, e.g.
+                ``"tier1"``). Validated HERE, at decoration time, against the
+                published catalog: a value that is not a ``SystemType`` member
+                (a raw string such as ``"tier1"`` included) raises
+                ``TypeError``, and a tier the platform cannot provision yet
+                raises ``ValueError``. ``simulo systems`` lists every tier and
+                which are available today. The selection is recorded on the
+                job; it does not yet choose hardware.
+            timeout: Wall-clock limit for one managed execution, in seconds
+                (a positive integer; validated HERE, at decoration time — a
+                zero, negative, or non-integer value raises ``ValueError``
+                immediately rather than failing later at run time on the
+                worker). Enforced by the platform worker: a job still
+                running at the limit is killed and reported ``failed`` with
+                reason ``timeout``. When omitted (``None``, the default),
+                the platform ceiling applies (1 hour by default); a declared
+                value larger than the ceiling is clamped down to it. The
+                ceiling is an operator knob on the worker
+                (``MAX_JOB_TIMEOUT_S=<seconds>``) for long unattended
+                training.
+            retries: Automatic re-attempts after a failure (default 0). All
+                attempts share one ``timeout`` budget.
+            **extra: Additional resource requests, recorded verbatim in the
+                job's resource spec. Three names are RESERVED and rejected —
+                ``produces``, ``consumes`` and ``gpu`` (see Raises below);
+                everything else passes through to the resource spec unchanged.
+
+        Raises:
+            ValueError: ``timeout`` is not ``None`` and is not a positive
+                integer. ``True`` and ``False`` are not accepted as timeouts.
+                Also raised when ``system`` names a tier the platform cannot
+                provision yet (``SYSTEM_SPECS[system].available`` is false).
+            TypeError: ``produces=`` or ``consumes=`` was passed. Outputs are
+                not declared on the decorator. Callbacks such as
+                ``ResumableCheckpoint`` already declare their supported
+                outputs. Return small JSON values from the job, or use a named
+                volume for files another job needs. ``consumes=`` is reserved;
+                continue from a checkpoint with
+                ``simulo run --from <job>[:latest|:best]`` instead.
+                Also raised for ``gpu=`` (the free-text GPU request this
+                parameter replaced; it would otherwise fall through
+                ``**extra`` into the resource spec unvalidated) and for a
+                ``system`` value that is not a :class:`simulo.SystemType`
+                member.
+        """
+        if timeout is not None and (isinstance(timeout, bool) or not isinstance(timeout, int) or timeout < 1):
+            raise ValueError(
+                "@app.job(timeout=...) must be a positive integer (seconds), or omitted/None to "
+                f"use the platform ceiling — got {timeout!r}."
+            )
+        if "produces" in extra:
+            raise TypeError(
+                "@app.job(produces=...) is not supported. Callbacks such as "
+                "ResumableCheckpoint and DebugOnAnomaly already declare their supported outputs. "
+                "Return small JSON values from the job, or use a named Volume for files another "
+                "job needs. Remove produces=."
+            )
+        if "consumes" in extra:
+            raise TypeError(
+                "@app.job(consumes=...) is reserved for a future input declaration and does nothing "
+                "today. To chain jobs, run with `simulo run --from <job>[:latest|:best]`. Remove "
+                "consumes=."
+            )
+        # ``gpu`` was a real named parameter until the system-tier catalog
+        # replaced it (#1362). Removing it from the signature alone does NOT
+        # reject ``gpu="L4"``: CPython routes the unknown keyword into
+        # ``**extra`` and it would land in the resource spec exactly as before,
+        # unvalidated. This guard is what makes the rename a rejection.
+        if "gpu" in extra:
+            raise TypeError(
+                "@app.job(gpu=...) is no longer supported. Request a GPU system tier instead: "
+                "@app.job(system=simulo.SystemType.TIER_1). Run `simulo systems` to list the "
+                "tiers and which are available today. Remove gpu=."
+            )
+        if system is not None:
+            # Static lookups against the published catalog — no fleet state
+            # is consulted. A raw string is refused even when it spells a
+            # valid wire value, so the one accepted spelling is the enum.
+            if not isinstance(system, SystemType):
+                raise TypeError(
+                    "@app.job(system=...) must be a simulo.SystemType member, e.g. "
+                    f"system=simulo.SystemType.TIER_1; got {system!r}. Run `simulo systems` to "
+                    "list the tiers."
+                )
+            spec = SYSTEM_SPECS[system]
+            if not spec.available:
+                available = ", ".join(
+                    f"SystemType.{tier.name} ({entry.gpu_model})"
+                    for tier, entry in SYSTEM_SPECS.items()
+                    if entry.available
+                )
+                raise ValueError(
+                    f"@app.job(system=SystemType.{system.name}) ({spec.gpu_model}) is not available on "
+                    f"the platform yet. Available today: {available}. Run `simulo systems` for the "
+                    "full catalog."
+                )
+
+        def decorate(func: F) -> JobFunction:
+            resources: dict[str, Any] = {}
+            if system is not None:
+                resources["system"] = system.value
+            resources.update(extra)
+            spec = JobSpec(
+                name=func.__name__,
+                module=func.__module__,
+                qualname=func.__qualname__,
+                fn=func,
+                resources=resources,
+                timeout=timeout,
+                retries=retries,
+                resume=resume,
+                callbacks=tuple(callbacks),
+                mounts=dict(self._mounts),
+            )
+            self._jobs[spec.name] = spec
+            return JobFunction(self, spec)
+
+        if fn is not None:
+            return decorate(fn)
+        return decorate
+
+    def entrypoint(self, fn: F) -> F:
+        """Register an entrypoint; redirect to the CLI if the file is ``python``-ed.
+
+        Returns ``fn`` unchanged. ``simulo run app.py [--flags]`` — the canonical
+        (and only) submit command — imports the file as a NON-``__main__`` module
+        and invokes the registered entrypoint explicitly (mapping ``--flag value``
+        onto the entrypoint's parameters). An entrypoint is OPTIONAL: without
+        one, ``simulo run`` maps the flags onto the job's own signature
+        (``--job NAME`` chooses among several); register one only to
+        orchestrate multiple submits yourself.
+
+        When the decorator is applied from a directly-run ``python app.py`` —
+        detected by frame-walking to the first frame outside this module and
+        checking that its ``__name__ == "__main__"`` with a real ``__file__`` —
+        nothing is submitted: the exact equivalent ``simulo run`` command (rebuilt
+        verbatim from ``sys.argv``) is printed to stderr and the process exits 2.
+        The ``SystemExit`` fires at DECORATION time, mid-import, so a file ending
+        in ``if __name__ == "__main__": main()`` never reaches ``main()`` — an
+        at-exit-only guard would let ``main()`` run and, with saved credentials,
+        actually submit a cloud job. Gating on the *calling frame* rather than
+        ``fn.__module__`` means the redirect fires even when the entrypoint
+        function is imported from another module. TYPED Jupyter/REPL cells
+        (``__name__ == "__main__"`` but no ``__file__``) never trigger it;
+        hosts that run the file under the ``__main__`` name with a real
+        ``__file__`` — ``runpy.run_path``, IPython's ``%run`` — DO see the
+        redirect, and that is safe by mechanism: this path raises
+        ``SystemExit`` (which such hosts catch and display) rather than
+        hard-exiting the host process.
+        """
+        self._entrypoints[fn.__name__] = fn
+        if _is_direct_script_run():
+            print(_cli_redirect_message(), file=sys.stderr)
+            raise SystemExit(2)
+        return fn
+
+    def resolve_job(self, name: str) -> Callable[..., object]:
+        """Return the underlying body for a registered job.
+
+        Used by the backend runner to execute the job — and a PUBLIC path for
+        running a job body in-process (``app.resolve_job("work")(x=7)``), so it
+        counts as deliberate work for the at-exit guard exactly like calling
+        the :class:`JobFunction` wrapper does.
+        """
+        global _ANY_JOB_INVOKED
+        _ANY_JOB_INVOKED = True
+        return self._jobs[name].fn
+
+    def resolve_job_function(self, name: str) -> "JobFunction":
+        """Return a :class:`JobFunction` for a registered job (so it can ``spawn``).
+
+        Used by ``simulo run`` to submit a file's sole ``@app.job`` when it
+        declares no ``@app.entrypoint``.
+        """
+        return JobFunction(self, self._jobs[name])
+
+    def resolve_entrypoint(self, name: str) -> Callable[..., object]:
+        """Return a registered ``@app.entrypoint`` callable by name.
+
+        Used by ``simulo run`` to invoke the entrypoint in-process; the
+        entrypoint's own ``spawn()``/``submit()`` calls then write the package.
+        """
+        return self._entrypoints[name]
+
+    def __getattr__(self, name: str) -> Any:
+        removed = _REMOVED_APP_ATTRS.get(name)
+        if removed is not None:
+            raise AttributeError(removed)
+        raise AttributeError(f"{type(self).__name__!r} object has no attribute {name!r}")
+
+
+# The pre-0.15 names, removed outright (full replacement — no alias, no
+# deprecation period). ``App.__getattr__`` fires only when normal lookup
+# fails, so this costs nothing on the live surface; it exists so a user
+# upgrading from simulo 0.14.x gets an actionable error naming the replacement
+# instead of a bare "'App' object has no attribute 'local_entrypoint'".
+# Module-level and never mutated (not a class attribute — keeps it out of the
+# class namespace and away from mutable-class-attribute pitfalls).
+_REMOVED_APP_ATTRS: Mapping[str, str] = {
+    "local_entrypoint": (
+        "@app.local_entrypoint was replaced by @app.entrypoint in simulo 0.15 "
+        "— rename the decorator; its behavior is unchanged."
+    ),
+    "local_entrypoint_names": "App.local_entrypoint_names was renamed to App.entrypoint_names in simulo 0.15.",
+    "resolve_local_entrypoint": "App.resolve_local_entrypoint was renamed to App.resolve_entrypoint in simulo 0.15.",
+}