blobhub-cli 0.4.0__tar.gz → 0.6.0__tar.gz

{blobhub_cli-0.4.0 → blobhub_cli-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: blobhub-cli
-Version: 0.4.0
+Version: 0.6.0
 Summary: BlobHub command line interface — work with blobs, revisions, and their contents from the terminal
 Project-URL: Homepage, https://blobhub.io/
 Project-URL: Documentation, https://docs.blobhub.io/

{blobhub_cli-0.4.0 → blobhub_cli-0.6.0}/src/blobhub_cli/__init__.py

@@ -5,4 +5,4 @@ Contract: this module is the sole source of the package version — hatchling re
 Invariant: no other file in this package defines `__version__`.
 """
 
-__version__ = "0.4.0"
+__version__ = "0.6.0"

{blobhub_cli-0.4.0 → blobhub_cli-0.6.0}/src/blobhub_cli/api/client.py

@@ -3,6 +3,8 @@
 Contract: `get`, `query`, `command`, and `raw_query` route every response through `_handle`,
 which maps HTTP status and the body's `status` field onto the `api.errors` hierarchy;
 `raw_query` alone skips the status gate, and `probe` skips both the gate and the retry loop.
+`get`, `query` and `raw_query` retry every transient failure; `command` retries only
+`errors.NEVER_RAN`, because any other failure can follow a write the platform already committed.
 Neither `query`, `command`, nor `raw_query` names which component serves a data-channel call --
 the target revision's blob type decides that server-side, so there is nothing for a caller to
 supply here at all, even for a scheduler `deploy` that legitimately writes schedules against one
@@ -20,19 +22,29 @@ import time
 import httpx
 
 from blobhub_cli.api.errors import (
+    NEVER_RAN,
+    TRANSIENT,
     ApiAuthError,
     ApiCommandError,
+    ApiConnectError,
+    ApiLimitExceeded,
     ApiNetworkError,
     ApiRateLimited,
     ApiTransientError,
 )
 
-_TRANSIENT = (ApiRateLimited, ApiTransientError, ApiNetworkError)
 _ATTEMPTS = 3
 _BASE_DELAY = 0.5
 _MAX_DELAY = 8.0
 
 
+def _network_error(exc: httpx.TransportError) -> ApiNetworkError:
+    """The transport failure as an `ApiNetworkError`, or an `ApiConnectError` when nothing was sent."""
+    error_type = ApiConnectError if isinstance(exc, (httpx.ConnectError, httpx.ConnectTimeout)) else ApiNetworkError
+    # str() of an httpx transport error is often empty (ReadError("")); the class name is then the only cause.
+    return error_type(str(exc) or type(exc).__name__)
+
+
 class Client:
     def __init__(
         self,
@@ -62,7 +74,7 @@ class Client:
         # parameters instead of ignoring them, so `?limit=` or `?cursor=None` is a 400.
         if params is not None:
             params = {key: value for key, value in params.items() if value is not None}
-        return self._send("GET", path, gate_status=True, params=params or None)
+        return self._send("GET", path, gate_status=True, idempotent=True, params=params or None)
 
     def probe(self, path: str = "/users/me") -> tuple[int, float]:
         """One unretried request, returning (status_code, elapsed_ms) without gating the body.
@@ -75,7 +87,7 @@ class Client:
         try:
             resp = self._http.request("GET", path)
         except httpx.TransportError as exc:
-            raise ApiNetworkError(str(exc)) from exc
+            raise _network_error(exc) from exc
         return resp.status_code, (time.monotonic() - start) * 1000
 
     def query(self, revision_id: str, command: str, **args: object) -> dict:
@@ -92,20 +104,26 @@ class Client:
     ) -> dict:
         path = f"/revisions/{revision_id}/data/{channel}"
         body = {"command": command, **args}
-        return self._send("POST", path, gate_status=gate_status, json=body)
+        return self._send("POST", path, gate_status=gate_status, idempotent=(channel == "query"), json=body)
 
