mostlyright-data 0.9.0__py3-none-any.whl

mostlyright/data_harness/ux/hosted_run_status.py

@@ -0,0 +1,619 @@
+"""Studio's own reading of one activated Run, reported exactly as Studio reports it.
+
+`mr-data deploy --resume` queues a Run and returns its `run_id`. Until now that identifier was the
+end of the conversation: nothing in this repository ever asked Studio how the Run was doing, so the
+only way to learn whether a Dataset had built was to open the Cloud dashboard. This module asks,
+through the same pinned generated client the deployment path already builds, and reports the answer
+without embellishing it.
+
+Three rules decide everything below.
+
+**The state vocabulary is Studio's.** `RecipeBoundRunStatus` has thirteen values, and every one of
+them is in :data:`RUN_STATES` with what it means and what the operator should do about it, each
+classified from Studio's own state machines rather than from how its name reads. The build is
+where a fourteenth value is caught: `tests/test_hosted_run_status.py` enumerates the enum out of
+the pinned client wheel, so a state added upstream fails there rather than reaching a person as a
+shrug. At runtime such a value is refused rather than rendered -- the pinned client will not parse
+it, and `DEPLOY_RUN_STATUS_UNKNOWN` guards the table for any answer that gets past it -- and in no
+case is it shown as a state, a terminal answer, or a released version.
+
+**Nothing displayed is derived from a clock.** Every fact in the payload comes out of one Studio
+response or out of the deployment journal. The one duration reported is the difference between two
+timestamps Studio persisted, and it is absent whenever either is. No percentage, no estimate, and
+no elapsed counter is manufactured here, because a number nobody measured is worse than no number.
+
+**A poll is a bounded request.** With no `--watch-seconds` this is exactly one read. With one, it
+is a bounded loop that stops the moment Studio's answer stops changing on its own -- at a terminal
+state, or at one of the two states that will not move until somebody acts elsewhere -- and, if the
+bound arrives first, says so as its own answer rather than claiming the Run ended.
+
+The polling shape, the backoff, and the two retryable refusals follow
+:mod:`mostlyright.data_harness.ux.hosted_acquisition`, which already polls a hosted Studio session
+to a terminal state; the binding check before an answer is believed follows its
+``_validate_initial_session``. Nothing here streams events, downloads an artifact, cancels, or
+retries a Run: this module reads one resource and prints what it says.
+"""
+
+from __future__ import annotations
+
+import time
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+from uuid import UUID
+
+from mostlyright.data_harness.hosted_deploy import (
+    STUDIO_SCHEMA_VERSION,
+    FileDeploymentStateStore,
+    GeneratedStudioDeploymentClient,
+    HostedDeployError,
+    StudioDeploymentClient,
+    StudioToken,
+    cloud_dashboard_url,
+)
+from mostlyright.data_harness.ux.credentials import ResolvedCloudCredentials
+
+RUN_STATUS_SCHEMA = "mostlyright-hosted-run-status.v1"
+
+#: The longest a `--watch-seconds` may ask this command to wait, and the same half hour
+#: `hosted_acquisition.POLL_TIMEOUT_SECONDS` bounds a hosted acquisition by. A watch is a
+#: foreground operation somebody is sitting in front of; it stays interruptible and it always ends.
+MAX_WATCH_SECONDS = 1800
+
+#: The first gap between reads, and the ceiling the doubling stops at. A hosted Run is minutes to
+#: hours long, so the gap grows quickly and then stays at half a minute rather than asking Studio
+#: about a Run that has not started yet twice a second.
+FIRST_POLL_DELAY_SECONDS = 2.0
+MAX_POLL_DELAY_SECONDS = 30.0
+
+#: What the harness does next, given a state. `watching` is the only value that keeps a watch
+#: going: `released`, `stopped` and `needs_a_person` are all places the answer stops changing
+#: without something happening outside this command.
+WATCHING = "watching"
+RELEASED = "released"
+STOPPED = "stopped"
+NEEDS_A_PERSON = "needs_a_person"
+
+_WAIT = "nothing to do here; the run continues on its own"
+_DEPLOY_AGAIN = (
+    "deploy again when you want another version, passing --previous-run-dir so it updates this "
+    "Dataset instead of founding a second one"
+)
+#: What to do about a run that ended without a version, said once. Both states that reach it need
+#: the same two things: a corrected Build, and the flag that keeps it on the same Dataset.
+_DEPLOY_CORRECTED = (
+    "correct the Recipe or the sources it names, then deploy the corrected Build with "
+    "--previous-run-dir pointing at this run directory"
+)
+
+
+@dataclass(frozen=True)
+class RunState:
+    """One of Studio's thirteen Run states, and what it means for whoever deployed.
+
+    ``disposition`` is what this command does about the state, not a coarser name for it: the
+    state itself is always reported verbatim beside it. ``terminal`` says Studio has finished with
+    this Run; a state that is neither terminal nor watched is one waiting on a person, which is a
+    third thing and is never folded into either of the other two.
+    """
+
+    disposition: str
+    terminal: bool
+    means: str
+    next: str
+
+    @property
+    def keep_watching(self) -> bool:
+        return self.disposition == WATCHING
+
+
+#: Every value of the pinned V3 contract's `RecipeBoundRunStatus`, with the sentence a person reads.
+#:
+#: ⚠ THIS TABLE IS THE CONTRACT, and it is checked against the pinned client rather than
+#: remembered. Five of these states -- the two retry states, the two that wait on a person, and
+#: `releasable` -- have no place at all in the five-step ladder this surface was first sketched as,
+#: and folding them into "building" or "failed" would have hidden the two situations where somebody
+#: has to go and do something. So each state says what it is and what to do, and a state that needs
+#: a person says so in the disposition as well as in the words.
+#:
+#: ⚠ WHICH STATES THOSE ARE IS STUDIO'S ANSWER, NOT A GUESS FROM THEIR NAMES. Every classification
+#: below is read off Studio's own machines -- `contracts/state-machines/run.json` and
+#: `run-orchestration-v2.json` in mostlyrightmd/mostlyright-studio -- because two of them read
+#: backwards from the outside. `awaiting_candidate_selection` sounds like a person choosing and is
+#: an ordinary step Studio takes itself (`awaiting_candidate_selection -> verifying`, actor
+#: `studio_orchestrator`) on the way through EVERY healthy run; parking a watch there would stop
+#: the common case dead and send the operator to do something nobody is permitted to do.
+#: `human_direction_required` sounds like a question somebody can answer and is listed in that
+#: machine's `terminal_states` with one way in (`repair_required`, at the fix-it cycle limit) and
+#: no way out at all, so the only move left is a corrected Build.
+#:
+#: ⚠ TWO OF STUDIO'S RUN STATES ARE NOT IN THIS TABLE, and that is Studio's doing rather than an
+#: omission here. The two machines together declare fifteen; `RecipeBoundRunStatus`, the vocabulary
+#: the pinned v2 read contract actually answers with, has thirteen. `reviewing` and
+#: `awaiting_approval` exist in `run.json` and in the `listRuns` filter, and have no value in the
+#: enum `get_run` returns, so no answer this module can receive is in either of them. They are
+#: written down here rather than left out silently, and
+#: `test_the_states_studio_cannot_report_are_named_here` fails the day one gains an enum value.
+STATES_STUDIO_CANNOT_REPORT: frozenset[str] = frozenset({"reviewing", "awaiting_approval"})
+
+RUN_STATES: dict[str, RunState] = {
+    "queued": RunState(
+        disposition=WATCHING,
+        terminal=False,
+        means="Studio has accepted this run and has not started it yet.",
+        next=_WAIT,
+    ),
+    "running": RunState(
+        disposition=WATCHING,
+        terminal=False,
+        means="A Builder is building this version of the Dataset.",
+        next=_WAIT,
+    ),
+    "verifying": RunState(
+        disposition=WATCHING,
+        terminal=False,
+        means="A Checker is re-running this version's own checks against it.",
+        next=_WAIT,
+    ),
+    "releasable": RunState(
+        disposition=WATCHING,
+        terminal=False,
+        means="Every check passed. Studio has not released the version yet.",
+        next=_WAIT,
+    ),
+    "released": RunState(
+        disposition=RELEASED,
+        terminal=True,
+        means="The new version passed and is live. This is the state a deployment is aiming at.",
+        next="read the Dataset at the current path this deployment recorded",
+    ),
+    "cancelled": RunState(
+        disposition=STOPPED,
+        terminal=True,
+        means="Somebody stopped this run before it produced a version.",
+        next=_DEPLOY_AGAIN,
+    ),
+    "failed": RunState(
+        disposition=STOPPED,
+        terminal=True,
+        means="The run stopped without producing a version.",
+        next=_DEPLOY_CORRECTED,
+    ),
+    "abandoned": RunState(
+        disposition=STOPPED,
+        terminal=True,
+        means="Studio stopped attempting this run. Nothing further will happen to it.",
+        next=_DEPLOY_AGAIN,
+    ),
+    "awaiting_candidate_selection": RunState(
+        disposition=WATCHING,
+        terminal=False,
+        means="The Builder finished and Studio has not started checking its result yet.",
+        next=_WAIT,
+    ),
+    "human_direction_required": RunState(
+        disposition=NEEDS_A_PERSON,
+        terminal=True,
+        means=(
+            "Studio reached its limit for fix-it attempts on this run and stopped. Nothing moves "
+            "it from here, and no answer given in Cloud restarts it."
+        ),
+        next=f"{_DEPLOY_CORRECTED}; this run itself will not go any further",
+    ),
+    "producer_retry_pending": RunState(
+        disposition=WATCHING,
+        terminal=False,
+        means="A build attempt did not finish, and Studio has queued another one.",
+        next=_WAIT,
+    ),
+    "verifier_retry_pending": RunState(
+        disposition=WATCHING,
+        terminal=False,
+        means="A checking attempt did not finish, and Studio has queued another one.",
+        next=_WAIT,
+    ),
+    "repair_required": RunState(
+        disposition=NEEDS_A_PERSON,
+        terminal=False,
+        means=(
+            "A check did not pass, and Studio has opened a fix-it task for it. The run waits "
+            "until that task is carried out and produces a corrected run."
+        ),
+        next=(
+            "follow that fix-it task in Cloud; this command displays the state and cannot carry "
+            "the task out"
+        ),
+    ),
+}
+
+
+@dataclass(frozen=True)
+class ActivatedRun:
+    """The coordinates one deployment journal already holds about the Run it queued.
+
+    Nothing here is invented and nothing is asked of Studio to build it: the deployment wrote all
+    of it down before this command existed, which is exactly why a killed process, a slept laptop,
+    or a fresh terminal can pick the same Run back up.
+    """
+
+    run_id: UUID
+    dataset_id: UUID
+    table_id: UUID
+    workspace_id: UUID
+    table_recipe_id: str
+    recipe: Mapping[str, Any]
+    schedule: Mapping[str, Any]
+    cloud_dataset_id: str | None
+    current_path: str | None
+    state_path: Path
+
+
+def journaled_activation(run_dir: Path) -> ActivatedRun:
+    """Read the queued Run's coordinates out of one deployment journal, writing no state.
+
+    Nothing recorded is changed, and no request leaves the machine. The one thing this does touch
+    is the journal's own directory: opening it goes through the deployment's file store, which
+    creates ``evidence/deployment/`` when it is absent and takes its lock, so a run directory that
+    has never been deployed gains two empty directories before being refused.
+
+    Raises:
+        HostedDeployError: when there is no journal, when it cannot be read safely, or when it
+            records no queued Run yet.
+    """
+
+    store = FileDeploymentStateStore(run_dir)
+    try:
+        if not store.exists():
+            raise HostedDeployError(
+                "DEPLOY_STATE_MISSING", f"no deployment journal exists at {store.path}"
+            )
+        state = store.load()
+        path = store.path
+    finally:
+        store.close()
+    resources = state.get("resources")
+    activation = resources.get("activation") if isinstance(resources, Mapping) else None
+    if not isinstance(activation, Mapping):
+        raise HostedDeployError(
+            "DEPLOY_RUN_NOT_ACTIVATED",
+            "this deployment has not queued a run yet; recover the exact deployment with "
+            "mr-data deploy --resume",
+        )
+    if state.get("schema_version") != "mostlyright-hosted-deployment-state.v3":
+        raise HostedDeployError(
+            "DEPLOY_STATE_INVALID",
+            "the deployment journal is not a V3 Dataset/Table deployment",
+        )
+    binding = resources.get("cloud_binding")
+    binding = binding if isinstance(binding, Mapping) else {}
+    inputs = state.get("identity_inputs")
+    inputs = inputs if isinstance(inputs, Mapping) else {}
+    schedule = state.get("schedule")
+    return ActivatedRun(
+        run_id=_journaled_uuid(activation, "run_id"),
+        dataset_id=_journaled_uuid(resources, "dataset_id"),
+        table_id=_journaled_uuid(activation, "table_id"),
+        workspace_id=_journaled_uuid(state, "workspace_id"),
+        table_recipe_id=_journaled_identifier(inputs, "table_recipe_id"),
+        # The V3 deployment journal records the exact TableRecipe coordinate before activation.
+        # Older V2 journals are deliberately not aliased: their dataset_id named the child object.
+        recipe={name: inputs[name] for name in ("recipe_version", "recipe_digest")},
+        schedule=dict(schedule) if isinstance(schedule, Mapping) else {},
+        cloud_dataset_id=_optional_text(binding, "cloud_dataset_id"),
+        current_path=_optional_text(binding, "current_path"),
+        state_path=path,
+    )
+
+
+def report_run_status(
+    run_dir: Path,
+    *,
+    token: StudioToken,
+    credentials: ResolvedCloudCredentials,
+    watch_seconds: int | None = None,
+    client_factory: Callable[[StudioToken], StudioDeploymentClient] | None = None,
+    clock: Callable[[], float] = time.monotonic,
+    sleep: Callable[[float], None] = time.sleep,
+) -> dict[str, Any]:
+    """Report the real state of the Run this deployment queued, reading Studio and nothing else.
+
+    With ``watch_seconds`` unset this makes exactly one read. With it set, it reads on a bounded
+    backoff until the state stops changing on its own or the bound arrives, whichever is first,
+    and each distinct state it saw is listed once in the answer.
+
+    Raises:
+        HostedDeployError: when the journal cannot be read, when it names no queued Run, when the
+            authenticated workspace is not the one that deployed, or when Studio's answer cannot
+            be reached, is refused, or is not bound to this deployment. An answer naming a state
+            this release does not know is refused too, though the pinned client refuses to parse
+            one before it can reach that check.
+    """
+
+    if watch_seconds is not None and (
+        isinstance(watch_seconds, bool)
+        or not isinstance(watch_seconds, int)
+        or not 1 <= watch_seconds <= MAX_WATCH_SECONDS
+    ):
+        raise HostedDeployError(
+            "DEPLOY_REQUEST_INVALID",
+            f"watch seconds must be between 1 and {MAX_WATCH_SECONDS}",
+        )
+    activated = journaled_activation(run_dir)
+    if token.workspace_id != activated.workspace_id:
+        raise HostedDeployError(
+            "DEPLOY_STATE_MISMATCH",
+            "this credential authenticates a different workspace from the one that deployed",
+        )
+    client = (client_factory or GeneratedStudioDeploymentClient)(token)
+    try:
+        run, observed, timed_out = _watch(
+            client,
+            activated,
+            watch_seconds=watch_seconds,
+            clock=clock,
+            sleep=sleep,
+        )
+    finally:
+        client.close()
+    return _payload(
+        activated,
+        run,
+        observed,
+        timed_out=timed_out,
+        watch_seconds=watch_seconds,
+        cloud_url=credentials.cloud_url,
+    )
+
+
+def _watch(
+    client: StudioDeploymentClient,
+    activated: ActivatedRun,
+    *,
+    watch_seconds: int | None,
+    clock: Callable[[], float],
+    sleep: Callable[[float], None],
+) -> tuple[Mapping[str, Any], list[str], bool]:
+    """Read until the state stops moving on its own, the bound arrives, or once when unwatched."""
+
+    # The bound starts before the first read, not after it. A read is itself bounded -- the client
+    # carries `REQUEST_TIMEOUT_SECONDS` -- but starting the clock afterwards would hand every watch
+    # one free request beyond the number the caller asked for.
+    deadline = None if watch_seconds is None else clock() + float(watch_seconds)
+    run = _read_run(client, activated)
+    observed = [str(run["status"])]
+    if deadline is None:
+        return run, observed, False
+    delay = FIRST_POLL_DELAY_SECONDS
+    while RUN_STATES[str(run["status"])].keep_watching:
+        remaining = deadline - clock()
+        if remaining <= 0:
+            return run, observed, True
+        # Never sleep past the bound the caller asked for: a watch that overshoots its own
+        # deadline is no longer the bounded foreground operation it was described as.
+        sleep(min(delay, remaining))
+        delay = min(delay * 2, MAX_POLL_DELAY_SECONDS)
+        run = _read_run(client, activated)
+        status = str(run["status"])
+        if status not in observed:
+            observed.append(status)
+    return run, observed, False
+
+
+def _read_run(client: StudioDeploymentClient, activated: ActivatedRun) -> Mapping[str, Any]:
+    """One read of one Run, believed only after it is bound to this deployment."""
+
+    try:
+        response = client.read("get_run", resource_id=activated.run_id)
+    except HostedDeployError:
+        raise
+    except Exception as error:
+        # ⚠ EVERY failure of the call itself is one refusal, and deliberately so.
+        #
+        # It is tempting to single out `ValueError` here and call it "Studio named a state this
+        # release does not know", because that is one thing it can mean: the pinned model builds
+        # `RecipeBoundRunStatus(...)` while parsing, so an unknown state raises before a body ever
+        # reaches this module. Doing that was WRONG, and measurably so. The generated operation
+        # parses the error body of every non-200 through `StableAPIError.from_dict`, which builds
+        # `StableAPIErrorCode(...)` -- an enum with no generic 5xx or not-found member -- and
+        # `response.json()` raises `JSONDecodeError`, itself a `ValueError`, on any HTML body. So a
+        # cold-start 503 behind Cloud, a 500 with no body, and a 404 for a run that is not there
+        # all raise `ValueError` too, and singling it out reported the commonest transient failure
+        # this deployment path has as a contract this release cannot read: the one refusal an
+        # operator must not retry, printed for the three they must.
+        #
+        # Nothing here can tell those apart -- the status code is inside the exception's own
+        # stack, not on it -- so this says the true and useful thing for all of them, and the run
+        # state vocabulary is held by the build-time gate in `tests/test_hosted_run_status.py`
+        # instead. `DEPLOY_RUN_STATUS_UNKNOWN` still guards the table below, for any answer that
+        # gets that far.
+        raise HostedDeployError(
+            "DEPLOY_RUN_POLL_UNAVAILABLE", "the run status could not be checked"
+        ) from error
+    if response.status_code != 200:
+        raise HostedDeployError(
+            "DEPLOY_RUN_POLL_REFUSED",
+            f"Studio refused the run status check (HTTP {response.status_code})",
+        )
+    _validate_run(response.body, activated)
+    return response.body
+
+
+def _validate_run(run: Mapping[str, Any], activated: ActivatedRun) -> None:
+    """Refuse an answer that is not this deployment's Run before a word of it is believed.
+
+    An answer is trusted for exactly one reason: every coordinate the deployment journaled is in
+    it and matches. Without this a substituted or stale response -- another workspace's Run, the
+    predecessor Dataset's Run, a replayed body from a different deployment -- would be rendered as
+    this Run's own state, and a `released` that belongs to something else is the one wrong answer
+    this surface must never give.
+    """
+
+    expected: dict[str, Any] = {
+        "schema_version": STUDIO_SCHEMA_VERSION,
+        "run_id": str(activated.run_id),
+        "workspace_id": str(activated.workspace_id),
+        "dataset_id": str(activated.dataset_id),
+        "table_id": str(activated.table_id),
+        "table_recipe_id": activated.table_recipe_id,
+        **dict(activated.recipe),
+    }
+    drifted = sorted(name for name, value in expected.items() if run.get(name) != value)
+    if drifted:
+        raise HostedDeployError(
+            "DEPLOY_RUN_BINDING",
+            "the run status answer is not bound to this deployment: " + ", ".join(drifted),
+        )
+    status = run.get("status")
+    if not isinstance(status, str) or status not in RUN_STATES:
+        raise HostedDeployError(
+            "DEPLOY_RUN_STATUS_UNKNOWN",
+            f"Studio reported a run state this release does not know: {status!r}",
+        )
+    for name in ("created_at", "started_at", "completed_at"):
+        if name in run:
+            _utc(run, name)
+
+
+def _payload(
+    activated: ActivatedRun,
+    run: Mapping[str, Any],
+    observed: list[str],
+    *,
+    timed_out: bool,
+    watch_seconds: int | None,
+    cloud_url: str,
+) -> dict[str, Any]:
+    """One answer, every fact in it read from Studio's response or from the journal."""
+
+    status = str(run["status"])
+    state = RUN_STATES[status]
+    duration = _duration_seconds(run)
+    payload: dict[str, Any] = {
+        "schema_version": RUN_STATUS_SCHEMA,
+        "status": "run_watch_timed_out" if timed_out else "run_status_reported",
+        "run_status": status,
+        "run_disposition": state.disposition,
+        "terminal": state.terminal,
+        "means": state.means,
+        "next": _next_action(state, activated, timed_out=timed_out, watch_seconds=watch_seconds),
+        "workspace_id": str(activated.workspace_id),
+        "dataset_id": str(activated.dataset_id),
+        "table_id": str(activated.table_id),
+        "table_recipe_id": activated.table_recipe_id,
+        "run_id": str(activated.run_id),
+        "run_kind": run.get("kind"),
+        "states_seen": list(observed),
+        "created_at": run.get("created_at"),
+    }
+    for name in ("started_at", "completed_at", "failure_code", "repair_task_id"):
+        if run.get(name) is not None:
+            payload[name] = run[name]
+    if duration is not None:
+        # The only number here, and it is a subtraction of two timestamps Studio persisted. It is
+        # absent whenever either of them is, because the alternative -- measuring from this
+        # command's own clock -- would report how long somebody had been watching as though it
+        # were how long the run had taken.
+        payload["run_seconds"] = duration
+    if watch_seconds is not None:
+        payload["watch_limit_seconds"] = watch_seconds
+    if activated.cloud_dataset_id is not None:
+        payload["cloud_dataset_id"] = activated.cloud_dataset_id
+    if activated.current_path is not None:
+        payload["current_path"] = activated.current_path
+    payload["schedule"] = dict(activated.schedule)
+    payload["state"] = str(activated.state_path)
+    payload["dashboard_url"] = cloud_dashboard_url(cloud_url, "datasets")
+    return payload
+
+
+def _next_action(
+    state: RunState,
+    activated: ActivatedRun,
+    *,
+    timed_out: bool,
+    watch_seconds: int | None,
+) -> str:
+    """What to do about this state, given what this deployment actually recorded.
+
+    Only two cases differ from the state's own written sentence, and both are cases where that
+    sentence would name something the reader does not have: a watch that ran out has not reached
+    the state its answer describes, and a released version cannot be read at a path this journal
+    never got as far as recording.
+    """
+
+    if timed_out:
+        # The limit, named as the limit. How long the watch really took is a measurement nobody
+        # here made, and this module does not print those.
+        return (
+            f"this watch reached its limit of {watch_seconds} seconds and the run had not "
+            "finished; run this command again to pick the same run back up"
+        )
+    if state.disposition == RELEASED and activated.current_path is None:
+        return "open this Dataset in Cloud; this deployment recorded no current path for it"
+    return state.next
+
+
+def _duration_seconds(run: Mapping[str, Any]) -> int | None:
+    """How long the Run took, from Studio's two persisted timestamps and from nothing else.
+
+    A pair that runs backwards is no measurement, so it is reported as none at all rather than as
+    a negative number of seconds -- the same rule as an absent timestamp, for the same reason.
+    """
+
+    if run.get("started_at") is None or run.get("completed_at") is None:
+        return None
+    seconds = (_utc(run, "completed_at") - _utc(run, "started_at")).total_seconds()
+    return None if seconds < 0 else round(seconds)
+
+
+def _utc(run: Mapping[str, Any], field: str) -> datetime:
+    value = run.get(field)
+    try:
+        parsed = datetime.fromisoformat(str(value).replace("Z", "+00:00"))
+    except ValueError as error:
+        raise HostedDeployError(
+            "DEPLOY_RUN_BINDING", f"the run status answer carries an unreadable {field}"
+        ) from error
+    if parsed.tzinfo is None or parsed.utcoffset() != UTC.utcoffset(parsed):
+        raise HostedDeployError(
+            "DEPLOY_RUN_BINDING", f"the run status answer carries a {field} that is not UTC"
+        )
+    return parsed
+
+
+def _journaled_uuid(value: Any, field: str) -> UUID:
+    selected = value.get(field) if isinstance(value, Mapping) else None
+    try:
+        parsed = UUID(selected) if isinstance(selected, str) else None
+    except ValueError:
+        parsed = None
+    if parsed is None or str(parsed) != selected:
+        raise HostedDeployError(
+            "DEPLOY_STATE_INVALID", f"the deployment journal records no usable {field}"
+        )
+    return parsed
+
+
+def _journaled_identifier(value: Any, field: str) -> str:
+    selected = value.get(field) if isinstance(value, Mapping) else None
+    if (
+        not isinstance(selected, str)
+        or not selected
+        or not selected[0].isalnum()
+        or len(selected) > 128
+        or any(
+            not (character.isascii() and (character.isalnum() or character in "_.-"))
+            for character in selected
+        )
+    ):
+        raise HostedDeployError(
+            "DEPLOY_STATE_INVALID", f"the deployment journal records no usable {field}"
+        )
+    return selected
+
+
+def _optional_text(value: Mapping[str, Any], field: str) -> str | None:
+    selected = value.get(field)
+    return selected if isinstance(selected, str) and selected else None