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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: urun-cli
-Version: 0.7.3
+Version: 0.7.5
 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
@@ -498,55 +498,41 @@ All `app` subcommands accept `--environment` (default `prod`) and `--json`.
 These commands are **experimental** and require the server-side `app`
 lifecycle endpoint, which is in development.
 
-## Scratch instances (rung-4 verification, dev-only)
+## Scratch occupants (GPU lane)
 
-The verification ladder for platform changes is: unit tests -> CPU harness ->
-kind hop -> **scratch pod** -> full deploy. Rungs 1-3 are one command each;
-`urun scratch` makes rung 4 one command too — a real GPU pod running the
-real render, without the 30-90 min deploy loop and without touching the
-live app:
+`urun scratch` runs an isolated, TTL-bounded scratch occupant for an app
+release — an app function or a bare `python -c` command in that release's
+venv with its weights. It rides the SAME pull-dispatch path as serving (a
+BullMQ demand job → node scheduler admission → resident spawn), so there is
+no separate provisioner and no kubectl. Authz is org-scoped via your API
+key, exactly like `urun deploy`.
 
 ```bash
-# Reproduce a broken app in isolation with debug env, candidate wheel overlaid:
-urun scratch gemma-voice dg-brain --shape rtx6000:1 \
-  --env VLLM_LOGGING_LEVEL=DEBUG --env CUDA_LAUNCH_BLOCKING=1 \
-  --env PYTHONFAULTHANDLER=1 --name dg-brain-noble-repro
+# Reproduce a broken app in isolation on its release's shape:
+urun scratch gemma-voice dg-brain --gpu rtx6000:1 --ttl 2h
 
-urun scratch ls                      # list scratch instances + expiry
-urun scratch rm dg-brain-noble-repro # tear down
-urun scratch rm --expired            # reap everything past its TTL
+# CPU-only occupant running a bare command (after --) instead of the server:
+urun scratch run --app demo --cpu 4 --ttl 90m -- "import torch; print(torch.__version__)"
+
+urun scratch list                      # live occupants: name, app, shape, node, state, expires
+urun scratch logs sc_8f3a…             # stream an occupant's stdout log
+urun scratch exec sc_8f3a… -- "print(os.environ['URUN_SCRATCH_ID'])"
+urun scratch end sc_8f3a…              # tear down before the TTL
 ```
 
 What it does:
 
-- **Clones the app's rendered StatefulSet** into an isolated instance with
-  every platform label detached: the materializer never adopts it, the
-  capacity reconciler never counts it, and no session is ever routed to it.
-  The clone boots even when the source app is crashlooping or scaled to 0.
-- **Overlays candidate artifacts**: `--wheel <req|url|path-on-storage>`
-  installs `--no-deps` into a hardlink COPY of the deps venv (the shared
-  venv is never modified); `--env KEY=VAL` adds debug vars; hot reload is
-  always pinned off so the instance stays on the currently-rendered release
-  (`--release <hash>` asserts which one that is).
-- **Takes GPUs explicitly**: `--shape` is required and must match the source
-  render; the target karpenter nodepool is checked against its GPU limit and
-  the command refuses at capacity unless `--allow-contention`. Scratch never
-  silently steals demo GPUs.
-- **Never leaks**: every instance carries a TTL annotation (default `4h`,
-  `--ttl 6h`/`90m`) consumed by the scratch reaper, which runs on **every**
-  cluster (prod included); scratch-labeled objects without the annotation
-  (hand-applied) are reaped after a default 24h TTL, with a loud
-  `ScratchTTLExpired` Event. `urun scratch rm` tears down sooner.
-  Boot/self-test logs stream to your terminal (Ctrl-C detaches without
-  tearing down).
-
-Dev-only (v1): talks to a dev cluster via your kubeconfig — the ACTIVE
-kubectl context by default (`--context` overrides; with no active context
-the command fails and demands one). Naming is the enforced control: the
-context name must mark a dev cluster (contain `dev`, e.g. `dev-usw2`,
-`dev-use2`) and must not contain `prod` — anything else is refused. There
-is no hardcoded default cluster: with two dev clusters, a silent default
-would fire kubectl at a cluster you are not looking at.
+- **Isolated, never serving-touching**: scratch demand is never counted by
+  the autoscaler (it never mints nodes) and scratch residents are the
+  preferred eviction victims — scratch can never take capacity from
+  serving. Pin a release with `--release <id>` or let it resolve the app's
+  current promoted release.
+- **Explicit compute**: `--gpu <shape>` (e.g. `l40s:1`) or `--cpu N` (shape
+  `cpu:N`). Omit both to use the release's default shape.
+- **Auto-reclaimed**: every occupant carries a TTL (`--ttl 2h` / `90m`;
+  default `4h`) and is reaped when it lapses; `urun scratch end` ends it
+  sooner. `--no-logs` skips streaming the occupant's log after creation
+  (Ctrl-C also detaches without tearing the occupant down).
 
 ## What gets deployed
 