-    def _send(self, method: str, path: str, *, gate_status: bool, **kwargs: object) -> dict:
+    def _send(
+        self, method: str, path: str, *, gate_status: bool, idempotent: bool, **kwargs: object
+    ) -> dict:
+        # A write retries only what proves it never ran (docs/specs/2026-10-06-safe-retries.md).
+        retryable = TRANSIENT if idempotent else NEVER_RAN
         last_error: Exception
         for attempt in range(_ATTEMPTS):
             try:
                 resp = self._http.request(method, path, **kwargs)
             except httpx.TransportError as exc:
-                last_error = ApiNetworkError(str(exc))
+                last_error = _network_error(exc)
             else:
                 try:
                     return self._handle(resp, gate_status=gate_status)
-                except _TRANSIENT as exc:
+                except TRANSIENT as exc:
                     last_error = exc
+            if not isinstance(last_error, retryable):
+                break
             if attempt < _ATTEMPTS - 1:
                 self._sleep(random.random() * min(_MAX_DELAY, _BASE_DELAY * 2**attempt))
         raise last_error
@@ -122,5 +140,7 @@ class Client:
         except ValueError as exc:
             raise ApiTransientError(f"non-JSON response: HTTP {resp.status_code}") from exc
         if gate_status and data.get("status") != "success":
-            raise ApiCommandError(data.get("error", "unknown"), data.get("message", ""))
+            if data.get("error") == "limit_exceeded":
+                raise ApiLimitExceeded(data.get("message", ""), data.get("limit"))
+            raise ApiCommandError(data.get("error", "unknown"), data.get("message", ""), data.get("limit"))
         return data

{blobhub_cli-0.4.0 → blobhub_cli-0.6.0}/src/blobhub_cli/api/commands.py

@@ -41,8 +41,8 @@ class Api:
             f"/blobs/{org}/{blob}/revisions", {"limit": limit, "cursor": cursor})
         return body["revisions"], body["cursor"]
 
-    def get_blob_limits(self, org: str, blob: str) -> dict:
-        return self._client.get(f"/blobs/{org}/{blob}/limits")["limits"]
+    def get_blob_limits(self, org: str, blob: str) -> list[dict]:
+        return self._client.get(f"/blobs/{org}/{blob}/limits")["groups"]
 
     def list_definitions(self, revision_id: str, category: str) -> list[dict]:
         return self._client.query(revision_id, "list_definitions", category=category)["definitions"]
@@ -76,20 +76,11 @@ class Api:
         return self._client.command(revision_id, "create_session", **args)["session"]
 
     def get_session(self, revision_id: str, session: str) -> dict:
-        # Accepts an id OR an alias -- `get_session_by_session_id_or_alias` server-side. Unlike
-        # `create_execution`, which resolves the id only (spec §1.1).
+        # Accepts an id OR an alias -- get_session_by_session_id_or_alias server-side.
         return self._client.query(revision_id, "get_session", session_id=session)["session"]
 
-    def create_execution(self, revision_id: str, session_id: str, *, definition_id: str) -> dict:
-        # Addressed by id, not alias: `CREATE_EXECUTION_SCHEMA` accepts either, but the server
-        # resolves `alias` via a `(revision_id, alias)` query with no category filter, taking
-        # whichever definition comes back first. Alias uniqueness is scoped per `(category, alias)`
-        # (F1 spec §1.3), so the same alias can legally name both a workflow and a playground
-        # definition -- an alias-addressed execution could resolve to either, unpredictably. The
-        # caller already has the id from `load_set`, so there is no reason to take that risk.
-        return self._client.command(
-            revision_id, "create_execution", session_id=session_id, definition_id=definition_id
-        )["execution"]
+    def create_execution(self, revision_id: str, *, target: dict, workflow: dict) -> dict:
+        return self._client.command(revision_id, "create_execution", target=target, workflow=workflow)["execution"]
 
     def get_execution(self, revision_id: str, execution_id: str) -> dict:
         return self._client.query(revision_id, "get_execution", execution_id=execution_id)["execution"]
@@ -112,19 +103,6 @@ class Api:
             args["limit"] = limit
         return self._client.query(revision_id, "list_execution_events", **args)["execution_events"]
 
