simulo 0.26.0__py3-none-any.whl

simulo/_client/packaging.py

@@ -0,0 +1,445 @@
+"""Content-addressed source packaging (stdlib only).
+
+``package`` walks a project root, filters out heavy / generated files, hashes the
+surviving tree into a stable source digest, and writes a bundle whose directory is
+named by a short, filesystem-safe form of the *submission's* package id (see
+:func:`bundle_dir_name`)::
+
+    <out>/sha256-<12 hex>/
+        source/                 # filtered copy of the project tree
+        simulo.manifest.json    # the v1 manifest (source_digest + FULL package_id stamped in)
+
+Two identities are computed:
+
+* ``source_digest`` — order-independent over the filtered tree (files are sorted
+  before hashing) and dependent on each file's relative path and its bytes, so
+  renames and content edits both change it. This is the *source-only* hash, kept
+  in the manifest for reproducibility / source caching.
+* ``package_id`` — ``sha256(source_digest + "\\0" + job_name + "\\0" +
+  canonical_json(args))``. The bundle directory is named by a SHORT,
+  filesystem-safe, NON-invertible form of it (:func:`bundle_dir_name` — ``:``
+  is reserved on Windows, and a full 64-hex name is itself too long to nest
+  safely under Windows' 260-char ``MAX_PATH``; see that function's docstring).
+  Two submits of the same source with a different job or args yield a
+  different ``package_id`` (logically a distinct package), so one submission
+  never clobbers another's recorded ``args`` — the
+  "submit = immutable job" model. Submitting the *same* (source, job, args)
+  yields the *same* id (idempotent / cached) — but because the on-disk name is
+  a short, non-injective digest prefix, every consumer of a possibly-cached
+  bundle directory MUST re-verify the FULL id against the bundle's manifest
+  (:func:`read_bundle_package_id`) before trusting it as a hit; never trust
+  the directory name alone as proof of identity.
+
+An optional deterministic tarball can be emitted alongside — named from the
+FULL id (see :func:`tar_path_for`), so it has no truncation-collision risk.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import shutil
+import tarfile
+from dataclasses import replace
+from fnmatch import fnmatch
+from hashlib import sha256
+from pathlib import Path, PurePosixPath
+from typing import Any, Optional
+
+from simulo.interfaces.platform.manifest import Manifest
+
+MANIFEST_FILENAME = "simulo.manifest.json"
+
+# Directory names pruned wholesale (never descended into).
+_DEFAULT_DIR_EXCLUDES = frozenset(
+    {"assets", "datasets", "checkpoints", "outputs", "logs", ".git", "__pycache__", ".simulo"}
+)
+
+# Glob patterns matched against each file's basename.
+_DEFAULT_GLOB_EXCLUDES = (
+    "*.usd",
+    "*.usda",
+    "*.usdc",
+    "*.pt",
+    "*.pth",
+    "*.onnx",
+    "*.mcap",
+    "*.mp4",
+    "*.pyc",
+)
+
+_SIMULOIGNORE = ".simuloignore"
+
+
+def _load_ignore_patterns(root: Path) -> list[str]:
+    """Read ``.simuloignore`` (gitignore-style) from the project root, if present."""
+    ignore_file = root / _SIMULOIGNORE
+    if not ignore_file.is_file():
+        return []
+    patterns: list[str] = []
+    for raw in ignore_file.read_text(encoding="utf-8").splitlines():
+        line = raw.strip()
+        if not line or line.startswith("#"):
+            continue
+        patterns.append(line)
+    return patterns
+
+
+def _matches_ignore(rel: PurePosixPath, pattern: str) -> bool:
+    """Match one gitignore-style pattern against a POSIX relative path."""
+    rel_str = str(rel)
+    if pattern.endswith("/"):
+        directory = pattern.rstrip("/")
+        return any(part == directory for part in rel.parts) or fnmatch(rel_str, f"{directory}/*")
+    if "/" in pattern:
+        return fnmatch(rel_str, pattern)
+    return fnmatch(rel.name, pattern) or any(fnmatch(part, pattern) for part in rel.parts)
+
+
+def _is_excluded(rel: PurePosixPath, ignore_patterns: list[str]) -> bool:
+    if any(part in _DEFAULT_DIR_EXCLUDES for part in rel.parts):
+        return True
+    if any(fnmatch(rel.name, glob) for glob in _DEFAULT_GLOB_EXCLUDES):
+        return True
+    return any(_matches_ignore(rel, pattern) for pattern in ignore_patterns)
+
+
+def _collect_files(root: Path, ignore_patterns: list[str]) -> list[tuple[PurePosixPath, Path]]:
+    """Return ``(relpath, abspath)`` for every non-excluded file under ``root``.
+
+    Symlinks (files and directories) are skipped entirely: a symlinked file whose
+    target lies outside ``root`` (e.g. ``creds -> ~/.aws/credentials``) would
+    otherwise pull out-of-tree bytes into the bundle and its digest — an
+    exfiltration vector once bundles are uploaded. ``os.walk`` already does not
+    follow symlinked directories (``followlinks=False``); we additionally prune
+    them from ``dirnames`` so they never appear as candidates.
+    """
+    collected: list[tuple[PurePosixPath, Path]] = []
+    for dirpath, dirnames, filenames in os.walk(root):
+        here = Path(dirpath)
+        # Prune excluded and symlinked directories in place so heavy / out-of-tree
+        # trees are never read.
+        kept: list[str] = []
+        for dirname in dirnames:
+            if (here / dirname).is_symlink():
+                continue
+            rel_dir = PurePosixPath((here / dirname).relative_to(root).as_posix())
+            if not _is_excluded(rel_dir, ignore_patterns):
+                kept.append(dirname)
+        dirnames[:] = kept
+        for filename in filenames:
+            abspath = here / filename
+            # Never include symlinked files — their target may lie outside ``root``.
+            if abspath.is_symlink():
+                continue
+            rel = PurePosixPath(abspath.relative_to(root).as_posix())
+            if rel.name == _SIMULOIGNORE:
+                continue
+            if _is_excluded(rel, ignore_patterns):
+                continue
+            collected.append((rel, abspath))
+    return collected
+
+
+def compute_digest(files: list[tuple[PurePosixPath, Path]]) -> str:
+    """Compute the order-independent ``sha256:`` digest for a file set."""
+    per_file: dict[str, str] = {}
+    for rel, abspath in files:
+        rel_str = str(rel)
+        data = abspath.read_bytes()
+        per_file[rel_str] = sha256(rel_str.encode("utf-8") + b"\0" + data).hexdigest()
+    manifest_lines = "\n".join(f"{rel}:{digest}" for rel, digest in sorted(per_file.items()))
+    return "sha256:" + sha256(manifest_lines.encode("utf-8")).hexdigest()
+
+
+def canonical_args(args: Optional[dict[str, Any]]) -> str:
+    """Canonical JSON for an args dict: sorted keys, no whitespace.
+
+    The same serialisation feeds both ``compute_package_id`` and the in-process
+    bundle memo key, so two submissions with equal args map to the same string
+    (and therefore the same package id / cache slot).
+    """
+    return json.dumps(args or {}, sort_keys=True, separators=(",", ":"))
+
+
+def compute_package_id(source_digest: str, job_name: str, args: Optional[dict[str, Any]]) -> str:
+    """Compute the submission's ``sha256:`` package id.
+
+    Identity is the *submission* — source + job + args — not the source alone, so
+    two submits of the same source with different job/args produce different ids
+    (distinct package dirs) and never clobber each other's manifest. Idempotent:
+    the same (source, job, args) yields the same id.
+    """
+    payload = (
+        source_digest.encode("utf-8") + b"\0" + job_name.encode("utf-8") + b"\0" + canonical_args(args).encode("utf-8")
+    )
+    return "sha256:" + sha256(payload).hexdigest()
+
+
+#: The one legal shape of a package id (``compute_package_id``): the constant
+#: ``sha256:`` prefix + exactly 64 LOWERCASE hex chars (``hexdigest()`` output).
+_PACKAGE_ID_RE = re.compile(r"sha256:[0-9a-f]{64}")
+
+#: Number of leading hex characters of the digest kept in the LOCAL bundle
+#: directory name (the Docker/git short-hash convention: enough entropy to
+#: make an accidental collision practically impossible, while keeping the
+#: bundle path short). A full 64-hex name (``sha256-<64 hex>`` = 71 chars)
+#: still blows Windows' 260-char ``MAX_PATH`` for a realistically nested
+#: project under a normal-length user path — the Windows validation rig
+#: (PR #364) measured a deepest path of 283 chars (>= 260) at a 133-char
+#: root even AFTER the colon fix, and put the safe budget for this segment
+#: at roughly <=35 chars. ``"sha256-" + 12 hex`` is 19 chars, well inside
+#: that budget with headroom for deeper project trees.
+#:
+#: 12 hex chars = 48 bits of entropy (2**48 ≈ 2.8e14) — an accidental
+#: same-prefix collision between two real submissions is not going to
+#: happen in practice, but this code does NOT rely on that probability
+#: argument alone: every read of a cached bundle directory verifies the
+#: manifest's full ``package_id`` against the id it was asked for and
+#: rebuilds on any mismatch (see ``read_bundle_package_id`` and
+#: ``bundle.ensure_bundle``'s cache-hit check) — so even a genuine
+#: collision degrades to a redundant rebuild, never a silently wrong
+#: package (the sha256-storage-key collision class of bug the cloud-submit
+#: wave already shipped once — see context/decisions/README.md).
+_BUNDLE_ID_PREFIX_LEN = 12
+
+#: Safety ceiling asserted by the MAX_PATH regression test — see
+#: ``test_packaging.py::test_bundle_dir_name_stays_under_the_max_path_budget``.
+#: Derived from the Windows rig's "roughly <=35 chars" finding (PR #364);
+#: kept as an explicit constant so a future change that lengthens the name
+#: fails a test instead of silently reintroducing WinError 123 / MAX_PATH.
+MAX_BUNDLE_DIR_NAME_LEN = 35
+
+
+def bundle_dir_name(package_id: str) -> str:
+    """The LOCAL filesystem directory name for a package id.
+
+    ``package_id`` (``sha256:<64 hex>``) is the wire/logical identity — it goes
+    into the manifest, the submit body, and the server's storage key, and must
+    stay byte-identical everywhere off-disk. The local name differs from it in
+    two ways, both required for Windows (see ``_BUNDLE_ID_PREFIX_LEN`` for the
+    second one and its rationale):
+
+    1. ``:`` is a reserved character on Windows (the drive separator: ``mkdir``
+       raises ``WinError 123``), so the prefix is rewritten ``sha256:`` ->
+       ``sha256-``.
+    2. Only the first ``_BUNDLE_ID_PREFIX_LEN`` hex characters are kept — a
+       full 64-hex name is itself long enough to blow Windows' 260-char
+       ``MAX_PATH`` once nested under a realistic project tree.
+
+    Applied on every platform (not just Windows), so a project directory is
+    portable across OSes and Linux tests exercise exactly the naming that
+    ships.
+
+    **Deliberately NOT injective** — a 12-hex prefix can theoretically collide
+    between two distinct ids. This is a probability trade against Windows
+    path-length safety, not a bug: nothing in this module trusts the
+    directory name alone as proof of identity. Every read path re-verifies
+    against the bundle's manifest (``read_bundle_package_id``) and treats a
+    mismatch as a cache miss, not a hit — see ``bundle.ensure_bundle``.
+    """
+    if not _PACKAGE_ID_RE.fullmatch(package_id):
+        raise ValueError(f"Unexpected package id shape: {package_id!r} (expected 'sha256:<64 lowercase hex>').")
+    return "sha256-" + package_id[len("sha256:") : len("sha256:") + _BUNDLE_ID_PREFIX_LEN]
+
+
+def read_bundle_package_id(bundle_dir: Path) -> Optional[str]:
+    """Read the ``package_id`` recorded in *bundle_dir*'s manifest, if present.
+
+    Every bundle this client writes stamps ``package_id`` into its manifest —
+    ``package()`` always sets it (see the two branches near the end of this
+    module), regardless of whether the caller supplied its own ``Manifest``.
+    This is the SAFE way to recover a bundle's logical id: the local directory
+    name is short and NOT invertible by design (see ``bundle_dir_name``), so
+    nothing may ever guess an id back from a directory name.
+
+    Returns ``None`` if the manifest is missing, unreadable, or carries no id
+    (a bundle written by a client older than this fix, or a manually tampered
+    / foreign directory) — callers MUST treat that as "unknown identity" and
+    fail loudly or rebuild, never guess.
+    """
+    manifest_path = bundle_dir / MANIFEST_FILENAME
+    if not manifest_path.is_file():
+        return None
+    try:
+        data = json.loads(manifest_path.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return None
+    package_id = data.get("package_id") if isinstance(data, dict) else None
+    return str(package_id) if package_id else None
+
+
+def _write_deterministic_tar(bundle_dir: Path, tar_path: Path) -> None:
+    """Write a reproducible tarball of ``bundle_dir`` (sorted, zeroed metadata)."""
+    members: list[tuple[str, Path]] = []
+    for path in sorted(bundle_dir.rglob("*")):
+        if path.is_file():
+            arcname = path.relative_to(bundle_dir).as_posix()
+            members.append((arcname, path))
+
+    def _reset(info: tarfile.TarInfo) -> tarfile.TarInfo:
+        info.mtime = 0
+        info.uid = info.gid = 0
+        info.uname = info.gname = ""
+        info.mode = 0o644
+        return info
+
+    with tarfile.open(tar_path, "w") as tar:
+        for arcname, path in sorted(members):
+            tar.add(path, arcname=arcname, filter=_reset)
+
+
+def tar_path_for(bundle_dir: Path) -> Path:
+    """The deterministic tar path a package's bundle directory writes to.
+
+    Named from the bundle's FULL ``package_id`` (via its manifest), not the
+    short, possibly-colliding ``bundle_dir.name`` — deliberately: unlike the
+    bundle directory itself (whose nested depth is the Windows MAX_PATH
+    concern ``bundle_dir_name`` trades against), this tar is a single sibling
+    FILE next to it, so there is no path-length reason to truncate its name,
+    and a full-length name means two DIFFERENT package ids can never produce
+    the same tar path — no truncation collision, no verify-on-read needed for
+    this one. Colon-sanitized the same way ``bundle_dir_name`` is (``:`` is
+    still illegal in a Windows filename).
+
+    Raises :class:`RuntimeError` if *bundle_dir* has no id in its manifest, OR
+    if the id present is not shape-valid: every bundle this client writes has a real
+    ``sha256:<64 hex>`` id (see ``read_bundle_package_id``), so a missing OR
+    malformed id means a foreign, corrupted, or tampered directory — and
+    slicing a garbage id into a path is exactly the failure mode this module
+    refuses to have. Without the shape check, a manifest carrying e.g.
+    ``"sha256:a:b"`` would reintroduce a colon into the tar path (the very
+    bug this PR exists to kill), and one carrying a too-short id could
+    collapse to a shared/degenerate path that ``ensure_tar``'s
+    reuse-without-verify would then serve for a DIFFERENT bundle.
+    """
+    package_id = read_bundle_package_id(bundle_dir)
+    if package_id is None or not _PACKAGE_ID_RE.fullmatch(package_id):
+        raise RuntimeError(
+            f"Cannot determine a tar filename for {bundle_dir}: its manifest has no valid package_id "
+            "(the bundle predates this client version, or its manifest is missing/corrupted). "
+            "Re-run `simulo run` (or call .spawn() again) to rebuild it."
+        )
+    full_name = "sha256-" + package_id[len("sha256:") :]
+    return bundle_dir.parent / f"{full_name}.tar"
+
+
+def ensure_tar(bundle_dir: Path) -> Path:
+    """Return the deterministic tar for *bundle_dir*, writing it if missing.
+
+    Cloud submit uploads exactly the bytes this produces (``upload_archive``);
+    written once per package id, then reused — a bundle directory's contents
+    are immutable once ``package()`` writes it (memoised by ``ensure_bundle``).
+    Safe to reuse an existing tar file without re-verifying its NAME:
+    ``tar_path_for`` already ties the tar's own filename to the FULL package
+    id, so an existing tar at that exact path can only have been written for
+    this exact id (see ``tar_path_for``'s docstring).
+
+    Written to a per-process temp name first, then moved into place with
+    ``os.replace`` (atomic on both POSIX and Windows) — never straight to
+    *tar_path* (a deliberate hardening). This design leans on "a file already
+    existing at this exact path == the correct bytes for this exact id"; a
+    crash or interruption mid-write with an in-place ``tarfile.open(path,
+    "w")`` would otherwise leave a truncated tar sitting at that same
+    "reuse it" path forever, silently uploaded on every future call. Any
+    write failure removes the temp file rather than leaving it stranded.
+    """
+    tar_path = tar_path_for(bundle_dir)
+    if not tar_path.is_file():
+        tmp_path = tar_path.with_name(f"{tar_path.name}.tmp-{os.getpid()}")
+        try:
+            _write_deterministic_tar(bundle_dir, tmp_path)
+            os.replace(tmp_path, tar_path)
+        except BaseException:
+            tmp_path.unlink(missing_ok=True)
+            raise
+    return tar_path
+
+
+def package(
+    app_file: "str | Path",
+    *,
+    out_dir: "str | Path",
+    project_root: Optional["str | Path"] = None,
+    tar: bool = False,
+    manifest: Optional[Manifest] = None,
+    job_name: str = "",
+) -> Path:
+    """Package a project tree into a per-submission bundle.
+
+    ``app_file`` is the entrypoint; ``project_root`` defaults to its directory.
+    The bundle directory is named by the *submission's* ``package_id`` —
+    ``sha256(source_digest + job_name + canonical_json(args))`` — so two submits of
+    the same source with a different job or args land in distinct dirs and never
+    clobber one another. ``job_name`` names the submitted job; ``args`` are taken
+    from ``manifest.args`` (the invocation the manifest already records). A
+    ``manifest`` (built by the CLI from discovered app metadata) is stamped with
+    both ``source_digest`` and ``package_id`` and written into the bundle; if
+    omitted, a minimal source-only manifest is written. Returns the bundle
+    directory.
+
+    The ``source/`` tree is written under each submission dir; duplicating source
+    across submissions of the same source is acceptable for v1 — a future
+    optimisation can dedupe by ``source_digest``.
+    """
+    resolved_app = Path(app_file).resolve()
+    root = Path(project_root).resolve() if project_root is not None else resolved_app.parent
+    out = Path(out_dir)
+
+    if not resolved_app.is_file():
+        raise FileNotFoundError(f"App file not found: {resolved_app}")
+    if not str(resolved_app).startswith(str(root) + os.sep) and resolved_app.parent != root:
+        raise ValueError(f"App file {resolved_app} is not inside project root {root}.")
+
+    ignore_patterns = _load_ignore_patterns(root)
+    files = _collect_files(root, ignore_patterns)
+    digest = compute_digest(files)
+
+    # Identity is the submission (source + job + args), not the source alone. Args
+    # come from the manifest the caller already built with the submitted kwargs.
+    args = dict(manifest.args) if manifest is not None else {}
+    package_id = compute_package_id(digest, job_name, args)
+
+    # The directory name is the id's filesystem-safe form (never the raw id —
+    # ``:`` is illegal on Windows); the manifest/wire keep the raw ``sha256:`` id.
+    bundle_dir = out / bundle_dir_name(package_id)
+    source_dir = bundle_dir / "source"
+    if bundle_dir.exists():
+        shutil.rmtree(bundle_dir)
+    source_dir.mkdir(parents=True, exist_ok=True)
+
+    for rel, abspath in files:
+        dest = source_dir / Path(*rel.parts)
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        # ``follow_symlinks=False`` is defensive: ``_collect_files`` already drops
+        # symlinks, so ``abspath`` is a regular file here.
+        shutil.copy2(abspath, dest, follow_symlinks=False)
+
+    if manifest is None:
+        manifest = Manifest(
+            source_digest=digest,
+            runtime_id="",
+            package_id=package_id,
+            entrypoint={
+                "file": resolved_app.relative_to(root).as_posix(),
+                "module": ".".join(resolved_app.relative_to(root).with_suffix("").parts),
+                # Pre-0.15 wire spelling kept on purpose — renaming it moves
+                # archive_sha256 under a fixed package_id, the server's 409
+                # package_conflict condition. See build_manifest in bundle.py.
+                "local_entrypoint": None,
+            },
+        )
+    else:
+        manifest = replace(manifest, source_digest=digest, package_id=package_id)
+
+    (bundle_dir / MANIFEST_FILENAME).write_text(manifest.to_json(), encoding="utf-8")
+
+    if tar:
+        # Routed through ``ensure_tar`` (not a direct ``_write_deterministic_tar``
+        # call) so this gets the same atomic temp-name + ``os.replace`` write as
+        # every other tar-writing path — a crash mid-write here must never leave
+        # a truncated tar sitting at the "already written, reuse it" path.
+        ensure_tar(bundle_dir)
+
+    return bundle_dir

simulo/_client/preflight_api.py

@@ -0,0 +1,186 @@
+"""HTTP client for the pre-submit "will this work?" check.
+
+Implements the client half of ``POST /v1/packages/preflight``
+(:data:`simulo.interfaces.platform.manifest.PACKAGE_PREFLIGHT_ROUTE`): builds
+the bounded request the server understands, POSTs it, and turns the response
+into a small, render-agnostic :class:`PreflightOutcome` — ``simulo prepare``
+(and, later, ``simulo run``'s preflight phase) decide what to do with it.
+
+## Fail-open is the whole point (a failure class that must not be repeated)
+
+Anything that is not a well-formed findings response — a 404 from a control
+plane that predates this route, any 5xx, a connection failure, a transport-
+level timeout, a malformed body — must never abort the caller. This module
+therefore NEVER raises for those cases: :meth:`PreflightApiClient.evaluate`
+always returns a :class:`PreflightOutcome`, either a genuine
+``findings=(...)`` answer or ``skipped=True`` with a human-readable reason
+for the CLI to print verbatim before proceeding. Only a genuinely
+well-formed 200 response can carry a ``blocking`` finding.
+
+The final ``except Exception`` in :meth:`PreflightApiClient.evaluate` is
+deliberate, not sloppy: measured against this codebase's own ``http.py``,
+``urllib.request.urlopen``'s connect/send-phase failures surface as
+``urllib.error.URLError`` (wrapped here as the thin client's ``HttpUnavailable``),
+but a peer that accepts the connection and then simply never answers (this
+PR's own connection-timeout test reproduces it) times out INSIDE
+``http.client.HTTPConnection.getresponse()`` — a call site ``http.py``'s
+existing ``except urllib.error.URLError`` does not wrap, so a bare
+``socket.timeout``/``TimeoutError`` can reach this call site unwrapped. The
+broad catch is the safety net for exactly that gap (and for anything else
+unanticipated) — preflight must not add a second instance of this failure class to the
+submit path.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from typing import Any, Optional
+
+from simulo._client import http
+from simulo.interfaces.platform.manifest import (
+    FINDING_CLASSIFICATIONS,
+    PACKAGE_PREFLIGHT_ROUTE,
+    Manifest,
+    PreflightFinding,
+)
+
+#: Every outbound call has an explicit timeout (NFR — no open-ended waits).
+#: Module-level so tests can shrink it to force a real client-side timeout.
+_PREFLIGHT_TIMEOUT_S = 10.0
+
+
+@dataclass(frozen=True)
+class PreflightOutcome:
+    """What ``simulo prepare``/``simulo run`` learned from one preflight call.
+
+    ``skipped=True`` means the server never produced a well-formed findings
+    answer (see the module docstring's fail-open contract) — ``findings`` is
+    then always empty and ``notice`` is the human-readable reason the CLI
+    prints before proceeding as if preflight had not run at all.
+    ``skipped=False`` means ``findings`` is the platform's real answer
+    (possibly empty — "nothing to report", a genuine pass).
+    """
+
+    skipped: bool
+    notice: Optional[str] = None
+    findings: tuple[PreflightFinding, ...] = field(default_factory=tuple)
+
+
+def _manifest_projection(manifest: Manifest) -> dict[str, Any]:
+    """The bounded projection of *manifest* the server's request schema binds
+    (``runtime_id``, ``runtime_env``, ``jobs``, ``pip_dependencies``,
+    ``manifest_version`` — see ``simulo_control_plane.preflight.schemas.
+    PreflightManifest``; every other field is ignored server-side).
+
+    Round-tripped through :meth:`Manifest.to_json` rather than hand-built
+    from the dataclass fields directly: that serialisation is already proven
+    JSON-safe (every real submit depends on it — ``jobs`` entries carry
+    values from a live ``App``'s declared job specs, not plain literals), so
+    reusing it here can never diverge from what a real submit would produce
+    for these same fields.
+    """
+    full = json.loads(manifest.to_json())
+    return {
+        "runtime_id": full["runtime_id"],
+        "runtime_env": full["runtime_env"],
+        "jobs": full["jobs"],
+        "pip_dependencies": full["pip_dependencies"],
+        "manifest_version": full["manifest_version"],
+    }
+
+
+def _notice_for_http_error(exc: http.HttpHTTPError) -> str:
+    """Human copy for a structured non-2xx preflight response.
+
+    404 (older control plane) and 5xx get dedicated copy; everything else
+    (a 401 from an unauthenticated caller, a 422, a 429, ...) still degrades
+    to a generic skip — the fail-open contract is "anything short of a
+    well-formed findings response", not an enumerated list of statuses.
+    """
+    if exc.status == 404:
+        return "this control plane doesn't support pre-submit checks yet (older server) — skipping"
+    if exc.status == 401:
+        return "not logged in — run `simulo login` to enable pre-submit checks; skipping for now"
+    if exc.status >= 500:
+        return f"pre-submit checks are temporarily unavailable (server error {exc.status}) — skipping"
+    return f"pre-submit checks could not run ({exc}) — skipping"
+
+
+def _parse_preflight_response(payload: Any) -> PreflightOutcome:
+    """Parse a 200 body into findings, or skip if it isn't well-formed.
+
+    A malformed body (wrong shape, an unrecognised ``classification``, ...)
+    is exactly as fail-open as a 5xx — see the module docstring — never a
+    crash and never treated as "no findings" (which would look like a pass).
+    """
+    if not isinstance(payload, dict) or not isinstance(payload.get("findings"), list):
+        return PreflightOutcome(skipped=True, notice="the preflight response was malformed — skipping")
+    findings: list[PreflightFinding] = []
+    for raw in payload["findings"]:
+        if not isinstance(raw, dict):
+            return PreflightOutcome(skipped=True, notice="the preflight response was malformed — skipping")
+        code = raw.get("code")
+        classification = raw.get("classification")
+        details = raw.get("details")
+        if not isinstance(code, str) or classification not in FINDING_CLASSIFICATIONS or not isinstance(details, dict):
+            return PreflightOutcome(skipped=True, notice="the preflight response was malformed — skipping")
+        findings.append(PreflightFinding(code=code, classification=classification, details=details))
+    return PreflightOutcome(skipped=False, findings=tuple(findings))
+
+
+class PreflightApiClient:
+    """Client for ``POST /v1/packages/preflight`` — see the module docstring."""
+
+    def __init__(self, base_url: str, *, token: Optional[str] = None) -> None:
+        self._base_url = base_url.rstrip("/")
+        self._token = token
+
+    def evaluate(
+        self,
+        manifest: Manifest,
+        *,
+        job_name: Optional[str] = None,
+        archive_size: Optional[int] = None,
+        seed_from_job_id: Optional[str] = None,
+        viewstream: bool = False,
+        assets: Optional[list[dict[str, str]]] = None,
+    ) -> PreflightOutcome:
+        """Ask the platform whether this submission tuple would work.
+
+        ``job_name``/``archive_size`` omitted (``simulo prepare``, which
+        checks the whole app, not one submitted job) versus both given
+        (``simulo run``'s preflight phase, PR-A6). Never raises: see the
+        module docstring's fail-open contract.
+        """
+        body: dict[str, Any] = {"manifest": _manifest_projection(manifest)}
+        if job_name is not None:
+            body["job_name"] = job_name
+        if archive_size is not None:
+            body["archive_size"] = archive_size
+        if seed_from_job_id is not None:
+            body["seed_from_job_id"] = seed_from_job_id
+        if viewstream:
+            body["viewstream"] = True
+        if assets:
+            body["assets"] = assets
+        try:
+            payload = http.request_json(
+                "POST",
+                self._base_url + PACKAGE_PREFLIGHT_ROUTE,
+                token=self._token,
+                api_base_url=self._base_url,
+                json_body=body,
+                timeout=_PREFLIGHT_TIMEOUT_S,
+            )
+        except http.HttpHTTPError as exc:
+            return PreflightOutcome(skipped=True, notice=_notice_for_http_error(exc))
+        except http.HttpUnavailable as exc:
+            # ``exc``'s own text already reads "Cannot reach the Simulo platform at
+            # <url> (<reason>)." (``http._unavailable_message``) — don't wrap it in
+            # a second "could not reach the Simulo platform (...)" that just repeats
+            # the same phrase back to the user.
+            return PreflightOutcome(skipped=True, notice=f"{exc} — skipping")
+        except Exception as exc:  # noqa: BLE001 - deliberate fail-open catch-all; see module docstring
+            return PreflightOutcome(skipped=True, notice=f"pre-submit checks failed unexpectedly ({exc}) — skipping")
+        return _parse_preflight_response(payload)