{urun_cli-0.7.3 → urun_cli-0.7.5}/README.md

@@ -473,55 +473,41 @@ All `app` subcommands accept `--environment` (default `prod`) and `--json`.
 These commands are **experimental** and require the server-side `app`
 lifecycle endpoint, which is in development.
 
-## Scratch instances (rung-4 verification, dev-only)
+## Scratch occupants (GPU lane)
 
-The verification ladder for platform changes is: unit tests -> CPU harness ->
-kind hop -> **scratch pod** -> full deploy. Rungs 1-3 are one command each;
-`urun scratch` makes rung 4 one command too — a real GPU pod running the
-real render, without the 30-90 min deploy loop and without touching the
-live app:
+`urun scratch` runs an isolated, TTL-bounded scratch occupant for an app
+release — an app function or a bare `python -c` command in that release's
+venv with its weights. It rides the SAME pull-dispatch path as serving (a
+BullMQ demand job → node scheduler admission → resident spawn), so there is
+no separate provisioner and no kubectl. Authz is org-scoped via your API
+key, exactly like `urun deploy`.
 
 ```bash
-# Reproduce a broken app in isolation with debug env, candidate wheel overlaid:
-urun scratch gemma-voice dg-brain --shape rtx6000:1 \
-  --env VLLM_LOGGING_LEVEL=DEBUG --env CUDA_LAUNCH_BLOCKING=1 \
-  --env PYTHONFAULTHANDLER=1 --name dg-brain-noble-repro
+# Reproduce a broken app in isolation on its release's shape:
+urun scratch gemma-voice dg-brain --gpu rtx6000:1 --ttl 2h
 
-urun scratch ls                      # list scratch instances + expiry
-urun scratch rm dg-brain-noble-repro # tear down
-urun scratch rm --expired            # reap everything past its TTL
+# CPU-only occupant running a bare command (after --) instead of the server:
+urun scratch run --app demo --cpu 4 --ttl 90m -- "import torch; print(torch.__version__)"
+
+urun scratch list                      # live occupants: name, app, shape, node, state, expires
+urun scratch logs sc_8f3a…             # stream an occupant's stdout log
+urun scratch exec sc_8f3a… -- "print(os.environ['URUN_SCRATCH_ID'])"
+urun scratch end sc_8f3a…              # tear down before the TTL
 ```
 
 What it does:
 
