urun-cli 0.7.2__tar.gz → 0.7.3__tar.gz

{urun_cli-0.7.2 → urun_cli-0.7.3}/CHANGELOG.md

@@ -1,3 +1,14 @@
+## 0.7.3
+
+- `urun serve --urun-wheel <version>` — pin a deploy to a specific urun wheel
+  version (e.g. `2.0.0+1497.g8439ef6b3b77`). The pin renders
+  `URUN_WHEEL_VERSION` into the generated serve shim beside the `--warm` pin,
+  BEFORE the bundled-app import, and is content-bearing: it changes the
+  manifest hash, so a wheel roll is a NEW RELEASE (the shared reconciler's
+  wheel-roll path) — never a re-register of an immutable release, which the
+  control plane's deploy-register refuses with a 409. Omitted = byte-identical
+  shim (no pin line).
+
 ## 0.7.2
 
 - Fix the generated serve shim: the `--warm N` pin assigns `URUN_SERVE_WARM`

{urun_cli-0.7.2 → urun_cli-0.7.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: urun-cli
-Version: 0.7.2
+Version: 0.7.3
 Summary: End-user CLI for deploying apps to urun
 Project-URL: Homepage, https://urun.sh
 Project-URL: Repository, https://github.com/urun-sh/urun-cli

{urun_cli-0.7.2 → urun_cli-0.7.3}/pyproject.toml

@@ -20,7 +20,7 @@ name = "urun-cli"
 # so every merge remains on the already-published version until this value is
 # advanced. Wiring semantic-release into CI remains separate work; this patch
 # bump is the minimal release unblock (post-v0.6.3 fixes + the Rust feature minor).
-version = "0.7.2"
+version = "0.7.3"
 description = "End-user CLI for deploying apps to urun"
 readme = "README.md"
 requires-python = ">=3.11"

{urun_cli-0.7.2 → urun_cli-0.7.3}/src/urun/catalog.py

@@ -384,7 +384,7 @@ ENGINE_DEPS: dict[str, list[str]] = {
         "pillow>=10.0.0",
         "openimageio",
         "cloudpickle>=3.1",
-        "huggingface_hub[hf_transfer]>=0.30.0,<1.0.0",
+        "huggingface_hub>=1.5.0,<2.0",
         "sentencepiece",
     ],
     "t2av": [
@@ -435,7 +435,7 @@ ENGINE_DEPS: dict[str, list[str]] = {
         "pillow>=10.0.0",
         "openimageio",
         "cloudpickle>=3.1",
-        "huggingface_hub[hf_transfer]>=0.30.0,<1.0.0",
+        "huggingface_hub>=1.5.0,<2.0",
         "sentencepiece",
         "nvidia-cuda-nvcc==13.0.88",
         "nvidia-cuda-crt==13.0.88",

{urun_cli-0.7.2 → urun_cli-0.7.3}/src/urun/scratch.py

@@ -326,14 +326,33 @@ def capacity_verdict(
 # ---------------------------------------------------------------------------
 
 
-def _scratch_labels(name: str, source_name: str) -> dict[str, str]:
-    return {
+#: THE WEIGHTS-TIER IDENTITY a clone MUST keep. The vineyard fleet controller
+#: (control-plane ``vineyard_fleet.py``) spawns the per-(node, org) vineyardd
+#: for pods matching ``urun.sh/gpu-type,urun.sh/org-id`` and reads the org
+#: from ``urun.sh/org-id-verbatim``; the runtime's armed boot contract then
+#: waits 120 s for that daemon's socket and fails LOUD without it. A clone
+#: that dropped these booted only by luck - when it landed on a node where
+#: its org's daemon was already up for a real pod (dev-usw2 2026-09-10: the
+#: scratch scheduled onto the node hosting another org's daemon and died 7x
+#: on "vineyard daemon socket did not appear"). These label the weights
+#: tier the pod needs, not the materializer / capacity / routing attachment
+#: the clone is detached from - those stay stripped.
+WEIGHTS_TIER_LABELS = ("urun.sh/gpu-type", "urun.sh/org-id", "urun.sh/org-id-verbatim")
+
+
+def _scratch_labels(name: str, source_name: str, source_labels: dict[str, str]) -> dict[str, str]:
+    labels = {
         "app.kubernetes.io/component": SCRATCH_COMPONENT,
         "app.kubernetes.io/managed-by": SCRATCH_MANAGED_BY,
         "app.kubernetes.io/name": name,
         SCRATCH_LABEL: "true",
         SCRATCH_SOURCE_LABEL: source_name,
     }
+    for key in WEIGHTS_TIER_LABELS:
+        value = source_labels.get(key)
+        if value:
+            labels[key] = value
+    return labels
 
 
 def _clean_annotations(annotations: dict[str, str]) -> dict[str, str]:
@@ -529,6 +548,25 @@ def _invalidate_wheel_metadata() -> None:
                 )
 
 
+def _pip_accepts_break_system_packages() -> bool:
+    """Does the copied venv's OWN pip understand ``--break-system-packages``?
+
+    The option (and PEP 668 enforcement itself) landed in pip 23.0: on pip
+    22.x the flag is an unknown option and ``python -m pip install`` exits
+    BEFORE resolving ("no such option"), breaking previously-working
+    overlays. ``derive_scratch_sts`` neither constrains nor upgrades the
+    source venv's pip, so the flag is passed ONLY when this interpreter's
+    pip supports it — where it is needed, it is pip's own PEP 668 opt-out.
+    """
+    try:
+        import pip
+
+        major, minor = (int(part) for part in str(pip.__version__).split(".")[:2])
+    except (ImportError, ValueError, TypeError):
+        return False
+    return (major, minor) >= (23, 0)
+
+
 def _install_and_resolve() -> dict:
     """Install the candidate ONCE and read the EXACT artifact from pip's report.
 
@@ -553,6 +591,12 @@ def _install_and_resolve() -> dict:
             "install",
             "--no-deps",
             "--force-reinstall",
+            # The copied deps venv is a uv-managed interpreter carrying the
+            # PEP 668 EXTERNALLY-MANAGED marker; the overlay is a private
+            # per-pod copy, so pip's own opt-out applies (without it: rc=1,
+            # no readiness). Only offered to pips that HAVE the option —
+            # pip 22.x rejects it before resolving ("no such option").
+            *(("--break-system-packages",) if _pip_accepts_break_system_packages() else ()),
             "--disable-pip-version-check",
             "--report",
             str(REPORT),
@@ -825,7 +869,26 @@ def derive_scratch_sts(
             )
 
     expires_at = (now.astimezone(UTC) + timedelta(hours=ttl_hours)).isoformat(timespec="seconds")
-    labels = _scratch_labels(name, source_name)
+    source_pod_labels = dict(
+        (sts.get("spec", {}).get("template", {}).get("metadata", {}) or {}).get("labels") or {}
+    )
+    # Fail-closed BEFORE any create: the org identity is what the vineyard
+    # fleet controller routes the per-(node, org) daemon by (it reads the
+    # org from ``urun.sh/org-id-verbatim``) and the runtime's armed boot
+    # contract fails loud 120 s in without its socket. ``gpu-type`` stays
+    # optional (a CPU source carries none and needs no vineyard daemon);
+    # a template missing the org pair is NOT a cloneable source — a clone
+    # that silently omits it boots only by luck, then dies.
+    missing_identity = [
+        key for key in (ORG_ID_LABEL, "urun.sh/org-id-verbatim") if not source_pod_labels.get(key)
+    ]
+    if missing_identity:
+        raise UrunError(
+            "the source pod template is missing required org identity "
+            "label(s) — the clone would not be routed to its org's "
+            "vineyard daemon: " + ", ".join(missing_identity)
+        )
+    labels = _scratch_labels(name, source_name, source_pod_labels)
 
     meta = sts["metadata"]
     for key in _SERVER_METADATA_KEYS:

{urun_cli-0.7.2 → urun_cli-0.7.3}/src/urun/serve.py

@@ -63,6 +63,22 @@ CATALOG_URL_ENV = "URUN_CATALOG_URL"
 ANON_KEY_ENVS = ("URUN_CATALOG_ANON_KEY", "URUN_SUPABASE_ANON_KEY")
 
 
+def _urun_wheel_version_type(value: str) -> str:
+    """argparse type for ``--urun-wheel``: a non-empty string, no whitespace.
+
+    The wheel version is embedded verbatim in the generated shim (and compared
+    by the control plane against the recorded release pin), so anything blank
+    or whitespace-carrying is a typo, not a version. Raises argparse's
+    ArgumentTypeError so `urun serve --urun-wheel ""` fails at parse time with
+    a usable message.
+    """
+    if not value or value.split() != [value]:
+        raise argparse.ArgumentTypeError(
+            f"--urun-wheel must be a non-empty version string with no whitespace, got {value!r}"
+        )
+    return value
+
+
 def add_serve_parser(sub: argparse._SubParsersAction) -> None:
     serve_parser = sub.add_parser(
         "serve",
@@ -133,6 +149,20 @@ def _add_serve_model_args(parser: argparse.ArgumentParser) -> None:
             "deploys pass the catalog row's warm (default 0)."
         ),
     )
+    parser.add_argument(
+        "--urun-wheel",
+        dest="urun_wheel",
+        type=_urun_wheel_version_type,
+        default=None,
+        metavar="VERSION",
+        help=(
+            "Pin THIS deploy to a specific urun wheel version (e.g. "
+            "2.0.0+1497.g8439ef6b3b77). Content-bearing: it changes the deploy's "
+            "manifest hash, so a wheel roll is a NEW RELEASE, not a rebuild. "
+            "Shared-endpoint deploys pass the platform's current wheel version. "
+            "Omit = the platform's default wheel resolution."
+        ),
+    )
     parser.add_argument(
         "--entrypoint",
         help=(
@@ -316,6 +346,23 @@ def _validated_exo_pin(args: argparse.Namespace) -> tuple[str | None, str | None
     return exo_class, exo_image
 
 
+def _validated_urun_wheel(value: str | None) -> str | None:
+    """Re-validate the ``--urun-wheel`` pin for Namespace-built call paths.
+
+    argparse already refuses empty/whitespace values (``_urun_wheel_version_type``);
+    a Namespace built in code (tests, future callers) skips argparse, so the pin
+    is checked again here with the SAME rule. The wheel version is CONTENT in
+    the generated shim — a blank value is a config error the deployer must see,
+    never a silently unpinned manifest that fails to change the release hash.
+    """
+    if value is None:
+        return None
+    try:
+        return _urun_wheel_version_type(value)
+    except argparse.ArgumentTypeError as exc:
+        raise UrunError(str(exc)) from None
+
+
 def _build_deploy_args(args: argparse.Namespace, row: CatalogRow) -> argparse.Namespace:
     """Prepare the deploy() Namespace + project root for the resolved row.
 
@@ -330,9 +377,13 @@ def _build_deploy_args(args: argparse.Namespace, row: CatalogRow) -> argparse.Na
     ``urun.serve.app:app``. When ``--warm`` is given, the idle replica floor rides
     the same channel (``URUN_SERVE_WARM``, JSON int) so the bundled app's
     ``@app.function(warm=...)`` declares it at import; an omitted ``--warm``
-    renders nothing (byte-identical shim, legacy always-on NULL). Those land
-    scoped to THIS deploy artifact (NOT a shared ``URUN_SERVE_CONFIG``
-    materializer env, the retired coupling bug). The bundled app resolves engine
+    renders nothing (byte-identical shim, legacy always-on NULL). When
+    ``--urun-wheel`` is given, the wheel version rides ``URUN_WHEEL_VERSION`` the
+    same way — content-bearing, so a wheel roll produces a new manifest hash (a
+    NEW release, never a re-register of an immutable one); an omitted
+    ``--urun-wheel`` renders nothing. Those land scoped to THIS deploy artifact
+    (NOT a shared ``URUN_SERVE_CONFIG`` materializer env, the retired coupling
+    bug). The bundled app resolves engine
     ARGS by-string at boot; the engine NAME is pinned here only to select the
     build-time dependency group (vllm / llama-cpp-python / ...) so the deps venv
     carries the engine the adapter imports at load.
@@ -351,6 +402,16 @@ def _build_deploy_args(args: argparse.Namespace, row: CatalogRow) -> argparse.Na
             "--warm only applies to the bundled serve app (it is pinned in the "
             "generated shim); it cannot be combined with --entrypoint."
         )
+    # --urun-wheel re-validation (argparse already refuses empty/whitespace):
+    # a Namespace built in code skips argparse, so the pin is checked again
+    # here. The wheel version rides the shim env, so --entrypoint (the user's
+    # own app) + --urun-wheel cannot combine either.
+    urun_wheel = _validated_urun_wheel(getattr(args, "urun_wheel", None))
+    if urun_wheel is not None and getattr(args, "entrypoint", None):
+        raise UrunError(
+            "--urun-wheel only applies to the bundled serve app (it is pinned in "
+            "the generated shim); it cannot be combined with --entrypoint."
+        )
 
     entrypoint = getattr(args, "entrypoint", None)
     if entrypoint:
@@ -363,7 +424,7 @@ def _build_deploy_args(args: argparse.Namespace, row: CatalogRow) -> argparse.Na
         shim_root = None
     else:
         project_root, rel_entrypoint = _write_serve_shim(
-            row, exo_class=exo_class, exo_image=exo_image, warm=warm
+            row, exo_class=exo_class, exo_image=exo_image, warm=warm, urun_wheel=urun_wheel
         )
         # PLATFORM RELEASE SCOPE (catalog prebuilt instant serve). The shim is
         # deterministic given the resolved row + gpu, so its manifest hash is an
@@ -429,13 +490,20 @@ def _write_serve_shim(
     exo_class: str | None = None,
     exo_image: str | None = None,
     warm: int | None = None,
+    urun_wheel: str | None = None,
 ) -> tuple[Path, str]:
     """Write the bundled-app shim ``app.py`` pinned to ``row`` into a temp root."""
     project_root = Path(tempfile.mkdtemp(prefix="urun-serve-"))
     try:
         app_path = project_root / "app.py"
         app_path.write_text(
-            render_serve_shim_py(row, exo_class=exo_class, exo_image=exo_image, warm=warm),
+            render_serve_shim_py(
+                row,
+                exo_class=exo_class,
+                exo_image=exo_image,
+                warm=warm,
+                urun_wheel=urun_wheel,
+            ),
             encoding="utf-8",
         )
         # Function-engine map for the launcher's PRE-IMPORT topology decision
@@ -554,6 +622,7 @@ def render_serve_shim_py(
     exo_class: str | None = None,
     exo_image: str | None = None,
     warm: int | None = None,
+    urun_wheel: str | None = None,
 ) -> str:
     """Render the tiny shim that deploys the BUNDLED urun-python serve app.
 
@@ -575,6 +644,11 @@ def render_serve_shim_py(
         the bundled app's ``@app.function(warm=...)`` declares the idle replica
         floor (app_functions.warm_replicas) at import. Unset renders NOTHING —
         byte-identical shim, legacy always-on.
+      * When ``urun_wheel`` is not None, ``URUN_WHEEL_VERSION`` is set before the
+        import so the platform's wheel resolver pins THAT urun wheel. The pin is
+        CONTENT-BEARING: it changes the shim (hence the manifest hash), so a
+        wheel roll is a NEW RELEASE, never a re-register of the immutable one.
+        Unset renders NOTHING — byte-identical shim.
 
     Values are embedded as JSON (NOT interpolated Python) so a weird model string,
     gpu spec, or engine name can never break the module. The catalog row's
@@ -641,6 +715,7 @@ os.environ["URUN_SERVE_GPUS"] = %(gpus)s
 os.environ["URUN_SERVE_ENGINE"] = %(engine)s
 %(exo_env)s
 %(warm_env)s
+%(urun_wheel_env)s
 %(serve_deps_env)s
 
 from urun.serve.app import app  # noqa: E402  (bundled urun-python serve app)
@@ -667,6 +742,11 @@ __all__ = ["app"]
         if warm is not None
         else ""
     )
+    urun_wheel_env = (
+        'os.environ["URUN_WHEEL_VERSION"] = ' + json.dumps(urun_wheel) + "\n"
+        if urun_wheel is not None
+        else ""
+    )
     return template % {
         "entrypoint": BUNDLED_SERVE_ENTRYPOINT,
         "model": model,
@@ -676,6 +756,7 @@ __all__ = ["app"]
         "serve_deps_env": serve_deps_env,
         "exo_env": exo_env,
         "warm_env": warm_env,
+        "urun_wheel_env": urun_wheel_env,
     }