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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: blobhub-cli
-Version: 0.3.0
+Version: 0.4.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/
@@ -151,7 +151,7 @@ my-project/
 type: workflow_blob_deployment
 version: "1.0"
 blob: acme-corp/checkout                # <org>/<blob>, or a bare <blob> plus --org/BLOBHUB_ORG
-revision: latest                        # or a pinned revision UUID
+revision: default                       # the blob's default revision, or a pinned revision UUID
 definitions:
   - alias: checkout_flow
     source: definitions/checkout_flow.json

{blobhub_cli-0.3.0 → blobhub_cli-0.4.0}/README.md

@@ -98,7 +98,7 @@ my-project/
 type: workflow_blob_deployment
 version: "1.0"
 blob: acme-corp/checkout                # <org>/<blob>, or a bare <blob> plus --org/BLOBHUB_ORG
-revision: latest                        # or a pinned revision UUID
+revision: default                       # the blob's default revision, or a pinned revision UUID
 definitions:
   - alias: checkout_flow
     source: definitions/checkout_flow.json

{blobhub_cli-0.3.0 → blobhub_cli-0.4.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.3.0"
+__version__ = "0.4.0"

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

@@ -57,8 +57,12 @@ class Client:
     def __exit__(self, *exc_info: object) -> None:
         self._http.close()
 
-    def get(self, path: str) -> dict:
-        return self._send("GET", path, gate_status=True)
+    def get(self, path: str, params: dict[str, object] | None = None) -> dict:
+        # A `None` entry is dropped rather than sent: the paged routes validate their query
+        # 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)
 
     def probe(self, path: str = "/users/me") -> tuple[int, float]:
         """One unretried request, returning (status_code, elapsed_ms) without gating the body.

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

@@ -26,8 +26,20 @@ class Api:
     def get_revision(self, revision_id: str) -> dict:
         return self._client.get(f"/revisions/{revision_id}")["revision"]
 
-    def list_revisions(self, org: str, blob: str) -> list[dict]:
-        return self._client.get(f"/blobs/{org}/{blob}/revisions")["revisions"]
+    def resolve_revision(self, org: str, blob: str, ref: str) -> dict:
+        # `ref` is a revision id or the literal `default`. Unlike `get_revision`, this route resolves
+        # the ref *within the blob*, so a revision id belonging to another blob answers the same 404
+        # as one that does not exist -- which `/revisions/{id}` cannot do, having no blob in its path.
+        return self._client.get(f"/blobs/{org}/{blob}/revisions/{ref}")["revision"]
+
+    def list_revisions(
+        self, org: str, blob: str, *, limit: int | None = None, cursor: str | None = None
+    ) -> tuple[list[dict], str | None]:
+        # One page and the next cursor -- this method deliberately does not loop, for the reason
+        # list_schedules gives: a loop here would hide the paging from every test that uses it.
+        body = self._client.get(
+            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"]

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

@@ -156,7 +156,7 @@ def build_app() -> typer.Typer:
 
     @blob_app.command("show")
     def blob_show(blob: str = typer.Argument(..., help="Blob as '<org>/<name>', or a bare name with --org.")) -> None:
-        """Show a blob's record and the phase of its latest revision."""
+        """Show a blob's record and the phase of its default revision."""
         from blobhub_cli.commands import blob as blob_cmd
 
         blob_cmd.show(blob)
@@ -165,7 +165,7 @@ def build_app() -> typer.Typer:
     def blob_revisions(
         blob: str = typer.Argument(..., help="Blob as '<org>/<name>', or a bare name with --org."),
     ) -> None:
-        """List a blob's revisions, newest first, marking the latest."""
+        """List a blob's revisions, newest first, marking the default."""
         from blobhub_cli.commands import blob as blob_cmd
 
         blob_cmd.revisions(blob)

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

@@ -88,7 +88,6 @@ SCHEDULE_NOT_ACCESSIBLE = "SCHEDULE_NOT_ACCESSIBLE"
 
 # Advisories (warnings, not exit-worthy failures)
 DEFINITION_LIST_TRUNCATED = "DEFINITION_LIST_TRUNCATED"
-REVISION_LIST_TRUNCATED = "REVISION_LIST_TRUNCATED"
 ALLOWLIST_UNREADABLE = "ALLOWLIST_UNREADABLE"
 ALLOWLIST_STALE = "ALLOWLIST_STALE"
 ALLOWLIST_ENTRY_UNUSABLE = "ALLOWLIST_ENTRY_UNUSABLE"

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

@@ -11,7 +11,6 @@ from collections.abc import Callable
 from datetime import UTC, datetime
 
 from blobhub_cli import codes, console
-from blobhub_cli import limits as limits_module
 from blobhub_cli.api.client import Client
 from blobhub_cli.api.commands import Api
 from blobhub_cli.api.errors import ApiAuthError, ApiError
@@ -49,9 +48,9 @@ def _render_show(payload: dict) -> None:
         ("Visibility", "visibility"), ("Status", "status"),
     ):
         print(f"{label + ':':<12} {record.get(key, '')}")
