mostlyright-data 0.9.0__py3-none-any.whl

mostlyright/data_harness/catalog_job.py

@@ -0,0 +1,625 @@
+"""One-shot Cloud Run wrapper for the catalogue harvest -> author -> publish pipeline.
+
+WHAT THIS IS FOR. ``catalog-harvest``, ``catalog-author`` and ``catalog-publish`` are the three
+provider-scale mutations that produce a sealed generation. They were built to be driven by an
+operator at a terminal, resumed by hand, and paced by hand -- and the data.gov sweep proved what
+that costs: thirty-six hours of a laptop staying awake, driven by a shell loop, with the key in
+somebody's shell history. Under ADR 0021 the pipeline belongs where every other lane went: a
+backend job, executed by Studio, whose configuration is deploy-owned and whose credential comes
+from Secret Manager at run time and is never baked into an image.
+
+WHAT THIS IS NOT. It is not a fourth catalogue command and it adds no new pipeline behaviour. It
+resolves one stage, builds that stage's exact argv, runs that stage's own ``run`` function, and
+publishes the receipt. Resume, pacing, bounds, the typed-incomplete receipt discipline and every
+refusal belong to the stage and are untouched here -- which is the point: an operator running the
+stage by hand and this job running it must produce the same receipt, or the hosted pipeline is a
+second implementation of the pipeline.
+
+WHAT IT DOES ADD, and why each is here rather than in the stage:
+
+* **The key file.** The harness key boundary requires a regular file owned by the running user
+  with no group or other permission bits (``acquisition.http._require_datagov_key_stat``). A
+  Cloud Run secret *volume* is none of those -- it is root-owned and world-readable -- so a
+  mounted secret cannot be handed to ``--api-key-file`` at all. The secret therefore arrives as an
+  environment variable and this wrapper materialises it into a private ``0400`` file, hands the
+  path to the stage, and removes the file afterwards whether the stage succeeded or refused. The
+  stage never learns where the secret came from, and no refusal in this module quotes a byte of
+  it.
+* **The pacing floor.** ``--min-request-interval-ms`` is an argument, which means a job spec could
+  set it to zero. Against a keyed provider lane that is not a configuration choice, it is a way to
+  get the key blocked, so the floor is enforced here and a spec below it is refused rather than
+  clamped. Refused rather than clamped because a spec that asked for something it may not have is
+  a mistake somebody should see.
+* **Receipt publication.** A receipt on a container filesystem is a receipt nobody has. Each stage
+  writes its receipt where the spec's ``receipt_path`` says, and this wrapper puts that exact file
+  and this job's own execution record into the release bucket, create-only, so a retried execution
+  cannot overwrite the first attempt's evidence.
+* **The verdict.** The execution record says what the stage answered -- ``stage_status`` is the
+  stage's own word, ``status`` is ``complete`` only when the stage's own ``exit_code`` says so --
+  and the job then exits with that code. Both, because the two are seen by different readers: the
+  receipt is what survives in the bucket for a person or a later stage, and the exit status is the
+  *only* thing Cloud Run itself can see. An execution's console row, ``gcloud run jobs executions
+  list`` and every alert built on them read the exit status and nothing about the receipt, so a
+  stage that stopped and exited zero is a green execution. That is not hypothetical: the data.gov
+  sweep of 2026-08-22 stalled for twenty-eight hours against a page it could not fetch, and the
+  only reason anybody noticed is that it was running on a laptop somebody was watching. The
+  verdict is read from the stage's ``exit_code`` rather than from a table of statuses kept here,
+  because the same word means different things to different stages and a second copy of that
+  judgement is a copy that goes stale.
+
+``--dry-run`` resolves everything and runs nothing: it parses the spec, builds and validates the
+argv against the stage's real parser, checks the pacing floor, reports whether the credential and
+the bucket are configured, and exits. It never reads the secret, never opens a socket, and never
+writes to the work root -- so it is safe to execute against production configuration, which is
+what makes it useful as a deployment check.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import ssl
+import stat
+import sys
+from collections.abc import Mapping, Sequence
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any, NoReturn
+from urllib.error import HTTPError
+from urllib.parse import quote, urlencode
+from urllib.request import HTTPRedirectHandler, HTTPSHandler, ProxyHandler, Request, build_opener
+
+CATALOG_JOB_SPEC_SCHEMA = "mostlyright-catalog-job.v1"
+CATALOG_JOB_RECEIPT_SCHEMA = "mostlyright-catalog-job-receipt.v1"
+
+#: The deploy-owned job specification, as one JSON object.
+JOB_SPEC_ENV = "MOSTLYRIGHT_CATALOG_JOB_SPEC_JSON"
+
+#: The provider key, delivered by Secret Manager as an environment variable. Never a file mount:
+#: see the module docstring for why a mounted secret cannot satisfy the key boundary.
+DATAGOV_KEY_ENV = "MOSTLYRIGHT_CATALOG_DATAGOV_API_KEY"
+
+#: Where receipts and release archives are published.
+RELEASES_BUCKET_ENV = "MOSTLYRIGHT_CATALOG_RELEASES_BUCKET"
+
+#: The three stages this job can execute, and the command module each is.
+STAGES = {
+    "harvest": "catalog_harvest",
+    "author": "catalog_author",
+    "publish": "catalog_publish",
+}
+
+#: The keyed data.gov lane's floor, in milliseconds between requests. Proven by running the sweep:
+#: api.data.gov's free tier is 1000 requests an hour, and 3700 ms is the interval the completed
+#: 155-page sweep ran at without a single refusal.
+DATAGOV_MIN_REQUEST_INTERVAL_MS = 3700
+
+#: The largest page the keyed lane asks for. Above this the provider truncates silently.
+DATAGOV_MAX_PER_PAGE = 1000
+
+#: Arguments the spec may not state, because this wrapper owns them.
+RESERVED_ARGUMENTS = ("--api-key-file", "--json")
+
+MAX_JOB_SPEC_BYTES = 64 * 1024
+MAX_KEY_BYTES = 4096
+MAX_RECEIPT_UPLOAD_BYTES = 64 * 1024 * 1024
+UPLOAD_TIMEOUT_SECONDS = 300.0
+METADATA_TOKEN_URL = (
+    "http://169.254.169.254/computeMetadata/v1/instance/service-accounts/default/token"
+)
+STORAGE_WRITE_SCOPE = "https://www.googleapis.com/auth/devstorage.read_write"
+
+_SPEC_KEYS = frozenset(
+    {"arguments", "receipt_object_prefix", "receipt_path", "run_id", "schema_version", "stage"}
+)
+
+
+class CatalogJobError(RuntimeError):
+    """A typed, credential-safe refusal. ``detail`` never carries the key or its bytes."""
+
+    def __init__(self, code: str, detail: str) -> None:
+        self.code = code
+        self.detail = detail
+        super().__init__(f"{code}: {detail}")
+
+
+# --------------------------------------------------------------------------------------------
+# The job specification
+
+
+class JobSpec:
+    """One resolved catalogue job: which stage, which arguments, and where the receipt goes."""
+
+    __slots__ = ("arguments", "receipt_object_prefix", "receipt_path", "run_id", "stage")
+
+    def __init__(
+        self,
+        *,
+        stage: str,
+        run_id: str,
+        arguments: tuple[str, ...],
+        receipt_path: str,
+        receipt_object_prefix: str,
+    ) -> None:
+        self.stage = stage
+        self.run_id = run_id
+        self.arguments = arguments
+        self.receipt_path = receipt_path
+        self.receipt_object_prefix = receipt_object_prefix
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "arguments": list(self.arguments),
+            "receipt_object_prefix": self.receipt_object_prefix,
+            "receipt_path": self.receipt_path,
+            "run_id": self.run_id,
+            "schema_version": CATALOG_JOB_SPEC_SCHEMA,
+            "stage": self.stage,
+        }
+
+
+def _require_run_id(value: Any) -> str:
+    if (
+        not isinstance(value, str)
+        or not 1 <= len(value) <= 128
+        or not all(character.isalnum() or character in "-_" for character in value)
+    ):
+        raise CatalogJobError(
+            "CATALOG_JOB_SPEC", "run_id must be one short alphanumeric, dash or underscore label"
+        )
+    return value
+
+
+def _require_object_prefix(value: Any) -> str:
+    if (
+        not isinstance(value, str)
+        or not 1 <= len(value) <= 256
+        or not value.endswith("/")
+        or value.startswith("/")
+        or ".." in value
+        or not all(character.isalnum() or character in "-_./" for character in value)
+    ):
+        raise CatalogJobError(
+            "CATALOG_JOB_SPEC",
+            "receipt_object_prefix must be one relative object prefix ending in a slash",
+        )
+    return value
+
+
+def parse_job_spec(data: Any) -> JobSpec:
+    """Parse the deploy-owned specification, refusing anything it does not exactly declare."""
+
+    if not isinstance(data, dict) or set(data) != _SPEC_KEYS:
+        raise CatalogJobError(
+            "CATALOG_JOB_SPEC", "the job specification must carry exactly the declared fields"
+        )
+    if data["schema_version"] != CATALOG_JOB_SPEC_SCHEMA:
+        raise CatalogJobError(
+            "CATALOG_JOB_SPEC", f"the job specification schema must be {CATALOG_JOB_SPEC_SCHEMA}"
+        )
+    stage = data["stage"]
+    if stage not in STAGES:
+        raise CatalogJobError("CATALOG_JOB_SPEC", "stage must be one of harvest, author or publish")
+    arguments = data["arguments"]
+    if not isinstance(arguments, list) or not all(
+        isinstance(item, str) and item and "\x00" not in item for item in arguments
+    ):
+        raise CatalogJobError("CATALOG_JOB_SPEC", "arguments must be a list of nonempty strings")
+    for reserved in RESERVED_ARGUMENTS:
+        if reserved in arguments:
+            raise CatalogJobError(
+                "CATALOG_JOB_SPEC",
+                f"{reserved} is supplied by the job wrapper and may not be stated in the spec",
+            )
+    receipt_path = data["receipt_path"]
+    if not isinstance(receipt_path, str) or not receipt_path.startswith("/"):
+        raise CatalogJobError(
+            "CATALOG_JOB_SPEC", "receipt_path must be one absolute path in the container"
+        )
+    return JobSpec(
+        stage=stage,
+        run_id=_require_run_id(data["run_id"]),
+        arguments=tuple(arguments),
+        receipt_path=receipt_path,
+        receipt_object_prefix=_require_object_prefix(data["receipt_object_prefix"]),
+    )
+
+
+def job_spec_from_environment(environment: Mapping[str, str]) -> JobSpec:
+    raw = environment.get(JOB_SPEC_ENV)
+    if not isinstance(raw, str) or not raw.strip():
+        raise CatalogJobError(
+            "CATALOG_JOB_SPEC", f"{JOB_SPEC_ENV} is not set on this job's template"
+        )
+    if len(raw.encode("utf-8")) > MAX_JOB_SPEC_BYTES:
+        raise CatalogJobError("CATALOG_JOB_SPEC", f"{JOB_SPEC_ENV} is larger than the bound")
+    try:
+        data = json.loads(raw)
+    except ValueError as error:
+        raise CatalogJobError("CATALOG_JOB_SPEC", f"{JOB_SPEC_ENV} is not one JSON object") from (
+            error
+        )
+    return parse_job_spec(data)
+
+
+# --------------------------------------------------------------------------------------------
+# Pacing
+
+
+def require_pacing_floor(stage: str, namespace: argparse.Namespace) -> None:
+    """Refuse a harvest that asks to go faster than the keyed lane may be driven.
+
+    Only the harvest stage reaches the provider; author and publish reach no network at all, so
+    there is nothing to pace and asserting a floor on them would be theatre.
+
+    A ``--preflight-only`` harvest is the same kind of theatre and is exempt for the same reason.
+    It reads the key file, makes no request, and writes nothing, and ``catalog_harvest`` forbids
+    ``--min-request-interval-ms`` in that form -- so demanding one here made the preflight spec
+    unsatisfiable: stating the flag is refused by the stage, and omitting it was refused here.
+    The floor belongs to the requests a sweep makes, and a preflight makes none.
+    """
+
+    if stage != "harvest":
+        return
+    if getattr(namespace, "preflight_only", False):
+        return
+    interval = getattr(namespace, "min_request_interval_ms", None)
+    if interval is None or int(interval) < DATAGOV_MIN_REQUEST_INTERVAL_MS:
+        raise CatalogJobError(
+            "CATALOG_JOB_PACING",
+            "--min-request-interval-ms must be at least "
+            f"{DATAGOV_MIN_REQUEST_INTERVAL_MS} for the keyed provider lane",
+        )
+    per_page = getattr(namespace, "per_page", None)
+    if per_page is not None and int(per_page) > DATAGOV_MAX_PER_PAGE:
+        raise CatalogJobError(
+            "CATALOG_JOB_PACING", f"--per-page must not exceed {DATAGOV_MAX_PER_PAGE}"
+        )
+
+
+def resolve_stage(spec: JobSpec, extra: Sequence[str] = ()) -> tuple[Any, argparse.Namespace]:
+    """Load the stage's own command descriptor and parse the spec's argv with its own parser.
+
+    Parsing with the real parser rather than a copy of it is what makes ``--dry-run`` worth
+    running: a spec that names an argument the stage does not have fails here, in a deployment
+    check, rather than an hour into an execution.
+
+    Argparse only carries the rules a flag states about itself, and the harvest's rules are
+    modal -- ``--output-root`` is required by a sweep and forbidden by a preflight -- so argparse
+    accepting a spec never meant the stage would. The stage's own ``validate`` is asked here,
+    on the path both ``--dry-run`` and a real execution take, so the two cannot disagree about
+    which specs are runnable and a spec that cannot run cannot sit deployed looking healthy.
+    """
+
+    from mostlyright.data_harness.sources.contracts import SourceContractError
+    from mostlyright.data_harness.ux.commands import discovered_commands
+
+    module = STAGES[spec.stage]
+    descriptor = next(
+        (item for item in discovered_commands() if item.implementation_module == module), None
+    )
+    if descriptor is None:  # pragma: no cover - the descriptor tuple is closed and tested
+        raise CatalogJobError("CATALOG_JOB_SPEC", f"no command is registered for {spec.stage}")
+    resolved = descriptor.resolve()
+    parser = argparse.ArgumentParser(prog=f"mr-data {resolved.name}", add_help=False)
+    resolved.add_arguments(parser)
+    try:
+        namespace = parser.parse_args([*spec.arguments, *extra])
+    except SystemExit as error:
+        raise CatalogJobError(
+            "CATALOG_JOB_SPEC", f"the {spec.stage} arguments are not valid for that command"
+        ) from error
+    require_pacing_floor(spec.stage, namespace)
+    if resolved.validate is not None:
+        try:
+            resolved.validate(namespace)
+        except SourceContractError as error:
+            raise CatalogJobError(
+                "CATALOG_JOB_SPEC",
+                f"the {spec.stage} arguments are not one this stage would run: {error}",
+            ) from error
+    return resolved, namespace
+
+
+# --------------------------------------------------------------------------------------------
+# The credential
+
+
+def materialize_key_file(environment: Mapping[str, str], directory: Path) -> Path:
+    """Write the Secret Manager key into a private file the key boundary will accept.
+
+    Created with ``O_EXCL`` at mode 0600 and then narrowed to 0400: the boundary requires no group
+    or other bits and a link count of exactly one, and creating it exclusively is what makes the
+    link count a fact rather than a hope.
+    """
+
+    raw = environment.get(DATAGOV_KEY_ENV)
+    if not isinstance(raw, str) or not raw.strip():
+        raise CatalogJobError(
+            "CATALOG_JOB_CREDENTIAL",
+            f"{DATAGOV_KEY_ENV} is not set; the keyed provider lane cannot run without it",
+        )
+    key = raw.strip()
+    if len(key) > MAX_KEY_BYTES or not all(0x21 <= ord(character) <= 0x7E for character in key):
+        raise CatalogJobError(
+            "CATALOG_JOB_CREDENTIAL", "the provider key is not one printable ASCII line"
+        )
+    directory.mkdir(parents=True, exist_ok=True)
+    os.chmod(directory, 0o700)
+    path = directory / "provider-api-key"
+    flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_NOFOLLOW", 0)
+    descriptor = os.open(path, flags, 0o600)
+    try:
+        os.write(descriptor, key.encode("ascii"))
+        os.fchmod(descriptor, stat.S_IRUSR)
+    finally:
+        os.close(descriptor)
+    return path
+
+
+def _discard_key_file(path: Path) -> None:
+    try:
+        os.chmod(path, stat.S_IWUSR)
+        os.unlink(path)
+    except OSError:  # pragma: no cover - a removed file is the outcome either way
+        pass
+
+
+# --------------------------------------------------------------------------------------------
+# Publishing the receipt
+
+
+class _NoRedirect(HTTPRedirectHandler):
+    def redirect_request(
+        self,
+        request: Request,
+        file_pointer: Any,
+        code: int,
+        message: str,
+        headers: Any,
+        new_url: str,
+    ) -> None:
+        return None
+
+
+def _opener() -> Any:
+    return build_opener(
+        ProxyHandler({}), HTTPSHandler(context=ssl.create_default_context()), _NoRedirect()
+    )
+
+
+def _access_token() -> str:
+    request = Request(
+        METADATA_TOKEN_URL + "?" + urlencode({"scopes": STORAGE_WRITE_SCOPE}),
+        headers={"Metadata-Flavor": "Google"},
+        method="GET",
+    )
+    try:
+        with _opener().open(request, timeout=30.0) as response:
+            payload = json.loads(response.read(16 * 1024))
+    except (HTTPError, OSError, ValueError) as error:
+        raise CatalogJobError(
+            "CATALOG_JOB_IDENTITY", "this job could not obtain its own access token"
+        ) from error
+    token = payload.get("access_token") if isinstance(payload, dict) else None
+    if not isinstance(token, str) or not token:
+        raise CatalogJobError(
+            "CATALOG_JOB_IDENTITY", "the metadata server returned no access token"
+        )
+    return token
+
+
+def upload_object(bucket: str, name: str, body: bytes, *, content_type: str) -> str:
+    """Write one object into the release bucket, and answer the object's name.
+
+    ``ifGenerationMatch=0`` makes the write create-only: a receipt is evidence about one execution
+    and must never overwrite evidence about another. A retried execution therefore fails to write
+    rather than silently replacing the first attempt's record.
+    """
+
+    if len(body) > MAX_RECEIPT_UPLOAD_BYTES:
+        raise CatalogJobError("CATALOG_JOB_RECEIPT", "the receipt is larger than the upload bound")
+    query = urlencode({"uploadType": "media", "name": name, "ifGenerationMatch": "0"})
+    url = f"https://storage.googleapis.com/upload/storage/v1/b/{quote(bucket, safe='')}/o?{query}"
+    request = Request(
+        url,
+        data=body,
+        headers={
+            "Authorization": "Bearer " + _access_token(),
+            "Content-Type": content_type,
+            "Content-Length": str(len(body)),
+        },
+        method="POST",
+    )
+    try:
+        with _opener().open(request, timeout=UPLOAD_TIMEOUT_SECONDS) as response:
+            if int(response.status) not in (200, 201):
+                raise CatalogJobError(
+                    "CATALOG_JOB_RECEIPT", f"the bucket answered {response.status}"
+                )
+    except HTTPError as error:
+        raise CatalogJobError(
+            "CATALOG_JOB_RECEIPT", f"the bucket answered {error.code} for {name}"
+        ) from error
+    except OSError as error:
+        raise CatalogJobError(
+            "CATALOG_JOB_RECEIPT", f"the receipt for {name} was not written"
+        ) from error
+    return name
+
+
+# --------------------------------------------------------------------------------------------
+# The job
+
+
+def _now() -> str:
+    return datetime.now(UTC).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+#: What ``--dry-run`` puts where the credential path will go. The harvest stage requires the
+#: argument to be present, and a dry run must not read the secret to satisfy a parser, so it
+#: parses a path that is never opened and is obviously not a real one if it ever leaks into a log.
+DRY_RUN_KEY_PATH = "/nonexistent/supplied-at-run-time"
+
+
+def _dry_run(spec: JobSpec, environment: Mapping[str, str]) -> dict[str, Any]:
+    extra = ("--api-key-file", DRY_RUN_KEY_PATH) if spec.stage == "harvest" else ()
+    resolved, namespace = resolve_stage(spec, extra)
+    return {
+        "schema_version": CATALOG_JOB_RECEIPT_SCHEMA,
+        "status": "dry-run",
+        "stage": spec.stage,
+        "run_id": spec.run_id,
+        "command": resolved.name,
+        "arguments": list(spec.arguments),
+        "resume": bool(getattr(namespace, "resume", False)),
+        "min_request_interval_ms": getattr(namespace, "min_request_interval_ms", None),
+        "receipt_path": spec.receipt_path,
+        "receipt_object_prefix": spec.receipt_object_prefix,
+        "credential_configured": bool(environment.get(DATAGOV_KEY_ENV)),
+        "releases_bucket": environment.get(RELEASES_BUCKET_ENV),
+    }
+
+
+def stage_verdict(resolved: Any, payload: Mapping[str, Any]) -> tuple[str | None, int]:
+    """Read the stage's own answer: the word it used, and whether that word is a success.
+
+    The verdict is *derived* from the stage's ``exit_code``, never from a table of acceptable
+    statuses kept here. The stages already own this judgement -- ``catalog-harvest`` knows that
+    ``harvest_incomplete`` is not a finished sweep and ``harvest_preflight_accepted`` is not a
+    failure -- and a second copy of it in this wrapper is a copy that goes stale. The day a stage
+    grows a fourth outcome, a table would not recognise it and would wave it through as complete;
+    deriving means an unrecognised answer fails closed instead.
+
+    A stage that declares no ``exit_code`` succeeded if it produced a payload at all, which is the
+    rule ``CommandSpec`` already states for the terminal.
+    """
+
+    stage_status = payload.get("status")
+    exit_code = 0 if resolved.exit_code is None else int(resolved.exit_code(payload))
+    return (stage_status if isinstance(stage_status, str) else None), exit_code
+
+
+def _read_stage_receipt(path: Path) -> bytes | None:
+    """The stage's own receipt file, or None when the stage did not write one there.
+
+    Bounded, and absence is not an error: ``--preflight-only`` writes no receipt, and a stage that
+    refused before installing one has nothing to publish. What is refused is a receipt too large
+    to be one, which is a fact about the file rather than about the stage.
+    """
+
+    try:
+        raw = path.read_bytes()
+    except OSError:
+        return None
+    if len(raw) > MAX_RECEIPT_UPLOAD_BYTES:
+        raise CatalogJobError(
+            "CATALOG_JOB_RECEIPT", f"the stage receipt at {path} is larger than the upload bound"
+        )
+    return raw
+
+
+def run_job(
+    environment: Mapping[str, str] | None = None, *, dry_run: bool = False
+) -> dict[str, Any]:
+    """Execute one stage of the catalogue pipeline, or resolve it and stop."""
+
+    env = os.environ if environment is None else environment
+    spec = job_spec_from_environment(env)
+    if dry_run:
+        return _dry_run(spec, env)
+    bucket = env.get(RELEASES_BUCKET_ENV)
+    if not bucket:
+        raise CatalogJobError(
+            "CATALOG_JOB_SPEC", f"{RELEASES_BUCKET_ENV} is not set on this job's template"
+        )
+    key_directory = Path(env.get("MOSTLYRIGHT_CATALOG_JOB_KEY_DIR") or "/tmp/catalog-job-key")
+    key_path: Path | None = None
+    extra: tuple[str, ...] = ()
+    if spec.stage == "harvest":
+        key_path = materialize_key_file(env, key_directory)
+        extra = ("--api-key-file", str(key_path))
+    try:
+        resolved, namespace = resolve_stage(spec, extra)
+        started_at = _now()
+        payload = resolved.run(namespace)
+    finally:
+        if key_path is not None:
+            _discard_key_file(key_path)
+    stage_status, exit_code = stage_verdict(resolved, payload)
+    receipt = {
+        "schema_version": CATALOG_JOB_RECEIPT_SCHEMA,
+        "status": "complete" if exit_code == 0 else "incomplete",
+        "stage_status": stage_status,
+        "exit_code": exit_code,
+        "stage": spec.stage,
+        "run_id": spec.run_id,
+        "command": resolved.name,
+        "arguments": list(spec.arguments),
+        "started_at": started_at,
+        "finished_at": _now(),
+        "stage_payload": payload,
+    }
+    published = [
+        upload_object(
+            bucket,
+            f"{spec.receipt_object_prefix}{spec.run_id}/{spec.stage}.json",
+            json.dumps(receipt, sort_keys=True, ensure_ascii=False).encode("utf-8"),
+            content_type="application/json",
+        )
+    ]
+    stage_receipt = _read_stage_receipt(Path(spec.receipt_path))
+    if stage_receipt is not None:
+        # The stage's own receipt, not a summary of it. It is the resume journal and the
+        # authoritative evidence for this stage, and a receipt that exists only on a container
+        # filesystem is a receipt nobody has once the execution ends.
+        published.append(
+            upload_object(
+                bucket,
+                f"{spec.receipt_object_prefix}{spec.run_id}/{spec.stage}-receipt.json",
+                stage_receipt,
+                content_type="application/json",
+            )
+        )
+    receipt["published_objects"] = published
+    return receipt
+
+
+def _fatal(error: Exception) -> NoReturn:
+    code = getattr(error, "code", None) or "CATALOG_JOB_FAILED"
+    detail = getattr(error, "detail", None) or type(error).__name__
+    sys.stderr.write(
+        json.dumps({"status": "failed", "code": code, "detail": detail}, sort_keys=True) + "\n"
+    )
+    raise SystemExit(1)
+
+
+def catalog_job_main(argv: Sequence[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="mr-data-catalog-job",
+        description="Run one stage of the catalogue pipeline as a backend job.",
+    )
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="resolve the spec and the stage's arguments, run nothing, and print the plan",
+    )
+    args = parser.parse_args(argv)
+    try:
+        payload = run_job(dry_run=args.dry_run)
+    except Exception as error:
+        _fatal(error)
+    sys.stdout.write(json.dumps(payload, sort_keys=True, ensure_ascii=False) + "\n")
+    # The receipt is already written and published by here, and only then does the job report the
+    # stage's verdict as its own exit status. Cloud Run sees nothing else: an execution's console
+    # row, `gcloud run jobs executions list`, and every alert built on either read the exit status
+    # and nothing about the receipt. A sweep that stopped and exited zero is a green execution, so
+    # the stall is invisible exactly when somebody most needs to see it. Ordering matters as much
+    # as the code: an incomplete harvest's receipt is its resume journal, so it is published first
+    # and the failure reported second, never the other way around.
+    return int(payload.get("exit_code", 0))
+
+
+if __name__ == "__main__":  # pragma: no cover - the console script is the entry point
+    raise SystemExit(catalog_job_main())