-    def list_executions(
-        self, revision_id: str, session_id: str, *, start_execution_id: str | None = None
-    ) -> tuple[list[dict], str | None]:
-        # start_execution_id is omitted rather than sent as null, same reason list_schedules omits
-        # start_schedule_id: LIST_EXECUTIONS_SCHEMA is additionalProperties: false. One page and the
-        # next cursor -- this method deliberately does not loop; the loop belongs to the caller that
-        # knows why it's paging (deploy's saturation count stops early on purpose).
-        args: dict[str, object] = {"session_id": session_id}
-        if start_execution_id is not None:
-            args["start_execution_id"] = start_execution_id
-        body = self._client.query(revision_id, "list_executions", **args)
-        return body["executions"], body["last_execution_id"]
-
     def create_schedule(self, revision_id: str, **fields: object) -> dict:
         return self._client.command(revision_id, "create_schedule", **fields)["schedule"]
 

blobhub_cli-0.6.0/src/blobhub_cli/api/errors.py

@@ -0,0 +1,90 @@
+"""Error hierarchy raised by `client.Client`.
+
+Contract: every failure raised is one of these classes, each carrying a `code` class attribute
+from `blobhub_cli.codes`; `ApiCommandError` additionally carries `.error`, the server's
+machine-readable failure string, kept separate from the human-readable `.message`, and `.limit`,
+the served limit object any refusal may carry -- `ApiLimitExceeded` is the `limit_exceeded` one.
+`outcome_unknown` says which failures leave a write's outcome unknown (the SDK-modernization
+epic's D5, `docs/specs/2026-10-06-safe-retries.md`).
+Invariant: no instance of any of these classes ever carries the API key — the client that
+raises them holds the only copy, and it is never included in a message here.
+"""
+
+import json
+
+from blobhub_cli import codes
+
+
+class ApiError(Exception):
+    """Base class for every error `Client` raises."""
+
+    code = "API_ERROR"
+
+
+class ApiAuthError(ApiError):
+    """The API key was rejected or the resource is forbidden (HTTP 401/403)."""
+
+    code = codes.AUTH_INVALID
+
+
+class ApiRateLimited(ApiError):
+    """API Gateway throttled the request (HTTP 429) before anything ran. Retried for every request."""
+
+    code = codes.API_RATE_LIMITED
+
+
+class ApiTransientError(ApiError):
+    """A server-side or malformed-response failure (HTTP 5xx, non-JSON body). Retried for reads only."""
+
+    code = codes.API_TRANSIENT_ERROR
+
+
+class ApiNetworkError(ApiError):
+    """A transport failure: no usable response arrived. Retried for reads only."""
+
+    code = codes.API_NETWORK_ERROR
+
+
+class ApiConnectError(ApiNetworkError):
+    """The connection was never established, so the request was never sent. Retried for every request."""
+
+
+class ApiCommandError(ApiError):
+    """A successful HTTP response whose body reports `status` other than `success`."""
+
+    code = codes.API_COMMAND_FAILED
+
+    def __init__(self, error: str, message: str = "", limit: dict | None = None) -> None:
+        message = with_limit(message, limit)
+        super().__init__(message or error)
+        self.error = error
+        self.message = message or error
+        self.limit = limit
+
+
+class ApiLimitExceeded(ApiCommandError):
+    """A `limit_exceeded` refusal: a quota or a configurable ceiling has been reached."""
+
+    code = codes.LIMIT_EXCEEDED
+
+    def __init__(self, message: str = "", limit: dict | None = None) -> None:
+        super().__init__("limit_exceeded", message, limit)
+
+
+def with_limit(message: str, limit: dict | None) -> str:
+    """`message` with the served limit appended, as `(limit <id>: value <v>[, held <h>])`."""
+    if not limit:
+        return message
+    held = f", held {json.dumps(limit['held'])}" if "held" in limit else ""
+    named = f"limit {limit.get('id')}: value {json.dumps(limit.get('value'))}{held}"
+    return f"{message} ({named})" if message else named
+
+
+TRANSIENT = (ApiRateLimited, ApiTransientError, ApiNetworkError)
+# A write may retry only these: a 429 is refused before any handler runs, and a failed connect sent nothing.
+NEVER_RAN = (ApiRateLimited, ApiConnectError)
+
+
+def outcome_unknown(error: BaseException) -> bool:
+    """Whether a failed request may still have been carried out by the platform."""
+    return isinstance(error, TRANSIENT) and not isinstance(error, NEVER_RAN)