-- **Clones the app's rendered StatefulSet** into an isolated instance with
-  every platform label detached: the materializer never adopts it, the
-  capacity reconciler never counts it, and no session is ever routed to it.
-  The clone boots even when the source app is crashlooping or scaled to 0.
-- **Overlays candidate artifacts**: `--wheel <req|url|path-on-storage>`
-  installs `--no-deps` into a hardlink COPY of the deps venv (the shared
-  venv is never modified); `--env KEY=VAL` adds debug vars; hot reload is
-  always pinned off so the instance stays on the currently-rendered release
-  (`--release <hash>` asserts which one that is).
-- **Takes GPUs explicitly**: `--shape` is required and must match the source
-  render; the target karpenter nodepool is checked against its GPU limit and
-  the command refuses at capacity unless `--allow-contention`. Scratch never
-  silently steals demo GPUs.
-- **Never leaks**: every instance carries a TTL annotation (default `4h`,
-  `--ttl 6h`/`90m`) consumed by the scratch reaper, which runs on **every**
-  cluster (prod included); scratch-labeled objects without the annotation
-  (hand-applied) are reaped after a default 24h TTL, with a loud
-  `ScratchTTLExpired` Event. `urun scratch rm` tears down sooner.
-  Boot/self-test logs stream to your terminal (Ctrl-C detaches without
-  tearing down).
-
-Dev-only (v1): talks to a dev cluster via your kubeconfig — the ACTIVE
-kubectl context by default (`--context` overrides; with no active context
-the command fails and demands one). Naming is the enforced control: the
-context name must mark a dev cluster (contain `dev`, e.g. `dev-usw2`,
-`dev-use2`) and must not contain `prod` — anything else is refused. There
-is no hardcoded default cluster: with two dev clusters, a silent default
-would fire kubectl at a cluster you are not looking at.
+- **Isolated, never serving-touching**: scratch demand is never counted by
+  the autoscaler (it never mints nodes) and scratch residents are the
+  preferred eviction victims — scratch can never take capacity from
+  serving. Pin a release with `--release <id>` or let it resolve the app's
+  current promoted release.
+- **Explicit compute**: `--gpu <shape>` (e.g. `l40s:1`) or `--cpu N` (shape
+  `cpu:N`). Omit both to use the release's default shape.
+- **Auto-reclaimed**: every occupant carries a TTL (`--ttl 2h` / `90m`;
+  default `4h`) and is reaped when it lapses; `urun scratch end` ends it
+  sooner. `--no-logs` skips streaming the occupant's log after creation
+  (Ctrl-C also detaches without tearing the occupant down).
 
 ## What gets deployed
 

{urun_cli-0.7.3 → urun_cli-0.7.5}/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.3"
+version = "0.7.5"
 description = "End-user CLI for deploying apps to urun"
 readme = "README.md"
 requires-python = ">=3.11"

{urun_cli-0.7.3 → urun_cli-0.7.5}/src/urun/api.py

@@ -45,6 +45,39 @@ class ApiClient:
         self.backoff = backoff
         self.on_retry = on_retry
 
+    @property
+    def session_api_origin(self) -> str:
+        """The BARE gateway origin the session-API (``/api/...``) surface lives on.
+
+        The CLI's ``api_url`` is the REST base carrying the ``/v1`` prefix
+        (``https://api.urun.sh/v1``) — but ``/v1/<name>`` routes are the
+        Supabase EDGE surfaces (``/v1/apps``, ``/v1/cli/*``, ...), while the
+        session-api-ts HTTP surface is served on the BARE origin
+        (``https://api.urun.sh/api/...`` behind Envoy). Sending ``/api/*``
+        through the ``/v1`` base hits the edge runtime's unknown-function 404
+        (``Requested function was not found``) — proven live on
+        ``GET /v1/api/scratch`` (2026-09-30, dev proof). One deterministic
+        transform, loud on surprise: strip exactly ONE trailing ``/v1`` path
+        segment (the mirror of :func:`urun.cli.sdk_base_url`); a bare origin
+        is returned as-is; anything else is a hard error.
+        """
+        parsed = urllib.parse.urlsplit(self.base_url)
+        if parsed.path == "/v1":
+            return urllib.parse.urlunsplit((parsed.scheme, parsed.netloc, "", "", ""))
+        if parsed.path in ("", "/"):
+            return self.base_url
+        raise UrunError(
+            f"cannot derive the session-API origin from api_url {self.base_url!r}: "
+            "expected a bare origin or a single trailing /v1 path segment "
+            "(the /api/* session-API surface lives on the bare gateway origin)"
+        )
+
+    def _url(self, path: str) -> str:
+        """Request URL for ``path``: ``/api/*`` → the session-API origin, rest → REST base."""
+        if path.startswith("/api/"):
+            return self.session_api_origin + path
+        return self.base_url + path
+
     def register_manifest(self, manifest: dict[str, Any]) -> dict[str, Any]:
         return self._json("POST", "/register-manifest", manifest)
 