-    revision_id = record.get("latest_revision_id")
-    revision = payload["latest_revision"]
-    print(f"{'Latest:':<12} {revision_id or '(none)'}")
+    revision_id = record.get("default_revision_id")
+    revision = payload["default_revision"]
+    print(f"{'Default:':<12} {revision_id or '(none)'}")
     if revision is None:
         # Two distinct states, and telling them apart is the difference between "mint a better key"
         # and "this blob has no revision yet".
@@ -68,7 +67,7 @@ def show(ref_text: str, *, api_factory: Callable[[Settings], Api] = _default_api
     record = _get_blob(api, ref)
 
     revision = None
-    revision_id = record.get("latest_revision_id")
+    revision_id = record.get("default_revision_id")
     if revision_id:
         try:
             revision = api.get_revision(revision_id)
@@ -79,7 +78,7 @@ def show(ref_text: str, *, api_factory: Callable[[Settings], Api] = _default_api
 
     # `blob` is the "org/name" label on every command in this group, never the record itself: one
     # key name across three sibling commands cannot carry two types and stay a machine contract.
-    payload = {"blob": ref.label(), "record": record, "latest_revision": revision}
+    payload = {"blob": ref.label(), "record": record, "default_revision": revision}
     console.result(payload, _render_show)
     return payload
 
@@ -89,7 +88,7 @@ def _render_revisions(payload: dict) -> None:
         return
     print(f"{'':2}{'REVISION':<38} {'PHASE':<9} {'STATUS':<11} {'CREATED':<26} COMMENT")
     for item in payload["revisions"]:
-        marker = "* " if item["latest"] else "  "
+        marker = "* " if item["default"] else "  "
         print(f"{marker}{item['id']:<38} {item['phase']:<9} {item['status']:<11} "
               f"{item['created_at']:<26} {item['comment']}")
 
@@ -98,41 +97,36 @@ def revisions(ref_text: str, *, api_factory: Callable[[Settings], Api] = _defaul
     ref, resolved = _resolve_ref(ref_text, "blob revisions")
     api = api_factory(resolved)
 
-    # The listing does not report which revision is latest, so the blob record is required, not
+    # The listing does not report which revision is the default, so the blob record is required, not
     # merely enrichment.
     record = _get_blob(api, ref)
-    latest_revision_id = record.get("latest_revision_id")
-    found = api.list_revisions(ref.org, ref.name)
-
-    maximum = limits_module.maximum(
-        limits_module.read_optional(api, ref.org, ref.name), limits_module.LIMIT_REVISIONS_PER_BLOB
-    )
-    if maximum is not None and len(found) >= maximum:
-        console.advisory(
-            codes.REVISION_LIST_TRUNCATED,
-            f"the revision listing returned {len(found)} revision(s), matching the blob's configured "
-            f"maximum of {maximum} -- the platform cannot page this listing, so the result may be "
-            "missing revisions it silently dropped",
-        )
-
-    # Newest first: DynamoDB returns index order, which is neither documented nor useful, and the
-    # reason to run this command is almost always to find the newest revision.
-    items = sorted(
-        (
-            {
-                "id": item["id"],
-                "phase": item.get("phase", ""),
-                "status": item.get("status", ""),
-                "created_at": item.get("created_at", ""),
-                "comment": item.get("comment", ""),
-                "parent_id": item.get("parent_id"),
-                "latest": item["id"] == latest_revision_id,
-            }
-            for item in found
-        ),
-        key=lambda item: item["created_at"],
-        reverse=True,
-    )
+    default_revision_id = record.get("default_revision_id")
+
+    # Drained page by page, terminating on the cursor and never on a short page -- the same rule
+    # `scheduler/schedules.py`'s `load_all` follows, and for the same reason: the cursor is absent
+    # only once the query is exhausted, so a final page can legitimately be exactly full.
+    found: list[dict] = []
+    cursor: str | None = None
+    while True:
+        page, cursor = api.list_revisions(ref.org, ref.name, cursor=cursor)
+        found.extend(page)
+        if cursor is None:
+            break
+
+    # Order comes from the route, which queries the `blob_id-created_at` index newest-first and
+    # documents that. Re-sorting a complete, ordered result could only reorder ties.
+    items = [
+        {
+            "id": item["id"],
+            "phase": item.get("phase", ""),
+            "status": item.get("status", ""),
+            "created_at": item.get("created_at", ""),
+            "comment": item.get("comment", ""),
+            "parent_id": item.get("parent_id"),
+            "default": item["id"] == default_revision_id,
+        }
+        for item in found
+    ]
 
     payload = {"blob": ref.label(), "revisions": items}
     console.result(payload, _render_revisions)

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

@@ -30,7 +30,8 @@ from blobhub_cli.workflow import definitions, executions
 
 # 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
-# reproduced below rather than assumed (spec §1.4).
+# reproduced below rather than assumed (spec §1.4). The revision rides as `?revision=`, never in the
+# path: that path form is deleted, and the slot it used is the debugger's own.
 DEBUGGER_BASE_URL = "https://blobhub.io"
 
 
@@ -85,7 +86,13 @@ def execute(
     definition_id = set_.remote[(entry.category, entry.alias)].id
     execution = api.create_execution(target.revision_id, session_id, definition_id=definition_id)
 
-    url = f"{DEBUGGER_BASE_URL}/{target.org_id}/{target.blob_id}/debugger/{session_id}/{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.
+    url = (
+        f"{DEBUGGER_BASE_URL}/{target.org_id}/{target.blob_id}/debugger/{session_id}/{execution['id']}"
+        f"?revision={target.revision_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():

{blobhub_cli-0.3.0 → blobhub_cli-0.4.0}/src/blobhub_cli/commands/scheduler.py

@@ -58,7 +58,7 @@ from blobhub_cli.config import settings
 from blobhub_cli.config.settings import Settings
 from blobhub_cli.exit import CliExit
 from blobhub_cli.formats import io
-from blobhub_cli.manifest import resolver, scheduler
+from blobhub_cli.manifest import base, resolver, scheduler
 from blobhub_cli.scheduler import references, schedules
 
 # Spec §8: the real workflow_executions_per_session maximum needs an admin key most callers don't
@@ -79,7 +79,7 @@ def _render_ls(payload: dict) -> None:
     print(f"{'':2}{'ALIAS':<30} {'ID':<38} {'REPEAT':<15} {'ENABLED':<8} {'STATE':<10} WORKFLOW")
     for item in payload["schedules"]:
         # `*` marks a schedule the manifest covers -- the same marker `workflow ls` and
-        # `_render_revisions` (`commands/blob.py`) use for coverage/latest, so this table reads like
+        # `_render_revisions` (`commands/blob.py`) use for coverage/default, so this table reads like
         # its siblings at a glance.
         marker = "* " if item["in_manifest"] else "  "
         # A schedule the platform stored with no alias has nothing to put in this column; the ID
@@ -136,15 +136,12 @@ def ls(
     return payload
 
 
-def _reversed_entry(api: Api, record: dict, *, manifest_org_id: str, original_revision: str) -> dict:
+def _reversed_entry(api: Api, record: dict, *, manifest_org_id: str) -> dict:
     # Built as a plain dict, not a `manifest.scheduler.ScheduleEntry` -- `pull` writes a document
     # through `formats.io`, and the dataclass exists to be parsed *from* a manifest, not serialized
     # back into one. Field order here matches the manifest sample in the spec, so a pulled file reads
     # the same way a hand-authored one does.
-    target = references.reverse_target(
-        api, record["invocation_target"], manifest_org_id=manifest_org_id,
-        original_revision=original_revision,
-    )
+    target = references.reverse_target(api, record["invocation_target"], manifest_org_id=manifest_org_id)
     target_doc = {
         "type": target.type,
         "blob": target.blob,
@@ -206,21 +203,11 @@ def pull(
     # firing, and dropping it silently is how an operator ends up with a schedule they cannot see.
     unmanageable = [record["id"] for record in records if record.get("alias") is None]
 
-    # Reversal must reproduce the symbol the entry actually wrote, and a stored `invocation_target`
-    # records only the resolved id -- so the manifest's own entries are the sole surviving evidence
-    # of whether a target revision was written as `latest` or deliberately pinned. Matched by alias,
-    # the same identity `deploy` decides create-versus-update on; a schedule with no manifest entry
-    # has no original symbol to reproduce, and `latest` stays the right default for it.
-    original_revisions = {entry.alias: entry.target.revision for entry in manifest.schedules}
-
     # Sorted by alias, like `ls`'s rows: deterministic output a diff or a script can rely on, not an
     # accident of `list_schedules`' newest-first paging order.
     entries = sorted(
         (
-            _reversed_entry(
-                api, record, manifest_org_id=target.org_id,
-                original_revision=original_revisions.get(record["alias"], "latest"),
-            )
+            _reversed_entry(api, record, manifest_org_id=target.org_id)
             for record in records if record.get("alias") is not None
         ),
         key=lambda entry: entry["alias"],
@@ -276,8 +263,12 @@ def _local_fields(
         "enabled": entry.enabled,
         "start_date": entry.start_date,
         "end_date": entry.end_date,
-        "target.revision": target.revision_id,
-        "target.session": target.session_id,
+        # The symbols the platform stores, not the ids they resolved to. `target.blob` is not
+        # cosmetic: under `revision: default` the revision symbol is identical for every blob, so
+        # without it a manifest retargeted at a different blob compares equal and is never written.
+        "target.blob": target.blob_id,
+        "target.revision": target.revision_ref,
+        "target.session": _stored_session(target),
         "target.workflow": target.workflow_alias,
         "target.input_data": target.input_data,
         "target.description": target.description,
@@ -298,8 +289,9 @@ def _remote_fields(record: dict) -> dict:
         "enabled": record["enabled"],
         "start_date": record.get("start_date"),
         "end_date": record.get("end_date"),
-        "target.revision": invocation_target["revision_id"],
-        "target.session": invocation_target["session_id"],
+        "target.blob": invocation_target["blob_id"],
+        "target.revision": invocation_target["revision"],
+        "target.session": invocation_target["session"],
         "target.workflow": invocation_target["workflow_alias"],
         "target.input_data": invocation_target.get("input_data", []),
         "target.description": invocation_target.get("description"),
@@ -373,9 +365,13 @@ def diff(
 
 
 def _invocation_target(resolved: references.ResolvedTarget) -> dict:
+    # INVOCATION_TARGET_SCHEMA is additionalProperties: false and has no `org_id` -- the platform
+    # derives the org from the blob. `revision` is the manifest's own symbol, not the id it resolved
+    # to, because storing the id is exactly the pinning a following target exists to avoid.
     target: dict[str, object] = {
-        "revision_id": resolved.revision_id,
-        "session_id": resolved.session_id,
+        "blob_id": resolved.blob_id,
+        "revision": resolved.revision_ref,
+        "session": _stored_session(resolved),
         "workflow_alias": resolved.workflow_alias,
         "input_data": resolved.input_data,
     }
@@ -384,6 +380,18 @@ def _invocation_target(resolved: references.ResolvedTarget) -> dict:
     return target
 
 
+def _stored_session(target: references.PreviewedTarget | references.ResolvedTarget) -> str | None:
+    """What the platform ends up holding in `invocation_target.session` for this target.
+
+    A following target keeps its alias -- `_resolve_invocation_target_blob` writes the resolved id
+    back only for a pinned one. Sending what the platform will store is what keeps a second `deploy`
+    of an unchanged manifest a no-op rather than a perpetual update.
+    """
+    if target.revision_ref == base.REVISION_DEFAULT:
+        return target.session_ref
+    return target.session_id
+
+
 def _schedule_fields(entry: scheduler.ScheduleEntry, resolved: references.ResolvedTarget) -> dict:
     # Keys omitted rather than sent as null: every command schema is additionalProperties: false
     # (api/commands.py), so an explicit start_date/end_date: null would be a 400, not an ignored field.

{blobhub_cli-0.3.0 → blobhub_cli-0.4.0}/src/blobhub_cli/commands/workflow.py

@@ -654,7 +654,7 @@ def _render_ls(payload: dict) -> None:
     print(f"{'':2}{'CATEGORY':<10} {'ALIAS':<30} ID")
     for item in payload["definitions"]:
         # `*` marks a definition the manifest covers -- the same marker `_render_revisions`
-        # (`commands/blob.py`) uses for "latest", so this table reads like its sibling at a glance.
+        # (`commands/blob.py`) uses for "default", so this table reads like its sibling at a glance.
         marker = "* " if item["in_manifest"] else "  "
         print(f"{marker}{item['category']:<10} {item['alias']:<30} {item['id']}")
 

{blobhub_cli-0.3.0 → blobhub_cli-0.4.0}/src/blobhub_cli/ids.py

@@ -1,4 +1,4 @@
-"""Identifier-shape checks shared across domains.
+r"""Identifier-shape checks shared across domains.
 
 Contract: `looks_like_uuid` is the one syntax check for whether a string is shaped like a UUID,
 factored out here so no single domain module (blob references, sessions, and schedules) owns a
@@ -6,7 +6,7 @@ check every domain needs.
 Invariant: this is a shape check, not an existence check -- a well-formed UUID may still resolve to
 nothing, and callers must still handle a not-found/not-accessible response after this returns True.
 
-There are two predicates here, not one, because they answer different questions. `looks_like_uuid`
+There are three predicates here, not one, because they answer different questions. `looks_like_uuid`
 is read-side and permissive on purpose: it delegates to `uuid.UUID`, which also accepts a dashless
 32-hex string, a `{braced}` form, and a `urn:uuid:` form, and every one of the CLI's existing
 "is this an id or an alias" branches wants exactly that leniency -- a caller handing back any spelling
@@ -19,6 +19,15 @@ ordinary alias as far as the platform is concerned -- `is_canonical_uuid` must n
 of `looks_like_uuid`, or it would reject aliases the platform accepts, and `looks_like_uuid` must
 never be used to gate alias creation, or it would reject aliases the platform accepts for a different
 reason (dashless 32-hex parses as a UUID but is not the canonical shape the platform refuses).
+
+`matches_platform_session_id_shape` is the third, and it is neither of the others: it is a literal
+copy of one JSON-Schema pattern, `INVOCATION_TARGET_SCHEMA`'s `SESSION_ID_SHAPE_PATTERN`, which
+decides whether a following schedule target's `session` is refused at save. It separates from
+`looks_like_uuid` in BOTH directions, which is why substituting either for the other is wrong:
+dashless 32-hex is a UUID to `uuid.UUID` and an ordinary alias to the schema, while a
+whitespace-padded UUID is not a UUID to `uuid.UUID` and IS a session id to the schema, whose pattern
+is wrapped in `\s*`. Use it only where the question is "what will that schema do", never as a
+general id check.
 """
 
 import re
@@ -29,6 +38,14 @@ import uuid
 # docstring for why a dashless 32-hex string must stay outside this pattern.
 _CANONICAL_UUID = re.compile(r"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$")
 
+# `INVOCATION_TARGET_SCHEMA`'s SESSION_ID_SHAPE_PATTERN, character for character (blobhub-infra
+# `api/blob_types/blobhub/compute/scheduler/component.py:147`). The `\s*` wrapper and the
+# case-insensitive hex are the platform's, not a convenience: `get_session_by_session_id_or_alias`
+# strips and lower-cases before deciding id-from-alias, so a padded or upper-case UUID reaches it as
+# an id. Copied rather than approximated -- an approximation refuses manifests the platform accepts.
+_PLATFORM_SESSION_ID_SHAPE = re.compile(
+    r"^\s*[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}\s*$")
+
 
 def looks_like_uuid(value: str) -> bool:
     try:
@@ -40,3 +57,8 @@ def looks_like_uuid(value: str) -> bool:
 
 def is_canonical_uuid(value: str) -> bool:
     return bool(_CANONICAL_UUID.match(value))
+
+
+def matches_platform_session_id_shape(value: str) -> bool:
+    """True when `INVOCATION_TARGET_SCHEMA` would read `value` as a session id rather than an alias."""
+    return bool(_PLATFORM_SESSION_ID_SHAPE.match(value))

{blobhub_cli-0.3.0 → blobhub_cli-0.4.0}/src/blobhub_cli/limits.py

@@ -10,8 +10,6 @@ answer confidently and wrongly.
 from blobhub_cli.api.commands import Api
 from blobhub_cli.api.errors import ApiError
 
-LIMIT_REVISIONS_PER_BLOB = "revisions_per_blob"
-
 
 def read_optional(api: Api, org: str | None, blob: str | None) -> dict | None:
     # Limits require an admin key (F1 spec §1.6); a read/write key gets a 403 here. There is no

{blobhub_cli-0.3.0 → blobhub_cli-0.4.0}/src/blobhub_cli/manifest/base.py

@@ -16,6 +16,13 @@ from blobhub_cli import codes
 from blobhub_cli.blob import reference
 from blobhub_cli.exit import CliExit
 
+# The one revision reference that is a resolution rule rather than an id: it names whatever the
+# blob's `default_revision_id` points at right now (blobhub-infra `RevisionsTable.REF_DEFAULT`).
+REVISION_DEFAULT = "default"
+
+# What `REVISION_DEFAULT` replaced. Kept only so the check below can name the rename.
+_REVISION_RENAMED_FROM = "latest"
+
 
 @dataclass(frozen=True)
 class ManifestBase:
@@ -59,18 +66,27 @@ def check_blob_reference(blob: str, hint: str, *, label: str = "blob") -> None:
 
 
 def check_revision(revision: str, hint: str, *, label: str = "revision") -> None:
-    """A revision reference is `latest` or a platform revision id, which is a bare lowercase UUID
+    """A revision reference is `default` or a platform revision id, which is a bare lowercase UUID
     (`Handler.generate_id`). Shared with `target.revision` for the same reason as above -- answered
     offline, where the message can name the malformed value, rather than as an unreachable revision
     one network round trip later.
     """
-    if revision == "latest":
+    if revision == REVISION_DEFAULT:
         return
+    if revision == _REVISION_RENAMED_FROM:
+        # A well-formed string, so the generic message below would send its author looking for a
+        # typo instead of a rename -- and the platform reads it as a revision id and answers 404.
+        raise CliExit(
+            codes.MANIFEST_INVALID,
+            f"{label} {revision!r} is no longer a revision reference; a blob's moving pointer is now "
+            f"named {REVISION_DEFAULT!r}",
+            hint,
+        )
     try:
         uuid.UUID(revision)
     except ValueError as exc:
         raise CliExit(
-            codes.MANIFEST_INVALID, f"{label} {revision!r} is neither 'latest' nor a UUID", hint,
+            codes.MANIFEST_INVALID, f"{label} {revision!r} is neither {REVISION_DEFAULT!r} nor a UUID", hint,
         ) from exc
 
 

{blobhub_cli-0.3.0 → blobhub_cli-0.4.0}/src/blobhub_cli/manifest/resolver.py

@@ -1,8 +1,8 @@
 """General reference resolver: turns a parsed `ManifestBase` into concrete platform coordinates.
 
 Contract: `resolve` checks blob accessibility, the caller-supplied `expect` blob type (before any
-data-channel call, which would otherwise answer an opaque `500`), `latest` resolution through
-`blob.latest_revision_id`, then the status/phase gate, in that fixed order. `expect` is a required
+data-channel call, which would otherwise answer an opaque `500`), the revision through the
+blob-scoped resolve route, then the status/phase gate, in that fixed order. `expect` is a required
 keyword-only argument -- this module resolves `blob`/`revision` coordinates for any blob type, and
 a default of the workflow type would leave that one type's assumption sitting inside a resolver
 that calls itself general.
@@ -14,7 +14,7 @@ from dataclasses import dataclass
 
 from blobhub_cli import codes
 from blobhub_cli.api.commands import Api
-from blobhub_cli.api.errors import ApiAuthError
+from blobhub_cli.api.errors import ApiAuthError, ApiCommandError
 from blobhub_cli.blob import reference
 from blobhub_cli.blob.reference import BlobRef
 from blobhub_cli.exit import CliExit
@@ -34,7 +34,6 @@ class Target:
     revision_id: str
     phase: str
     status: str
-    latest_revision_id: str
 
 
 def command_group(expect: str) -> str:
@@ -80,19 +79,26 @@ def resolve(
             f"blob {org}/{blob_name} is {blob_type!r}, not a {expect!r} blob",
         )
 
-    revision_id = base.revision
-    latest_revision_id = blob["latest_revision_id"]
-    if revision_id == "latest":
-        revision_id = latest_revision_id
-
+    # The manifest's symbol goes to the platform verbatim: `default` is the platform's own
+    # resolution rule, and the route resolves it against the blob in the path -- which is also what
+    # makes it refuse a pinned revision belonging to some other blob, something `/revisions/{id}`
+    # has no blob to check against.
     try:
-        revision = api.get_revision(revision_id)
-    except ApiAuthError as exc:
+        revision = api.resolve_revision(org, blob_name, base.revision)
+    except (ApiAuthError, ApiCommandError) as exc:
+        # Both, not just the first: the route answers 403 for a blob the key cannot read and a
+        # `revision_not_found` body at 404 for a revision that is missing or belongs elsewhere, and
+        # the client maps those to two different classes.
+        # The second clause is not decoration: a well-formed UUID that resolved yesterday now fails
+        # because the route checks ownership, and without it the message sends its author hunting
+        # for a deleted revision instead of at the `blob:` line above it.
         raise CliExit(
             codes.REVISION_NOT_ACCESSIBLE,
-            f"revision {revision_id} is absent or not reachable",
+            f"revision {base.revision} is absent or not reachable on {org}/{blob_name}; a pinned "
+            f"revision must belong to the blob named in 'blob:'",
             f"blobhub {group} diff -f {base.path}",
         ) from exc
+    revision_id = revision["id"]
 
     status = revision["status"]
     phase = revision["phase"]
@@ -111,11 +117,4 @@ def resolve(
         revision_id=revision_id,
         phase=phase,
         status=status,
-        latest_revision_id=latest_revision_id,
     )
-
-
-def reverse_revision(base_revision: str, resolved_id: str, latest_revision_id: str) -> str:
-    if base_revision != "latest":
-        return base_revision
-    return "latest" if resolved_id == latest_revision_id else resolved_id

{blobhub_cli-0.3.0 → blobhub_cli-0.4.0}/src/blobhub_cli/manifest/scheduler.py

@@ -128,10 +128,24 @@ def _parse_target(raw: object, hint: str) -> TargetRef:
     revision_ref = _require_str(raw, "revision", hint)
     base.check_revision(revision_ref, hint, label="target revision")
 
+    # INVOCATION_TARGET_SCHEMA's one cross-field rule, mirrored offline: a following target may not
+    # name its session by id, because no session id survives a revision boundary. The predicate is
+    # the schema's own pattern rather than `looks_like_uuid`, which differs from it in both
+    # directions and would refuse a legal alias as readily as it would miss a real id.
+    session_ref = _require_str(raw, "session", hint)
+    if revision_ref == base.REVISION_DEFAULT and ids.matches_platform_session_id_shape(session_ref):
+        raise CliExit(
+            codes.MANIFEST_INVALID,
+            f"target session {session_ref!r} is a session id, and a target following "
+            f"{base.REVISION_DEFAULT!r} must name its session by alias -- no session id survives the "
+            "revision the default moves to",
+            hint,
+        )
+
     return TargetRef(
         blob=blob_ref,
         revision=revision_ref,
-        session=_require_str(raw, "session", hint),
+        session=session_ref,
         workflow=_require_str(raw, "workflow", hint),
         input_data=input_data,
         description=description,

{blobhub_cli-0.3.0 → blobhub_cli-0.4.0}/src/blobhub_cli/scheduler/references.py

@@ -11,19 +11,19 @@ refuse the target runs while refusing is still free. A failure anywhere in the b
 workflow-alias trio is re-raised as one `SCHEDULE_TARGET_INVALID` naming the target's own blob or
 alias, matching the code's documented scope; a session failure is not folded in and keeps
 `resolve_session`'s own codes, since `SCHEDULE_TARGET_INVALID` names only blob/revision/workflow.
-`reverse_target` undoes it: a `revision` the entry wrote as `latest` reverses to `"latest"` only
-while it still leads the blob and to the literal id otherwise, while one the entry *pinned* reverses
-to that pin -- which is why the original symbol is a caller-supplied argument rather than assumed
-(`resolver.reverse_revision`, reused unchanged), a session id
-reverses to its alias when it has one, and `blob` reverses to a bare name when the target lives in
-the *manifest's own* org -- reproducing the original symbol, not a UUID, which is the whole point of
-`pull` (spec §12.1, §13.3) -- and to a fully-qualified `org_id/blob_alias` reference otherwise, since
-a blob record carries no human-readable org handle to qualify it with instead. The caller supplies
+`reverse_target` undoes it, and now mostly by *reading* rather than deriving: a stored target records
+`blob_id`, the `revision` symbol itself (`default` or a pinned id) and, for a following target, the
+session alias -- so `revision` reverses verbatim and a following target needs no session lookup at
+all. Only a pinned target still resolves its session id back to an alias, since that is the one shape
+the platform rewrites. `blob` reverses to a bare name when the target lives in the *manifest's own*
+org -- reproducing the original symbol, not a UUID, which is the whole point of `pull` (spec §12.1,
+§13.3) -- and to a fully-qualified `org_id/blob_alias` reference otherwise, since a blob record
+carries no human-readable org handle to qualify it with instead. The caller supplies
 `manifest_org_id` because it already has it: `pull` must resolve the manifest's own scheduler blob
-before it can list schedules at all, and that resolution already returns `Target.org_id`.
-Invariant: the target blob/revision is read-only here (`require_writable=False`) -- deploying a
-schedule creates a session on the target revision but never writes to the revision's own content,
-so scheduling against a `commit` or `managed` phase target is fine.
+before it can list schedules at all, and that resolution already returns `Target.org_id`. Why the
+symbol is read rather than derived from the blob's pointer: docs/specs/2026-09-21-revision-default.md
+Invariant: a target revision must admit writes (`{draft, managed}`), because the schedule's whole
+purpose is to write an execution into it and the platform checks that phase at save time.
 
 `ResolvedTarget.blob_id` (Task 8) exists only so `deploy`'s saturation check can read the target
 blob's limits without a second resolution: `get_blob`/`get_blob_limits` both resolve `blob` by
@@ -53,7 +53,7 @@ from blobhub_cli import codes, console, ids, limits
 from blobhub_cli.api.commands import Api
 from blobhub_cli.api.errors import ApiAuthError
 from blobhub_cli.exit import CliExit
-from blobhub_cli.manifest import resolver
+from blobhub_cli.manifest import base, resolver
 from blobhub_cli.manifest.base import ManifestBase
 from blobhub_cli.manifest.resolver import Target
 from blobhub_cli.manifest.scheduler import TargetRef
@@ -66,6 +66,9 @@ _WORKFLOW_DEFINITIONS_LIMIT = "workflow_definitions_per_revision"
 @dataclass(frozen=True)
 class ResolvedTarget:
     revision_id: str
+    revision_ref: str  # the manifest's own symbol -- `default` or a pinned id -- which is what the
+    # platform stores; `revision_id` is what it resolved to here and is what every other call needs.
+    session_ref: str   # likewise the manifest's own symbol, which is what a FOLLOWING target stores
     session_id: str
     session_created: bool
     workflow_alias: str
@@ -88,8 +91,12 @@ def _target_base(target: TargetRef) -> ManifestBase:
 
 def _resolve_blob_revision(api: Api, target: TargetRef, *, manifest_org: str) -> Target:
     try:
+        # `require_writable=True`, because firing this schedule writes an execution into the target
+        # revision and `create_schedule` refuses a phase outside PHASES_WRITE
+        # (blobhub-infra scheduler `component.py:623`). Refusing here is what keeps that 403 out of
+        # `deploy`'s pass 2, where earlier entries are already written and already firing.
         return resolver.resolve(
-            api, _target_base(target), require_writable=False, expect=resolver.WORKFLOW_BLOB,
+            api, _target_base(target), require_writable=True, expect=resolver.WORKFLOW_BLOB,
             default_org=manifest_org,
         )
     except CliExit as exc:
@@ -167,6 +174,8 @@ def resolve_target(api: Api, target: TargetRef, *, manifest_org: str) -> Resolve
 
     return ResolvedTarget(
         revision_id=resolved.revision_id,
+        revision_ref=target.revision,
+        session_ref=target.session,
         session_id=session_id,
         session_created=session_created,
         workflow_alias=target.workflow,
@@ -179,11 +188,14 @@ def resolve_target(api: Api, target: TargetRef, *, manifest_org: str) -> Resolve
 @dataclass(frozen=True)
 class PreviewedTarget:
     revision_id: str
+    revision_ref: str
+    session_ref: str
     workflow_alias: str
     input_data: list
     description: str | None
     session_id: str | None  # None means the session does not exist yet -- diff must not create it
     session_would_create: bool
+    blob_id: str
 
 
 def preview_target(api: Api, target: TargetRef, *, manifest_org: str) -> PreviewedTarget:
@@ -213,19 +225,19 @@ def preview_target(api: Api, target: TargetRef, *, manifest_org: str) -> Preview
 
     return PreviewedTarget(
         revision_id=resolved.revision_id,
+        revision_ref=target.revision,
+        session_ref=target.session,
         workflow_alias=target.workflow,
         input_data=target.input_data,
         description=target.description,
         session_id=session_id,
         session_would_create=session_would_create,
+        blob_id=resolved.blob_id,
     )
 
 
-def reverse_target(
-    api: Api, invocation_target: dict, *, manifest_org_id: str, original_revision: str = "latest"
-) -> TargetRef:
-    revision_id = invocation_target["revision_id"]
-    blob_id = api.get_revision(revision_id)["blob_id"]
+def reverse_target(api: Api, invocation_target: dict, *, manifest_org_id: str) -> TargetRef:
+    blob_id = invocation_target["blob_id"]
 
     # `GET /blobs/{org}/{blob}` resolves `{blob}` by primary key, and never consults `{org}` at all,
     # the moment `{blob}` is a real id rather than an alias (`get_blob_by_org_id_and_blob_id`,
@@ -238,16 +250,17 @@ def reverse_target(
     # handle, only its raw `org_id`, so a genuinely cross-org target is qualified with that id rather
     # than an alias -- it was explicitly qualified by whoever authored it in the first place.
     blob_ref = blob["alias"] if blob["org_id"] == manifest_org_id else f"{blob['org_id']}/{blob['alias']}"
-    # `original_revision` is the symbol the manifest entry actually wrote, supplied by the caller
-    # because nothing in a stored `invocation_target` records it: the platform keeps only the
-    # resolved id. A manifest that pinned a literal revision did so precisely so the next revision
-    # cut would not retarget the schedule, and reversing that to `latest` would undo the pin
-    # silently -- indistinguishably so when the pinned id happens to still be the blob's latest.
-    # `"latest"` is only the right default where there is no entry to have written anything.
-    revision_ref = resolver.reverse_revision(original_revision, revision_id, blob["latest_revision_id"])
+    # Verbatim: the stored target records the symbol the manifest wrote, `default` included.
+    revision_ref = invocation_target["revision"]
 
-    session = api.get_session(revision_id, invocation_target["session_id"])
-    session_ref = session.get("alias") or invocation_target["session_id"]
+    if revision_ref == base.REVISION_DEFAULT:
+        # A following target keeps the alias it was deployed with -- the platform deliberately does
+        # not pin it, because no session id survives the revision the default moves to. There is
+        # nothing to look up, and no revision id to look it up in.
+        session_ref = invocation_target["session"]
+    else:
+        session = api.get_session(revision_ref, invocation_target["session"])
+        session_ref = session.get("alias") or invocation_target["session"]
 
     return TargetRef(
         blob=blob_ref,