{blobhub_cli-0.4.0 → blobhub_cli-0.6.0}/src/blobhub_cli/cli/app.py

@@ -12,7 +12,7 @@ import typer
 from typer.completion import completion_init
 
 from blobhub_cli import __version__, codes, console
-from blobhub_cli.api.errors import ApiError
+from blobhub_cli.api.errors import ApiCommandError, ApiError
 from blobhub_cli.commands.completion import Shell as CompletionShell
 from blobhub_cli.config import settings
 from blobhub_cli.exit import CliExit
@@ -175,7 +175,7 @@ def build_app() -> typer.Typer:
         blob: str = typer.Argument(..., help="Blob as '<org>/<name>', or a bare name with --org."),
         refresh: bool = typer.Option(False, "--refresh", help="Also refresh the compiler's local allowlist cache."),
     ) -> None:
-        """Show a blob's limits, including the import allowlist. Requires an admin-scoped key."""
+        """Show a blob's limits by group: id, holding, source and value."""
         from blobhub_cli.commands import blob as blob_cmd
 
         blob_cmd.limits(blob, refresh)
@@ -234,13 +234,12 @@ def build_app() -> typer.Typer:
         manifest: Path = typer.Option(..., "-f", "--file", help="Path to the workflow manifest."),  # noqa: B008
         definition: list[str] = typer.Option([], "--definition", help="Limit to this alias, repeatable."),  # noqa: B008
         force: bool = typer.Option(False, "--force", help="Overwrite code edited outside the CLI."),
-        strict_imports: bool = typer.Option(False, "--strict-imports", help="Treat an unverifiable import as fatal."),
         dry_run: bool = typer.Option(False, "--dry-run", help="Report the intended calls and perform none."),
     ) -> None:
         """Build, upload only what changed, and check the workflow definitions that were uploaded."""
         from blobhub_cli.commands import workflow
 