@@ -650,6 +683,74 @@ class ApiClient:
     def org_config(self) -> dict[str, Any]:
         return self._json("GET", "/org-config", None)
 
+    # --- Scratch occupants ------------------------------------------------- #
+    # `urun scratch` rides the same pull-dispatch path as serving: the
+    # session API enqueues a BullMQ scratch demand job, the node scheduler
+    # admits it and spawns the resident. Org scoping comes from the same
+    # org-API-key authz the deploy/client-token routes use. GET
+    # /api/scratch/:id/logs and POST /api/scratch/:id/exec are Slice A
+    # (urun-infra) endpoints — this client is coded against the shared
+    # contract ({cmd} -> streamed output / polled log text).
+
+    def post_scratch_run(self, body: dict[str, Any]) -> dict[str, Any]:
+        """Request a scratch occupant (``POST /api/scratch/run``).
+
+        ``body`` is :func:`urun.scratch.scratch_run_body`'s payload: app,
+        optional function/gpu/release_id/cmd/name, and ``ttl_s``. The server
+        resolves the app's current promoted release when ``release_id`` is
+        omitted and answers ``{scratch_id, queue, expires_at}``.
+        """
+        return self._post("/api/scratch/run", body)
+
+    def get_scratch(self) -> dict[str, Any]:
+        """List the org's live scratch occupants (``GET /api/scratch``)."""
+        return self._get("/api/scratch")
+
+    def end_scratch(self, scratch_id: str) -> dict[str, Any]:
+        """End a scratch occupant (``POST /api/scratch/:id/end``).
+
+        Removes the demand job and marks the Valkey row ``end_requested``;
+        the node scheduler reaps the resident on its next tick.
+        """
+        return self._post(f"/api/scratch/{urllib.parse.quote(scratch_id, safe='')}/end", {})
+
+    def get_scratch_logs(self, scratch_id: str, tail: int | None = None) -> str:
+        """Read a scratch occupant's stdout log (``GET /api/scratch/:id/logs``).
+
+        The endpoint proxies the scheduler's ``log_http`` surface and answers
+        **text/plain**; the scheduler's 404-after-reap is forwarded verbatim,
+        so ``ApiError`` with ``status == 404`` is the occupant-gone end of
+        the stream, not a routing error.
+        """
+        payload = self._request_bytes(
+            "GET",
+            self._url(
+                self._path(
+                    f"/api/scratch/{urllib.parse.quote(scratch_id, safe='')}/logs", {"tail": tail}
+                )
+            ),
+            None,
+            timeout=self.timeout,
+        )
+        return payload.decode("utf-8", "replace")
+
+    def post_scratch_exec(self, scratch_id: str, cmd: str) -> dict[str, Any]:
+        """Run an extra ``python -c`` command in the resident's venv.
+
+        ``POST /api/scratch/:id/exec`` answers ``{exec_id, exec_state
+        ("done"|"failed"), exec_exit, log_http, log_path}`` after the server's
+        own bounded poll (min remaining ttl, 600s cap; 504 on timeout).
+        """
+        return self._post(
+            f"/api/scratch/{urllib.parse.quote(scratch_id, safe='')}/exec", {"cmd": cmd}
+        )
+
+    def get_scratch_exec_output(self, log_http: str) -> str:
+        """Fetch an exec's streamed output from its ``log_http`` surface (text/plain)."""
+        return self._request_bytes("GET", log_http, None, timeout=self.timeout).decode(
+            "utf-8", "replace"
+        )
+
     def trust_auth_connection(self, payload: dict[str, Any]) -> dict[str, Any]:
         """Register a trusted JWT/JWKS provider for the authenticated org.
 
@@ -800,7 +901,7 @@ class ApiClient:
             if body is None
             else json.dumps(body, sort_keys=True, separators=(",", ":")).encode("utf-8")
         )
-        url = self.base_url + path
+        url = self._url(path)
         try:
             payload = self._request_bytes(method, url, data, timeout=self.timeout)
         except ApiError:
@@ -825,7 +926,7 @@ class ApiClient:
             if body is None
             else json.dumps(body, sort_keys=True, separators=(",", ":")).encode("utf-8")
         )
-        url = self.base_url + path
+        url = self._url(path)
 
         try:
             payload = retry_call(

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

@@ -148,10 +148,11 @@ ENGINE_DEPS: dict[str, list[str]] = {
         "orjson",
     ],
     "sglang": [
-        "sglang[all]==0.5.17",
+        "sglang[all]==0.5.6.post3.dev11375+gf0e400193",
         "flash-attn-4==4.0.0b18",
-        "torch==2.11.0",
-        "torchvision==0.26.0",
+        "cuda-tile==1.6.0rc5",
+        "torch==2.13.0",
+        "torchvision==0.28.0",
         "torchaudio==2.11.0",
         "transformers==5.12.1",
         "accelerate",
@@ -335,6 +336,8 @@ ENGINE_DEPS: dict[str, list[str]] = {
         "accelerate",
         "torchaudio==2.6.0",
         "onnxruntime>=1.20",
+        "mistral-common[image]>=1.8.8",
+        "soundfile",
         "soxr>=0.5",
     ],
     "tts": [
@@ -349,6 +352,7 @@ ENGINE_DEPS: dict[str, list[str]] = {
         "kokoro>=0.9.2",
         "misaki[en,ja,zh]>=0.9.3",
         "qwen-tts>=0.1.1",
+        "voxcpm>=2.0.3",
     ],
     "ar": [
         "torch==2.11.0",
@@ -419,6 +423,7 @@ ENGINE_DEPS: dict[str, list[str]] = {
         "omegaconf",
         "gpustat",
         "ninja",
+        "ftfy>=6.3.1",
         "fastvideo-kernel==0.3.2; sys_platform == 'linux'",
     ],
     "ltx-realtime": [
@@ -525,6 +530,73 @@ def parse_gpu_spec(spec: str) -> tuple[str, int]:
     return kind, (n if n > 0 else 1)
 
 
+#: ``app_functions.dispatch_provider``'s DB CHECK (urun-infra migration
+#: 20271051000000), spelled here so `urun serve` refuses a bad pin BEFORE any
+#: deploy. Kept in lockstep with ``_validated_dispatch_provider`` (urun-python)
+#: and ``dispatchShapeClass`` (session-api-ts) — the queue name is compared
+#: byte-for-byte across all three, so one loose spelling is a silent mismatch.
+_DISPATCH_PROVIDER_RE = re.compile(r"^[a-z0-9]{1,32}$")
+
+
+def split_gpu_provider_pin(spec: str) -> tuple[str, str | None]:
+    """Split ``<class>[-<provider>]:<count>`` into its bare spec and provider pin.
+
+    ``urun serve --gpu rtx6000-spheron:1`` names a LANE, not two orthogonal
+    things: the provider-pinned dispatch queue is literally keyed on
+    ``{shape_class}-{provider}``, so the flag uses the SAME spelling the queue
+    does rather than inventing a second vocabulary for the same concept.
+
+    Returns ``(bare_spec, provider)`` — ``("rtx6000:1", "spheron")`` above, and
+    ``(spec, None)`` for every unpinned spec, which is the overwhelming majority
+    and passes through byte-identical.
+
+    PARSE FIRST, THEN VALIDATE (review: Keegan, 2026-09-15). Every caller
+    downstream — the VRAM floor check, ``resolve_row``, the catalog SKU match —
+    must see the BARE class, because ``rtx6000-spheron`` matches no SKU and
+    would hard-fail there with a misleading "unknown GPU" error.
+
+    NEVER GUESSES THE SPLIT. A class is only treated as pinned when the full
+    token is NOT itself a known class AND the part before the last ``-`` IS one
+    — the same rule ``base_accelerator_class`` applies in urun-python's node
+    scheduler, so all three languages agree on where the boundary falls. No
+    class in :data:`GPU_VRAM_GB` contains a ``-`` today, but a future
+    ``h100-sxm`` must resolve as a CLASS, not as ``h100`` pinned to ``sxm``.
+    An unrecognized base raises rather than silently deploying to a queue that
+    nothing consumes.
+
+    CASE IS NORMALIZED, NOT REJECTED — and this is a deliberate divergence from
+    ``_validated_dispatch_provider`` (urun-python) and the DB CHECK, which both
+    refuse uppercase outright. ``parse_gpu_spec`` already lowercases the whole
+    ``<class>:<count>`` token, so ``--gpu L4:1`` is long-standing CLI behavior;
+    rejecting ``--gpu RTX6000-SPHERON:1`` while accepting ``--gpu L4:1`` would
+    split one token's rules down the middle. Because the provider is read off
+    the ALREADY-lowercased token, this normalization can only ever emit a value
+    the stricter downstream validators accept — it widens what the CLI takes,
+    never what it sends.
+    """
+    kind, sep, count = (spec or "").partition(":")
+    kind = kind.strip().lower()
+    suffix = f"{sep}{count}" if sep else ""
+    if "-" not in kind or kind in GPU_VRAM_GB:
+        return spec, None
+    base, _, provider = kind.rpartition("-")
+    if base not in GPU_VRAM_GB:
+        raise ValueError(
+            f"--gpu {spec!r}: {kind!r} is neither a known GPU class nor "
+            f"'<class>-<provider>' with a known class ({base!r} is not one of "
+            f"{sorted(GPU_VRAM_GB)}). Refusing to guess where the provider pin "
+            f"starts — a wrong split deploys to a dispatch queue nothing consumes."
+        )
+    if not _DISPATCH_PROVIDER_RE.fullmatch(provider):
+        raise ValueError(
+            f"--gpu {spec!r}: provider pin {provider!r} must be lowercase "
+            f"alphanumeric, 1..32 characters. It names the provider half of this "
+            f"deploy's dispatch queue ('{base}-{provider}'); anything else would "
+            f"key a queue no autoscaler scales and no scheduler consumes."
+        )
+    return f"{base}{suffix}", provider
+
+
 def gpu_vram_gb(spec: str) -> int | None:
     """Total VRAM (GB) a ``<kind>:<count>`` SKU provides, or None if unknown kind."""
     kind, count = parse_gpu_spec(spec)
@@ -835,7 +907,10 @@ class CatalogRow:
 
     model_id: str
     variant: str
-    gpu_spec: str
+    # NULL for a CPU placement (`cpu: N` — owner design 2026-09-30: a CPU
+    # workload declares CORES, never a GPU SKU). A non-null value is the
+    # GPU spec ("<kind>:<count>").
+    gpu_spec: str | None
     engine: str
     family: str
     task: str
@@ -851,6 +926,9 @@ class CatalogRow:
     # ``default_gpu`` is model-level recommended placement (e.g. "l4:1");
     # ``min_vram_gb`` is the GPU-resident VRAM floor for this placement;
     # ``min_host_ram_gb`` is the host-RAM floor for tiered-offload (GGUF) models.
+    # PLACEMENT-level CPU cores for a CPU placement (gpu_spec NULL); None for
+    # every GPU row (additive — older catalogs lack the column).
+    cpu: int | None = None
     default_gpu: str | None = None
     min_vram_gb: int | None = None
     min_host_ram_gb: int | None = None
@@ -871,7 +949,13 @@ class CatalogRow:
 
     @property
     def gpu_count(self) -> int:
-        """GPU count parsed from ``<kind>:<n>`` (e.g. ``b200:8`` -> 8)."""
+        """GPU count parsed from ``<kind>:<n>`` (e.g. ``b200:8`` -> 8).
+
+        A CPU placement (gpu_spec NULL) has ZERO GPUs — the cores declaration
+        (``cpu``) is the capacity axis there, never a GPU count.
+        """
+        if self.gpu_spec is None:
+            return 0
         _, _, count = self.gpu_spec.partition(":")
         try:
             return int(count)
@@ -880,8 +964,8 @@ class CatalogRow:
 
     @property
     def is_dev_testable(self) -> bool:
-        """Contract rule: 1-GPU, non-disagg placements are dev-testable."""
-        return self.gpu_count == 1 and not self.disagg
+        """Contract rule: 1-GPU (or single CPU-unit) non-disagg placements."""
+        return (self.gpu_count == 1 or self.gpu_spec is None) and not self.disagg
 
 
 # PEP 508 requirement SHAPE (stdlib-only; this module deliberately carries no
@@ -983,11 +1067,25 @@ def parse_row(raw: dict[str, Any]) -> CatalogRow:
                     "the catalog is public reference data — use a secret-managed index"
                 )
 
+    gpu_spec = raw.get("gpu_spec")
+    if gpu_spec is not None and (not isinstance(gpu_spec, str) or not gpu_spec):
+        raise UrunError("catalog row 'gpu_spec' must be a non-empty string or null")
+    # THE CPU SENTINEL: the DB keeps gpu_spec NOT NULL (it is part of the PK)
+    # — a CPU row is the 'none' literal, normalized to None here (owner design
+    # 2026-09-30), so every consumer reads one shape.
+    if gpu_spec == "none":
+        gpu_spec = None
+    if gpu_spec is None and opt_int("cpu") is None:
+        raise UrunError(
+            "catalog row with NULL gpu_spec must declare 'cpu' cores "
+            "(the CPU declaration: a CPU workload names its cores, never a GPU SKU)"
+        )
     return CatalogRow(
         model_id=req_str("model_id"),
         variant=req_str("variant"),
-        gpu_spec=req_str("gpu_spec"),
+        gpu_spec=gpu_spec,
         engine=req_str("engine"),
+        cpu=opt_int("cpu"),
         family=req_str("family"),
         task=req_str("task"),
         hf_repo=req_str("hf_repo"),
@@ -1063,7 +1161,7 @@ def resolve_row(
         return for_variant[0]
     for_gpu = [r for r in for_variant if r.gpu_spec == gpu_spec]
     if not for_gpu:
-        known = ", ".join(sorted({r.gpu_spec for r in for_variant}))
+        known = ", ".join(sorted(str(g) for g in {r.gpu_spec for r in for_variant}))
         raise UrunError(
             f"no placement on GPU {gpu_spec!r} for {model_id}:{variant}. "
             f"Available placements: {known}"
@@ -1112,9 +1210,20 @@ def validate_gpu_against_row(
     representative = resolve_row(rows, model_id, variant, None)
     resolved_variant = representative.variant
     for_variant = [r for r in rows if r.model_id == model_id and r.variant == resolved_variant]
-    enumerated = sorted({r.gpu_spec for r in for_variant})
+    enumerated = sorted(str(g) for g in {r.gpu_spec for r in for_variant})
     ref = f"{model_id}:{resolved_variant}"
 
+    if representative.gpu_spec is None and requested_gpu in (None, "", "none"):
+        # THE CPU DECLARATION (owner design 2026-09-30): the variant's row
+        # declares CORES (gpu_spec NULL) and the request names no GPU — there
+        # is no VRAM axis to check and no unknown-SKU error; the cores
+        # declaration IS the placement. Clean, like an enumerated GPU row.
+        return (
+            "ok",
+            f"{ref} is a CPU placement (cpu: {representative.cpu} cores; no GPU SKU)."
+            f"{_host_ram_note(representative)}",
+        )
+
     if is_neuron_gpu_class(requested_gpu):
         # Neuron (trn2): DELIBERATELY absent from GPU_VRAM_GB (mirroring
         # urun-python, which omits trn2 from its VRAM map) — the VRAM floor is