bladekit 4.5.0__py3-none-any.whl

bladekit/_app.py

@@ -0,0 +1,3241 @@
+"""Object API: ``App``, ``Function``, ``FunctionCall`` (spawn handle).
+
+This is the ergonomic surface (SPEC §1). It also owns the run lifecycle a single
+``blade run`` (or interactive session) maps onto:
+
+- The *first* remote invocation of a function creates a code bundle, a run, and
+  the first call. Subsequent ``.remote()`` / ``.spawn()`` of the *same* function
+  in the same process reuse the same run — i.e. the same hot container — by
+  appending calls (FIFO), per SPEC §3.3.
+- ``complete_session()`` POSTs ``/complete`` on every open run so the container
+  drains immediately at script end instead of waiting for the idle timeout.
+"""
+
+from __future__ import annotations
+
+import sys
+import time
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Callable, Dict, List, Mapping, Optional, Sequence, TYPE_CHECKING
+
+if TYPE_CHECKING:  # pragma: no cover — typing only, avoids an import cycle
+    from ._map import MapHandle
+
+from . import exceptions as exc
+from ._constants import (
+    CALL_TERMINAL_STATES,
+    DEFAULT_CPU_MILLICORES,
+    DEFAULT_IDLE_TIMEOUT_SECONDS,
+    DEFAULT_MEMORY_MB,
+    DEFAULT_TIMEOUT_SECONDS,
+    GPU_COUNT_MAX,
+    GPU_COUNT_MIN,
+    POLL_INITIAL_INTERVAL,
+    POLL_MAX_INTERVAL,
+    PRIORITY_MAX,
+    PRIORITY_MIN,
+    RETRIES_BACKOFF_FACTOR_MAX,
+    RETRIES_BACKOFF_FACTOR_MIN,
+    RETRIES_BACKOFF_INITIAL_MAX,
+    RETRIES_BACKOFF_MAX_MAX,
+    RETRIES_MAX,
+)
+
+_APP_NAME_RE = re.compile(r"^[a-z][a-z0-9-]{2,62}$")
+
+# Parse "GPU_TYPE:N" for multi-GPU (conventions.md §6, scheduler-v2.md §5).
+# Examples: "RTX-A4500" -> ("RTX-A4500", 1); "RTX-A4500:4" -> ("RTX-A4500", 4).
+_GPU_COUNT_RE = re.compile(r"^(.+):(\d+)$")
+_HTTP_METHODS = frozenset({"GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS", "HEAD"})
+_ASGI_METHODS = ("GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS", "HEAD")
+
+
+def _python_version() -> str:
+    return f"{sys.version_info.major}.{sys.version_info.minor}"
+
+
+@dataclass
+class _Session:
+    """Process-wide registry of open runs, so we can drain them at exit."""
+
+    client: Any = None
+    open_run_ids: List[str] = field(default_factory=list)
+
+    def register_run(self, run_id: str) -> None:
+        if run_id not in self.open_run_ids:
+            self.open_run_ids.append(run_id)
+
+    def complete_all(self) -> None:
+        if self.client is None:
+            return
+        for run_id in self.open_run_ids:
+            try:
+                self.client.complete_run(run_id)
+            except exc.FabricError:
+                pass  # best-effort drain; idle timeout is the fallback
+        self.open_run_ids.clear()
+
+
+# A module-level session keyed nowhere special: a `blade run` is one process,
+# one script. The CLI calls `complete_session()` after the entrypoint returns.
+_SESSION = _Session()
+
+
+def complete_session() -> None:
+    """POST /complete on every run opened in this process (drain hot containers)."""
+    _SESSION.complete_all()
+
+
+def _emit_run_warnings(run: dict) -> None:
+    """Print structured creation warnings in yellow (conventions.md §2).
+
+    GPU_TYPE_UNAVAILABLE lists the GPU types actually known to the fleet so the
+    user can fix the typo / pick an available type. Unknown warning codes are
+    shown verbatim (extensible registry — never branch logic on them).
+    """
+    warnings = run.get("warnings")
+    if not warnings:
+        return
+    try:
+        from ._render import err_console
+    except Exception:  # pragma: no cover - rich import failure is non-fatal
+        return
+    for w in warnings:
+        code = w.get("code", "WARNING")
+        message = w.get("message", "")
+        err_console.print(f"[yellow]warning[/yellow] [bold]{code}[/bold]: {message}")
+        if code == "GPU_TYPE_UNAVAILABLE":
+            details = w.get("details") or {}
+            known = details.get("known_types") or []
+            if known:
+                err_console.print(
+                    f"  [yellow]available GPU types:[/yellow] {', '.join(known)}"
+                )
+            else:
+                err_console.print(
+                    "  [yellow]no GPU types are currently online in the fleet.[/yellow]"
+                )
+            err_console.print(
+                "  [dim]the run will stay pending until a node of this type "
+                "appears.[/dim]"
+            )
+        elif code == "ORG_GPU_QUOTA_REACHED":
+            details = w.get("details") or {}
+            in_use = details.get("in_use", "?")
+            limit = details.get("limit", "?")
+            gpu_type = details.get("gpu_type", "*")
+            scope = "GPUs" if gpu_type == "*" else f"GPUs of type {gpu_type!r}"
+            err_console.print(
+                f"  [dim]your organization is using {in_use}/{limit} {scope}; "
+                "the run waits until usage drops below the limit.[/dim]"
+            )
+        if code in ("GPU_QUOTA_REACHED", "ORG_GPU_QUOTA_REACHED"):
+            # Let the run spinner say "waiting for quota" instead of the
+            # misleading "waiting for capacity" (_render.RunProgress).
+            try:
+                from ._render import mark_quota_queued
+
+                mark_quota_queued(run.get("run_id", ""))
+            except Exception:  # pragma: no cover - render import is optional
+                pass
+
+
+@dataclass(frozen=True)
+class Autoscale:
+    """Per-endpoint autoscaling policy (autoscaling v2).
+
+    Every knob is optional and only ADDS to the default concurrency-based
+    autoscaler — guardrails (min/max clamp, cooldown, breaker) always win.
+
+    - ``target_inputs``: per-replica concurrency the autoscaler AIMS for;
+      ``max_inputs`` (from ``@app.concurrent``) stays the admission ceiling
+      replicas may burst to while new capacity boots. Scale before saturation.
+    - ``buffer_replicas``: warm spare replicas kept only WHILE the endpoint is
+      active — an idle endpoint still settles to ``min_replicas``.
+    - ``vllm_target_waiting``: the curated vLLM preset (``@app.web_server``
+      endpoints only): scale on vLLM's scheduler queue so continuous batching
+      pressure is visible to the autoscaler. The platform owns the metrics
+      plumbing — no exporter config, no PromQL.
+    - ``scaledown_window``: stabilization window (seconds, 30..3600) of the
+      PROPORTIONAL scale-down path — how long the endpoint must be
+      continuously observed needing fewer replicas before a surplus replica
+      is shed. Unset = ``max(server default, scale_down_idle_seconds)``. It
+      never affects scale-up, the hard ``max_replicas`` cap, or
+      scale-to-zero (which stays governed by ``scale_down_idle_seconds``).
+      Requires a control plane of 2026-08-11 or newer (contracts CHANGELOG,
+      autoscaling anti-flap entry): older control planes reject the unknown
+      policy field with ``400 SCALING_POLICY_INVALID``.
+
+    Example::
+
+        @app.web_server(
+            startup_timeout=600, min_replicas=1, max_replicas=6,
+            autoscale=bladekit.Autoscale(target_inputs=24, buffer_replicas=1,
+                                      vllm_target_waiting=4),
+        )
+        @app.concurrent(max_inputs=32)
+        @app.function(gpu="RTX-A4500", image=vllm_image)
+        def serve(): ...
+    """
+
+    target_inputs: Optional[int] = None
+    buffer_replicas: Optional[int] = None
+    vllm_target_waiting: Optional[int] = None
+    scaledown_window: Optional[int] = None
+
+    def __post_init__(self) -> None:
+        if (
+            self.target_inputs is None
+            and self.buffer_replicas is None
+            and self.vllm_target_waiting is None
+            and self.scaledown_window is None
+        ):
+            raise exc.InvalidArgumentError(
+                "SCALING_POLICY_INVALID",
+                "bladekit.Autoscale requires at least one of target_inputs, "
+                "buffer_replicas, vllm_target_waiting, scaledown_window",
+            )
+        if self.target_inputs is not None and (
+            not isinstance(self.target_inputs, int)
+            or isinstance(self.target_inputs, bool)
+            or self.target_inputs < 1
+            or self.target_inputs > 100
+        ):
+            raise exc.InvalidArgumentError(
+                "SCALING_POLICY_INVALID",
+                "target_inputs must be an integer between 1 and 100",
+            )
+        if self.buffer_replicas is not None and (
+            not isinstance(self.buffer_replicas, int)
+            or isinstance(self.buffer_replicas, bool)
+            or self.buffer_replicas < 0
+            or self.buffer_replicas > 10
+        ):
+            raise exc.InvalidArgumentError(
+                "SCALING_POLICY_INVALID",
+                "buffer_replicas must be an integer between 0 and 10",
+            )
+        if self.vllm_target_waiting is not None and (
+            not isinstance(self.vllm_target_waiting, int)
+            or isinstance(self.vllm_target_waiting, bool)
+            or self.vllm_target_waiting < 1
+            or self.vllm_target_waiting > 1000
+        ):
+            raise exc.InvalidArgumentError(
+                "SCALING_POLICY_INVALID",
+                "vllm_target_waiting must be an integer between 1 and 1000",
+            )
+        # Mirrors the server rule (scaledown_window_seconds 30..3600, the same
+        # bounds as scale_down_idle_seconds).
+        if self.scaledown_window is not None and (
+            not isinstance(self.scaledown_window, int)
+            or isinstance(self.scaledown_window, bool)
+            or self.scaledown_window < 30
+            or self.scaledown_window > 3600
+        ):
+            raise exc.InvalidArgumentError(
+                "SCALING_POLICY_INVALID",
+                "scaledown_window must be an integer between 30 and 3600",
+            )
+
+
+@dataclass
+class EndpointDeclaration:
+    """SDK-side endpoint metadata attached by ``@app.web_endpoint`` / ASGI."""
+
+    name: Optional[str]
+    kind: str
+    path: str
+    methods: tuple[str, ...]
+    min_replicas: Optional[int] = None
+    max_replicas: Optional[int] = None
+    max_concurrent_inputs: Optional[int] = None
+    scale_down_idle_seconds: Optional[int] = None
+    # Ingress queue bound (0 = unbounded); sent only when set — the server
+    # default (0) preserves the historical unbounded queueing.
+    max_queue_depth: Optional[int] = None
+    reserved_replicas: Optional[int] = None  # hybrid: always-on floor on 'reserved'
+    public: bool = False  # public endpoint (no auth); private by default
+    # §13.5 — local HTTP server endpoints (web_server / asgi_app).
+    port: Optional[int] = None  # server_port: user-provided for web_server, None for asgi_app
+    startup_timeout_seconds: Optional[int] = None  # loopback readiness budget
+    # Autoscaling v2 — policy declared on the endpoint decorator (autoscale=).
+    autoscale: Optional[Autoscale] = None
+    # GPU snapshot opt-in (coldstart-snapshot.md §5). Valid ONLY on web_server
+    # with gpu_count==1 — validated in _endpoint_specs() (mirror of the server).
+    snapshot: bool = False
+
+
+@dataclass
+class DeploymentManifest:
+    """Serializable deployment manifest derived from an ``App``.
+
+    ``to_dict()`` is intentionally richer than ``DeploymentCreateRequest`` so
+    local tooling can inspect functions/classes/resources/images/secrets/volumes.
+    ``to_deployment_request()`` narrows it to the current control-plane contract.
+    """
+
+    app_name: str
+    bundle_id: Optional[str]
+    runtime: dict
+    endpoints: list[dict]
+    image: Optional[str] = None
+    image_build_id: Optional[str] = None
+    labels: Optional[dict[str, str]] = None
+    functions: list[dict] = field(default_factory=list)
+    classes: list[dict] = field(default_factory=list)
+    crons: list[dict] = field(default_factory=list)
+
+    def to_dict(self) -> dict:
+        data: dict[str, Any] = {
+            "app_name": self.app_name,
+            "runtime": self.runtime,
+            "endpoints": self.endpoints,
+            "functions": self.functions,
+            "classes": self.classes,
+            "crons": self.crons,
+        }
+        if self.bundle_id is not None:
+            data["bundle_id"] = self.bundle_id
+        if self.image is not None:
+            data["image"] = self.image
+        if self.image_build_id is not None:
+            data["image_build_id"] = self.image_build_id
+        if self.labels:
+            data["labels"] = self.labels
+        return data
+
+    def to_deployment_request(self) -> dict:
+        if not self.bundle_id:
+            raise exc.InvalidArgumentError(
+                "INVALID_ARGUMENT",
+                "deployment manifest has no bundle_id; build/upload the bundle first.",
+            )
+        if not self.endpoints and not self.crons:
+            raise exc.InvalidArgumentError(
+                "INVALID_ARGUMENT", "deployment manifest has no endpoints or crons."
+            )
+        if (self.image is None) == (self.image_build_id is None):
+            raise exc.InvalidArgumentError(
+                "INVALID_ARGUMENT",
+                "deployment manifest must have exactly one of image or image_build_id.",
+            )
+        body: dict[str, Any] = {
+            "bundle_id": self.bundle_id,
+            "runtime": self.runtime,
+            "endpoints": self.endpoints,
+        }
+        if self.crons:
+            body["crons"] = self.crons
+        if self.image is not None:
+            body["image"] = self.image
+        if self.image_build_id is not None:
+            body["image_build_id"] = self.image_build_id
+        if self.labels:
+            body["labels"] = self.labels
+        return body
+
+
+class FunctionCall:
+    """Handle returned by ``Function.spawn`` — non-blocking.
+
+    ``.get(timeout=)`` blocks until the call finishes and returns the result (or
+    re-raises the remote exception); ``.cancel()`` cancels the whole run.
+    """
+
+    def __init__(self, function: "Function", run_id: str, call_id: str) -> None:
+        self._function = function
+        self.run_id = run_id
+        self.call_id = call_id
+
+    def __repr__(self) -> str:
+        return f"FunctionCall(call_id={self.call_id!r}, run_id={self.run_id!r})"
+
+    def get(self, timeout: Optional[float] = None) -> Any:
+        return self._function._await_call(self.call_id, self.run_id, timeout=timeout)
+
+    def cancel(self) -> None:
+        """Cancel the underlying run (a run == a container; cancel is run-level)."""
+        self._function._app._client_cancel(self.run_id)
+
+
+def _reject_coroutine_function(fn: Callable[..., Any], what: str = "an AI Fabric function") -> None:
+    """Reject ``async def`` at decoration time instead of inside the container.
+
+    No runner path awaits a coroutine: a function call does ``fn(*args, **kwargs)``
+    (runner-protocol §3.4.d), class methods and their ``@bladekit.enter``/``build``/
+    ``exit`` hooks are invoked the same way (§10), and both local-server kinds call
+    the decorated function synchronously — ``web_server`` to start the server,
+    ``asgi_app`` to obtain the ASGI app object.
+
+    So an ``async def`` used to be accepted here, ship, get scheduled, pull its
+    image, and only then fail deep in the container with "cannot pickle 'coroutine'
+    object" (or, on a web endpoint, "unsupported HTTP response body type") — an
+    error naming neither the cause nor the fix. A lifecycle hook was worse than an
+    error: the coroutine was never awaited, so ``@bladekit.enter`` silently did not
+    load the model and the failure surfaced later as an unrelated AttributeError.
+
+    ``asgi_app``/``web_server`` are not exceptions: their factory is sync and
+    returns the async application, which is where user coroutines legitimately
+    live. Awaiting user coroutines in the runner is a separate change; until it
+    lands, failing at the decorator is the honest behaviour.
+    """
+    import inspect  # noqa: PLC0415 - only needed on the decoration path
+
+    if not inspect.iscoroutinefunction(fn):
+        return
+    name = getattr(fn, "__name__", "<function>")
+    raise exc.InvalidArgumentError(
+        "INVALID_ARGUMENT",
+        f"{name!r} is an 'async def' function, which AI Fabric cannot execute yet as "
+        f"{what}: the runner calls it synchronously. Wrap the coroutine, e.g.\n"
+        f"    def {name}(*args, **kwargs):\n"
+        f"        return asyncio.run(_{name}(*args, **kwargs))\n"
+        "For an ASGI app (FastAPI, Starlette), use @app.asgi_app on a SYNC "
+        "factory that returns the application object.",
+    )
+
+
+class Function:
+    """A decorated function, callable remotely."""
+
+    def __init__(
+        self,
+        app: "App",
+        fn: Callable[..., Any],
+        *,
+        gpu: Optional[str] = None,
+        cpu: Optional[float] = None,
+        memory: Optional[int] = None,
+        timeout: Optional[int] = None,
+        image: Any = None,
+        idle_timeout: Optional[int] = None,
+        volumes: Optional[Dict[str, Any]] = None,
+        secrets: Optional[List[Any]] = None,
+        class_name: Optional[str] = None,
+        serve: bool = False,
+        retries: Optional[dict] = None,
+        priority: Optional[int] = None,
+        namespace: Optional[str] = None,
+        schedule: Any = None,
+        # spot/reserved capacity classes, preemption budget
+        gpu_class: str = "spot",
+        best_effort: bool = False,
+        max_interruptions: Optional[int] = None,
+        # Bound bladekit.parameter() values for a parametrized @app.cls method.
+        parameters: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        _validate_gpu_class(gpu_class)
+        _reject_coroutine_function(fn)
+        self._app = app
+        self._fn = fn
+        self.gpu = gpu
+        self.cpu = cpu
+        self.memory = memory
+        self.timeout = timeout
+        # ``image`` may be a string (alias/ref) or a ``bladekit.Image`` (DSL).
+        self.image = image
+        self.idle_timeout = idle_timeout
+        # {mount_path: bladekit.Volume}, [bladekit.Secret], @app.cls class name.
+        self.volumes = volumes
+        self.secrets = secrets
+        self.class_name = class_name
+        self.serve = serve
+        # retry policy, scheduling priority, namespace, cron schedule.
+        self.retries = _normalize_retries(retries)
+        self.priority = priority
+        self.namespace = namespace
+        self.schedule = schedule
+        # capacity class + preemption budget (runner-protocol §15.2.1,
+        # m8-spot.md §13). gpu_class defaults to "spot" (the cheap, preemptible
+        # default); best_effort and max_interruptions default to default behaviour.
+        self.gpu_class = gpu_class
+        self.best_effort = best_effort
+        self.max_interruptions = max_interruptions
+        # Bound bladekit.parameter() values (name -> value) for a parametrized
+        # @app.cls method; None for a plain function or an unparametrized class.
+        # Carried into FunctionRef.parameters so the runner instantiates the class
+        # with them and routes the call to the matching parametrized container.
+        self.parameters = parameters
+        self._endpoints: list[EndpointDeclaration] = []
+        self._max_concurrent_inputs: Optional[int] = None
+        # Autoscaling v2: function-level target concurrency from
+        # @app.concurrent(target_inputs=), folded into the endpoint's
+        # scaling_policy at manifest time (_endpoint_specs).
+        self._target_inputs: Optional[int] = None
+        # The run reused for hot-container call batching in this process.
+        self._run_id: Optional[str] = None
+        # Make the wrapped function still usable locally / introspectable.
+        self.__name__ = getattr(fn, "__name__", "fn")
+        self.__qualname__ = getattr(fn, "__qualname__", self.__name__)
+        self.__doc__ = getattr(fn, "__doc__", None)
+
+        for decl in getattr(fn, "__forge_endpoints__", []):
+            self._add_endpoint(decl)
+        pending_concurrency = getattr(fn, "__forge_max_concurrent_inputs__", None)
+        if pending_concurrency is not None:
+            self._set_concurrency(pending_concurrency)
+        pending_target = getattr(fn, "__forge_target_inputs__", None)
+        if pending_target is not None:
+            self._set_target_inputs(pending_target)
+        # Dynamic batching (@bladekit.batched): the wrapped function carries its
+        # batch config, which rides on the run/deploy manifest so the runner
+        # accumulates individual calls into batches (batching.md §4). None for a
+        # plain function — the wire body is then byte-for-byte unchanged.
+        self.batch_config: Optional[dict] = getattr(fn, "__forge_batched__", None)
+
+    def __repr__(self) -> str:
+        return f"<bladekit.Function {self._app.name}.{self.__name__} gpu={self.gpu!r}>"
+
+    @classmethod
+    def from_name(
+        cls, app_name: str, function_name: str, *, version: Optional[int] = None
+    ) -> "_NamedFunction":
+        """Reference a deployed function by name.
+
+        The public contract does not yet define SDK invocation of deployed
+        functions by name. The lightweight object is useful for discovery and
+        fails clearly if called.
+
+        ``version``: pin to a deployment version. The endpoint is resolved once
+        and cached, so without a pin a long-lived reference silently follows a
+        redeploy or rollback. With one, a version change raises
+        ``NotFoundError("DEPLOYMENT_VERSION_MISMATCH")`` instead — the call fails
+        where it can be handled rather than reaching different code than intended.
+        This pins RESOLUTION, not execution: a superseded deployment has no
+        replicas, so it cannot be invoked.
+        """
+        return _NamedFunction(app_name, function_name, version=version)
+
+    def __call__(self, *args: Any, **kwargs: Any) -> Any:
+        """Direct invocation runs the wrapped function in-process (no fleet).
+
+        This is load-bearing for remote execution: `FunctionRef.qualname`
+        points at the *decorated* object, so when forge-runner imports the
+        bundle module and calls `fn(*args, **kwargs)` (runner-protocol §3.4.d)
+        it is THIS method that executes the user code inside the container.
+        Locally it makes the decorated function behave like the plain one.
+        """
+        return self._fn(*args, **kwargs)
+
+    def local(self, *args: Any, **kwargs: Any) -> Any:
+        """Call the function locally (no remote execution). Handy for tests."""
+        return self._fn(*args, **kwargs)
+
+    def _add_endpoint(self, decl: EndpointDeclaration) -> None:
+        name = decl.name or self.__name__
+        normalized = EndpointDeclaration(
+            name=name,
+            kind=decl.kind,
+            path=decl.path,
+            methods=decl.methods,
+            min_replicas=decl.min_replicas,
+            max_replicas=decl.max_replicas,
+            max_concurrent_inputs=(
+                decl.max_concurrent_inputs or self._max_concurrent_inputs
+            ),
+            scale_down_idle_seconds=decl.scale_down_idle_seconds,
+            max_queue_depth=decl.max_queue_depth,
+            reserved_replicas=decl.reserved_replicas,
+            public=decl.public,
+            port=decl.port,
+            startup_timeout_seconds=decl.startup_timeout_seconds,
+            autoscale=decl.autoscale,
+            snapshot=decl.snapshot,
+        )
+        self._endpoints.append(normalized)
+
+    def _set_concurrency(self, max_concurrent_inputs: int) -> None:
+        _validate_concurrency(max_concurrent_inputs)
+        self._max_concurrent_inputs = max_concurrent_inputs
+        for i, decl in enumerate(self._endpoints):
+            self._endpoints[i] = EndpointDeclaration(
+                name=decl.name,
+                kind=decl.kind,
+                path=decl.path,
+                methods=decl.methods,
+                min_replicas=decl.min_replicas,
+                max_replicas=decl.max_replicas,
+                max_concurrent_inputs=max_concurrent_inputs,
+                scale_down_idle_seconds=decl.scale_down_idle_seconds,
+                max_queue_depth=decl.max_queue_depth,
+                reserved_replicas=decl.reserved_replicas,
+                public=decl.public,
+                port=decl.port,
+                startup_timeout_seconds=decl.startup_timeout_seconds,
+                autoscale=decl.autoscale,
+                snapshot=decl.snapshot,
+            )
+
+    def _set_target_inputs(self, target_inputs: int) -> None:
+        if (
+            not isinstance(target_inputs, int)
+            or isinstance(target_inputs, bool)
+            or target_inputs < 1
+            or target_inputs > 100
+        ):
+            raise exc.InvalidArgumentError(
+                "SCALING_POLICY_INVALID",
+                "target_inputs must be an integer between 1 and 100",
+            )
+        self._target_inputs = target_inputs
+
+    # -- resource / handshake builders -------------------------------------
+
+    def _parse_gpu(self) -> tuple[str, int]:
+        """Parse ``self.gpu`` into ``(gpu_type, gpu_count)``.
+
+        Supports ``"RTX-A4500:4"`` syntax (scheduler-v2.md §5).
+        Validates gpu_count in [0, GPU_COUNT_MAX].
+        """
+        raw = self.gpu or "none"
+        if raw == "none":
+            return "none", 0
+        m = _GPU_COUNT_RE.match(raw)
+        if m:
+            gpu_type = m.group(1)
+            gpu_count = int(m.group(2))
+        else:
+            gpu_type = raw
+            gpu_count = 1
+        # Validate gpu_count (conventions.md §6: 0–8).
+        if gpu_count < GPU_COUNT_MIN or gpu_count > GPU_COUNT_MAX:
+            raise exc.InvalidArgumentError(
+                "INVALID_ARGUMENT",
+                f"gpu_count={gpu_count} is out of range [{GPU_COUNT_MIN}, {GPU_COUNT_MAX}]; "
+                f"use gpu=\"{gpu_type}:N\" with N between 1 and {GPU_COUNT_MAX}.",
+            )
+        return gpu_type, gpu_count
+
+    def _resource_spec(self) -> dict:
+        gpu_type, gpu_count = self._parse_gpu()
+        spec: dict[str, Any] = {"gpu_type": gpu_type, "gpu_count": gpu_count}
+        if self.cpu is not None:
+            # round() not int(): cpu=1.001 should map to 1001 millicores, not 1000
+            # (int truncates). Keeps the millicore value faithful to the request.
+            millicores = round(self.cpu * 1000)
+            # Server floor is 100 millicores (openapi ResourceSpec.cpu_millicores,
+            # conventions §6). Catch cpu<0.1 locally with a clear message instead of
+            # a late, opaque 400 INVALID_ARGUMENT from the server.
+            if millicores < 100:
+                raise exc.InvalidArgumentError(
+                    "INVALID_ARGUMENT",
+                    f"cpu={self.cpu!r} is below the minimum of 0.1 cores "
+                    f"(100 millicores); raise cpu= on @app.function.",
+                )
+            spec["cpu_millicores"] = millicores
+        else:
+            spec["cpu_millicores"] = DEFAULT_CPU_MILLICORES
+        spec["memory_mb"] = self.memory if self.memory is not None else DEFAULT_MEMORY_MB
+        spec["timeout_seconds"] = (
+            self.timeout if self.timeout is not None else DEFAULT_TIMEOUT_SECONDS
+        )
+        spec["idle_timeout_seconds"] = (
+            self.idle_timeout
+            if self.idle_timeout is not None
+            else DEFAULT_IDLE_TIMEOUT_SECONDS
+        )
+        return spec
+
+    def _function_ref(self) -> dict:
+        module = getattr(self._fn, "__module__", "__main__")
+        # The bundle root is the entrypoint script's directory; a function in the
+        # entrypoint module is importable as that script's module name. The CLI
+        # sets the module explicitly when running a file; in-process callers fall
+        # back to __module__.
+        module = self._app._module_for(module)
+        ref: dict[str, Any] = {"module": module, "qualname": self.__qualname__}
+        # @app.cls: class_name discriminates "instantiate then call method"
+        # from a plain function (runner-protocol.md §10). Absent for plain functions.
+        if self.class_name:
+            ref["class_name"] = self.class_name
+        # Parametrized @app.cls (bladekit.parameter): the bound values travel in the
+        # ref so the agent injects FORGE_FUNCTION_PARAMETERS and the runner
+        # instantiates the class with them (routing by parameter value). Absent
+        # (omitted) for a plain function or an unparametrized class.
+        if self.parameters:
+            ref["parameters"] = dict(self.parameters)
+        return ref
+
+    def _resolve_image(self) -> tuple[Optional[str], Optional[str]]:
+        """Resolve the image into ``(image_str, image_build_id)`` for the run body.
+
+        - ``bladekit.Image`` (DSL): ensure the build (idempotent), stream build
+          logs if not yet succeeded, then return its build id.
+        - string (alias / registry ref): returned as-is, build id None — except a
+          ``fabric/<name>`` alias, sent as ``forge/<name>`` (``to_wire_image``).
+        """
+        from ._image import Image
+
+        img = self.image if self.image is not None else self._app.default_image
+        if img is None:
+            raise exc.FabricError(
+                f"function {self.__name__!r} has no image: pass image=... to "
+                "@app.function or set a default image on the App."
+            )
+        if isinstance(img, Image):
+            build_id = self._app._ensure_image_build(img)
+            return None, build_id
+        from ._image import to_wire_image
+
+        return to_wire_image(img), None
+
+    # -- run lifecycle ------------------------------------------------------
+
+    def _ensure_run(self) -> str:
+        """Create (once) the run backing this function's calls in this process."""
+        if self._run_id is not None:
+            return self._run_id
+
+        client = self._app._require_client()
+        bundle_id = self._app._ensure_bundle()
+
+        from ._serialize import cloudpickle_version
+
+        # Resolve image first: a DSL image triggers (and waits on) a build,
+        # streaming build logs to the terminal. Either `image` or
+        # `image_build_id` is set, never both (RunCreateRequest, openapi).
+        image_str, image_build_id = self._resolve_image()
+
+        body: dict[str, Any] = {
+            "function": self._function_ref(),
+            "bundle_id": bundle_id,
+            "resources": self._resource_spec(),
+            "runtime": {
+                "python_version": _python_version(),
+                "cloudpickle_version": cloudpickle_version(),
+            },
+        }
+        if image_str is not None:
+            body["image"] = image_str
+        if image_build_id is not None:
+            body["image_build_id"] = image_build_id
+        if self.serve:
+            body["serve"] = True
+        volumes = self._volume_specs()
+        if volumes:
+            body["volumes"] = volumes
+        bucket_mounts = self._bucket_mount_specs()
+        if bucket_mounts:
+            body["bucket_mounts"] = bucket_mounts
+        secrets = self._secret_names()
+        if secrets:
+            body["secrets"] = secrets
+        if self._app.name:
+            body["app_name"] = self._app.name
+        # priority, namespace, retries (optional — absent = default behaviour).
+        if self.priority is not None:
+            _validate_priority(self.priority)
+            body["priority"] = self.priority
+        if self.namespace is not None:
+            body["namespace"] = self.namespace
+        if self.retries is not None:
+            body["retries"] = self.retries
+        # capacity class + preemption budget (m8-spot.md §13.6). Omitted
+        # when default so a default run body is byte-for-byte unchanged.
+        if self.gpu_class != "spot":
+            body["gpu_class"] = self.gpu_class
+        if self.best_effort:
+            body["best_effort"] = True
+        if self.max_interruptions is not None:
+            body["max_interruptions"] = self.max_interruptions
+        # dynamic batching config (batching.md §4). Omitted when the function is
+        # not batched so a default run body is byte-for-byte unchanged.
+        if self.batch_config is not None:
+            body["batch_config"] = self.batch_config
+
+        run = client.create_run(body)
+        self._run_id = run["run_id"]
+        _SESSION.client = client
+        _SESSION.register_run(self._run_id)
+        _emit_run_warnings(run)
+        return self._run_id
+
+    # -- volume / secret specs ------------------------------------------
+
+    def _volume_specs(self) -> list:
+        """Build VolumeMountSpec list, create-or-get volumes that ask for it."""
+        if not self.volumes:
+            return []
+        from ._bucket import CloudBucketMount
+        from ._volume import Volume
+
+        client = self._app._require_client()
+        specs = []
+        for mount_path, vol in self.volumes.items():
+            # CloudBucketMount rides in the same map but serializes separately
+            # (see _bucket_mount_specs); skip it here.
+            if isinstance(vol, CloudBucketMount):
+                continue
+            if not isinstance(vol, Volume):
+                raise exc.InvalidArgumentError(
+                    "INVALID_ARGUMENT",
+                    f"volumes[{mount_path!r}] must be a bladekit.Volume or "
+                    f"bladekit.CloudBucketMount, got {type(vol).__name__}",
+                )
+            if vol._create_if_missing:
+                client.create_volume(vol.name)
+            if vol._auto_commit_on_ready:
+                # Mirror of the server-side rule (runs.go): auto-commit fires
+                # on serving-ready, which one-shot runs never emit.
+                raise exc.InvalidArgumentError(
+                    "INVALID_ARGUMENT",
+                    f"volumes[{mount_path!r}]: auto_commit_on_ready is only "
+                    "valid on deployed web_server/asgi_app endpoints, not on "
+                    "one-shot runs",
+                )
+            if vol._auto_commit_every:
+                # Same rule, same reason: the periodic sweep is a replica
+                # feature, and a one-shot run commits with vol.commit().
+                raise exc.InvalidArgumentError(
+                    "INVALID_ARGUMENT",
+                    f"volumes[{mount_path!r}]: auto_commit_every is only valid "
+                    "on deployed web_server/asgi_app endpoints, not on "
+                    "one-shot runs",
+                )
+            spec: dict[str, Any] = {"name": vol.name, "mount_path": mount_path}
+            if vol._read_only:
+                spec["read_only"] = True
+            specs.append(spec)
+        return specs
+
+    def _secret_names(self) -> list:
+        if not self.secrets:
+            # No explicit secrets, but CloudBucketMount entries still need theirs.
+            return list(self._bucket_secret_names())
+        from ._secret import Secret
+
+        names = []
+        for s in self.secrets:
+            if not isinstance(s, Secret):
+                raise exc.InvalidArgumentError(
+                    "INVALID_ARGUMENT",
+                    f"secrets must be bladekit.Secret objects, got "
+                    f"{type(s).__name__}",
+                )
+            names.append(s.name)
+        # Fold in the secrets that back any CloudBucketMount so their credentials
+        # are injected as env vars (the runner reads them at mount time).
+        for name in self._bucket_secret_names():
+            if name not in names:
+                names.append(name)
+        return names
+
+    def _secret_name_refs(self) -> list[str]:
+        # Explicit secrets plus the secrets that back any CloudBucketMount (their
+        # credentials must be injected as env vars for the runner to mount).
+        names = [getattr(s, "name", str(s)) for s in (self.secrets or [])]
+        for name in self._bucket_secret_names():
+            if name not in names:
+                names.append(name)
+        return names
+
+    def _bucket_secret_names(self) -> list[str]:
+        """Secret names required by the function's CloudBucketMount entries."""
+        if not self.volumes:
+            return []
+        from ._bucket import CloudBucketMount
+
+        names: list[str] = []
+        for vol in self.volumes.values():
+            if isinstance(vol, CloudBucketMount) and vol.secret_name not in names:
+                names.append(vol.secret_name)
+        return names
+
+    def _bucket_mount_specs(self) -> list[dict]:
+        """Build the BucketMountSpec list from CloudBucketMount entries.
+
+        Each spec carries the bucket name, mount path, options, and the *name* of
+        the secret that provides credentials — never a credential value. The
+        control plane resolves the secret and injects its values as container env
+        vars (mirroring ``secrets=``); the runner mounts the bucket at start.
+        """
+        if not self.volumes:
+            return []
+        from ._bucket import CloudBucketMount
+
+        specs = []
+        for mount_path, vol in self.volumes.items():
+            if isinstance(vol, CloudBucketMount):
+                specs.append(vol._spec(mount_path))
+        return specs
+
+    def _volume_refs(self, *, include_auto_commit: bool = False) -> list[dict]:
+        """Deploy-path volume refs. Like _volume_specs(), honours
+        create_if_missing so a deployed endpoint's volume is created (the RUN
+        path did this; the DEPLOY path silently dropped it).
+
+        ``include_auto_commit``: only the ENDPOINT spec path carries the
+        auto-commit flag (it is validated against the endpoint kind there);
+        the function-manifest path omits it."""
+        if not self.volumes:
+            return []
+        from ._bucket import CloudBucketMount
+        from ._volume import Volume
+
+        client = self._app._require_client()
+        refs = []
+        for mount_path, vol in self.volumes.items():
+            # CloudBucketMount serializes via _bucket_mount_specs, not here.
+            if isinstance(vol, CloudBucketMount):
+                continue
+            if not isinstance(vol, Volume):
+                raise exc.InvalidArgumentError(
+                    "INVALID_ARGUMENT",
+                    f"volumes[{mount_path!r}] must be a bladekit.Volume or "
+                    f"bladekit.CloudBucketMount, got {type(vol).__name__}",
+                )
+            if vol._create_if_missing:
+                client.create_volume(vol.name)
+            ref: dict[str, Any] = {"name": vol.name, "mount_path": mount_path}
+            if include_auto_commit and vol._auto_commit_on_ready:
+                ref["auto_commit"] = True
+            if include_auto_commit and vol._auto_commit_every:
+                ref["auto_commit_interval_seconds"] = vol._auto_commit_every
+            if vol._read_only:
+                ref["read_only"] = True
+            refs.append(ref)
+        return refs
+
+    def _image_manifest(self) -> dict:
+        img = self.image if self.image is not None else self._app.default_image
+        if img is None:
+            return {}
+        from ._image import Image
+
+        if isinstance(img, Image):
+            return {
+                "image_definition": img.to_definition(),
+                "definition_hash": img.definition_hash(),
+            }
+        from ._image import to_wire_image
+
+        return {"image": to_wire_image(img)}
+
+    def _manifest_function(self) -> dict:
+        data: dict[str, Any] = {
+            "name": self.__name__,
+            "function": self._function_ref(),
+            "resources": self._resource_spec(),
+        }
+        if self.class_name:
+            data["class_name"] = self.class_name
+        image = self._image_manifest()
+        if image:
+            data.update(image)
+        secrets = self._secret_name_refs()
+        if secrets:
+            data["secrets"] = secrets
+        volumes = self._volume_refs()
+        if volumes:
+            data["volumes"] = volumes
+        bucket_mounts = self._bucket_mount_specs()
+        if bucket_mounts:
+            data["bucket_mounts"] = bucket_mounts
+        if self._max_concurrent_inputs is not None:
+            data["max_concurrent_inputs"] = self._max_concurrent_inputs
+        if self.batch_config is not None:
+            data["batch_config"] = self.batch_config
+        return data
+
+    def _cron_spec(self) -> Optional[dict]:
+        """Serialize this function's cron schedule for the deployment request.
+
+        Returns None if the function has no ``schedule=bladekit.Cron(...)``. The
+        server (handleCreateDeployment) inserts a cron_schedules row from this
+        (scheduler-v2.md §6, map-protocol.md is unrelated).
+        """
+        if self.schedule is None:
+            return None
+        res = self._resource_spec()
+        spec: dict[str, Any] = {
+            "name": self.__name__,
+            "cron_expr": self.schedule.expression,
+            "overlap_policy": self.schedule.overlap_policy,
+            "function": self._function_ref(),
+            "resources": {
+                "gpu_type": res["gpu_type"],
+                "gpu_count": res["gpu_count"],
+                "cpu_millicores": res["cpu_millicores"],
+                "memory_mb": res["memory_mb"],
+                "timeout_seconds": res["timeout_seconds"],
+            },
+        }
+        if self.priority is not None:
+            spec["priority"] = self.priority
+        if self.namespace is not None:
+            spec["namespace"] = self.namespace
+        return spec
+
+    def _endpoint_specs(self) -> list[dict]:
+        specs = []
+        for decl in self._endpoints:
+            autoscaling = _autoscaling_spec(
+                min_replicas=decl.min_replicas,
+                max_replicas=decl.max_replicas,
+                max_concurrent_inputs=(
+                    decl.max_concurrent_inputs or self._max_concurrent_inputs
+                ),
+                scale_down_idle_seconds=decl.scale_down_idle_seconds,
+                max_queue_depth=decl.max_queue_depth,
+                reserved_replicas=decl.reserved_replicas,
+            )
+            # Autoscaling v2: fold the endpoint's Autoscale and the
+            # function-level @app.concurrent(target_inputs=) into the wire
+            # policy ({"v":1, ...}); None when neither is declared (v1).
+            policy = _scaling_policy_spec(
+                autoscale=decl.autoscale,
+                fn_target_inputs=self._target_inputs,
+                max_concurrent_inputs=autoscaling["max_concurrent_inputs"],
+                kind=decl.kind,
+            )
+            if policy is not None:
+                autoscaling["scaling_policy"] = policy
+            spec = {
+                "name": decl.name or self.__name__,
+                "kind": decl.kind,
+                "function": self._function_ref(),
+                "path": decl.path,
+                "methods": list(decl.methods),
+                "resources": self._resource_spec(),
+                "autoscaling": autoscaling,
+            }
+            # Deploy path: carry the function's volume mounts so replicas mount
+            # them (create-or-get volumes that ask for it). Mirrors the run path.
+            # auto_commit_on_ready rides only on local-server kinds (the commit
+            # fires on serving-ready) — validated here, mirror of the server rule.
+            volumes = self._volume_refs(include_auto_commit=True)
+            if decl.kind not in ("web_server", "asgi_app"):
+                for v in volumes:
+                    if v.get("auto_commit"):
+                        raise exc.InvalidArgumentError(
+                            "INVALID_ARGUMENT",
+                            f"volumes[{v['mount_path']!r}]: auto_commit_on_ready "
+                            f"requires a web_server or asgi_app endpoint, not "
+                            f"{decl.kind!r}",
+                        )
+                    if v.get("auto_commit_interval_seconds"):
+                        raise exc.InvalidArgumentError(
+                            "INVALID_ARGUMENT",
+                            f"volumes[{v['mount_path']!r}]: auto_commit_every "
+                            f"requires a web_server or asgi_app endpoint, not "
+                            f"{decl.kind!r}",
+                        )
+            if volumes:
+                spec["volumes"] = volumes
+            # Carry the function's bucket mounts so each replica mounts them
+            # (mirrors the run path). The backing secret rides in `secrets` below.
+            bucket_mounts = self._bucket_mount_specs()
+            if bucket_mounts:
+                spec["bucket_mounts"] = bucket_mounts
+            # Carry the function's secrets so each replica gets them injected as
+            # env vars (mirrors the run path). Without this, secrets on a
+            # web_server/asgi_app/web_endpoint deployment are silently dropped.
+            secrets = self._secret_name_refs()
+            if secrets:
+                spec["secrets"] = secrets
+            if decl.public:
+                spec["public"] = True
+            # §13.5: local HTTP server endpoints (web_server / asgi_app). The key
+            # names MUST match openapi EndpointSpec (server_port /
+            # startup_timeout_seconds). Emitted only when set, mirroring `public`.
+            if decl.port is not None:
+                spec["server_port"] = decl.port
+            if decl.startup_timeout_seconds is not None:
+                spec["startup_timeout_seconds"] = decl.startup_timeout_seconds
+            # GPU snapshot opt-in (coldstart-snapshot.md §5). Emitted only when
+            # True (mirrors `public`). Local mirror of the server rule: valid
+            # ONLY on web_server with gpu_count==1 — fail here, before any
+            # network call, instead of on a late 400 INVALID_ARGUMENT.
+            if decl.snapshot:
+                _, gpu_count = self._parse_gpu()
+                if decl.kind != "web_server" or gpu_count != 1:
+                    raise exc.InvalidArgumentError(
+                        "INVALID_ARGUMENT",
+                        "snapshot=True requires web_server with a single GPU "
+                        "(gpu_count==1)",
+                    )
+                spec["snapshot"] = True
+            # deployed endpoint's capacity class (m8-spot.md §13.1/§13.6,
+            # EndpointSpec.gpu_class). Omitted when default ("spot"), mirroring
+            # how `public` is only emitted when non-default.
+            if self.gpu_class != "spot":
+                spec["gpu_class"] = self.gpu_class
+            # dynamic batching config (batching.md §4). The runner reads it from
+            # the deployed endpoint to fuse concurrent requests into batches.
+            if self.batch_config is not None:
+                spec["batch_config"] = self.batch_config
+            specs.append(spec)
+        return specs
+
+    def _enqueue_call(self, args: tuple, kwargs: dict) -> tuple[str, str]:
+        from ._serialize import dumps_args, make_payload_in
+
+        client = self._app._require_client()
+
+        # Serialize and UPLOAD BEFORE the run exists. A run's idle_timeout_seconds
+        # starts running against it the moment it can accept work, so anything done
+        # between creating the run and posting the call is charged to that budget.
+        # An out-of-line payload is a PUT of the caller's arguments to the object
+        # store over the caller's uplink: 7 MB of audio measured 1.2s on a good
+        # link and 28s on a normal one, and the ordering made that difference a
+        # lifecycle risk for the run rather than just latency. The payload is
+        # org-scoped and only bound to a run when the call is created, so it does
+        # not need the run to exist yet.
+        raw = dumps_args(args, kwargs)
+        payload_in, object_bytes = make_payload_in(raw)
+        if object_bytes is not None:
+            decl = client.create_payload(payload_in["size_bytes"], payload_in["sha256"])
+            client.upload_to_presigned(
+                decl["put_url"], object_bytes, "application/octet-stream"
+            )
+            payload_in["payload_id"] = decl["payload_id"]
+
+        run_id = self._ensure_run()
+
+        try:
+            call = client.create_call(run_id, payload_in)
+        except exc.ConflictError as e:
+            if e.code == "RUN_NOT_ACCEPTING_CALLS":
+                # Race: the run failed at startup (IMAGE_PULL_FAILED,
+                # CONTAINER_FAILED, PYTHON_VERSION_MISMATCH, …) between
+                # _ensure_run and create_call.  The stub and control-plane both
+                # return RUN_NOT_ACCEPTING_CALLS when a call is posted to a
+                # terminal run. Fetch the run's actual error and raise the
+                # correct, actionable RunError instead of the generic conflict.
+                self._check_run_terminal(client, run_id)
+                # If _check_run_terminal did not raise (e.g. the run moved to
+                # succeeded or back to a live state), propagate the original
+                # error.
+            raise
+        return run_id, call["call_id"]
+
+    # -- public invocation --------------------------------------------------
+
+    def spawn(self, *args: Any, **kwargs: Any) -> FunctionCall:
+        """Fire-and-forget: enqueue a call, return a handle (non-blocking).
+
+        IMPORTANT — semantics differ from Modal. ``.spawn()`` appends a
+        call to the SAME run (and therefore the SAME hot container) as every
+        other ``.remote()`` / ``.spawn()`` of this function in this process.
+        Calls run **FIFO, one at a time** on that one container — ``.spawn()``
+        does NOT start a parallel container. So two ``.spawn()`` calls do not run
+        concurrently; the second waits for the first. (True fan-out across the
+        fleet — concurrent containers — arrives with ``Function.map()``.)
+        """
+        run_id, call_id = self._enqueue_call(args, kwargs)
+        return FunctionCall(self, run_id, call_id)
+
+    def remote(self, *args: Any, **kwargs: Any) -> Any:
+        """Blocking remote call: returns the result or re-raises the remote error."""
+        run_id, call_id = self._enqueue_call(args, kwargs)
+        return self._await_call(call_id, run_id, timeout=None)
+
+    def map(
+        self,
+        iterable: Any,
+        *,
+        order: str = "index",
+        return_exceptions: bool = False,
+        retries: Optional[dict] = None,
+        input_timeout_seconds: Optional[int] = None,
+        priority: Optional[int] = None,
+        namespace: Optional[str] = None,
+        max_concurrency: Optional[int] = None,
+    ):
+        """Fan-out ``f(x)`` over an iterable on the GPU fleet.
+
+        Yields results in the same order as the input iterable by default
+        (``order="index"``).  Use ``order="arrival"`` for maximum throughput
+        when order does not matter.
+
+        The batch is persisted server-side: a client disconnect does NOT lose
+        work. Inputs are pushed in streaming chunks so a 1 M-item iterable
+        never sits in memory.
+
+        Args:
+            iterable: Any Python iterable of arguments.  Each element is passed
+                as the *sole positional argument* to the function.
+            order: ``"index"`` (default) or ``"arrival"``.
+            return_exceptions: if ``True``, exceptions are yielded in-place
+                instead of raising; the generator never stops early.  If
+                ``False`` (default), the first failed input raises immediately.
+            retries: override the retry policy for this batch, e.g.
+                ``{"max_retries": 3, "backoff": {"initial_seconds": 1,
+                "max_seconds": 60, "factor": 2.0}}``.
+            input_timeout_seconds: per-input timeout (distinct from the run
+                global ``timeout=``).
+            priority: scheduling priority 0–9 (9=urgent, 0=best-effort batch).
+                Defaults to the function's priority or 5 (FIFO).
+            namespace: override the namespace for quota accounting.
+            max_concurrency: cap on concurrent worker runs for this batch.
+
+        Yields:
+            The return value of the function for each input, in ``order`` order.
+        """
+        # Wrap each item as (args=(item,), kwargs={}) for the wire format.
+        def _items():
+            for item in iterable:
+                yield (item,), {}
+
+        yield from self._run_map(
+            _items(),
+            order=order,
+            return_exceptions=return_exceptions,
+            retries=retries,
+            input_timeout_seconds=input_timeout_seconds,
+            priority=priority,
+            namespace=namespace,
+            max_concurrency=max_concurrency,
+        )
+
+    def starmap(
+        self,
+        iterable: Any,
+        *,
+        order: str = "index",
+        return_exceptions: bool = False,
+        retries: Optional[dict] = None,
+        input_timeout_seconds: Optional[int] = None,
+        priority: Optional[int] = None,
+        namespace: Optional[str] = None,
+        max_concurrency: Optional[int] = None,
+    ):
+        """Fan-out ``f(*args)`` over an iterable of arg tuples.
+
+        Like ``itertools.starmap``: each element of ``iterable`` is unpacked
+        as positional arguments to the function.
+
+        Args:
+            iterable: An iterable of tuples; each tuple is splatted as
+                positional args.  A tuple ``(a, b)`` maps to ``f(a, b)``.
+            (remaining args: same as :meth:`map`)
+
+        Yields:
+            The return value of the function for each input.
+        """
+        def _items():
+            for item in iterable:
+                if not isinstance(item, tuple):
+                    item = tuple(item)
+                yield item, {}
+
+        yield from self._run_map(
+            _items(),
+            order=order,
+            return_exceptions=return_exceptions,
+            retries=retries,
+            input_timeout_seconds=input_timeout_seconds,
+            priority=priority,
+            namespace=namespace,
+            max_concurrency=max_concurrency,
+        )
+
+    def spawn_map(
+        self,
+        iterable: Any,
+        *,
+        retries: Optional[dict] = None,
+        input_timeout_seconds: Optional[int] = None,
+        priority: Optional[int] = None,
+        namespace: Optional[str] = None,
+        max_concurrency: Optional[int] = None,
+    ) -> "MapHandle":
+        """Fire an async fan-out of ``f(x)`` over an iterable; return a handle.
+
+        ``spawn_map`` is to :meth:`map` what :meth:`spawn` is to :meth:`remote`:
+        it combines ``spawn`` + ``map``. It creates the batch, pushes every
+        input, and finalizes it server-side, then returns a
+        :class:`~bladekit._map.MapHandle` IMMEDIATELY — it never blocks waiting for
+        results. The batch is durable server-side, so you can poll it, walk away,
+        or re-attach from another process with ``blade map resume <map_id>``.
+
+        Collect results later by iterating ``handle.results()`` (same ``order`` /
+        ``return_exceptions`` options as :meth:`map`), inspect progress with
+        ``handle.status()``, or stop it with ``handle.cancel()``.
+
+        Args:
+            iterable: any iterable of arguments; each element is passed as the
+                sole positional argument to the function (like :meth:`map`).
+            (remaining args: same as :meth:`map`, minus ``order`` /
+            ``return_exceptions`` — those are chosen when reading results.)
+
+        Returns:
+            A :class:`~bladekit._map.MapHandle` for the in-flight batch.
+        """
+        def _items():
+            for item in iterable:
+                yield (item,), {}
+
+        return self._spawn_map(
+            _items(),
+            retries=retries,
+            input_timeout_seconds=input_timeout_seconds,
+            priority=priority,
+            namespace=namespace,
+            max_concurrency=max_concurrency,
+        )
+
+    def spawn_starmap(
+        self,
+        iterable: Any,
+        *,
+        retries: Optional[dict] = None,
+        input_timeout_seconds: Optional[int] = None,
+        priority: Optional[int] = None,
+        namespace: Optional[str] = None,
+        max_concurrency: Optional[int] = None,
+    ) -> "MapHandle":
+        """Like :meth:`spawn_map`, but each element is splatted as positional args.
+
+        The ``starmap`` counterpart of :meth:`spawn_map`: a tuple ``(a, b)`` maps
+        to ``f(a, b)``. Returns a :class:`~bladekit._map.MapHandle` without blocking.
+        """
+        def _items():
+            for item in iterable:
+                if not isinstance(item, tuple):
+                    item = tuple(item)
+                yield item, {}
+
+        return self._spawn_map(
+            _items(),
+            retries=retries,
+            input_timeout_seconds=input_timeout_seconds,
+            priority=priority,
+            namespace=namespace,
+            max_concurrency=max_concurrency,
+        )
+
+    def _spawn_map(
+        self,
+        inputs,
+        *,
+        retries: Optional[dict],
+        input_timeout_seconds: Optional[int],
+        priority: Optional[int],
+        namespace: Optional[str],
+        max_concurrency: Optional[int],
+    ) -> "MapHandle":
+        """Shared implementation for spawn_map()/spawn_starmap()."""
+        from ._map import spawn_map as _spawn_map_impl
+        from ._serialize import cloudpickle_version
+
+        client = self._app._require_client()
+        bundle_id = self._app._ensure_bundle()
+        image_str, image_build_id = self._resolve_image()
+
+        eff_priority = priority if priority is not None else self.priority
+        if eff_priority is not None:
+            _validate_priority(eff_priority)
+        eff_namespace = namespace if namespace is not None else self.namespace
+        eff_retries = (
+            _normalize_retries(retries) if retries is not None else self.retries
+        )
+
+        return _spawn_map_impl(
+            client,
+            function_ref=self._function_ref(),
+            bundle_id=bundle_id,
+            resource_spec=self._resource_spec(),
+            runtime={
+                "python_version": _python_version(),
+                "cloudpickle_version": cloudpickle_version(),
+            },
+            image=image_str,
+            image_build_id=image_build_id,
+            app_name=self._app.name if self._app.name else None,
+            inputs=inputs,
+            retries=eff_retries,
+            input_timeout_seconds=input_timeout_seconds,
+            priority=eff_priority,
+            namespace=eff_namespace,
+            max_concurrency=max_concurrency,
+            gpu_class=self.gpu_class,
+            best_effort=self.best_effort,
+            max_interruptions=self.max_interruptions,
+        )
+
+    def _run_map(
+        self,
+        inputs,
+        *,
+        order: str,
+        return_exceptions: bool,
+        retries: Optional[dict],
+        input_timeout_seconds: Optional[int],
+        priority: Optional[int],
+        namespace: Optional[str],
+        max_concurrency: Optional[int],
+    ):
+        """Shared implementation for map()/starmap()."""
+        from ._map import run_map
+        from ._serialize import cloudpickle_version
+
+        client = self._app._require_client()
+        bundle_id = self._app._ensure_bundle()
+        image_str, image_build_id = self._resolve_image()
+
+        # Priority: explicit argument > function default > contract default (5).
+        eff_priority = priority if priority is not None else self.priority
+        if eff_priority is not None:
+            _validate_priority(eff_priority)
+
+        # Namespace: explicit argument > function default.
+        eff_namespace = namespace if namespace is not None else self.namespace
+
+        # Retries: explicit argument > function default. Both accept an int
+        # shorthand or a RetryPolicy dict (self.retries is already normalized).
+        eff_retries = _normalize_retries(retries) if retries is not None else self.retries
+
+        yield from run_map(
+            client,
+            function_ref=self._function_ref(),
+            bundle_id=bundle_id,
+            resource_spec=self._resource_spec(),
+            runtime={
+                "python_version": _python_version(),
+                "cloudpickle_version": cloudpickle_version(),
+            },
+            image=image_str,
+            image_build_id=image_build_id,
+            app_name=self._app.name if self._app.name else None,
+            inputs=inputs,
+            order=order,
+            return_exceptions=return_exceptions,
+            retries=eff_retries,
+            input_timeout_seconds=input_timeout_seconds,
+            priority=eff_priority,
+            namespace=eff_namespace,
+            max_concurrency=max_concurrency,
+            # the batch's worker runs carry the function's capacity class
+            # and preemption budget (m8-spot.md §13.6).
+            gpu_class=self.gpu_class,
+            best_effort=self.best_effort,
+            max_interruptions=self.max_interruptions,
+        )
+
+    # -- result resolution --------------------------------------------------
+
+    def _await_call(
+        self, call_id: str, run_id: str, *, timeout: Optional[float]
+    ) -> Any:
+        client = self._app._require_client()
+        deadline = None if timeout is None else time.monotonic() + timeout
+        interval = POLL_INITIAL_INTERVAL
+
+        while True:
+            call = client.get_call(call_id)
+            state = call.get("state")
+
+            if state in CALL_TERMINAL_STATES:
+                return self._resolve_terminal_call(call, run_id)
+
+            # A cold-start infra failure (PYTHON_VERSION_MISMATCH, IMAGE_PULL_FAILED,
+            # BUNDLE_FETCH_FAILED, CONTAINER_FAILED, NODE_LOST, …) fails the *run*
+            # before any call is claimed, so the call stays `pending` forever
+            # (schema.sql has no pending→failed call transition for infra). Poll the
+            # run too and surface its error, otherwise `.remote(timeout=None)` hangs
+            # instead of raising the clear error the contract promises (runner-
+            # protocol.md §5). We only need this while the call hasn't been
+            # claimed (`pending`): once `running`, the call itself becomes terminal
+            # (running→failed via the agent handler) and carries the error.
+            if state == "pending":
+                self._check_run_terminal(client, run_id)
+
+            if deadline is not None and time.monotonic() >= deadline:
+                raise exc.FabricError(
+                    f"timed out after {timeout}s waiting for call {call_id} "
+                    f"(state={state})"
+                )
+
+            time.sleep(interval)
+            interval = min(interval * 1.5, POLL_MAX_INTERVAL)
+
+    def _check_run_terminal(self, client: Any, run_id: str) -> None:
+        """Raise if the run reached a non-succeeded terminal state.
+
+        Used to break out of waiting on a call that will never be claimed because
+        the run failed at startup. A run in ``succeeded`` with the call still
+        non-terminal is left alone (the call result lands shortly after).
+        """
+        run = client.get_run(run_id)
+        run_state = run.get("state")
+        if run_state == "lost":
+            err = run.get("error") or {
+                "code": "NODE_LOST",
+                "message": "run lost before the call ran",
+            }
+            raise exc.run_lost_from_payload(err, run_id=run_id)
+        if run_state == "failed":
+            err = run.get("error")
+            if err:
+                raise exc.run_error_from_payload(err, run_id=run_id)
+            raise exc.run_error_from_payload(
+                {"code": "INTERNAL", "message": "run failed before the call ran"},
+                run_id=run_id,
+            )
+        if run_state == "cancelled":
+            raise exc.RunCancelled(run_id)
+
+    def _resolve_terminal_call(self, call: dict, run_id: str) -> Any:
+        from ._serialize import decode_payload_out, loads
+
+        client = self._app._require_client()
+        state = call.get("state")
+
+        if state == "succeeded":
+            result = call.get("result")
+            if result is None:
+                return None
+            raw = decode_payload_out(result, fetch=client.download_presigned)
+            return loads(raw)
+
+        if state == "failed":
+            # User exception vs infra error are mutually exclusive (openapi Call).
+            user_exc = call.get("exception")
+            if user_exc:
+                raise self._build_remote_exception(user_exc, client)
+            err = call.get("error")
+            if err:
+                raise exc.run_error_from_payload(err, run_id=run_id)
+            raise exc.RunError("call failed without details", run_id=run_id)
+
+        if state == "cancelled":
+            # A pending call is moved to `cancelled` when its RUN fails at
+            # startup (IMAGE_PULL_FAILED, CONTAINER_FAILED, NODE_LOST, …) before
+            # the call is ever claimed — the call carries no error then. Surface
+            # the RUN's actual error so the user sees the real cause and a
+            # non-zero exit, not a misleading "run cancelled" (GPU-PILOT-REPORT
+            # UX debt). Only fall back to RunCancelled if the run was genuinely
+            # cancelled (or has no failure recorded).
+            self._check_run_terminal(client, run_id)
+            raise exc.RunCancelled(run_id)
+
+        if state == "lost":
+            err = call.get("error") or {"code": "NODE_LOST", "message": "call lost"}
+            raise exc.run_lost_from_payload(err, run_id=run_id)
+
+        raise exc.FabricError(f"unexpected terminal call state {state!r}")
+
+    def _build_remote_exception(self, info: dict, client: Any) -> BaseException:
+        """Reconstruct (or wrap) the remote user exception.
+
+        Prefer re-raising the *original* exception (so user ``except`` clauses
+        work) when ``pickled`` is present and unpickles; attach the remote
+        traceback to its message. Otherwise raise the generic
+        ``RemoteFunctionError`` carrying the traceback.
+        """
+        from ._serialize import decode_payload_out, loads
+
+        exc_type = info.get("type", "Exception")
+        message = info.get("message", "")
+        tb = info.get("traceback_str", "")
+
+        pickled = info.get("pickled")
+        if pickled:
+            try:
+                raw = decode_payload_out(pickled, fetch=client.download_presigned)
+                original = loads(raw)
+                if isinstance(original, BaseException):
+                    # Surface the remote traceback on the re-raised exception so
+                    # it reads "as if local".
+                    original._forge_remote_traceback = tb  # type: ignore[attr-defined]
+                    note = f"\n\n--- remote traceback ---\n{tb}"
+                    if hasattr(original, "add_note"):
+                        try:
+                            original.add_note(note)  # py3.11+
+                        except Exception:
+                            pass
+                    return original
+            except Exception:
+                pass  # fall through to generic wrapper
+
+        return exc.RemoteFunctionError(exc_type, message, tb)
+
+
+_MISSING = object()
+
+
+# function_calls.state → the async-handle status vocabulary (async-jobs-study.md
+# §3.3), aligned with Runpod/Replicate.
+_ASYNC_STATE_MAP = {
+    "pending": "queued",
+    "running": "running",
+    "succeeded": "completed",
+    "failed": "failed",
+    "cancelled": "cancelled",
+    "lost": "failed",
+}
+
+
+class DeployedFunctionCall:
+    """Pollable handle to an async job spawned on a deployed endpoint.
+
+    Returned by ``Function.from_name(app, fn).spawn(...)`` (async-jobs-study.md).
+    Re-attach from another process with ``DeployedFunctionCall.from_id(call_id)``.
+    Distinct from ``FunctionCall`` (which decodes a cloudpickle result): here the
+    result is the JSON body the deployed endpoint returned.
+    """
+
+    def __init__(
+        self, client: Any, call_id: str, *, webhook_secret: Optional[str] = None
+    ) -> None:
+        self._client = client
+        self.call_id = call_id
+        self.webhook_secret = webhook_secret  # returned once if the CP generated it
+
+    def __repr__(self) -> str:
+        return f"<bladekit.DeployedFunctionCall {self.call_id}>"
+
+    @classmethod
+    def from_id(cls, call_id: str, *, client: Any = None) -> "DeployedFunctionCall":
+        """Re-attach to an async job by id from any process (parity Modal)."""
+        if client is None:
+            from ._client import Client
+            from .config import load_config
+
+            cfg = load_config()
+            if not cfg.token:
+                raise exc.AuthenticationError(
+                    "UNAUTHENTICATED",
+                    "no token configured: run `blade token set <token>` or set FABRIC_TOKEN",
+                )
+            client = Client(cfg.api_url, cfg.token)
+        return cls(client, call_id)
+
+    @property
+    def object_id(self) -> str:  # parity Modal
+        return self.call_id
+
+    def status(self) -> str:
+        """Current status: queued|running|completed|failed|cancelled."""
+        st = self._client.get_call(self.call_id).get("state", "")
+        return _ASYNC_STATE_MAP.get(st, st)
+
+    def cancel(self) -> None:
+        """Cancel the job (best-effort; the shared replica keeps running)."""
+        self._client.cancel_call(self.call_id)
+
+    def get(self, timeout: Optional[float] = None) -> Any:
+        """Block until terminal; return the endpoint's decoded JSON body.
+
+        Raises on a failed/cancelled/lost job. ``timeout`` bounds the wait in
+        seconds (None waits indefinitely; 0 polls once then raises if not done).
+        """
+        deadline = None if timeout is None else time.monotonic() + timeout
+        interval = POLL_INITIAL_INTERVAL
+        while True:
+            call = self._client.get_call(self.call_id)
+            state = call.get("state", "")
+            if state in CALL_TERMINAL_STATES:
+                if state != "succeeded":
+                    exc_info = call.get("exception") or {}
+                    err = call.get("error") or {}
+                    msg = (
+                        exc_info.get("message")
+                        or err.get("message")
+                        or f"async call {self.call_id} ended {state}"
+                    )
+                    code = err.get("code") or exc_info.get("type") or state.upper()
+                    raise exc.FabricError(f"{code}: {msg}")
+                return _decode_async_body(call)
+            if deadline is not None and time.monotonic() >= deadline:
+                raise exc.TimeoutError_(
+                    f"async call {self.call_id} not finished within {timeout}s"
+                )
+            time.sleep(interval)
+            interval = min(interval * 2, POLL_MAX_INTERVAL)
+
+
+def _decode_async_body(call: dict) -> Any:
+    """Decode http_response.body from a succeeded async call: inline_b64 XOR a
+    presigned get_url (async-jobs-study.md §3.5). Returns parsed JSON, or the raw
+    text if the body is not JSON, or None if empty."""
+    import base64
+    import json as _json
+
+    resp = call.get("http_response") or {}
+    body = resp.get("body") or {}
+    raw = b""
+    if "inline_b64" in body:
+        raw = base64.b64decode(body["inline_b64"])
+    elif body.get("get_url"):
+        import urllib.request
+
+        with urllib.request.urlopen(body["get_url"], timeout=60) as r:  # noqa: S310
+            raw = r.read()
+    if not raw:
+        return None
+    try:
+        return _json.loads(raw)
+    except Exception:
+        return raw.decode("utf-8", "replace")
+
+
+def _absolute_endpoint_url(endpoint: Optional[dict]) -> Optional[str]:
+    """The endpoint's own address, when the server reports an absolute one.
+
+    The server decides which ingress is live and says so in the endpoint's `url`:
+    relative (`/serve/<app>/<path>`) while the path route is registered, absolute
+    (`https://<app>.<domain><path>`) once it has been retired. Following it lets the
+    SDK move with the deployment instead of hard-coding a route that may be gone, and
+    an older control plane — which always reports the relative form — is unaffected.
+
+    None means the caller builds the path form, exactly as before. `request(path=...)`
+    skips the endpoint resolve entirely, so it always takes that branch.
+    """
+    url = (endpoint or {}).get("url")
+    if isinstance(url, str) and url.startswith(("http://", "https://")):
+        return url
+    return None
+
+
+class _NamedFunction:
+    def __init__(
+        self, app_name: str, function_name: str, version: Optional[int] = None
+    ) -> None:
+        if not isinstance(app_name, str) or not app_name:
+            raise exc.InvalidArgumentError("INVALID_ARGUMENT", "app_name must be non-empty")
+        if not isinstance(function_name, str) or not function_name:
+            raise exc.InvalidArgumentError(
+                "INVALID_ARGUMENT", "function_name must be non-empty"
+            )
+        if version is not None and (not isinstance(version, int) or isinstance(version, bool)):
+            raise exc.InvalidArgumentError(
+                "INVALID_ARGUMENT", "version must be an int (a deployment version)"
+            )
+        if version is not None and version < 1:
+            raise exc.InvalidArgumentError(
+                "INVALID_ARGUMENT", "version must be >= 1"
+            )
+        self.app_name = app_name
+        self.function_name = function_name
+        self.version = version
+        self._client: Any = None
+        self._endpoint: Optional[dict] = None
+
+    def __repr__(self) -> str:
+        return f"<bladekit.Function.from_name {self.app_name}.{self.function_name}>"
+
+    def _require_client(self) -> Any:
+        if self._client is None:
+            from ._client import Client
+            from .config import load_config
+
+            cfg = load_config()
+            if not cfg.token:
+                raise exc.AuthenticationError(
+                    "UNAUTHENTICATED",
+                    "no token configured: run `blade token set <token>` or set "
+                    "FABRIC_TOKEN",
+                )
+            self._client = Client(cfg.api_url, cfg.token)
+            self._client.warn_if_outdated()
+        return self._client
+
+    def _resolve_endpoint(self) -> dict:
+        if self._endpoint is not None:
+            return self._endpoint
+
+        client = self._require_client()
+        app_obj = client.get_app_by_name(self.app_name)
+        if app_obj.get("state") == "stopped":
+            raise exc.UnavailableError(
+                "APP_STOPPED", f"app {self.app_name!r} is stopped"
+            )
+        deployment = client.get_active_deployment_for_app(app_obj)
+        # Resolve-and-VERIFY pinning. The resolved endpoint is cached for this
+        # object's lifetime, so a long-lived caller that resolved before a
+        # rollback keeps routing to whatever is active now — silently, and with a
+        # different version of the code answering. version=N does not pin
+        # EXECUTION to a dead deployment (nothing serves it); it turns that silent
+        # drift into a deterministic error the caller can retry or fail on.
+        if self.version is not None:
+            active = deployment.get("version")
+            if active != self.version:
+                raise exc.NotFoundError(
+                    "DEPLOYMENT_VERSION_MISMATCH",
+                    f"app {self.app_name!r} is serving version {active!r}, not the "
+                    f"pinned version {self.version}; the app was redeployed or "
+                    "rolled back. Drop version= to follow the active deployment.",
+                )
+        endpoints = deployment.get("endpoints") or []
+        if not endpoints:
+            raise exc.NotFoundError(
+                "DEPLOYMENT_NOT_FOUND",
+                f"app {self.app_name!r} has no deployed web endpoints",
+            )
+
+        selector = self.function_name
+        matches = [
+            ep for ep in endpoints if _endpoint_matches_selector(ep, selector)
+        ]
+        if not matches:
+            available = ", ".join(
+                sorted(
+                    str(ep.get("name") or ep.get("path"))
+                    for ep in endpoints
+                    if ep.get("name") or ep.get("path")
+                )
+            )
+            suffix = f"; available endpoints: {available}" if available else ""
+            raise exc.NotFoundError(
+                "NOT_FOUND",
+                f"no web endpoint {selector!r} on deployed app {self.app_name!r}"
+                f"{suffix}",
+            )
+        if len(matches) > 1:
+            raise exc.InvalidArgumentError(
+                "INVALID_ARGUMENT",
+                f"endpoint selector {selector!r} is ambiguous; pass a path like "
+                "'/predict' instead",
+            )
+        self._endpoint = matches[0]
+        return self._endpoint
+
+    def request(
+        self,
+        *,
+        method: str = "POST",
+        path: Optional[str] = None,
+        json: Any = None,
+        headers: Optional[Mapping[str, str]] = None,
+        params: Optional[Mapping[str, Any]] = None,
+    ) -> Any:
+        """Invoke the deployed web endpoint over HTTP and return JSON."""
+        endpoint = None if path else self._resolve_endpoint()
+        endpoint_path = path or str((endpoint or {}).get("path"))
+        if not endpoint_path.startswith("/"):
+            endpoint_path = f"/{endpoint_path}"
+        try:
+            return self._require_client().invoke_web_endpoint(
+                self.app_name,
+                endpoint_path,
+                method=method,
+                json=json,
+                headers=headers,
+                params=params,
+                url=_absolute_endpoint_url(endpoint),
+            )
+        except exc.NotFoundError:
+            # The cached endpoint went stale mid-flight (redeploy or rollback
+            # dropped this path). Re-resolve ONCE against the now-active
+            # deployment and retry. Only for a resolved endpoint: an explicit
+            # path= is the caller's own routing, so its 404 is the real answer.
+            #
+            # Under version=, the re-resolve is what converts a bare 404 into the
+            # DEPLOYMENT_VERSION_MISMATCH above, which says what actually changed.
+            if path is not None or self._endpoint is None:
+                raise
+            self._endpoint = None
+            retry_endpoint = self._resolve_endpoint()
+            retry_path = str(retry_endpoint.get("path"))
+            if not retry_path.startswith("/"):
+                retry_path = f"/{retry_path}"
+            # The re-resolved endpoint's OWN url, not the stale one's: the very
+            # redeploy that invalidated the path is what retires a path route and
+            # turns the server's reported url absolute, so reusing the first
+            # endpoint's answer here would retry against the address that just
+            # went away.
+            return self._require_client().invoke_web_endpoint(
+                self.app_name,
+                retry_path,
+                method=method,
+                json=json,
+                headers=headers,
+                params=params,
+                url=_absolute_endpoint_url(retry_endpoint),
+            )
+
+    def web(
+        self,
+        payload: Any = _MISSING,
+        *,
+        method: str = "POST",
+        path: Optional[str] = None,
+        headers: Optional[Mapping[str, str]] = None,
+        params: Optional[Mapping[str, Any]] = None,
+        **json_fields: Any,
+    ) -> Any:
+        return self.remote_json(
+            payload,
+            method=method,
+            path=path,
+            headers=headers,
+            params=params,
+            **json_fields,
+        )
+
+    def remote_json(
+        self,
+        payload: Any = _MISSING,
+        *,
+        method: str = "POST",
+        path: Optional[str] = None,
+        headers: Optional[Mapping[str, str]] = None,
+        params: Optional[Mapping[str, Any]] = None,
+        **json_fields: Any,
+    ) -> Any:
+        """POST a JSON payload to the matching deployed web endpoint."""
+        if payload is not _MISSING and json_fields:
+            raise exc.InvalidArgumentError(
+                "INVALID_ARGUMENT",
+                "remote_json accepts either one payload or keyword JSON fields, not both",
+            )
+        body = json_fields if payload is _MISSING and json_fields else payload
+        if body is _MISSING:
+            body = None
+        return self.request(
+            method=method,
+            path=path,
+            json=body,
+            headers=headers,
+            params=params,
+        )
+
+    def remote(self, *args: Any, **kwargs: Any) -> Any:
+        """Invoke a deployed web endpoint and return the JSON response.
+
+        Contractual path: the control plane routes the call through the web
+        endpoint HTTP ingress (``/serve/<app>/<path>``, conventions.md §13).
+        There is no cloudpickle-over-RPC endpoint for deployed functions in the
+        current contract (see sdk/CONTRACT-ISSUES.md).
+
+        Calling convention:
+        - A single positional arg is sent as the JSON body.
+        - Keyword args are sent as the JSON body dict.
+        - No args → empty JSON body (null).
+        - Mixing positional and keyword args raises InvalidArgumentError.
+        """
+        if args and kwargs:
+            raise exc.InvalidArgumentError(
+                "INVALID_ARGUMENT",
+                "Function.from_name.remote() accepts either one positional arg "
+                "or keyword args, not both. For full RPC semantics, see "
+                "sdk/CONTRACT-ISSUES.md.",
+            )
+        if len(args) > 1:
+            raise exc.InvalidArgumentError(
+                "INVALID_ARGUMENT",
+                "Function.from_name.remote() accepts at most one positional arg "
+                "(the JSON body). For multi-arg calls, use keyword args or "
+                "remote_json().",
+            )
+        body = args[0] if args else (kwargs if kwargs else None)
+        return self.request(json=body)
+
+    def spawn(
+        self, *args: Any, webhook: "Any" = None, **kwargs: Any
+    ) -> "DeployedFunctionCall":
+        """Invoke a deployed endpoint ASYNCHRONOUSLY; return a pollable handle.
+
+        Route: ``POST /v1/serve-async/<app>/<path>`` — the control plane enqueues
+        an HTTP function call and answers ``202`` with a ``call_id`` WITHOUT
+        holding the connection (async-jobs-study.md). Poll the returned handle
+        with ``.get()`` / ``.status()``, or re-attach from another process with
+        ``DeployedFunctionCall.from_id(call_id)``.
+
+        JSON-only, same body convention as ``remote()``: one positional arg OR
+        keyword args become the JSON body sent to the endpoint. ``webhook=`` (a
+        ``bladekit.Webhook``, dict, or bare URL str) registers a completion webhook;
+        if it is signed and the CP generated the secret, it comes back once on
+        ``handle.webhook_secret``. Setup errors (app not found, no active
+        deployment, ambiguous selector) propagate.
+
+        NOTE: this REPLACES the previous fire-and-forget ``spawn`` (which returned
+        ``None`` and discarded the response) — hence the 0.5.0 contract bump.
+        """
+        if args and kwargs:
+            raise exc.InvalidArgumentError(
+                "INVALID_ARGUMENT",
+                "Function.from_name.spawn() accepts either one positional arg "
+                "or keyword args, not both.",
+            )
+        if len(args) > 1:
+            raise exc.InvalidArgumentError(
+                "INVALID_ARGUMENT",
+                "Function.from_name.spawn() accepts at most one positional arg.",
+            )
+        from ._webhook import _webhook_dict
+
+        body = args[0] if args else (kwargs if kwargs else None)
+        # Resolve the endpoint eagerly: NotFoundError, UnavailableError
+        # (APP_STOPPED) and InvalidArgumentError (ambiguous selector) must
+        # propagate so the caller learns they misfired.
+        endpoint = self._resolve_endpoint()
+        endpoint_path = str(endpoint.get("path"))
+        if not endpoint_path.startswith("/"):
+            endpoint_path = f"/{endpoint_path}"
+        client = self._require_client()
+        resp = client.spawn_async_endpoint(
+            self.app_name, endpoint_path, input=body, webhook=_webhook_dict(webhook)
+        )
+        return DeployedFunctionCall(
+            client, resp["call_id"], webhook_secret=(resp.get("webhook") or {}).get("secret")
+        )
+
+
+def _endpoint_matches_selector(endpoint: dict, selector: str) -> bool:
+    path = endpoint.get("path")
+    if selector.startswith("/"):
+        return path == selector
+
+    if endpoint.get("name") == selector:
+        return True
+
+    function_ref = endpoint.get("function") or {}
+    qualname = str(function_ref.get("qualname") or "")
+    if qualname == selector or qualname.rsplit(".", 1)[-1] == selector:
+        return True
+
+    if isinstance(path, str) and path.lstrip("/") == selector:
+        return True
+    return False
+
+
+_GPU_CLASSES = ("spot", "reserved")
+
+
+def _validate_gpu_class(gpu_class: str) -> None:
+    """Validate gpu_class ∈ {spot, reserved} (m8-spot.md §13.1)."""
+    if gpu_class not in _GPU_CLASSES:
+        raise exc.InvalidArgumentError(
+            "INVALID_ARGUMENT",
+            f"gpu_class must be one of {_GPU_CLASSES} (spot = cheap/preemptible, "
+            f"reserved = no preemption); got {gpu_class!r}",
+        )
+
+
+def _validate_priority(priority: int) -> None:
+    """Validate priority is in [PRIORITY_MIN, PRIORITY_MAX] (conventions.md §6)."""
+    if not isinstance(priority, int) or priority < PRIORITY_MIN or priority > PRIORITY_MAX:
+        raise exc.InvalidArgumentError(
+            "PRIORITY_INVALID",
+            f"priority must be an integer between {PRIORITY_MIN} and {PRIORITY_MAX} "
+            f"(higher = more urgent); got {priority!r}",
+        )
+
+
+def _normalize_retries(retries):
+    """Accept ``retries`` as an int shorthand (Modal-style ``retries=3``) or a
+    full RetryPolicy dict; return the validated dict form (or None)."""
+    if retries is None:
+        return None
+    if isinstance(retries, bool):
+        raise exc.InvalidArgumentError(
+            "RETRY_POLICY_INVALID", "retries must be an int or a dict, not a bool"
+        )
+    if isinstance(retries, int):
+        retries = {"max_retries": retries}
+    _validate_retries(retries)
+    return retries
+
+
+def _validate_retries(retries: dict) -> None:
+    """Validate a RetryPolicy dict (conventions.md §6)."""
+    if not isinstance(retries, dict):
+        raise exc.InvalidArgumentError(
+            "RETRY_POLICY_INVALID",
+            f"retries must be an int (e.g. retries=3) or a RetryPolicy dict, "
+            f"got {type(retries).__name__}",
+        )
+    max_retries = retries.get("max_retries", 0)
+    if not isinstance(max_retries, int) or max_retries < 0 or max_retries > RETRIES_MAX:
+        raise exc.InvalidArgumentError(
+            "RETRY_POLICY_INVALID",
+            f"retries.max_retries must be an integer between 0 and {RETRIES_MAX}; "
+            f"got {max_retries!r}",
+        )
+    backoff = retries.get("backoff")
+    if backoff is not None:
+        if not isinstance(backoff, dict):
+            raise exc.InvalidArgumentError(
+                "RETRY_POLICY_INVALID", "retries.backoff must be a dict"
+            )
+        initial = backoff.get("initial_seconds", 1)
+        if not isinstance(initial, (int, float)) or initial < 0 or initial > RETRIES_BACKOFF_INITIAL_MAX:
+            raise exc.InvalidArgumentError(
+                "RETRY_POLICY_INVALID",
+                f"retries.backoff.initial_seconds must be between 0 and "
+                f"{RETRIES_BACKOFF_INITIAL_MAX}; got {initial!r}",
+            )
+        max_s = backoff.get("max_seconds", 60)
+        if not isinstance(max_s, (int, float)) or max_s < 0 or max_s > RETRIES_BACKOFF_MAX_MAX:
+            raise exc.InvalidArgumentError(
+                "RETRY_POLICY_INVALID",
+                f"retries.backoff.max_seconds must be between 0 and "
+                f"{RETRIES_BACKOFF_MAX_MAX}; got {max_s!r}",
+            )
+        factor = backoff.get("factor", 2.0)
+        if not isinstance(factor, (int, float)) or factor < RETRIES_BACKOFF_FACTOR_MIN or factor > RETRIES_BACKOFF_FACTOR_MAX:
+            raise exc.InvalidArgumentError(
+                "RETRY_POLICY_INVALID",
+                f"retries.backoff.factor must be between {RETRIES_BACKOFF_FACTOR_MIN} "
+                f"and {RETRIES_BACKOFF_FACTOR_MAX}; got {factor!r}",
+            )
+
+
+def _validate_app_name(name: str) -> None:
+    if not isinstance(name, str) or not _APP_NAME_RE.match(name):
+        raise exc.InvalidArgumentError(
+            "APP_NAME_INVALID",
+            f"invalid app name {name!r}; must match '^[a-z][a-z0-9-]{{2,62}}$'",
+        )
+
+
+def _normalize_methods(
+    methods: Optional[Sequence[str]], *, default: Sequence[str]
+) -> tuple[str, ...]:
+    raw = tuple(default if methods is None else methods)
+    if not raw:
+        raise exc.InvalidArgumentError(
+            "INVALID_ARGUMENT", "endpoint methods cannot be empty"
+        )
+    normalized = tuple(str(m).upper() for m in raw)
+    bad = [m for m in normalized if m not in _HTTP_METHODS]
+    if bad:
+        raise exc.InvalidArgumentError(
+            "INVALID_ARGUMENT",
+            f"unsupported HTTP method(s): {', '.join(bad)}",
+        )
+    if len(normalized) > 8:
+        raise exc.InvalidArgumentError(
+            "INVALID_ARGUMENT", "endpoint methods are limited to 8 entries"
+        )
+    if len(set(normalized)) != len(normalized):
+        raise exc.InvalidArgumentError(
+            "INVALID_ARGUMENT", "endpoint methods must be unique"
+        )
+    return normalized
+
+
+def _validate_path(path: str) -> str:
+    if not isinstance(path, str) or not path.startswith("/"):
+        raise exc.InvalidArgumentError(
+            "INVALID_ARGUMENT", f"endpoint path {path!r} must start with '/'"
+        )
+    if len(path) > 1024:
+        raise exc.InvalidArgumentError(
+            "INVALID_ARGUMENT", "endpoint path cannot exceed 1024 characters"
+        )
+    return path
+
+
+def _reject_pinned_server_port(port: Optional[int]) -> None:
+    # §13.5: web_server is DYNAMIC-ONLY. The agent assigns each container a
+    # node-unique loopback port via FORGE_SERVER_PORT (so co-located replicas can
+    # never collide on a shared host loopback) and the user's server binds
+    # $FABRIC_SERVER_PORT. Pinning a fixed port is no longer supported: it
+    # re-introduced the co-location cross-talk bug this design exists to prevent.
+    if port is not None:
+        raise exc.InvalidArgumentError(
+            "INVALID_ARGUMENT",
+            "web_server no longer accepts a pinned port= (it caused co-located "
+            "replicas to collide on the shared host loopback). Omit it and bind "
+            "$FABRIC_SERVER_PORT — the agent assigns a unique port per container.",
+        )
+
+
+def _validate_startup_timeout(value: int) -> None:
+    # §13.5 / openapi EndpointSpec.startup_timeout_seconds: integer >= 10.
+    #
+    # The UPPER bound is the server's to enforce, not this SDK's. It used to be
+    # a hardcoded 1800 here as well as there, and thirty minutes is under what a
+    # first torch.compile over four ranks costs — so the client refused a
+    # perfectly legal value before the request was ever made, which is the worst
+    # place to be wrong: the deployment's real ceiling
+    # (FORGE_MAX_STARTUP_TIMEOUT) is not something this process can know, and a
+    # mirrored constant is guaranteed to disagree with some deployment. The
+    # server answers 400 INVALID_ARGUMENT naming its own ceiling.
+    if not isinstance(value, int) or isinstance(value, bool) or value < 10:
+        raise exc.InvalidArgumentError(
+            "INVALID_ARGUMENT",
+            "startup_timeout must be an integer of at least 10 seconds",
+        )
+
+
+def _validate_concurrency(value: int) -> None:
+    if not isinstance(value, int) or value < 1 or value > 100:
+        raise exc.InvalidArgumentError(
+            "INVALID_ARGUMENT",
+            "max_concurrent_inputs must be an integer between 1 and 100",
+        )
+
+
+def _validate_autoscaling(
+    *,
+    min_replicas: Optional[int],
+    max_replicas: Optional[int],
+    max_concurrent_inputs: Optional[int],
+    scale_down_idle_seconds: Optional[int],
+    max_queue_depth: Optional[int] = None,
+) -> None:
+    if min_replicas is not None and (
+        not isinstance(min_replicas, int)
+        or min_replicas < 0
+        or min_replicas > 50
+    ):
+        raise exc.InvalidArgumentError(
+            "AUTOSCALE_LIMIT_INVALID", "min_replicas must be between 0 and 50"
+        )
+    if max_replicas is not None and (
+        not isinstance(max_replicas, int)
+        or max_replicas < 1
+        or max_replicas > 50
+    ):
+        raise exc.InvalidArgumentError(
+            "AUTOSCALE_LIMIT_INVALID", "max_replicas must be between 1 and 50"
+        )
+    if (
+        min_replicas is not None
+        and max_replicas is not None
+        and min_replicas > max_replicas
+    ):
+        raise exc.InvalidArgumentError(
+            "AUTOSCALE_LIMIT_INVALID", "min_replicas cannot exceed max_replicas"
+        )
+    if max_concurrent_inputs is not None:
+        _validate_concurrency(max_concurrent_inputs)
+    if scale_down_idle_seconds is not None and (
+        not isinstance(scale_down_idle_seconds, int)
+        or scale_down_idle_seconds < 30
+        or scale_down_idle_seconds > 3600
+    ):
+        raise exc.InvalidArgumentError(
+            "AUTOSCALE_LIMIT_INVALID",
+            "scale_down_idle_seconds must be between 30 and 3600",
+        )
+    if max_queue_depth is not None and (
+        not isinstance(max_queue_depth, int)
+        or isinstance(max_queue_depth, bool)
+        or max_queue_depth < 0
+        or max_queue_depth > 10000
+    ):
+        raise exc.InvalidArgumentError(
+            "AUTOSCALE_LIMIT_INVALID",
+            "max_queue_depth must be between 0 and 10000 (0 = unbounded)",
+        )
+
+
+def _validate_endpoint_autoscale(kind: str, autoscale: Optional[Autoscale]) -> None:
+    """Reject kind-incompatible policies at decorator time (before any I/O).
+
+    The vLLM preset scrapes the long-lived server's own /metrics, which only
+    exists for ``web_server`` endpoints — mirrors the server-side check.
+    """
+    if autoscale is None:
+        return
+    if autoscale.vllm_target_waiting is not None and kind != "web_server":
+        raise exc.InvalidArgumentError(
+            "SCALING_POLICY_INVALID",
+            f"vllm_target_waiting requires @app.web_server (got {kind})",
+        )
+
+
+def _autoscaling_spec(
+    *,
+    min_replicas: Optional[int],
+    max_replicas: Optional[int],
+    max_concurrent_inputs: Optional[int],
+    scale_down_idle_seconds: Optional[int],
+    max_queue_depth: Optional[int] = None,
+    reserved_replicas: Optional[int] = None,
+) -> dict:
+    _validate_autoscaling(
+        min_replicas=min_replicas,
+        max_replicas=max_replicas,
+        max_concurrent_inputs=max_concurrent_inputs,
+        scale_down_idle_seconds=scale_down_idle_seconds,
+        max_queue_depth=max_queue_depth,
+    )
+    max_eff = 1 if max_replicas is None else max_replicas
+    if reserved_replicas is not None and (
+        not isinstance(reserved_replicas, int)
+        or isinstance(reserved_replicas, bool)
+        or reserved_replicas < 0
+        or reserved_replicas > max_eff
+    ):
+        raise exc.InvalidArgumentError(
+            "AUTOSCALE_LIMIT_INVALID",
+            "reserved_replicas must be an integer between 0 and max_replicas",
+        )
+    spec = {
+        "min_replicas": 0 if min_replicas is None else min_replicas,
+        "max_replicas": max_eff,
+        "max_concurrent_inputs": (
+            1 if max_concurrent_inputs is None else max_concurrent_inputs
+        ),
+        "scale_down_idle_seconds": (
+            300 if scale_down_idle_seconds is None else scale_down_idle_seconds
+        ),
+    }
+    # Sent only when declared: the server default (0 = unbounded) keeps the
+    # historical behavior, and an explicit 0 round-trips to the same thing.
+    if max_queue_depth is not None:
+        spec["max_queue_depth"] = max_queue_depth
+    if reserved_replicas:
+        spec["reserved_replicas"] = reserved_replicas
+    return spec
+
+
+def _scaling_policy_spec(
+    *,
+    autoscale: Optional[Autoscale],
+    fn_target_inputs: Optional[int],
+    max_concurrent_inputs: int,
+    kind: str,
+) -> Optional[dict]:
+    """Build the wire ``scaling_policy`` ({"v": 1, ...}) or ``None`` (v1).
+
+    Merges the endpoint-level ``autoscale=`` declaration with the
+    function-level ``@app.concurrent(target_inputs=)``. Declaring
+    ``target_inputs`` in BOTH places is an error (no silent precedence).
+    Mirrors the server-side validation (docs/specs/autoscaling-v2.md §4.3) so
+    a bad policy fails at import/deploy build time, before any network call.
+    """
+    target = fn_target_inputs
+    buffer_replicas: Optional[int] = None
+    vllm_waiting: Optional[int] = None
+    scaledown_window: Optional[int] = None
+    if autoscale is not None:
+        if autoscale.target_inputs is not None:
+            if target is not None:
+                raise exc.InvalidArgumentError(
+                    "SCALING_POLICY_INVALID",
+                    "target_inputs declared both in @app.concurrent and in "
+                    "bladekit.Autoscale — declare it in exactly one place",
+                )
+            target = autoscale.target_inputs
+        buffer_replicas = autoscale.buffer_replicas
+        vllm_waiting = autoscale.vllm_target_waiting
+        scaledown_window = autoscale.scaledown_window
+    if (
+        target is None
+        and buffer_replicas is None
+        and vllm_waiting is None
+        and scaledown_window is None
+    ):
+        return None
+    if target is not None and target > max_concurrent_inputs:
+        raise exc.InvalidArgumentError(
+            "SCALING_POLICY_INVALID",
+            f"target_inputs ({target}) cannot exceed max_concurrent_inputs "
+            f"({max_concurrent_inputs})",
+        )
+    if vllm_waiting is not None and kind != "web_server":
+        raise exc.InvalidArgumentError(
+            "SCALING_POLICY_INVALID",
+            "vllm_target_waiting requires a @app.web_server endpoint "
+            f"(got {kind})",
+        )
+    policy: dict[str, Any] = {"v": 1}
+    if target is not None:
+        policy["target_inputs"] = target
+    if buffer_replicas is not None and buffer_replicas > 0:
+        policy["buffer_replicas"] = buffer_replicas
+    if vllm_waiting is not None:
+        policy["vllm"] = {"target_waiting": vllm_waiting}
+    # Serialized ONLY when the user set it: an older control plane rejects
+    # unknown policy fields with 400 SCALING_POLICY_INVALID.
+    if scaledown_window is not None:
+        policy["scaledown_window_seconds"] = scaledown_window
+    if len(policy) == 1:
+        return None  # only {"v":1} left (e.g. buffer_replicas=0): no policy
+    return policy
+
+
+def _apply_endpoint_marker(target: Any, decl: EndpointDeclaration) -> Any:
+    if isinstance(target, Function):
+        target._add_endpoint(decl)
+        return target
+    existing = list(getattr(target, "__forge_endpoints__", []))
+    existing.append(decl)
+    setattr(target, "__forge_endpoints__", existing)
+    return target
+
+
+def _apply_concurrency_marker(
+    target: Any, max_concurrent_inputs: int, target_inputs: Optional[int] = None
+) -> Any:
+    if isinstance(target, Function):
+        target._set_concurrency(max_concurrent_inputs)
+        if target_inputs is not None:
+            target._set_target_inputs(target_inputs)
+        return target
+    setattr(target, "__forge_max_concurrent_inputs__", max_concurrent_inputs)
+    if target_inputs is not None:
+        setattr(target, "__forge_target_inputs__", target_inputs)
+    return target
+
+
+# Default image when neither the App nor a @app.function specifies one. The
+# minimal CPU base from the catalog (pre-built, so no build on first run). GPU
+# work overrides it with a GPU image (e.g. "fabric/torch") + gpu=… per function.
+# Sent as forge/base until the server knows the fabric/ spelling (to_wire_image).
+DEFAULT_IMAGE = "fabric/base"
+
+
+class App:
+    """An AI Fabric application: a namespace of remotely-callable functions."""
+
+    def __init__(
+        self,
+        name: str,
+        *,
+        image: Any = None,
+    ) -> None:
+        self.name = name
+        # Modal-style ergonomics: a function with no image falls back to the
+        # App's default, and the App defaults to the catalog CPU base — so
+        # `@app.function()` just works. Pass image=… to override (any alias,
+        # registry ref, or bladekit.Image DSL).
+        self.default_image = image if image is not None else DEFAULT_IMAGE
+        self.functions: Dict[str, Function] = {}
+        self.classes: Dict[str, Any] = {}
+        self.local_entrypoints: List[Callable[..., Any]] = []
+        # the most-recently registered @app.on_preempt free-function hook
+        # (runner-protocol.md §15.2.1). None until a hook is registered.
+        self.on_preempt_hook: Optional[Callable[..., Any]] = None
+        # cache of definition_hash -> build_id so the same DSL image in a
+        # process resolves its build once.
+        self._image_builds: Dict[str, str] = {}
+        # Bundle root + module mapping, set when the CLI loads an entrypoint file.
+        self._bundle_root: Optional[Path] = None
+        self._entry_module: Optional[str] = None
+        self._client: Any = None
+        self._bundle_id: Optional[str] = None
+        self._bundle_sha256: Optional[str] = None
+
+    def __repr__(self) -> str:
+        return f"<bladekit.App {self.name!r} functions={list(self.functions)}>"
+
+    # -- decorators ---------------------------------------------------------
+
+    def function(
+        self,
+        _fn: Optional[Callable[..., Any]] = None,
+        *,
+        gpu: Optional[str] = None,
+        cpu: Optional[float] = None,
+        memory: Optional[int] = None,
+        timeout: Optional[int] = None,
+        image: Any = None,
+        idle_timeout: Optional[int] = None,
+        volumes: Optional[Dict[str, Any]] = None,
+        secrets: Optional[List[Any]] = None,
+        retries: Optional[dict] = None,
+        priority: Optional[int] = None,
+        namespace: Optional[str] = None,
+        schedule: Any = None,
+        gpu_class: str = "spot",
+        best_effort: bool = False,
+        max_interruptions: Optional[int] = None,
+    ):
+        """Decorator: register a function for remote execution.
+
+        Usable bare (``@app.function``) or with arguments
+        (``@app.function(gpu="RTX-A4500")``). ``image`` is a catalogue alias / raw
+        registry ref (str) OR a ``bladekit.Image`` DSL definition. ``volumes``
+        maps mount paths to ``bladekit.Volume`` objects; ``secrets`` is a list of
+        ``bladekit.Secret``.
+
+        Additional options:
+        - ``timeout``: max seconds for ONE execution (server default 3600).
+          It bounds the work, never the worker: a one-shot ``blade run`` /
+          cron / map run is killed past it, while on a DEPLOYED endpoint it
+          caps each request — the service itself never expires (replica
+          lifetime belongs to the autoscaler: ``min_replicas``, idle
+          scale-down, redeploy).
+        - ``retries``: retry policy dict, e.g.
+          ``{"max_retries": 3, "backoff": {"initial_seconds": 1, "max_seconds": 60,
+          "factor": 2.0}}``.  Applied per-input for ``map()`` calls.
+        - ``priority``: scheduling priority 0–9 (9=urgent, 0=best-effort).
+          Default 5 (FIFO, same as all runs).
+        - ``namespace``: team namespace for GPU quota accounting.
+        - ``schedule``: a ``bladekit.Cron(...)`` object for cron-scheduled execution
+          (only takes effect in a deployed app, not in ``blade run``).
+        - ``gpu="RTX-A4500:4"``: multi-GPU per container (``":N"`` suffix
+          sets ``gpu_count``; N must be 1–8).
+        """
+        # Validate priority/retries params at decoration time (not at call time).
+        # retries accepts an int shorthand (retries=3) or a RetryPolicy dict.
+        if priority is not None:
+            _validate_priority(priority)
+        if retries is not None:
+            retries = _normalize_retries(retries)
+        # validate gpu_class client-side with a clear error.
+        _validate_gpu_class(gpu_class)
+
+        def wrap(fn: Callable[..., Any]) -> Function:
+            if isinstance(fn, Function):
+                if fn._app is not self:
+                    raise exc.InvalidArgumentError(
+                        "INVALID_ARGUMENT",
+                        "@app.function cannot wrap a Function from another App",
+                    )
+                if gpu is not None:
+                    fn.gpu = gpu
+                if cpu is not None:
+                    fn.cpu = cpu
+                if memory is not None:
+                    fn.memory = memory
+                if timeout is not None:
+                    fn.timeout = timeout
+                if image is not None:
+                    fn.image = image
+                if idle_timeout is not None:
+                    fn.idle_timeout = idle_timeout
+                if volumes is not None:
+                    fn.volumes = volumes
+                if secrets is not None:
+                    fn.secrets = secrets
+                if retries is not None:
+                    fn.retries = retries
+                if priority is not None:
+                    fn.priority = priority
+                if namespace is not None:
+                    fn.namespace = namespace
+                if schedule is not None:
+                    fn.schedule = schedule
+                # only override on a non-default (gpu_class can't be None,
+                # so a bare default must not clobber a value set on the wrapped fn).
+                if gpu_class != "spot":
+                    fn.gpu_class = gpu_class
+                if best_effort:
+                    fn.best_effort = best_effort
+                if max_interruptions is not None:
+                    fn.max_interruptions = max_interruptions
+                self.functions[fn.__name__] = fn
+                return fn
+            f = Function(
+                self,
+                fn,
+                gpu=gpu,
+                cpu=cpu,
+                memory=memory,
+                timeout=timeout,
+                image=image,
+                idle_timeout=idle_timeout,
+                volumes=volumes,
+                secrets=secrets,
+                retries=retries,
+                priority=priority,
+                namespace=namespace,
+                schedule=schedule,
+                gpu_class=gpu_class,
+                best_effort=best_effort,
+                max_interruptions=max_interruptions,
+            )
+            self.functions[f.__name__] = f
+            return f
+
+        if _fn is not None:
+            return wrap(_fn)
+        return wrap
+
+    def web_endpoint(
+        self,
+        _fn: Optional[Callable[..., Any]] = None,
+        *,
+        path: Optional[str] = None,
+        methods: Optional[Sequence[str]] = None,
+        name: Optional[str] = None,
+        min_replicas: Optional[int] = None,
+        max_replicas: Optional[int] = None,
+        max_concurrent_inputs: Optional[int] = None,
+        scale_down_idle_seconds: Optional[int] = None,
+        max_queue_depth: Optional[int] = None,
+        reserved_replicas: Optional[int] = None,
+        public: bool = False,
+        autoscale: Optional[Autoscale] = None,
+    ):
+        """Decorator: expose a function through HTTP call routing.
+
+        Usable alone (it registers a function with default resources) or stacked
+        with ``@app.function`` / ``@app.concurrent`` in either order.
+
+        Endpoints are PRIVATE by default (the /serve ingress requires a valid
+        user token). Pass ``public=True`` to opt out (no auth).
+
+        ``max_queue_depth`` (0..10000) bounds how many requests may wait for a
+        replica slot at the platform ingress; at the bound, new requests get an
+        immediate ``503 ENDPOINT_QUEUE_FULL`` + ``Retry-After`` instead of
+        waiting out a cold start. Unset/0 = unbounded (the historical
+        behavior).
+        """
+        methods_tuple = _normalize_methods(methods, default=("POST",))
+        _validate_autoscaling(
+            min_replicas=min_replicas,
+            max_replicas=max_replicas,
+            max_concurrent_inputs=max_concurrent_inputs,
+            scale_down_idle_seconds=scale_down_idle_seconds,
+            max_queue_depth=max_queue_depth,
+        )
+        _validate_endpoint_autoscale("web_endpoint", autoscale)
+
+        def wrap(fn: Callable[..., Any]) -> Function:
+            endpoint_path = _validate_path(path or f"/{getattr(fn, '__name__', 'endpoint')}")
+            decl = EndpointDeclaration(
+                name=name,
+                kind="web_endpoint",
+                path=endpoint_path,
+                methods=methods_tuple,
+                min_replicas=min_replicas,
+                max_replicas=max_replicas,
+                max_concurrent_inputs=max_concurrent_inputs,
+                scale_down_idle_seconds=scale_down_idle_seconds,
+                max_queue_depth=max_queue_depth,
+                reserved_replicas=reserved_replicas,
+                public=public,
+                autoscale=autoscale,
+            )
+            if isinstance(fn, Function):
+                return _apply_endpoint_marker(fn, decl)
+            _apply_endpoint_marker(fn, decl)
+            return self.function(fn)
+
+        if _fn is not None:
+            return wrap(_fn)
+        return wrap
+
+    def web_server(
+        self,
+        _fn: Optional[Callable[..., Any]] = None,
+        *,
+        port: Optional[int] = None,
+        startup_timeout: int = 300,
+        path: str = "/",
+        name: Optional[str] = None,
+        min_replicas: Optional[int] = None,
+        max_replicas: Optional[int] = None,
+        max_concurrent_inputs: Optional[int] = None,
+        scale_down_idle_seconds: Optional[int] = None,
+        max_queue_depth: Optional[int] = None,
+        reserved_replicas: Optional[int] = None,
+        public: bool = False,
+        autoscale: Optional[Autoscale] = None,
+        snapshot: bool = False,
+    ):
+        """Decorator: serve a long-lived HTTP server running inside the container.
+
+        Unlike ``web_endpoint`` (a handler called per request), the decorated
+        function is invoked ONCE at container boot to start a long-lived server
+        — typically a non-blocking ``subprocess.Popen(["vllm", "serve", …])``.
+        AI Fabric probes the loopback until the server accepts connections (up to
+        ``startup_timeout`` seconds) then forwards every web request to it
+        (runner-protocol.md §13.5). The server owns its own method/path routing,
+        so the endpoint captures all methods under ``path``.
+
+        **Port.** Each container is assigned a node-unique loopback port via the
+        ``FABRIC_SERVER_PORT`` env var, so co-located replicas never collide on a
+        shared host port. Your server MUST bind ``$FABRIC_SERVER_PORT``. Passing a
+        fixed ``port=`` is rejected (it re-introduced co-location cross-talk).
+
+        Combine with ``@app.concurrent(max_inputs=N)`` to let multiple requests
+        be forwarded concurrently — this is what enables server-side continuous
+        batching (e.g. vLLM). Stackable with ``@app.function`` / ``@app.concurrent``
+        in either order. Only non-streaming responses are supported for now
+        (SSE/WebSocket deferred, §13.5).
+
+        **Snapshot.** ``snapshot=True`` (coldstart-snapshot.md §5) opts the
+        endpoint into GPU checkpoint/restore: the platform injects the
+        snapshotability recipe into every replica, checkpoints a warm replica at
+        drain and restores it on scale-up (falling back to a normal boot on any
+        error). Valid ONLY on a single-GPU ``web_server`` (``gpu_count == 1``);
+        otherwise it raises ``bladekit.InvalidArgumentError`` at deploy build time.
+
+        **Queue bound.** ``max_queue_depth`` (0..10000) caps how many requests
+        may wait for a replica slot at the platform ingress — mostly the
+        cold-start window; at the bound new requests get an immediate
+        ``503 ENDPOINT_QUEUE_FULL`` + ``Retry-After``. Unset/0 = unbounded
+        (the historical behavior). Note the scope: traffic load-balanced
+        straight to a WARM replica is not queued by the platform — its backlog
+        lives inside your own server (e.g. the vLLM scheduler queue).
+
+        Example::
+
+            @app.web_server(startup_timeout=600)
+            @app.concurrent(max_inputs=32)
+            @app.function(gpu="RTX-A4500", image=vllm_image)
+            def serve():
+                import os, subprocess
+                port = os.environ["FABRIC_SERVER_PORT"]
+                subprocess.Popen(
+                    ["vllm", "serve", "meta-llama/Llama-3.1-8B-Instruct",
+                     "--port", port],
+                )
+        """
+        _reject_pinned_server_port(port)
+        _validate_startup_timeout(startup_timeout)
+        endpoint_path = _validate_path(path)
+        _validate_autoscaling(
+            min_replicas=min_replicas,
+            max_replicas=max_replicas,
+            max_concurrent_inputs=max_concurrent_inputs,
+            scale_down_idle_seconds=scale_down_idle_seconds,
+            max_queue_depth=max_queue_depth,
+        )
+        _validate_endpoint_autoscale("web_server", autoscale)
+
+        def wrap(fn: Callable[..., Any]) -> Function:
+            decl = EndpointDeclaration(
+                name=name,
+                kind="web_server",
+                path=endpoint_path,
+                methods=_ASGI_METHODS,  # the server owns method routing
+                min_replicas=min_replicas,
+                max_replicas=max_replicas,
+                max_concurrent_inputs=max_concurrent_inputs,
+                scale_down_idle_seconds=scale_down_idle_seconds,
+                max_queue_depth=max_queue_depth,
+                reserved_replicas=reserved_replicas,
+                public=public,
+                port=port,
+                startup_timeout_seconds=startup_timeout,
+                autoscale=autoscale,
+                snapshot=snapshot,
+            )
+            if isinstance(fn, Function):
+                return _apply_endpoint_marker(fn, decl)
+            _apply_endpoint_marker(fn, decl)
+            return self.function(fn)
+
+        if _fn is not None:
+            return wrap(_fn)
+        return wrap
+
+    def asgi_app(
+        self,
+        _fn: Optional[Callable[..., Any]] = None,
+        *,
+        path: str = "/",
+        startup_timeout: int = 300,
+        name: Optional[str] = None,
+        min_replicas: Optional[int] = None,
+        max_replicas: Optional[int] = None,
+        max_concurrent_inputs: Optional[int] = None,
+        scale_down_idle_seconds: Optional[int] = None,
+        max_queue_depth: Optional[int] = None,
+        reserved_replicas: Optional[int] = None,
+        public: bool = False,
+        autoscale: Optional[Autoscale] = None,
+    ):
+        """Decorator: serve an ASGI app (FastAPI, Starlette, …) as an endpoint.
+
+        The decorated function returns the ASGI app object. At boot the runner
+        allocates a free loopback port, starts ``uvicorn`` on the returned app,
+        and forwards each web request to it (runner-protocol.md §13.5). ``uvicorn``
+        must be present in the image. ``startup_timeout`` (seconds) bounds how long
+        the runner probes the loopback before the replica is marked ready; the
+        replica fails if the server never answers.
+
+        Stackable with ``@app.function`` / ``@app.concurrent`` like ``web_endpoint``.
+        Only non-streaming responses are supported for now — SSE/WebSocket are
+        deferred (§13.5).
+        """
+        endpoint_path = _validate_path(path)
+        _validate_startup_timeout(startup_timeout)
+        _validate_autoscaling(
+            min_replicas=min_replicas,
+            max_replicas=max_replicas,
+            max_concurrent_inputs=max_concurrent_inputs,
+            scale_down_idle_seconds=scale_down_idle_seconds,
+            max_queue_depth=max_queue_depth,
+        )
+        _validate_endpoint_autoscale("asgi_app", autoscale)
+
+        def wrap(fn: Callable[..., Any]) -> Function:
+            decl = EndpointDeclaration(
+                name=name,
+                kind="asgi_app",
+                path=endpoint_path,
+                methods=_ASGI_METHODS,
+                min_replicas=min_replicas,
+                max_replicas=max_replicas,
+                max_concurrent_inputs=max_concurrent_inputs,
+                scale_down_idle_seconds=scale_down_idle_seconds,
+                max_queue_depth=max_queue_depth,
+                reserved_replicas=reserved_replicas,
+                autoscale=autoscale,
+                # Deployed endpoints are PRIVATE by default (a valid user token is
+                # required). public=True opts out so the URL opens directly in a
+                # browser — needed for ASGI apps that serve a UI / WebRTC signaling.
+                public=public,
+                # Runner allocates the loopback port for uvicorn; server_port stays None.
+                port=None,
+                startup_timeout_seconds=startup_timeout,
+            )
+            if isinstance(fn, Function):
+                return _apply_endpoint_marker(fn, decl)
+            _apply_endpoint_marker(fn, decl)
+            return self.function(fn)
+
+        if _fn is not None:
+            return wrap(_fn)
+        return wrap
+
+    def concurrent(
+        self,
+        _fn: Optional[Callable[..., Any]] = None,
+        *,
+        max_inputs: Optional[int] = None,
+        max_concurrent_inputs: Optional[int] = None,
+        target_inputs: Optional[int] = None,
+    ):
+        """Decorator: set per-replica HTTP concurrency for endpoints.
+
+        ``max_inputs`` is the admission ceiling per replica. The optional
+        ``target_inputs`` is what the autoscaler AIMS for (autoscaling v2,
+        Modal semantics): the fleet is sized to hold ~``target_inputs``
+        in-flight calls per replica, and the margin up to ``max_inputs``
+        absorbs bursts while new replicas boot. Pick ``target_inputs`` from
+        your latency budget and ``max_inputs`` from resource limits::
+
+            @app.concurrent(max_inputs=32, target_inputs=24)
+        """
+        value = max_concurrent_inputs if max_concurrent_inputs is not None else max_inputs
+        if value is None:
+            raise exc.InvalidArgumentError(
+                "INVALID_ARGUMENT",
+                "app.concurrent requires max_inputs= or max_concurrent_inputs=",
+            )
+        _validate_concurrency(value)
+        if target_inputs is not None:
+            if (
+                not isinstance(target_inputs, int)
+                or isinstance(target_inputs, bool)
+                or target_inputs < 1
+                or target_inputs > 100
+            ):
+                raise exc.InvalidArgumentError(
+                    "SCALING_POLICY_INVALID",
+                    "target_inputs must be an integer between 1 and 100",
+                )
+            if target_inputs > value:
+                raise exc.InvalidArgumentError(
+                    "SCALING_POLICY_INVALID",
+                    f"target_inputs ({target_inputs}) cannot exceed "
+                    f"max_inputs ({value})",
+                )
+
+        def wrap(fn: Callable[..., Any]) -> Any:
+            return _apply_concurrency_marker(fn, value, target_inputs)
+
+        if _fn is not None:
+            return wrap(_fn)
+        return wrap
+
+    # -- @app.cls / @app.method ----------------------------------------
+
+    def cls(
+        self,
+        _cls: Optional[type] = None,
+        *,
+        gpu: Optional[str] = None,
+        cpu: Optional[float] = None,
+        memory: Optional[int] = None,
+        timeout: Optional[int] = None,
+        image: Any = None,
+        idle_timeout: Optional[int] = None,
+        volumes: Optional[Dict[str, Any]] = None,
+        secrets: Optional[List[Any]] = None,
+        gpu_class: str = "spot",
+        best_effort: bool = False,
+        max_interruptions: Optional[int] = None,
+    ):
+        """Decorator: register a class whose ``@app.method``s are callable remotely.
+
+        Methods marked ``@bladekit.enter()`` run once per container (model load).
+        The runner instantiates the class with no args, runs the enter hooks,
+        then calls the target method (runner-protocol.md §10). A method marked
+        ``@bladekit.on_preempt`` runs on the preemption grace window
+        (runner-protocol.md §15.2.1).
+
+        ``timeout`` has the same semantics as ``@app.function``: max seconds
+        for one call (or one request on a deployed endpoint) — never the
+        lifetime of a deployed service, which lives under the autoscaler.
+        """
+        from ._cls import Cls
+
+        _validate_gpu_class(gpu_class)
+
+        def wrap(user_cls: type):
+            c = Cls(
+                self,
+                user_cls,
+                gpu=gpu,
+                cpu=cpu,
+                memory=memory,
+                timeout=timeout,
+                image=image,
+                idle_timeout=idle_timeout,
+                volumes=volumes,
+                secrets=secrets,
+                gpu_class=gpu_class,
+                best_effort=best_effort,
+                max_interruptions=max_interruptions,
+            )
+            self.classes[c.__name__] = c
+            # A @app.web_endpoint / @app.asgi_app / @app.web_server applied to a
+            # METHOD of this class registered a module-level Function wrapping the
+            # UNBOUND method with no class_name — so the deploy manifest omitted
+            # class_name, the runner took the plain-function path, and every call
+            # failed with "'Cls' object has no attribute '<method>'". Rewire each
+            # such method: (1) tag the Function with this class so the manifest
+            # carries class_name and the runner takes the instantiate-then-call
+            # path (runner-protocol §10, exactly like @app.method); (2) restore
+            # the raw method on the class so the runner's getattr(instance, name)
+            # binds it. Without (2) the class attribute would still be the
+            # Function object, not a bound method.
+            for attr_name, attr in list(vars(user_cls).items()):
+                if isinstance(attr, Function) and attr._endpoints:
+                    attr.class_name = c.__name__
+                    # web_endpoint built this Function (via self.function(fn))
+                    # BEFORE @app.cls ran, so it has no image/resources — it would
+                    # deploy on forge/base with no GPU (the method's calls then 500
+                    # with ModuleNotFoundError: torch). Inherit the @app.cls config
+                    # for anything the method didn't set itself, exactly as
+                    # @app.method methods inherit it via Cls._function_for.
+                    if attr.image is None:
+                        attr.image = image
+                    if attr.gpu is None:
+                        attr.gpu = gpu
+                    if attr.cpu is None:
+                        attr.cpu = cpu
+                    if attr.memory is None:
+                        attr.memory = memory
+                    if attr.timeout is None:
+                        attr.timeout = timeout
+                    if attr.idle_timeout is None:
+                        attr.idle_timeout = idle_timeout
+                    if attr.volumes is None:
+                        attr.volumes = volumes
+                    if attr.secrets is None:
+                        attr.secrets = secrets
+                    if attr.gpu_class == "spot":
+                        attr.gpu_class = gpu_class
+                    if not attr.best_effort:
+                        attr.best_effort = best_effort
+                    if attr.max_interruptions is None:
+                        attr.max_interruptions = max_interruptions
+                    setattr(user_cls, attr_name, attr._fn)
+            return c
+
+        if _cls is not None:
+            return wrap(_cls)
+        return wrap
+
+    def method(self, _fn: Optional[Callable[..., Any]] = None):
+        """Decorator: mark a method of an ``@app.cls`` class as remotely callable."""
+        from ._cls import Method
+
+        def wrap(fn: Callable[..., Any]) -> "Method":
+            return Method(fn)
+
+        if _fn is not None:
+            return wrap(_fn)
+        return wrap
+
+    # -- preemption hook ---------------------------------------------
+
+    def on_preempt(self, fn: Callable[..., Any]) -> Callable[..., Any]:
+        """Decorator: register a callback to run when the container is preempted.
+
+        Usable as ``@app.on_preempt`` (alias of the module-level
+        ``@bladekit.on_preempt``). Marks the callback with the SDK↔runner
+        ``__forge_on_preempt__`` attribute so the runner discovers it on the
+        SIGTERM grace window the same way it finds ``@bladekit.enter`` hooks
+        (runner-protocol.md §15.2.1). Works on a free function (found in the
+        bundle module) or an ``@app.cls`` method (found on the live instance).
+        The last registered callback wins (deterministic, one callback).
+        """
+        from ._preempt import on_preempt as _mark
+
+        marked = _mark(fn)
+        # Track the most-recently registered free-function hook on the app too —
+        # convenient for introspection/tests; the runner's source of truth is the
+        # __forge_on_preempt__ marker it scans for, not this attribute.
+        self.on_preempt_hook = marked
+        return marked
+
+    # -- image builds --------------------------------------------------
+
+    def _ensure_image_build(self, image: Any) -> str:
+        """Create-or-find the build for a ``bladekit.Image`` and wait for success.
+
+        Idempotent by definition hash (image-dsl.md §7): the server dedups, so
+        re-running an unchanged image triggers zero rebuild. If the build is not
+        yet ``succeeded`` the build logs are streamed live; a failed build raises
+        an actionable :class:`bladekit.ImageBuildError`.
+        """
+        definition = image.to_definition()
+        definition_hash = image.definition_hash()
+        cache = self._image_builds
+        cached = cache.get(definition_hash)
+        if cached is not None:
+            return cached
+
+        client = self._require_client()
+        from ._build import resolve_image_build
+
+        build_id = resolve_image_build(
+            client,
+            definition,
+            definition_hash,
+            context_data=getattr(image, "_context_data", None),
+        )
+        cache[definition_hash] = build_id
+        return build_id
+
+    # -- deployment manifests -----------------------------------------
+
+    def deployment_manifest(
+        self,
+        *,
+        bundle_id: Optional[str] = None,
+        labels: Optional[dict[str, str]] = None,
+    ) -> DeploymentManifest:
+        """Return a serializable manifest without uploading/building anything."""
+        return self._deployment_manifest(bundle_id=bundle_id, labels=labels, resolve=False)
+
+    def _deployment_manifest(
+        self,
+        *,
+        bundle_id: Optional[str] = None,
+        labels: Optional[dict[str, str]] = None,
+        resolve: bool = False,
+        require_endpoints: bool = False,
+    ) -> DeploymentManifest:
+        from ._serialize import cloudpickle_version
+
+        if resolve and bundle_id is None:
+            bundle_id = self._ensure_bundle()
+
+        functions = [fn._manifest_function() for fn in self.functions.values()]
+        classes = []
+        for cls in self.classes.values():
+            classes.append(
+                {
+                    "name": cls.__name__,
+                    "qualname": cls.__qualname__,
+                    "methods": sorted(cls.methods.keys()),
+                }
+            )
+
+        endpoints: list[dict] = []
+        endpoint_functions: list[Function] = []
+        seen_routes: set[tuple[str, str]] = set()
+        for fn in self.functions.values():
+            for spec in fn._endpoint_specs():
+                for method in spec["methods"]:
+                    route = (method, spec["path"])
+                    if route in seen_routes:
+                        raise exc.ConflictError(
+                            "ENDPOINT_ROUTE_CONFLICT",
+                            f"duplicate endpoint route {method} {spec['path']}",
+                        )
+                    seen_routes.add(route)
+                endpoints.append(spec)
+                endpoint_functions.append(fn)
+
+        crons: list[dict] = []
+        cron_functions: list[Function] = []
+        for fn in self.functions.values():
+            cron_spec = fn._cron_spec()
+            if cron_spec is not None:
+                crons.append(cron_spec)
+                cron_functions.append(fn)
+
+        if len(endpoints) > 64:
+            raise exc.InvalidArgumentError(
+                "INVALID_ARGUMENT", "deployments are limited to 64 endpoints"
+            )
+        if len(crons) > 64:
+            raise exc.InvalidArgumentError(
+                "INVALID_ARGUMENT", "deployments are limited to 64 cron schedules"
+            )
+        # a deployment may declare endpoints OR crons (or both). blade deploy
+        # only needs at least one of the two to be a valid deployment.
+        if require_endpoints and not endpoints and not crons:
+            raise exc.InvalidArgumentError(
+                "INVALID_ARGUMENT",
+                "blade deploy requires at least one @app.web_endpoint(), "
+                "@app.web_server(), @app.asgi_app(), or "
+                "@app.function(schedule=bladekit.Cron(...))",
+            )
+
+        image: Optional[str] = None
+        image_build_id: Optional[str] = None
+        image_functions = endpoint_functions + cron_functions
+        if image_functions:
+            if resolve:
+                image, image_build_id = self._resolve_deployment_image(image_functions)
+            else:
+                image = self._unresolved_deployment_image(image_functions)
+
+        return DeploymentManifest(
+            app_name=self.name,
+            bundle_id=bundle_id,
+            runtime={
+                "python_version": _python_version(),
+                "cloudpickle_version": cloudpickle_version(),
+            },
+            image=image,
+            image_build_id=image_build_id,
+            labels=labels,
+            endpoints=endpoints,
+            functions=functions,
+            classes=classes,
+            crons=crons,
+        )
+
+    def _resolve_deployment_image(
+        self, endpoint_functions: Sequence[Function]
+    ) -> tuple[Optional[str], Optional[str]]:
+        resolved: set[tuple[str, str]] = set()
+        for fn in endpoint_functions:
+            image_str, image_build_id = fn._resolve_image()
+            if image_str is not None:
+                resolved.add(("image", image_str))
+            elif image_build_id is not None:
+                resolved.add(("image_build_id", image_build_id))
+        if len(resolved) != 1:
+            raise exc.InvalidArgumentError(
+                "INVALID_ARGUMENT",
+                "all deployment endpoints must use the same effective image",
+            )
+        kind, value = next(iter(resolved))
+        if kind == "image":
+            return value, None
+        return None, value
+
+    def _unresolved_deployment_image(
+        self, endpoint_functions: Sequence[Function]
+    ) -> Optional[str]:
+        images = []
+        for fn in endpoint_functions:
+            img = fn.image if fn.image is not None else self.default_image
+            if isinstance(img, str):
+                from ._image import to_wire_image
+
+                images.append(to_wire_image(img))
+            elif img is not None:
+                return None
+        return images[0] if images and len(set(images)) == 1 else None
+
+    def local_entrypoint(
+        self, _fn: Optional[Callable[..., Any]] = None
+    ) -> Callable[..., Any]:
+        """Decorator: mark the function ``blade run`` should invoke locally.
+
+        Usable bare (``@app.local_entrypoint``) or called
+        (``@app.local_entrypoint()``).
+        """
+
+        def wrap(fn: Callable[..., Any]) -> Callable[..., Any]:
+            self.local_entrypoints.append(fn)
+            return fn
+
+        if _fn is not None:
+            return wrap(_fn)
+        return wrap
+
+    # -- wiring used by the CLI and lifecycle ------------------------------
+
+    def _bind_client(self, client: Any) -> None:
+        self._client = client
+
+    def _set_bundle_context(self, root: Path, entry_module: str) -> None:
+        self._bundle_root = root
+        self._entry_module = entry_module
+
+    def _module_for(self, module: str) -> str:
+        """Map the *defining* module to the name importable inside the bundle.
+
+        A function defined in the entrypoint script reports ``__main__`` when the
+        script is executed directly; remotely it must be imported by the script's
+        own module name (the file stem). The CLI provides that mapping.
+        """
+        if module in ("__main__", "__mp_main__") and self._entry_module:
+            return self._entry_module
+        return module
+
+    def _require_client(self) -> Any:
+        if self._client is None:
+            from ._client import Client
+            from .config import load_config
+
+            cfg = load_config()
+            if not cfg.token:
+                raise exc.AuthenticationError(
+                    "UNAUTHENTICATED",
+                    "no token configured: run `blade token set <token>` or set "
+                    "FABRIC_TOKEN",
+                )
+            self._client = Client(cfg.api_url, cfg.token)
+            self._client.warn_if_outdated()
+        return self._client
+
+    def _client_cancel(self, run_id: str) -> None:
+        self._require_client().cancel_run(run_id)
+
+    def _ensure_bundle(self) -> str:
+        """Build (once) the project bundle and upload it, with dedup."""
+        if self._bundle_id is not None:
+            return self._bundle_id
+        bundle_id, _sha = self._build_and_upload_bundle()
+        return bundle_id
+
+    def _rebuild_bundle(self) -> tuple[str, str]:
+        """Re-bundle the project from scratch (used by ``blade serve``).
+
+        Returns ``(bundle_id, sha256)``. Dedup makes an unchanged project a
+        no-op upload (same sha256 → server returns the existing bundle). Forces
+        a fresh build (does not reuse ``self._bundle_id``) so edits are picked up.
+        """
+        return self._build_and_upload_bundle(force=True)
+
+    def _build_and_upload_bundle(self, *, force: bool = False) -> tuple[str, str]:
+        if not force and self._bundle_id is not None and self._bundle_sha256:
+            return self._bundle_id, self._bundle_sha256
+
+        from ._bundle import build_bundle
+
+        root = self._bundle_root or Path.cwd()
+        data, sha256, _arcnames = build_bundle(root)
+
+        # Local pre-check against the 256 MiB ceiling (conventions §6). The server
+        # is authoritative and returns 413 BUNDLE_TOO_LARGE, but failing here avoids
+        # paying for a large presigned upload that is bound to be rejected.
+        from ._constants import BUNDLE_MAX_BYTES
+
+        if len(data) > BUNDLE_MAX_BYTES:
+            raise exc.PayloadTooLargeError(
+                "BUNDLE_TOO_LARGE",
+                f"code bundle is {len(data)} bytes, over the "
+                f"{BUNDLE_MAX_BYTES}-byte (256 MiB) limit; trim files or add them "
+                "to .forgeignore.",
+            )
+
+        client = self._require_client()
+        resp = client.create_bundle(len(data), sha256)
+        bundle = resp["bundle"]
+        if not resp.get("deduplicated"):
+            upload_url = resp.get("upload_url")
+            if not upload_url:
+                # Contract: a non-deduplicated bundle must carry an upload_url.
+                # If it doesn't, the bundle stays `pending_upload` and the next
+                # create_run fails with an opaque 409 BUNDLE_NOT_READY. Fail loud
+                # here instead of shipping a half-created bundle id.
+                raise exc.FabricError(
+                    f"control plane returned a non-deduplicated bundle "
+                    f"{bundle.get('bundle_id')!r} without an upload_url; cannot "
+                    "complete the bundle upload."
+                )
+            client.upload_to_presigned(upload_url, data, "application/gzip")
+            bundle = client.complete_bundle(bundle["bundle_id"])
+        self._bundle_id = bundle["bundle_id"]
+        self._bundle_sha256 = sha256
+        return self._bundle_id, sha256