-        workflow.deploy(manifest, tuple(definition), force, strict_imports, dry_run)
+        workflow.deploy(manifest, tuple(definition), force, dry_run)
 
     @workflow_app.command("eject")
     def workflow_eject(
@@ -258,7 +257,10 @@ def build_app() -> typer.Typer:
     @workflow_app.command("execute")
     def workflow_execute(
         manifest: Path = typer.Option(..., "-f", "--file", help="Path to the workflow manifest."),  # noqa: B008
-        definition: str = typer.Option(..., "--definition", help="Alias of the workflow definition to execute."),
+        definition: str = typer.Option(
+            ..., "--definition",
+            help="A manifest alias, or <blob-id>/<revision>/<definition> or <org>/<blob>/<revision>/<definition>.",
+        ),
         session: str = typer.Option(None, "--session", help="Session alias or id; created if the alias is new."),
         watch: bool = typer.Option(False, "--watch", help="Follow execution events until the run finishes."),
         open_browser: bool = typer.Option(False, "--open", help="Open the execution in the web debugger."),
@@ -315,10 +317,11 @@ def build_app() -> typer.Typer:
     def scheduler_pull(
         manifest: Path = typer.Option(..., "-f", "--file", help="Path to the scheduler manifest."),  # noqa: B008
     ) -> None:
-        """Reverse each deployed schedule's stored UUIDs back into a symbolic manifest.
+        """Rewrite the manifest's schedules as the platform stores them, field for field.
 
-        Not the inverse of deploy: deploy resolves symbols into UUIDs and may create a session, a
-        side effect pull cannot undo."""
+        Replaces every entry in the file, local edits included, and rewrites a manifest in the retired
+        layout. Ids stay ids: nothing is turned back into an alias. Not the inverse of deploy: deploy
+        may create a session, a side effect pull cannot undo."""
         from blobhub_cli.commands import scheduler
 
         scheduler.pull(manifest)
@@ -333,10 +336,10 @@ def build_app() -> typer.Typer:
     ) -> None:
         """Make the manifest real: create schedules that don't exist, update those that do, by alias.
 
-        Refuses before writing anything if any target fails validation -- a half-deployed schedule
-        set is worse than a refused one, since the half that landed is already firing. Not pull's
-        inverse: deploy resolves symbols into UUIDs and may create a session, a side effect pull
-        cannot undo, even under --dry-run."""
+        Validates every entry before writing anything -- a half-deployed schedule set is worse than a
+        refused one, since the half that landed is already firing -- then sends each as written, a
+        pinned target's session as its resolved id. Not pull's inverse: deploy may create a session, a
+        side effect pull cannot undo, even under --dry-run."""
         from blobhub_cli.commands import scheduler
 
         scheduler.deploy(manifest, dry_run)
@@ -377,7 +380,8 @@ def main(argv: list[str] | None = None) -> int:
         # so wrap it in a CliExit rather than let a raw traceback reach the user. Only AUTH_INVALID
         # has a hint that's genuinely a runnable command; inventing one for the rest would be prose.
         hint = "blobhub login" if exc.code == codes.AUTH_INVALID else ""
-        console.error(CliExit(exc.code, str(exc), hint))
+        limit = exc.limit if isinstance(exc, ApiCommandError) else None
+        console.error(CliExit(exc.code, str(exc), hint, limit=limit))
         return 1
     except Exception as exc:  # usage errors carry exit_code; anything else is a real bug
         # Typer >=0.24 vendors its own click fork under `typer._click` rather than

{blobhub_cli-0.4.0 → blobhub_cli-0.6.0}/src/blobhub_cli/codes.py

@@ -31,7 +31,6 @@ MANIFEST_VERSION_UNSUPPORTED = "MANIFEST_VERSION_UNSUPPORTED"
 BLOB_REFERENCE_INVALID = "BLOB_REFERENCE_INVALID"
 BLOB_NOT_ACCESSIBLE = "BLOB_NOT_ACCESSIBLE"
 BLOB_NOT_WORKFLOW = "BLOB_NOT_WORKFLOW"
-LIMITS_NOT_ACCESSIBLE = "LIMITS_NOT_ACCESSIBLE"
 REVISION_NOT_ACCESSIBLE = "REVISION_NOT_ACCESSIBLE"
 REVISION_NOT_WRITABLE = "REVISION_NOT_WRITABLE"
 
@@ -43,6 +42,9 @@ ALIAS_IN_USE = "ALIAS_IN_USE"
 LIMIT_EXCEEDED = "LIMIT_EXCEEDED"
 PRUNE_NOT_CONFIRMED = "PRUNE_NOT_CONFIRMED"
 
+# Workflow references
+WORKFLOW_REFERENCE_INVALID = "WORKFLOW_REFERENCE_INVALID"
+
 # Format
 FORMAT_UNSUPPORTED = "FORMAT_UNSUPPORTED"
 FORMAT_PARSE_ERROR = "FORMAT_PARSE_ERROR"
@@ -79,6 +81,7 @@ SESSION_NOT_ACCESSIBLE = "SESSION_NOT_ACCESSIBLE"
 SESSION_NOT_OPEN = "SESSION_NOT_OPEN"
 DEFINITION_NOT_EXECUTABLE = "DEFINITION_NOT_EXECUTABLE"
 EXECUTION_FAILED = "EXECUTION_FAILED"
+EXECUTION_OUTCOME_UNKNOWN = "EXECUTION_OUTCOME_UNKNOWN"
 
 # Schedules
 SCHEDULE_ALIAS_REQUIRED = "SCHEDULE_ALIAS_REQUIRED"

{blobhub_cli-0.4.0 → blobhub_cli-0.6.0}/src/blobhub_cli/commands/blob.py

@@ -7,10 +7,11 @@ Those are right for a command about to drive a workflow blob and wrong for an in
 in an unusable phase is precisely what someone runs `blob show` to diagnose.
 """
 
+import json
 from collections.abc import Callable
 from datetime import UTC, datetime
 
-from blobhub_cli import codes, console
+from blobhub_cli import console
 from blobhub_cli.api.client import Client
 from blobhub_cli.api.commands import Api
 from blobhub_cli.api.errors import ApiAuthError, ApiError
@@ -19,7 +20,6 @@ from blobhub_cli.blob.reference import BlobRef
 from blobhub_cli.compiler import allowlist
 from blobhub_cli.config import settings
 from blobhub_cli.config.settings import Settings
-from blobhub_cli.exit import CliExit
 
 
 def _default_api_factory(resolved: Settings) -> Api:
@@ -135,11 +135,14 @@ def revisions(ref_text: str, *, api_factory: Callable[[Settings], Api] = _defaul
 
 def _render_limits(payload: dict) -> None:
     print(f"Limits for {payload['blob']}")
-    for name, entry in sorted(payload["limits"].items()):
-        fields = (
-            ", ".join(f"{key}={entry[key]}" for key in sorted(entry)) if isinstance(entry, dict) else str(entry)
-        )
-        print(f"  {name:<40} {fields}")
+    ids = [entry["id"] for group in payload["groups"] for entry in group["limits"]]
+    width = max(map(len, ids), default=2)
+    print(f"  {'ID':<{width}}  {'HELD':<8} {'SOURCE':<8} VALUE")
+    for group in payload["groups"]:
+        print(f"{group['label']} ({group['group']})")
+        for entry in group["limits"]:
+            print(f"  {entry['id']:<{width}}  {entry.get('held', '')!s:<8} {entry['source']:<8} "
+                  f"{json.dumps(entry['value'])}")
     if payload["refreshed"]:
         print(f"Allowlist cache written to {payload['cache_path']}")
 
@@ -147,28 +150,14 @@ def _render_limits(payload: dict) -> None:
 def limits(ref_text: str, refresh: bool, *, api_factory: Callable[[Settings], Api] = _default_api_factory) -> dict:
     ref, resolved = _resolve_ref(ref_text, "blob limits")
     api = api_factory(resolved)
-
-    # A hard failure, not a degradation to cache -- deliberately unlike `allowlist.fetch`, which
-    # swallows this same 403. The difference is what the caller asked for: `build` wants imports
-    # validated and a cached answer serves that; this command wants the limits, and a partial
-    # answer silently sourced from a week-old file is worse than a clear refusal.
     try:
-        record = api.get_blob_limits(ref.org, ref.name)
+        groups = api.get_blob_limits(ref.org, ref.name)
     except ApiAuthError as exc:
-        # The same handler 403s an unknown blob (spec §1.1), so the message must not assert a cause
-        # it cannot know -- sending someone off to mint an admin key over a typo'd blob name is a
-        # worse failure than saying plainly that the platform conflates the two.
-        raise CliExit(
-            codes.LIMITS_NOT_ACCESSIBLE,
-            f"limits for {ref.label()} are not readable: reading limits needs an admin-scoped key "
-            f"(the read/write keys recommended for automation cannot), or the blob is absent -- "
-            f"the platform returns the same 403 for both",
-            "blobhub whoami",
-        ) from exc
+        raise reference.not_accessible(ref) from exc
 
     cache_path = None
     if refresh:
-        modules = set(record.get(allowlist.LIMIT_KEY, {}).get("value", []))
+        modules = allowlist.modules_from(groups)
         # Keyed on the raw positional text, exactly as `build`/`diff`/`deploy` key on the manifest's
         # `blob:` field as written: `normalize_cache_key` org-qualifies precisely when its input
         # does, so keying on `ref.label()` here would write `acme/flow.yaml` for the bare reference
@@ -176,6 +165,6 @@ def limits(ref_text: str, refresh: bool, *, api_factory: Callable[[Settings], Ap
         cache_key = allowlist.normalize_cache_key(ref_text)
         cache_path = str(allowlist.store(cache_key, modules, datetime.now(UTC).isoformat(), ref.org, ref.name))
 
-    payload = {"blob": ref.label(), "limits": record, "refreshed": refresh, "cache_path": cache_path}
+    payload = {"blob": ref.label(), "groups": groups, "refreshed": refresh, "cache_path": cache_path}
     console.result(payload, _render_limits)
     return payload

{blobhub_cli-0.4.0 → blobhub_cli-0.6.0}/src/blobhub_cli/commands/execute.py

@@ -1,11 +1,11 @@
 """`workflow execute`: create an execution of a workflow definition, optionally following it.
 
-Contract: `--definition` must name a `workflow`-category manifest entry -- a `playground` alias is
-refused with `DEFINITION_NOT_EXECUTABLE` before anything is created, and an alias absent from the
-manifest surfaces F1's `DEFINITION_NOT_ACCESSIBLE` straight out of `load_set`. The definition is
-addressed by id, never by `alias=`, in the `create_execution` call: the server resolves a bare alias
-with no category filter, so an alias shared across categories could resolve to the wrong definition
-(spec §4.3, F1 spec §1.3).
+Contract: `--definition` is a workflow reference in the path form (`workflow/reference.py`), sent to
+`create_execution` as the `workflow` object exactly as typed, beside `target: {session: <id>}` -- the id of the
+session `resolve_session` found or created. A bare alias must name a deployed
+`workflow`-category manifest entry -- a `playground` one is refused with `DEFINITION_NOT_EXECUTABLE`
+before anything is created -- while a qualified reference names a definition outside the local
+package, so it skips the manifest and is resolved by the platform alone.
 Invariant: `console.result` always runs before an `EXECUTION_FAILED` raise, so a `--json` consumer
 still receives the payload -- including the execution id -- for a failed run. The debugger URL is
 always in the payload; `--open` launches a browser only when `console` is not in JSON mode
@@ -22,11 +22,13 @@ from pathlib import Path
 from blobhub_cli import codes, console
 from blobhub_cli.api.client import Client
 from blobhub_cli.api.commands import Api
+from blobhub_cli.api.errors import ApiAuthError, ApiCommandError, ApiError, outcome_unknown
 from blobhub_cli.config import settings
 from blobhub_cli.config.settings import Settings
 from blobhub_cli.exit import CliExit
 from blobhub_cli.manifest import resolver, workflow
-from blobhub_cli.workflow import definitions, executions
+from blobhub_cli.workflow import definitions, executions, reference
+from blobhub_cli.workflow.reference import WorkflowRef
 
 # blobhub-web serves the routes `Navigation.workflowPath` builds (src/context/nav.js) from
 # blobhub.io; the path itself -- `/{org_id}/{blob_id}/debugger/{session_id}/{execution_id}` -- is
@@ -49,9 +51,69 @@ def _render_execute(payload: dict) -> None:
     print(f"debugger: {payload['url']}")
 
 
+def _check_local_definition(api: Api, target: resolver.Target, manifest: workflow.WorkflowManifest, alias: str) -> None:
+    set_ = definitions.load_set(
+        api, target.revision_id, manifest, only=(alias,), org=target.org_id, blob=target.blob_id
+    )
+    # `load_set(only=...)` already raised DEFINITION_NOT_ACCESSIBLE for an alias absent from the manifest. An
+    # alias declared in both categories has no qualifier here, so the workflow-category entry is preferred.
+    entry = next((e for e in set_.entries if e.category == "workflow"), set_.entries[0])
+    if entry.category != "workflow":
+        raise CliExit(
+            codes.DEFINITION_NOT_EXECUTABLE,
+            f"{alias!r} is a {entry.category!r} definition, and the platform executes workflow definitions only",
+            f"blobhub workflow ls -f {manifest.base.path}",
+        )
+    if (entry.category, entry.alias) not in set_.remote:
+        raise CliExit(
+            codes.DEFINITION_NOT_ACCESSIBLE,
+            f"{alias!r} is in the manifest but not deployed on revision {target.revision_id}",
+            f"blobhub workflow deploy -f {manifest.base.path}",
+        )
+
+
+def _debugger_url(target: resolver.Target, session_id: str, execution_id: str | None = None) -> str:
+    """The web debugger's page for a session, or for one of its executions."""
+    path = f"{DEBUGGER_BASE_URL}/{target.org_id}/{target.blob_id}/debugger/{session_id}"
+    if execution_id is not None:
+        path = f"{path}/{execution_id}"
+    # `?revision=` carries the RESOLVED id, never the manifest's symbol: an execution lives in one
+    # revision, and a link without it opens on whatever revision the reader last chose, where this
+    # session does not exist. blobhub-web drops the parameter itself once it names the default.
+    return f"{path}?revision={target.revision_id}"
+
+
+def _create_execution(api: Api, revision_id: str, session_id: str, ref: WorkflowRef, session_url: str) -> dict:
+    try:
+        return api.create_execution(revision_id, target={"session": session_id}, workflow=ref.to_object())
+    except ApiAuthError as exc:
+        raise CliExit(
+            codes.DEFINITION_NOT_ACCESSIBLE,
+            f"workflow {ref.path()!r} is absent or not reachable with this key, or this key cannot write to the "
+            "session's blob -- the platform answers the same 403 for each",
+            "blobhub whoami",
+        ) from exc
+    except ApiCommandError as exc:
+        if exc.error != "invalid_definition_category":
+            raise
+        raise CliExit(
+            codes.DEFINITION_NOT_EXECUTABLE,
+            f"{ref.path()!r} is a playground definition, and the platform executes workflow definitions only",
+        ) from exc
+    except ApiError as exc:
+        if not outcome_unknown(exc):
+            raise
+        raise CliExit(
+            codes.EXECUTION_OUTCOME_UNKNOWN,
+            f"creating the execution of {ref.path()!r} failed after the request may have reached the platform "
+            f"({exc}), so a run may have started. Check session {session_id} for it before running the command "
+            f"again: {session_url}",
+        ) from exc
+
+
 def execute(
     manifest_path: Path,
-    definition_alias: str,
+    definition: str,
     session: str | None,
     watch: bool,
     open_browser: bool,
@@ -59,40 +121,20 @@ def execute(
     api_factory: Callable[[Settings], Api] = _default_api_factory,
     browser: Callable[[str], object] = webbrowser.open,
 ) -> dict:
+    ref = reference.parse(definition, hint=f"blobhub workflow execute -f {manifest_path} --definition <reference>")
     resolved = settings.resolve()
     api = api_factory(resolved)
     manifest = workflow.load(manifest_path)
     target = resolver.resolve(
         api, manifest.base, require_writable=False, expect=resolver.WORKFLOW_BLOB, default_org=resolved.org
     )
-    set_ = definitions.load_set(
-        api, target.revision_id, manifest, only=(definition_alias,), org=target.org_id, blob=target.blob_id
-    )
-
-    # `load_set(only=...)` already raised DEFINITION_NOT_ACCESSIBLE if the alias isn't in the
-    # manifest at all, so at least one entry is guaranteed here. A manifest may legally declare the
-    # same alias in both categories (F1 spec §1.3); `--definition` has no category qualifier to
-    # disambiguate that case, so this deliberately takes the first and does not detect the collision.
-    entry = set_.entries[0]
-    if entry.category != "workflow":
-        raise CliExit(
-            codes.DEFINITION_NOT_EXECUTABLE,
-            f"{definition_alias!r} is a {entry.category!r} definition, and the platform executes "
-            "workflow definitions only",
-            f"blobhub workflow ls -f {manifest.base.path}",
-        )
+    if not ref.qualified:
+        _check_local_definition(api, target, manifest, ref.definition)
 
     session_id, session_created = executions.resolve_session(api, target.revision_id, session)
-    definition_id = set_.remote[(entry.category, entry.alias)].id
-    execution = api.create_execution(target.revision_id, session_id, definition_id=definition_id)
+    execution = _create_execution(api, target.revision_id, session_id, ref, _debugger_url(target, session_id))
 
-    # `?revision=` carries the RESOLVED id, never the manifest's symbol: an execution lives in one
-    # revision, and a link without it opens on whatever revision the reader last chose, where this
-    # session does not exist. blobhub-web drops the parameter itself once it names the default.
-    url = (
-        f"{DEBUGGER_BASE_URL}/{target.org_id}/{target.blob_id}/debugger/{session_id}/{execution['id']}"
-        f"?revision={target.revision_id}"
-    )
+    url = _debugger_url(target, session_id, execution["id"])
     # Launching a browser is a side effect, not output -- there is no `console.stream()` call this
     # could route through -- so it is the one place this command asks `console.json_mode()` directly.
     if open_browser and not console.json_mode():
@@ -102,7 +144,7 @@ def execute(
         "execution_id": execution["id"],
         "session_id": session_id,
         "session_created": session_created,
-        "definition": definition_alias,
+        "definition": definition,
         "status": execution.get("status", ""),
         "url": url,
     }
@@ -124,7 +166,7 @@ def execute(
             raise CliExit(
                 codes.EXECUTION_FAILED,
                 f"execution {execution['id']} reached a terminal 'failed' status",
-                f"blobhub workflow execute -f {manifest.base.path} --definition {definition_alias} --open",
+                f"blobhub workflow execute -f {manifest.base.path} --definition {definition} --open",
             )
 
     console.result(payload, _render_execute)